ドキュメント API

ドキュメント API は、ERP、Web フォーム、スクリプトなどから JSON で送ったデータをテンプレートに差し込みます。元になるレコードは必要ありません。完成したドキュメントへのリンクが返され、形式はテンプレートの出力形式か、リクエストで指定した形式になります。

どの種類のテンプレートでも使えます。テンプレート本来のデータソースは使われず、送信した JSON がそのままレコードになります。

ドキュメント API は Free を含むすべてのプランで使えます。API で作られたドキュメントは自動生成ドキュメントです。まず Business シートの枠から、次に月間の無料枠から、その次にドキュメントパックから差し引かれ、すべて使い切ると API は QUOTA_EXCEEDED を返します。Free プランでは、購入したパックがない限りドキュメントに「Generated with AutomaDoc」のフッター行が入り、テンプレートの Webhookコールバックは Pro（またはトライアル）か Business シート がある場合にのみ送信されます。HTTPトリガーは別です。データの1件のレコード（Lark Base のレコード、Excel や Google スプレッドシートの行、SharePoint のアイテム、Dataverse の行）からドキュメントを作るもので、Pro、トライアル、または Business シートが必要です。

認証

API キーを X-Webhook-API-Key ヘッダーで送信します。使えるキーは2種類です。

テンプレート自身のキー：テンプレート タブの ドキュメント API にあります（HTTPトリガーと同じキーです）。そのテンプレート1つだけに使えます。
会社の API キー：管理者（Lark の会社では Lark のアプリ管理者）が会社ポータルの 会社 → API キー で作成します。会社のすべてのテンプレートに使えます。キーは作成時に一度だけ表示されるので、パスワードと同じように保管してください。承認テンプレートには専用のキーがないため、会社のキーを使います。

会社のキーを無効にしたり、テンプレートのキーをリセットしたりすると、そのキーはすぐに使えなくなります。

ドキュメントを作成する

POST https://api.automadoc.cc/api/v1/templates/{templateId}/documents

テンプレート ID は、テンプレートの ドキュメント API カードに表示されるエンドポイントに含まれています。

フィールド	必須	内容
`data`	はい	レコード。キーがプレースホルダーになります。オブジェクトのリストを送ると、項目ごとに1つのドキュメントが作られます。複数のレコードから1つのドキュメントを作るテンプレートでは、すべての項目から1つのドキュメントが作られます（複数のドキュメントをまとめて作成するを参照）。
`format`	いいえ	`"pdf"`、`"png"`（1ページ目を画像として）、または `"native"`（テンプレート本来のファイル形式。例: `.docx`）。既定はテンプレートの設定です。
`filename`	いいえ	このリクエストで使うファイル名パターン。`{Field}` プレースホルダーを使えます。テンプレートのパターンの代わりに使われます。
`recordId`	いいえ	ドキュメントが1つの場合に `{Record_ID}` が出力する値。既定はドキュメントの ID です。
`mode`	いいえ	`"separate"`、`"list"`、`"continuous"`、`"labels"` のいずれか。テンプレートが作るものを確認のために指定します。省略するとテンプレートの設定に従います（複数のドキュメントをまとめて作成するを参照）。

?wait=20（最大 25 秒）を付けると、ドキュメントの準備ができるまでレスポンスを待つため、1回のリクエストで済みます。付けない場合はすぐにレスポンスが返るので、ステータス URL をポーリングします。

202 + Location のポーリング規約に従うワークフローツール（Power Automate、Logic Apps など）は、代わりに ?async=true を付けられます。ドキュメントの作成中は、202 レスポンスにポーリング先の Location ヘッダーと Retry-After ヘッダー（5 秒）が付きます。その URL は、ドキュメントが完成する（200）か失敗する（422。"code": "DOCUMENT_FAILED" と、error に理由）まで 202 を返します。リクエストに応答する時点ですでに失敗しているドキュメントには、すぐにその 422 が返ります。ステータスのエンドポイントも ?async=true を受け付けます。async は1つのドキュメントを追うため、項目ごとに1つのドキュメントを作るテンプレートで data にリストを送る場合には使えません（INVALID_ASYNC）。Power Automate コネクタはこれを使っています。

レスポンス：ドキュメントの作成中は 202 Accepted、wait の間に完成した場合は 200 OK が返ります。

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "processing",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000
}

ドキュメントを取得する

