スキーマ

このページでは、DocMap APIが返すデータモデルを文書化しています。すべてのレスポンスはJSONを使用します。

ExtractionRecord

抽出レコードは、単一のドキュメント抽出 -- テンプレートに対してPDFを処理した結果を表します。

typescript

interface ExtractionRecord {
  id: string              // 一意の抽出ID
  userId: string          // 所有者のユーザーID
  templateId: string      // 抽出に使用されたテンプレート
  templateName: string    // 人間が読めるテンプレート名
  fileName: string        // アップロードされた元のファイル名
  status: 'processing' | 'completed' | 'failed'
  extractedData: Record<string, unknown> | null  // 構造化データ、失敗した場合はnull
  error: string | null    // 失敗した場合のエラーメッセージ、成功した場合はnull
  variables: Variable[]   // 使用されたテンプレート変数定義
  source: 'dashboard' | 'api'  // 抽出が開始された方法
  runId: string | null    // バッチ実行ID、バッチの一部でない場合はnull
  processingTimeMs: number | null  // 処理時間（ミリ秒）
  createdAt: string       // ISO 8601タイムスタンプ
}

フィールドの説明

フィールド	型	説明
`id`	`string`	抽出レコードの一意の識別子。
`userId`	`string`	この抽出を所有するユーザーのID。
`templateId`	`string`	抽出スキーマの定義に使用されたテンプレートのID。
`templateName`	`string`	抽出時点でのテンプレートの表示名。
`fileName`	`string`	アップロードされたファイルの元の名前（例：`"invoice-march.pdf"`）。
`status`	`string`	抽出の実行中（非同期モード）は `"processing"`、抽出成功時は `"completed"`、失敗時は `"failed"`。
`extractedData`	`object \| null`	ドキュメントから抽出された構造化データで、テンプレートの変数定義に一致します。抽出が失敗した場合は `null`。
`error`	`string \| null`	何が問題だったかの説明。抽出が成功した場合は `null`。
`variables`	`Variable[]`	この抽出に使用されたテンプレート変数定義。Variableを参照。
`source`	`string`	Web UIから抽出が実行された場合は `"dashboard"`、API経由で実行された場合は `"api"`。
`runId`	`string \| null`	抽出がバッチ実行の一部の場合、共有実行ID。個別の抽出の場合は `null`。
`processingTimeMs`	`number \| null`	抽出にかかった時間（ミリ秒）。記録されていない場合は `null`。
`createdAt`	`string`	抽出が作成されたISO 8601タイムスタンプ。

例

json

{
  "id": "ext_kp92mf7x",
  "userId": "u_abc123",
  "templateId": "tpl_inv001",
  "templateName": "Standard Invoice",
  "fileName": "acme-invoice-2024-003.pdf",
  "status": "completed",
  "extractedData": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-003",
    "invoice_date": "2024-11-15",
    "due_date": "2024-12-15",
    "total_amount": 4750.00,
    "currency": "USD",
    "line_items": [
      {
        "description": "Cloud Hosting - Pro Plan",
        "quantity": 1,
        "unit_price": 2500.00
      },
      {
        "description": "SSL Certificate (Wildcard)",
        "quantity": 3,
        "unit_price": 750.00
      }
    ]
  },
  "error": null,
  "variables": [
    { "key": "vendor_name", "type": "string", "context": "Name of the vendor or supplier", "required": true },
    { "key": "invoice_number", "type": "string", "context": "Invoice or reference number" },
    { "key": "invoice_date", "type": "date", "context": "Date the invoice was issued" },
    { "key": "due_date", "type": "date", "context": "Payment due date" },
    { "key": "total_amount", "type": "number", "context": "Total amount due" },
    { "key": "currency", "type": "string", "context": "Currency code (e.g. USD, EUR)" },
    {
      "key": "line_items",
      "type": "array",
      "context": "Individual line items on the invoice",
      "arrayType": "object",
      "fields": [
        { "key": "description", "type": "string", "context": "Item description" },
        { "key": "quantity", "type": "number", "context": "Quantity ordered" },
        { "key": "unit_price", "type": "number", "context": "Price per unit" }
      ]
    }
  ],
  "source": "api",
  "runId": null,
  "processingTimeMs": 3842,
  "createdAt": "2024-11-20T14:30:00.000Z"
}

ApiKeyPublic

APIキーの公開プロジェクション。実際のキー値とそのハッシュは、作成後に返されることはありません。

typescript

