自动放置字段

一份文档手动放置字段没有问题。但如果是每周都要发送的合同，或由 AutomaDoc 生成的文档，不如在文档中写入标签：在客户签名的位置写 [[sign:Client]]，在填写日期的位置写 [[date:Client]]。文档预处理时，AutomaDoc 会找到每个标签并在那里放置字段。无法编辑文档的 API 调用方可以使用锚点：相对于文档中已有文字放置的字段。

文字标签

Word 中的示例

在需要放置字段的地方，以普通文字的形式输入标签：

Signed for the client:

[[sign:Client]]

Name: [[name:Client]]          Date: [[date:Client]]
Company: [[company:Client]]
Purchase order: [[text:Client:PO number;optional]]

[[check:Client:Terms]] I have read and accept the terms.

Signed for the supplier:

[[sign:Supplier;w=180;h=50]]
Initials on every page: [[initials:Supplier]]

把这份文档加入请求后，它会有两个位置：Client 和 Supplier。把每个位置分配给一位收件人，该角色的所有字段就都归此人。通过 API 时，设置 autoTags: true 并为每位收件人指定 slot。

标签在 PDF、Word、Excel、PowerPoint 文件以及 AutomaDoc 模板中的用法都一样：生成过程不会改动方括号，因此由带标签的模板生成的文档进入请求时，字段已经可以直接放置。这也是标签使用 [[ ]] 而不是模板占位符的 { } 的原因。

语法

[[ kind : role ]]
[[ kind : role : label ]]
[[ kind : role ; option ; option ]]
[[ kind : role : label ; option ]]

类型（kind，不区分大小写）说明字段是什么：

类型	也可写作	字段
`sign`	`signature`	签名
`initials`	`initial`	姓名缩写
`name`		姓名
`date`		签署日期（自动填入）
`text`		文本
`check`	`checkbox`	复选框
`company`		公司
`email`		邮箱

角色（role）是字段所属的位置：1 到 60 个字母、数字、附加符号或下划线，任何文字均可（Client、Witness_1、客户）。不能有空格。区分大小写：Client 和 client 是两个不同的位置。角色后面紧跟 # 加数字的写法保留给 AutomaDoc 内部使用。

标签名（label，选填）为 1 到 100 个字符，作为字段名称显示给签署人，例如 [[text:Client:PO number]]。其中不能包含 [、]、; 或 :。

选项（option）每个都写在 ; 之后，不区分大小写：

选项	含义
`w=180`	宽度，单位为磅（1 磅为 1/72 英寸），8 到 1000，最多两位小数
`h=50`	高度，单位为磅，8 到 1000
`optional`	签署人可以不填
`required`	签署人必须填写（默认）

每个部分前后都可以有空格和换行，所以 [[ sign : Client ]] 可以使用，在两个部分之间折到第二行的标签也可以使用。但在一个词的中间换行（比如在 Client 中间）会破坏标签。

一个标签从 [[ 到 ]] 最多 200 个字符。超过这个长度，或者没有闭合的 ]]，它就会被当作普通文字并被忽略。

字段放在哪里

字段的左上角就是标签的左上角。字段的大小取标签的 w 和 h，否则使用该字段的默认大小（单位为磅：签名 160 × 48，姓名缩写 64 × 40，复选框 14 × 14，邮箱 180 × 20，日期 110 × 20，其他文本字段 160 × 20）。没有 h 时，字段高度不会小于标签文字的高度。超出页面的字段会被移回页面内。

因此，请在每个标签的右侧和下方留出空间：签名字段从标签顶部向下延伸 48 磅（约 1.7 厘米）。

出错时

不符合语法的 [[…]] 永远不会被猜测含义：它作为文字留在页面上，不会生成字段，发件人会收到提示，并附上标签原文（每份文档最多列出前 50 个）。常见原因是缺少角色、角色中有空格、类型或选项无法识别，或大小超出 8 到 1000 的范围。

其他限制：

每页最多读取 500 个标签，每份文档也最多 500 个；超出部分会被忽略，并给出提示；
只搜索 PDF 中真正包含的文字：扫描页面是一张图片，其中的标签无法被找到；
角色未分配给任何收件人的标签不会生成字段。没有任何字段的签署人会导致请求无法发送。

再次应用标签会替换由标签生成的字段。您手动放置的字段保持不变。

通过 API 使用锚点

锚点相对于文档中已有的文字放置字段，例如“Client signature:”。它适用于您无法编辑的文档。锚点是 POST /api/v1/envelopes 的一部分（请参阅 Envelopes API）。下面的请求以 multipart/form-data 发送：这段 JSON 放在名为 envelope 的部分中，PDF 放在名为 contract 的部分中。

{
  "title": "Service agreement",
  "documents": [{ "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Ana Lim", "email": "ana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetY": 14 },
    { "anchor": "Date:", "occurrence": 2, "recipient": "client", "type": "date_signed", "offsetX": 30, "offsetY": -2 }
  ],
  "send": true
}

属性
`anchor`	要查找的文字，1 到 200 个字符。必填。
`recipient`	同一请求中某位收件人的 `key`。必填。
`type`	`signature`、`initials`、`name`、`date_signed`、`text`、`checkbox`、`company` 或 `email`。必填。
`occurrence`	`"all"`（默认）或一个数字：在整个请求中的第 1 个、第 2 个……匹配。
`offsetX`, `offsetY`	相对于匹配文字左上角的磅数，-2000 到 2000。正值向右、向下。默认 0。
`w`, `h`	大小，单位为磅，8 到 1000。默认：该字段类型的默认大小。
`required`	默认为 `true`。
`label`	作为字段名称显示给签署人。

一个请求最多可包含 50 个锚点。

文字如何匹配

完全一致且区分大小写：Signature: 不会匹配 signature: 或 Signature。
锚点中任意一串空格、制表符或换行都能匹配文档中任意一串空格、制表符或换行，因为 PDF 文字不保留可靠的间距。锚点开头和结尾的空格会被忽略。
匹配结果不会重叠。
出现次数按阅读顺序在整个请求中计算：按文档顺序，然后逐页、从上到下、从左到右。"occurrence": 2 是整个请求中的第二个匹配，而不是每页的第二个。
每个锚点最多 200 个匹配。超过这个数量会被视为错误：请写一个更长的锚点。

没有匹配到任何内容的锚点不会生成字段，文档会记录一条 anchor_not_found 提示。与标签一样，锚点生成的字段如果超出页面会被移回页面内；任何签署人如果一个字段都没有，请求就无法发送：此时 GET /api/v1/envelopes/:id 会在 sendError 中报告原因。

您可以在一个请求中同时使用坐标字段、标签（autoTags）和锚点，总共最多 500 个字段。