GET https://api.automadoc.cc/api/v1/documents/{generationId}

リクエストに使ったものと同じキーを使います。status は processing、completed、failed のいずれかです。

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "status": "completed",
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

downloadUrl にキーは不要です。会社が生成済みドキュメントを保持する期間（プランによって決まります）、または無期限に保持する設定の場合は30日間有効で、ドキュメントが削除されると使えなくなります。ステータスを取得するたびに新しいリンクが返されます。failed のドキュメントには、理由を示す error が含まれます。完成したドキュメントには warnings が含まれることがあります。URL から取得できなかった画像など、ドキュメントに入らなかったものを、フィールド名と URL のホストで示します。データに値がなかったプレースホルダーは、ほかの警告の後に 1 行にまとめて示されます（「3 fields had no value in the data: …」）。

このエンドポイントでは、HTTPトリガーで開始されたドキュメントも確認できます。HTTPトリガーのレスポンスに、それらの generationIds が含まれています。

キーで確認できるのは、そのキーが使えるテンプレートのドキュメントだけです。拡張機能で手動生成したドキュメントは、API からは見えません。

キーを使ってファイルをダウンロードする

GET https://api.automadoc.cc/api/v1/documents/{generationId}/file

完成したファイルそのものを、同じキーで取得します。リンクではなくファイルを受け取るツール向けです。ドキュメントの作成中は 409 と DOCUMENT_NOT_READY、失敗した場合は 422 と DOCUMENT_FAILED（error に理由）、会社の保存期間によってファイルが削除された後は 404 と DOCUMENT_FILE_MISSING を返します。Content-Type と Content-Disposition（ファイル名）がファイルの内容を示します。

テンプレートとそのデータを一覧する

GET https://api.automadoc.cc/api/v1/templates
GET https://api.automadoc.cc/api/v1/templates/{templateId}

1つ目は会社のすべてのテンプレートを一覧します。id、name、source（base または approval）、templateFormat、mode（リクエストで何が作られるか。複数のドキュメントをまとめて作成するを参照）、outputFormat、ready（テンプレートにファイルがない間や、修正すべきエラーがある間は false）です。会社の API キーが必要で、テンプレート自身のキーは COMPANY_KEY_REQUIRED で拒否されます。

2つ目は1つのテンプレートを説明します（どちらのキーでも使えます）。dataSchema（受け取る data の JSON スキーマ。プレースホルダーごとに1つのプロパティで、テキスト、数値または画像の URL、条件にははい/いいえ、ループにはリスト）、sampleData、documentsUrl が加わります。ワークフローツールはこれを使って、プレースホルダーごとに入力欄を1つ表示します。

これらのルートの完全な説明は、OpenAPI ドキュメントとして https://api.automadoc.cc/api/v1/openapi.json にあります。

データがテンプレートに入る仕組み

名前。 各キーは、Base のフィールド名とまったく同じ方法でプレースホルダー名に変換されます。スペース、ドット、その他の記号は _ になり、どの言語の文字と数字もそのまま残ります。大文字と小文字は区別されます。

送信するキー	入力されるプレースホルダー
`"Customer"`	`{Customer}`
`"Invoice No."`	`{Invoice_No_}`
`"Unit price"`	`{Unit_price}`
`"客户名称"`	`{客户名称}`

同じオブジェクト内の2つのキーが同じ名前になる場合（"Unit price" と "Unit-price" など）は、どちらかが黙って優先されることはなく、DATA_NAME_COLLISION で拒否されます。

値。

