抽出を実行

POST /v1/extractions/run

PDFドキュメントに対して抽出を実行します。ドキュメントは指定されたテンプレートを使用して処理され、テンプレートのフィールド定義に一致する構造化JSONとして抽出データが返されます。

試してみる

このエンドポイントを Swagger UI でインタラクティブにテストできます。

認証が必要です

Authorization ヘッダーにAPIキーを含めてください。

リクエスト

ヘッダー

ヘッダー	値	必須
`Authorization`	`Bearer <token>`	はい
`Content-Type`	`application/json`	はい

クエリパラメータ

パラメータ	型	必須	説明
`async`	`string`	いいえ	`"true"` に設定すると、完了を待たずにすぐに `processing` ステータスで応答を返します。デフォルト動作（省略または `"false"`）は同期です。

ボディ

フィールド	型	必須	説明
`templateId`	`string`	はい	使用する抽出テンプレートのID。
`fileName`	`string`	はい	ドキュメントの元のファイル名。
`pdfBase64`	`string`	はい	PDFファイルのBase64エンコードされた内容。
`mimeType`	`string`	はい	ファイルのMIMEタイプ。受け入れ可能な値: `application/pdf`、`application/vnd.openxmlformats-officedocument.wordprocessingml.document`。
`runId`	`string`	いいえ	バッチ実行で関連する抽出をグループ化するためのオプションの識別子。

コード例

curlTypeScriptPython

bash

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

typescript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

const { data } = await response.json()
console.log(data.extractedData)

python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

data = response.json()["data"]
print(data["extractedData"])

レスポンス

ステータス: 200 OK

レスポンスボディは data オブジェクトでラップされています。

フィールド

フィールド	型	説明
`id`	`string`	一意の抽出ID（`extract_` プレフィックス付き）。
`userId`	`string`	この抽出を所有するユーザーのID。
`templateId`	`string`	抽出に使用されたテンプレートのID。
`templateName`	`string`	使用されたテンプレートの表示名。
`fileName`	`string`	アップロードされたドキュメントの元のファイル名。
`status`	`"processing"` \| `"completed"` \| `"failed"`	現在の抽出ステータス。非同期モードの場合は `"processing"`、成功時は `"completed"`、エラー時は `"failed"`。
`extractedData`	`object` \| `null`	テンプレートフィールドに一致する抽出データ。抽出が失敗した場合は `null`。
`error`	`string` \| `null`	失敗を説明するエラーメッセージ。抽出が成功した場合は `null`。
`variables`	`Variable[]`	抽出中に使用されたテンプレート変数定義の配列。
`source`	`"dashboard"` \| `"api"`	抽出がトリガーされた方法。
`runId`	`string` \| `null`	リクエストで指定された場合のバッチ実行ID。
`processingTimeMs`	`number` \| `null`	処理にかかった合計時間（ミリ秒）。
`createdAt`	`string`	抽出が作成されたISO 8601タイムスタンプ。

例

json

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

非同期モード

デフォルトでは、APIは抽出が完了するまで待機してからレスポンスを返します（同期）。長時間実行される抽出の場合、非同期モードを使用して即座にレスポンスを取得し、結果をポーリングできます。

URLに ?async=true を追加して非同期モードを有効にします：

bash

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

レスポンス: 202 Accepted

レスポンスは同期レスポンスと同じ形式ですが、status は "processing"、extractedData は null、processingTimeMs は null になります：

json

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "processing",
    "extractedData": null,
    "error": null,
    "variables": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

返された id を使用して、status が "completed" または "failed" に変わるまで抽出の取得エンドポイントをポーリングします。

WARNING

抽出が2分以上 "processing" ステータスのままの場合は、失敗として扱ってください。自動タイムアウトはありません -- まれなケース（例：サーバーの再起動）では、レコードが "processing" のまま無期限に残る場合があります。

エラー

ステータス	コード	説明
`401`	`UNAUTHORIZED`	APIキー/トークンが欠落、無効、または期限切れです。
`404`	`NOT_FOUND`	指定されたテンプレートが見つからないか、アカウントに属していません。
`429`	`USAGE_LIMIT_EXCEEDED`	プランの月間抽出制限に達しました。
`500`	`INTERNAL_ERROR`	抽出処理中に予期しないエラーが発生しました。

抽出を実行 ​

リクエスト ​

ヘッダー ​

クエリパラメータ ​

ボディ ​

コード例 ​

レスポンス ​

フィールド ​

例 ​

非同期モード ​

エラー ​