API クイックスタート

このページでは、空のアカウントから、自分のコードで作った完成ドキュメントまでをたどります。必要なのは、アカウント、テンプレート、キー、そして HTTP リクエスト1つです。すべてのフィールド、応答、エラーはドキュメント API リファレンスで説明しています。

1. アカウント

API はどの AutomaDoc アカウントからでも呼び出せます。Microsoft 365 組織、Google Workspace ドメイン、Lark ワークスペース、メールアカウントのいずれでもかまいません。API だけを使うなら、メールアドレスで登録してください。API 専用アカウントを参照してください。

ステップ2と3は company.automadoc.cc の会社ポータルで行い、アカウントの管理者（Lark ワークスペースでは Lark のアプリ管理者）が必要です。

2. テンプレートとその ID

テンプレートは、データが入る位置にプレースホルダーを置いた Word・Excel・PowerPoint のファイルです。このページでは、次の内容を含む Word の請求書を例にします。

本文に {Invoice_No} と {Customer}。
最初のセルが {#Items}{Product} で始まり、次に {Qty}、最後のセルが {Price}{/Items} で終わる表の行。この行は項目ごとに1回繰り返されます。
表の下に {Total | currency:"USD"}。

構文の全体はテンプレート構文にあります。

会社ポータルでテンプレートを追加するには、次のようにします。

テンプレート を開き、新しい API テンプレート をクリックします。
名前を入力し、API テンプレートを作成 をクリックします。
テンプレートの行の末尾にあるメニューを開き、ファイルをアップロード を選びます。ファイルはアップロード時にチェックされます。問題があればページに表示されるので、修正したファイルをアップロードし直してください。
同じメニューで テンプレート ID をコピー を選びます。

API は API テンプレートに限らず、会社のどのテンプレートにもデータを入れられます。Excel アドイン、Google スプレッドシート、Lark Base 拡張機能で作ったテンプレートも同じように使え、テンプレート の行には同じ テンプレート ID をコピー があります。Lark で会社ポータルにログインしている場合は、Base 拡張機能でテンプレートを作成してください。テンプレート タブにある ドキュメント API カードにも、ID 入りのエンドポイントが表示されます。

3. 会社 API キー

会社ポータルで 会社 → API キー を開き、新しい API キー をクリックします。
キー名 に、キーを使うシステムの名前（例：ERP）を入力し、キーを作成 をクリックします。
キーをコピーします。キーは amk_ で始まり、一度だけ表示されます。

会社キーは、会社のすべてのテンプレートを開けます。パスワードと同じように保管してください。同じページの 無効にする で、すぐに使えなくできます。

Lark Base のテンプレートには、そのテンプレートだけを開ける独自のキーもあり、ドキュメント API カードに表示されます。

4. 最初のリクエストを送る

テンプレートのデータを JSON で POST /api/v1/templates/{templateId}/documents に送り、キーを X-Webhook-API-Key ヘッダーに入れます。

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": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

data はレコードです。各キーが同じ名前のプレースホルダーを埋めます。キーに含まれるスペース、ドット、そのほかの記号は _ になるので、"Invoice No." は {Invoice_No_} を埋めます。大文字と小文字は区別されます。
format は省略できます。"pdf"、"png"（1ページ目を画像として）、"native"（テンプレート自体と同じ種類のファイル）のいずれかです。省略すると、テンプレートの設定に従います。
?wait=20 は、ドキュメントの作成中、応答を最大20秒（上限25秒）待たせます。そのため、多くの場合リクエスト1回で済みます。

filename、recordId、mode も省略できます。ドキュメントを作成するを参照してください。

5. 応答を読んでファイルを受け取る

待機時間内にドキュメントが完成すると、応答は 200 OK です。

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

まだ作成中の場合、応答は "status": "processing" を含む 202 Accepted で、リンクはまだありません。status が completed または failed になるまで、同じキーで数秒ごとに statusUrl を読み取ります（1つのドキュメントにつき1分間に最大60回）。

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

completed：downloadUrl はキーなしでファイルを開けます。会社が生成したドキュメントを保持している間は有効で、ステータスを読み取るたびに新しいリンクが返ります。
failed：error に理由が入ります。たとえば、閉じられていないループなどです。
warnings がある場合は、除外されたものが一覧表示されます。たとえば、URL を取得できなかった画像や、データに値がなかったプレースホルダーです。

リンクではなく、キーを使ってファイルそのものを受け取るには、次のようにします。

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

リクエストが拒否されたとき

拒否にはすべて code と英語の error があります。最初に出会うことが多いものは次のとおりです。

ステータス	`code`	対処
401	`API_KEY_MISSING`	`X-Webhook-API-Key` ヘッダーを追加してください
403	`API_KEY_INVALID`	キーとテンプレート ID を確認してください。ID が間違っている場合もこの応答になります
409	`TEMPLATE_FILE_MISSING`	テンプレートのファイルをアップロードしてください
400	`TEMPLATE_VALIDATION_ERRORS`	テンプレートのファイルを修正してください。`validationErrors` に問題が一覧表示されます
403	`QUOTA_EXCEEDED`	今月のドキュメントが残っていません。パックかシートを購入してください
429	`RATE_LIMITED`	1つのテンプレートで1分間に60リクエスト、または会社で1分間に600ドキュメントを超えました。少し待ってから再試行してください

すべての一覧はエラーにあります。

Node.js で同じことをする

Node.js 18 以降には fetch が組み込まれています。次を quickstart.mjs として保存し、AUTOMADOC_KEY=amk_… node quickstart.mjs で実行します。

import { writeFile } from 'node:fs/promises'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY
const TEMPLATE_ID = 'TEMPLATE_ID'

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

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

次のステップ

ループ。 オブジェクトのリストで {#Items}…{/Items} ループを埋めると、オブジェクトごとに1行または1ブロックになります。ループでは行の絞り込み、並べ替え、件数の制限ができます。ループを参照してください。
画像。 テンプレート内の画像の代替テキストを {Logo} にして、"Logo": "https://…" を送ります。URL は公開された http(s) アドレスである必要があります。テンプレートのそれ以外の場所では、URL はただのテキストです。動的な画像とデータがテンプレートに入る仕組みを参照してください。
PDF、画像、Office ファイル。 "format" で、リクエストごとに出力を選べます。省略すると、テンプレート自体の設定が適用されます。
1回のリクエストで複数のドキュメント。 data を最大50個のオブジェクトのリストとして送ると、項目ごとに1つのドキュメントができます。複数のドキュメントをまとめて作成するを参照してください。
複数のレコードから1つのドキュメント。 一覧、レコードごとに1ページ、ラベルを作るよう設定したテンプレートは、最大500項目のリストを1つのドキュメントにし、1件として数えます。複数のレコードから1つのドキュメントとすべての項目から1つのドキュメントを作るを参照してください。
電子署名。 署名フィールドのある Lark Base のテンプレートでは、sign ブロックを付けると、ドキュメントができたらすぐに署名に送られます。ドキュメントの署名を依頼するを参照してください。
コードを書かずに。 Microsoft 365 では、Power Automate コネクタがフローから同じリクエストを送ります。