テキストと数値 は送信したとおりに出力されます。数値は数値のまま扱われるため、number、currency、sum などのフィルターが使えます。
true / false は条件に使えます: {#if Paid}…{/if}。
null と 空のリスト は何も出力せず、{#if} では空として扱われます。
オブジェクト はドット記法のプレースホルダーに入ります: {"Customer": {"Name": "Acme"}} は {Customer.Name} に入ります。
オブジェクトのリスト はループになります: {"Items": [{"Product": "Pen", "Qty": 2}]} は {#Items}{Product} × {Qty}{/Items} に入ります。
単純な値のリスト はカンマ区切りで出力されます: ["red", "blue"] は red, blue と出力されます。
画像: テンプレートに画像プレースホルダー（代替テキストが {Logo} の画像。ループの行の中でも可）がある箇所には、https:// の URL を送ります。{Photos[1]}、{Photos[2]} には URL のリストを送ります。URL はインターネットからアクセスできる必要があります。それ以外の場所では、URL は単なるテキストです。
添付ファイル: {ATTACH:Field} が追加するのは Base の添付ファイルフィールドまたは承認フォームのファイルだけです。ドキュメント API からはファイルを送れません。何も追加されず、送信した URL はテキストとして出力されます。
{QR:Field} と {BARCODE:Field} は、送信したテキストのコードを出力します。

Record_ID、Template_Name、Print_Time は AutomaDoc が設定します。同じ名前のキーを送ると置き換えられます（レスポンスで警告されます）。

承認テンプレートでは、そのページに一覧表示される変数が、送信する名前になります。承認テンプレートの既定のファイル名は承認申請を名前に使いますが、JSON には申請がないため、API で作られたドキュメントは filename を送らない限り {Template_Name}-{Record_ID} という名前になります。

複数のドキュメントをまとめて作成する

data を最大50個のオブジェクトのリストとして送ると、項目ごとに1つのドキュメントが作られます。レスポンスにはそれらが一覧で返されます。

{ "documents": [ { "generationId": "…", "status": "processing", "statusUrl": "…" }, … ] }

いずれかの項目が拒否された場合は、何も作成されません。リストを送る場合、recordId は使えません。

すべての項目から1つのドキュメントを作る

テンプレートが複数のレコードから1つのドキュメントを作る設定（一覧、レコードごとに1ページ、ラベル）の場合、data のリストからは1つのドキュメントが作られます。各項目は送った順に、{#Records} ループの1レコード、1ページ、または1枚のラベルになります。項目は最大500個です。単一のオブジェクトを送ると、1項目のドキュメントになります。レスポンスはその1つのドキュメントで、recordCount が付きます。

{ "generationId": "…", "status": "processing", "statusUrl": "…", "recordCount": 120 }

{Record_ID} は各項目の位置（1 から項目数まで）を出力します。
ファイル名のパターンは最初の項目と、{RecordCount}、{Date} を参照します。パターンがない場合、ドキュメント名は {Template_Name}-{Date} になります。
"format": "png" を指定しても PDF が作られます。画像では最初のページしか入らないためです。
1つのドキュメントとして数えられます。会社ごとの1分あたり600ドキュメントの制限では、レコードごとに1ページの場合は1項目ごとに1つ、一覧またはラベルの場合は10項目ごとに1つとして数えられます。
署名を依頼することはできません（ESIGN_COMBINED）。

どちらになるかは、テンプレートの1つの文書に含めるレコードの設定で決まります。mode（項目ごとに1つのドキュメントなら "separate"、または "list"、"continuous"（レコードごとに1ページ）、"labels"）を送ると、設定が異なるテンプレートではリクエストが MODE_MISMATCH で拒否されます。スクリプトが想定と異なる数のファイルを受け取ることはありません。

例: curl

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice No.": "INV-2026-001",
      "Customer": { "Name": "Acme Corp", "Address": "1 Main St" },
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Logo": "https://example.com/logo.png"
    },
    "format": "pdf"
  }'

テンプレートの ドキュメント API カードでは、このようなリクエストをテンプレート自身のプレースホルダーから作成してコピーできます。

例: Node.js

const API = 'https://api.automadoc.cc'
const headers = { 'X-Webhook-API-Key': process.env.AUTOMADOC_KEY, 'Content-Type': 'application/json' }

async function generate(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Still processing after the wait: poll the status URL.
  while (doc.status === 'processing') {
    await new Promise((r) => setTimeout(r, 2000))
    doc = await (await fetch(doc.statusUrl, { headers })).json()
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc.downloadUrl
}

ドキュメントの署名を依頼する

sign ブロックを追加すると、ドキュメントが生成されるとすぐに署名を依頼できます。ドキュメントの生成分以外に費用はかかりません。

sign が使えるのは Lark Base テンプレート です。署名欄のある Word テンプレート（電子署名を参照）で、レコードごとに1つのドキュメントを作り、data を1つのオブジェクトとして送るものに限ります。それ以外のテンプレートはすべて SIGN_BASE_TEMPLATES_ONLY で拒否します。Excel、SharePoint リスト、Dataverse、Google スプレッドシート、API 専用のテンプレート、そして承認の中で署名する Lark 承認テンプレートがこれにあたります。Lark Base テンプレートがあるのは Lark アカウントだけなので、Microsoft、Google、メールのアカウントでは sign を受け付けるテンプレートはありません。

{
  "data": { "Customer": "Acme Corp" },
  "sign": {
    "signers": {
      "Customer": { "name": "Budi Santoso", "contact": "budi@acme.example" },
      "Supplier": { "larkUserId": "ou_1234…" }
    },
    "order": "sequential"
  }
}

フィールド	内容
`signers`	テンプレートの署名の役割ごとに1人の署名者を、役割名で指定します。署名者を読み取るレコードがないため、すべての役割に署名者が必要です。社外の人は `{ "name", "contact"? }` です。名前と、任意で依頼とともに保存される連絡先のメモ（メールアドレスなど）を指定します。この連絡先には何も送信されません。同僚は `{ "larkUserId" }` です。AutomaDoc を使っている、自社の Lark の人の Lark open_id を指定します。
`order`	`"parallel"`（全員が同時に署名）または `"sequential"`（テンプレートの順番どおりに署名）。既定はテンプレートの設定です。
`generatePasswords`	社外の署名者ごとにパスワードを自動生成します。既定は `true` です。
`locale`	ボットメッセージと監査ページの言語。例: `"en"`。

署名依頼は、ドキュメントの準備ができた時点で開始されます。同僚には Lark で AutomaDoc ボットからメッセージが届きます。社外の署名者のリンクと自動生成のパスワードは、依頼の開始後に最初に行った GET /api/v1/documents/{generationId} のレスポンスで一度だけ返されます。

{
  "status": "completed",
  "signing": {
    "status": "started",
    "requestId": "…",
    "links": [{ "role": "Customer", "displayName": "Budi Santoso", "url": "https://…/sign/…", "password": "K7mQ…" }]
  }
}

リンクはご自身で署名者に送ってください。できればパスワードは別の手段で送ります。2回目以降の取得でも同じ項目が返されますが、url と password は null になり、"linksRedacted": true が付きます。リンクを紛失した場合は、電子署名ページから新しいリンクを発行してください。signing.status はドキュメントが完成するまで queued、依頼を開始する間は一時的に starting で、その後 started または failed（error コード付き）になります。

data がリストの場合（SIGN_SINGLE_DOCUMENT）と、複数のレコードから1つのドキュメントを作るテンプレートの場合（ESIGN_COMBINED）、sign は拒否されます。

ドキュメントの準備ができたら

テンプレートに Webhookコールバックが設定されている場合は、API で作られたドキュメントでも、ダウンロードリンク付きで呼び出されます。ほかの自動生成ドキュメントと同じく、Pro（またはトライアル）か Business シートが必要です。

エラー

拒否された場合は、必ず code と英語の error が返されます。

ステータス	`code`	理由
400	`INVALID_JSON`, `DATA_REQUIRED`, `DATA_NOT_OBJECT`	ボディが JSON ではない、`data` がない、または `data` がオブジェクトでもオブジェクトのリストでもない
400	`DATA_NAME_COLLISION`, `DATA_INVALID_NAME`	2つのキーが同じプレースホルダーに入る。キーに文字も数字も含まれていない
400	`DATA_MIXED_ARRAY`	リストにオブジェクトと単純な値が混在している
400	`DATA_TOO_DEEP`, `DATA_ARRAY_TOO_LONG`, `DATA_TOO_MANY_KEYS`, `DATA_STRING_TOO_LONG`	制限を超えている
400	`IMAGE_URL_NOT_ALLOWED`, `TOO_MANY_IMAGES`	画像の URL が公開された `http(s)` アドレスではない。画像が多すぎる
400	`BATCH_EMPTY`, `BATCH_TOO_LARGE`	リストが空。項目が50個（複数のレコードから1つのドキュメントを作るテンプレートでは500個）を超えている
400	`INVALID_FORMAT`, `INVALID_FILENAME`, `INVALID_RECORD_ID`, `INVALID_WAIT`, `INVALID_MODE`, `INVALID_ASYNC`	オプションが無効
400	`TEMPLATE_VALIDATION_ERRORS`	テンプレートファイルに先に修正すべきエラーがある（`validationErrors` に一覧表示）
400	`MODE_MISMATCH`	`mode` がテンプレートの作るものと一致しない
401	`API_KEY_MISSING`	`X-Webhook-API-Key` ヘッダーがない
403	`API_KEY_INVALID`	キーが間違っている、無効にされている、またはこのテンプレートに使えない（存在しないテンプレート ID もこの応答になります）
403	`QUOTA_EXCEEDED`	今月のドキュメントが残っていない。パックまたはシートを購入してください
403	`TEMPLATE_DISABLED`	テンプレートがプランのテンプレート上限を超えている
403	`COMPANY_KEY_REQUIRED`	テンプレートの一覧には、テンプレート自身のキーではなく会社の API キーが必要
404	`TEMPLATE_NOT_FOUND`, `DOCUMENT_NOT_FOUND`	このキーで使えるテンプレートまたはドキュメントが存在しない
404	`DOCUMENT_FILE_MISSING`	会社の保存期間によって、ドキュメントのファイルが削除されている
409	`TEMPLATE_FILE_MISSING`, `TEMPLATE_NO_OWNER`	テンプレートにまだファイルがない。テンプレートに所有者がいない（一度開いて保存するか、会社のキーを使ってください）
409	`DOCUMENT_NOT_READY`	作成中のドキュメントのファイルをダウンロードしようとした
413	`BODY_TOO_LARGE`	ボディが 1 MB を超えている
422	`DOCUMENT_FAILED`	失敗したドキュメントのファイルをダウンロードしようとした、または失敗したドキュメントに `async=true` でリクエストやステータス取得をした。理由は `error` に入ります
429	`RATE_LIMITED`	1 つのテンプレートに 1 分間 60 回を超えるリクエスト、1 社で 1 分間 600 件を超えるドキュメント、1 つのドキュメントに 1 分間 60 回を超えるステータス取得またはダウンロード、または 1 社で 1 分間 60 回を超えるテンプレート一覧の取得。HTTPトリガーのドキュメントは会社の 600 件に数えられます。リクエストにはテンプレートごとに 1 分間 300 回という独自の上限があります
400	`SIGN_INVALID`, `SIGN_SINGLE_DOCUMENT`, `SIGN_BASE_TEMPLATES_ONLY`	`sign` ブロックが無効、`data` がリスト、またはテンプレートが Lark Base テンプレートではないため、そのドキュメントを署名に送れない
400, 409	`ESIGN_…`	電子署名で拒否された: `ESIGN_ROLES_MISMATCH`（署名者のいない役割、または存在しない役割がある）、`ESIGN_SIGNER_FIELD`（署名者をフィールドから読み取る設定になっている）、`ESIGN_INVALID_SIGNER`（`larkUserId` が自社のユーザーではない）、`ESIGN_NO_MASTER`（テンプレートに署名欄がない）、`ESIGN_COMBINED`（テンプレートが複数のレコードから1つのドキュメントを作る）、`ESIGN_RECORD_UNREADABLE`（依頼の送信者となるテンプレートの所有者がいない）
502	`WORKER_UNAVAILABLE`	ドキュメントサービスに接続できなかった。しばらくしてから再試行してください
503	`TEMPLATE_FORMAT_UNAVAILABLE`	テンプレートが、ドキュメントサービスでまだ開けない Excel または PowerPoint ファイルです。後でもう一度お試しください
503	`COMBINED_UNAVAILABLE`	現在、複数のレコードから1つのドキュメントを作れません。後でもう一度お試しください
503	`ATTACHMENTS_UNAVAILABLE`	テンプレートが複数のレコードから1つのドキュメントを作り、PDF に添付ファイルを追加しますが、現在は実行できません。後でもう一度お試しください

制限


リクエストボディ	1 MB
1リクエストあたりのドキュメント数	50（複数のレコードから作る1つのドキュメントでは500項目）
オブジェクトとリストの入れ子	8階層
リストの項目数	1,000
オブジェクトのキー数	500
値の文字数	100,000
1ドキュメントあたりの画像数	50（複数のレコードから作る1つのドキュメントでは、全項目の合計で500）
`wait`	25秒
1テンプレートあたりのリクエスト数	1分間に60回（HTTPトリガーは独自に1分間に300回）
1ドキュメントあたりのステータス取得	1分間に60回（ファイルのダウンロードは別に60回）
テンプレート一覧	会社ごとに1分間に60回（1つのテンプレートの説明は1分間に60回）
会社あたりのドキュメント数	1分間に600件（ドキュメント API と HTTPトリガーの合計）