入力欄を自動で配置する

文書が 1 件だけなら、入力欄を手作業で配置しても問題ありません。毎週送る契約書や 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 の 2 つの枠ができます。それぞれの枠を受信者に割り当てると、その役割のすべての入力欄がその人のものになります。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、小数点以下 2 桁まで
`h=50`	高さ（ポイント）。8〜1000
`optional`	署名者は入力欄を空のままにできます
`required`	署名者は入力欄を埋める必要があります（既定）

各部分の前後にはスペースや改行を入れられるので、[[ sign : Client ]] も使えますし、部分と部分の間で 2 行目に折り返したタグも使えます。単語の途中（たとえば Client の途中）で改行するとタグは壊れます。

タグは [[ から ]] までで最大 200 文字です。それより長いものや、閉じる ]] がないものは普通のテキストとして扱われ、無視されます。

入力欄が置かれる位置

入力欄の左上の角は、タグの左上の角に合わせられます。サイズはタグの w と h、指定がなければ入力欄の既定のサイズです（ポイント単位で、署名 160 × 48、イニシャル 64 × 40、チェックボックス 14 × 14、メールアドレス 180 × 20、日付 110 × 20、そのほかのテキスト欄 160 × 20）。h がない場合、入力欄の高さがタグの文字より低くなることはありません。ページからはみ出す入力欄は、ページ内に移動されます。

そのため、各タグの右側と下側には余白を空けておいてください。署名欄はタグの上端から 48 ポイント（約 1.7 cm）下まで届きます。

問題がある場合

書式に従っていない [[…]] について、AutomaDoc が意図を推測することはありません。テキストとしてページに残り、入力欄は作られず、書かれたとおりのタグとともに送信者に警告が表示されます（文書ごとに最初の 50 件）。よくある原因は、役割がない、役割の中にスペースがある、種類やオプションが不明、サイズが 8〜1000 の範囲外、のいずれかです。

そのほかの制限：

読み取るタグは 1 ページあたり 500 個まで、1 文書あたりも 500 個までです。それを超えた分は警告とともに無視されます。
検索されるのは PDF に実際に含まれているテキストだけです。スキャンしたページは画像なので、その中のタグは見つかりません。
どの受信者にも割り当てられていない役割のタグからは、入力欄は作られません。入力欄が 1 つもない署名者がいると、依頼は送信できません。

タグをもう一度適用すると、タグから作られた入力欄が置き換えられます。手作業で配置した入力欄はそのまま残ります。

API からのアンカー

アンカーは、「Client signature:」のように文書にすでにあるテキストを基準に入力欄を置きます。編集できない文書のための機能です。アンカーは POST /api/v1/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`	入力欄の名前として署名者に表示されます。

1 件の依頼には最大 50 個のアンカーを指定できます。

テキストの照合方法

完全一致で、大文字と小文字を区別します。Signature: は signature: にも Signature にも一致しません。
アンカー内のスペース、タブ、改行の連続は、文書内のそれらのどんな連続とも一致します。PDF のテキストでは空白が正確に保たれないためです。アンカーの先頭と末尾のスペースは無視されます。
一致した範囲が重なることはありません。
一致の順番は、依頼全体を読む順に数えます。文書の順に、ページごとに、上から下、左から右へ進みます。"occurrence": 2 は、各ページの 2 番目ではなく、依頼全体での 2 番目の一致です。
1 つのアンカーの一致は最大 200 件です。それを超えると間違いとみなされます。もっと長いアンカーを書いてください。

何にも一致しないアンカーからは入力欄は作られず、文書に anchor_not_found の警告が記録されます。タグと同じく、ページからはみ出すアンカーの入力欄はページ内に移動されます。また、入力欄が 1 つもない署名者がいると依頼は送信されず、その理由は GET /api/v1/envelopes/:id の sendError で確認できます。

1 件の依頼で、座標による入力欄、タグ（autoTags）、アンカーを組み合わせられます。入力欄は全部で最大 500 個です。