使用Docusign API实现PDF表单转换与预填字段共存的问题

启用transformPdfFields时，Docusign会自动将PDF表单字段转换为对应Docusign标签。此时如果同时手动添加同名/同位置的锚点标签，会导致生成重复无效字段，预填值无法生效，签名标签也会冲突失效。

方案1：基于转换后的PDF表单字段直接预填（推荐） #

无需依赖锚点，直接针对转换后的字段设置预填值，同时利用PDF签名域自动转换的SignHere标签（若PDF包含签名域），或在非表单字段位置添加锚点签名（确保锚点字符串不是PDF表单字段名）。

修改后的代码示例：

// 1. 配置签署人及签名标签（PDF无签名域时用锚点，有则可省略）
val signHereAnchor = SignHere()
signHereAnchor.anchorString = "SignAnchorTextHere" // 确保该字符串不是PDF表单字段名
val signerTabs = Tabs()
signerTabs.signHereTabs = listOf(signHereAnchor)

val signer = Signer()
signer.email = "nobody@test.com"
signer.name = "John Doe"
signer.recipientId = "1"
signer.tabs = signerTabs

// 2. 预填转换后的PDF表单字段（tabLabel与PDF表单字段名完全一致）
val prefillText1 = Text()
prefillText1.tabLabel = "PrefillAnchorField" // 对应PDF中的表单字段名
prefillText1.value = "pre-fill value for PDF field"

val prefillText2 = Text()
prefillText2.tabLabel = "OtherPDFTextField" // 另一个PDF表单字段名
prefillText2.value = "another pre-filled value"

val prefillTabs = PrefillTabs()
prefillTabs.textTabs = listOf(prefillText1, prefillText2)
val docTabs = Tabs()
docTabs.prefillTabs = prefillTabs

// 3. 配置文档，启用PDF字段转换
val doc = Document()
doc.documentId = "1"
doc.tabs = docTabs
doc.transformPdfFields = "true"
doc.documentBase64 = b64pdf
doc.name = "anchorprefilltest"
doc.fileExtension = "pdf"

// 4. 创建信封
val envDef = EnvelopeDefinition()
envDef.emailSubject = "test pdf"
envDef.recipients = Recipients().signers(listOf(signer))
envDef.status = "sent"
envDef.documents = listOf(doc)

方案2：禁用PDF字段转换，纯锚点实现所有需求 #

如果不需要保留PDF表单字段的映射关系，直接用锚点定义所有预填字段和签名字段，彻底避免转换冲突。

修改后的代码示例：

// 1. 签署人签名标签
val signHereAnchor1 = SignHere()
signHereAnchor1.anchorString = "SignAnchorTextHere"
val signHereAnchor2 = SignHere()
signHereAnchor2.anchorString = "SignByAnchorField"
val signerTabs = Tabs()
signerTabs.signHereTabs = listOf(signHereAnchor1, signHereAnchor2)

val signer = Signer()
signer.email = "nobody@test.com"
signer.name = "John Doe"
signer.recipientId = "1"
signer.tabs = signerTabs

// 2. 预填字段（用锚点定位）
val prefillText1 = Text()
prefillText1.anchorString = "PrefillAnchorText"
prefillText1.value = "pre-fill value test on anchor text"

val prefillText2 = Text()
prefillText2.anchorString = "PrefillAnchorField"
prefillText2.value = "pre-fill value text on anchor field"

val prefillTabs = PrefillTabs()
prefillTabs.textTabs = listOf(prefillText1, prefillText2)
val docTabs = Tabs()
docTabs.prefillTabs = prefillTabs

// 3. 配置文档，禁用PDF字段转换
val doc = Document()
doc.documentId = "1"
doc.tabs = docTabs
doc.transformPdfFields = "false" // 关闭自动转换
doc.documentBase64 = b64pdf
doc.name = "anchorprefilltest"
doc.fileExtension = "pdf"

// 4. 创建信封
val envDef = EnvelopeDefinition()
envDef.emailSubject = "test pdf"
envDef.recipients = Recipients().signers(listOf(signer))
envDef.status = "sent"
envDef.documents = listOf(doc)

• 启用transformPdfFields时，Docusign会自动生成与PDF表单字段同名的标签，此时手动添加同tabLabel或同位置的锚点标签会导致重复，必须二选一。
• 预填字段必须放在PrefillTabs中，确保只有发送方能设置，签署人无法修改（若需要签署人可修改，直接放在签署人的Tabs集合中）。
• 如需排除部分PDF表单字段不转换，可使用transformPdfFieldsOptions参数指定规则，例如：doc.transformPdfFieldsOptions = "exclude=field1,field2"。

内容的提问来源于stack exchange，提问作者computerguy