interface ApiKeyPublic {
  id: string              // キーID
  userId: string          // 所有者のユーザーID
  name: string            // キーのラベル
  prefix: string          // キーの先頭16文字（例："dm_live_a1b2c3d4"）
  expiresAt: string | null  // ISO 8601の有効期限、無期限の場合はnull
  lastUsedAt: string | null // ISO 8601の最終使用日時、未使用の場合はnull
  createdAt: string       // ISO 8601タイムスタンプ
  revoked: boolean        // キーが無効化されているかどうか
}

フィールドの説明

フィールド	型	説明
`id`	`string`	APIキーの一意の識別子。
`userId`	`string`	このキーを所有するユーザーのID。
`name`	`string`	キーの人間が読めるラベル（例：`"Production Server"`）。
`prefix`	`string`	キーの先頭16文字で、完全な値を公開せずに使用中のキーを識別するのに便利です。
`expiresAt`	`string \| null`	キーの有効期限のISO 8601タイムスタンプ。有効期限なしで作成された場合は `null`。
`lastUsedAt`	`string \| null`	キーが最後にリクエストの認証に使用されたISO 8601タイムスタンプ。未使用の場合は `null`。
`createdAt`	`string`	キーが作成されたISO 8601タイムスタンプ。
`revoked`	`boolean`	キーが無効化されているかどうか。一覧レスポンスでは無効化されたキーはフィルタリングされるため、通常は `false` です。

例

json

{
  "id": "key_m3x9kq72",
  "userId": "u_abc123",
  "name": "Production Server",
  "prefix": "dm_live_a1b2c3d4",
  "expiresAt": "2025-03-15T00:00:00.000Z",
  "lastUsedAt": "2025-01-10T09:22:14.000Z",
  "createdAt": "2024-12-15T10:00:00.000Z",
  "revoked": false
}

WebhookPublic

Webhookの公開プロジェクション。署名シークレットは作成後に返されることはありません。

typescript

interface WebhookPublic {
  id: string              // Webhook ID
  userId: string          // 所有者のユーザーID
  url: string             // 登録されたエンドポイントURL
  events: WebhookEvent[]  // 購読しているイベント
  active: boolean         // Webhookがアクティブかどうか
  createdAt: string       // ISO 8601タイムスタンプ
}

type WebhookEvent = 'extraction.completed' | 'extraction.failed'

フィールドの説明

フィールド	型	説明
`id`	`string`	Webhookの一意の識別子。
`userId`	`string`	このWebhookを所有するユーザーのID。
`url`	`string`	Webhook POSTリクエストを受信するHTTPSエンドポイント。
`events`	`string[]`	このWebhookが購読しているイベント。値: `"extraction.completed"`、`"extraction.failed"`。
`active`	`boolean`	Webhookがアクティブかどうか。一覧レスポンスではアクティブなWebhookのみ返されるため、常に `true` です。
`createdAt`	`string`	Webhookが作成されたISO 8601タイムスタンプ。

例

json

{
  "id": "webhook-abc123def456",
  "userId": "uid_a1b2c3d4e5f6",
  "url": "https://your-app.com/webhooks/docmap",
  "events": ["extraction.completed", "extraction.failed"],
  "active": true,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

Variable

変数は、抽出テンプレート内の単一のフィールドを定義します。変数はAIに対して、どのデータを探すか、どの型で返すかを指示します。

typescript

interface Variable {
  key: string              // 抽出データ内のフィールド名
  type: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array'
  context: string          // AIエクストラクターへの説明/ヒント
  required?: boolean       // フィールドが必須かどうか
  fields?: Variable[]      // ネストされたフィールド（type: 'object' の場合）
  arrayType?: 'string' | 'number' | 'object'  // アイテムの型（type: 'array' の場合）
}

フィールドの説明

フィールド	型	説明
`key`	`string`	抽出データのキーとして表示されるフィールド名。1文字以上である必要があります。
`type`	`string`	期待されるデータ型。`string`、`number`、`date`、`boolean`、`object`、`array` のいずれか。
`context`	`string`	AIがこのフィールドで何を抽出すべきかを理解するための自然言語での説明。より具体的なコンテキストほど良い結果が得られます。
`required`	`boolean`	(オプション) `true` の場合、AIは常にこのフィールドの値を返そうとします。
`fields`	`Variable[]`	(オプション) `type: "object"` の場合、オブジェクト内のネストされたフィールドを定義します。これは再帰的です -- ネストされたオブジェクトは独自の `fields` を含むことができます。
`arrayType`	`string`	(オプション) `type: "array"` の場合、配列内のアイテムの型を指定します。`string`、`number`、`object` のいずれか。`arrayType` が `"object"` の場合、`fields` を使用して各アイテムの形状を定義します。

再帰的構造

変数は fields プロパティによる任意のネストをサポートしています。object 変数は子変数を含み、arrayType: "object" の array 変数も fields を使用して各配列アイテムを記述します。

これにより、明細行付きの請求書、複数の当事者がいる契約書、その他の階層的なデータなど、複雑なドキュメント構造をモデル化できます。

例：ネストされた変数を持つ請求書テンプレート

json

[
  {
    "key": "vendor_name",
    "type": "string",
    "context": "Name of the vendor or supplier company",
    "required": true
  },
  {
    "key": "invoice_number",
    "type": "string",
    "context": "Invoice or reference number"
  },
  {
    "key": "invoice_date",
    "type": "date",
    "context": "Date the invoice was issued (YYYY-MM-DD)"
  },
  {
    "key": "total_amount",
    "type": "number",
    "context": "Total amount due including tax"
  },
  {
    "key": "billing_address",
    "type": "object",
    "context": "The billing address on the invoice",
    "fields": [
      { "key": "street", "type": "string", "context": "Street address" },
      { "key": "city", "type": "string", "context": "City name" },
      { "key": "state", "type": "string", "context": "State or province" },
      { "key": "zip", "type": "string", "context": "Postal or ZIP code" },
      { "key": "country", "type": "string", "context": "Country name or code" }
    ]
  },
  {
    "key": "line_items",
    "type": "array",
    "context": "Individual line items listed on the invoice",
    "arrayType": "object",
    "fields": [
      { "key": "description", "type": "string", "context": "Item description" },
      { "key": "quantity", "type": "number", "context": "Quantity ordered" },
      { "key": "unit_price", "type": "number", "context": "Price per unit" },
      { "key": "total", "type": "number", "context": "Line total (quantity x unit_price)" }
    ]
  },
  {
    "key": "tags",
    "type": "array",
    "context": "Keywords or categories that describe this invoice",
    "arrayType": "string"
  }
]

この例では：

billing_address は5つのネストされた string フィールドを持つ object です。
line_items はオブジェクトの array で、各オブジェクトには description、quantity、unit_price、total があります。
tags はネストされた fields を持たないシンプルな文字列の array です。

UsageResponse

GET /v1/usage エンドポイントによって返されます。認証済みユーザーの現在のプランと請求期間の抽出使用量を表示します。

typescript

interface UsageResponse {
  plan: 'free' | 'starter' | 'core' | 'pro'
  usage: number            // この期間で使用された抽出回数
  limit: number            // 現在のプランの最大回数
  periodKey: string        // 現在の期間（例："2025-01"）
}

フィールドの説明

フィールド	型	説明
`plan`	`string`	ユーザーの現在のプラン。`free`、`starter`、`core`、`pro` のいずれか。
`usage`	`number`	現在の請求期間で消費された抽出回数。
`limit`	`number`	ユーザーのプランで許可される最大抽出回数。
`periodKey`	`string`	現在の請求期間（`YYYY-MM` 形式、例：`"2025-01"`）。

例

json

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2025-01"
  }
}

TIP

使用量エンドポイントは、上記のように data オブジェクトでラップされたデータを返します。

ErrorResponse

すべてのAPIエラーは、マシンリーダブルな code と人間が読める message を含む一貫した構造に従います。

typescript

interface ErrorResponse {
  error: {
    code: string           // マシンリーダブルなエラーコード
    message: string        // 人間が読める説明
  }
}

例

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Extraction not found"
  }
}

エラーコード、HTTPステータスコード、解決手順の完全なリストについては、エラーコードリファレンスをご覧ください。

スキーマ ​

ExtractionRecord ​

フィールドの説明 ​

例 ​

ApiKeyPublic ​

フィールドの説明 ​

例 ​

WebhookPublic ​

フィールドの説明 ​

例 ​

Variable ​

フィールドの説明 ​

再帰的構造 ​

例：ネストされた変数を持つ請求書テンプレート ​

UsageResponse ​

フィールドの説明 ​

例 ​

ErrorResponse ​

例 ​

スキーマ

ExtractionRecord

フィールドの説明

例

ApiKeyPublic

フィールドの説明

例

WebhookPublic

フィールドの説明

例

Variable

フィールドの説明

再帰的構造

例：ネストされた変数を持つ請求書テンプレート

UsageResponse

フィールドの説明

例

ErrorResponse

例