ドキュメント

ドキュメントは、処理済みの1ページです。アップロードされた画像、またはアップロードされたPDFからレンダリングされた1ページです。各ドキュメントはバッチ（batch_nameで識別）に属し、実際に処理を開始する単位となります。マルチページPDFをアップロードすると、同じバッチ内にページごとに1つのドキュメントが作成されます。詳細は以下のドキュメントをアップロードを参照してください。

ドキュメントをアップロード

単一ファイル（画像、PDF、Word、またはプレーンテキスト）をバッチにアップロードします。batch_nameを省略すると、自動生成されレスポンスで返されます。アップロードだけでは抽出は開始されません。一緒に処理したいすべてのファイルをアップロードしたら、バッチの処理を開始を呼び出してください。レスポンスのremaining_batch_capacityは、プランの最大バッチサイズ（アカウントのmax_batch_sizeを参照）に達するまで、このバッチにあと何件のドキュメントを受け入れられるかを示します。これは、別途ルックアップを行うことなく、クライアント側でこのバッチに追加を続けるか新しいバッチを開始するかを判断するのに役立ちます。

POST /api/v1/documents

パラメータ

名前	場所	型	説明
`file`	body (multipart)	file	`url`が指定されない場合に必須。画像（JPEG/PNG等）、PDF、Word文書（`.docx`のみ — レガシーな`.doc`バイナリ形式は非対応、事前に`.docx`として保存してください）、またはプレーンテキストファイル（`.txt`）。PDFは1アップロードあたり最大50ページに制限され、1ページごとに1つのドキュメントとして分割されます。`.docx`/`.txt`はサーバー側でまずPDFに変換され、その後同じページ単位の分割が適用されます。
`url`	body (multipart)	string, optional	`file`の代替 — ファイルを添付する代わりに、サーバーがこのURLからファイルをダウンロードします。`file`とは排他的で、どちらか一方のみを指定してください。公開された`http://`または`https://`のURLである必要があります（localhost/プライベートネットワークアドレスは不可）。ダウンロードは30MB、読み取りタイムアウトは15秒に制限されています。
`batch_name`	body (multipart)	string, optional	このドキュメントを追加するバッチ。省略すると新しいバッチ名が自動生成され（レスポンスで返されます）、複数のアップロードで同じ値を再利用して、処理前に1つのバッチを構築できます。
`template_id`	body (multipart)	integer, optional	アカウントが所有するテンプレートIDで、このドキュメントに事前に関連付けます。必須ではありません — `process`を呼び出す際にテンプレート（またはアドホックなフィールド）を渡すこともできます。
`password`	body (multipart)	string, optional	PDFのみ。ファイルがパスワード保護されている場合に最初に試行されます。省略された場合、またはファイルのロックが解除できない場合、アカウントのEmail Inbox設定に保存されている既存のパスワードにフォールバックします。このフィールドはEmail Inboxの設定を必要とせず、呼び出しごとの代替手段として機能します。
`Idempotency-Key`	header, optional	string	再試行しても安全です。冪等性を参照してください。

PDF（および変換されたWord/テキスト）のアップロードは、単一のIDではなく配列を返します。 PDFをアップロードすると、各ページが個別のドキュメントとしてレンダリングされ、レスポンスのdocument_idはJSON配列（ページ順に各ページの文字列）になり、さらにpage_countフィールドが追加されます。.docx/.txtのアップロードで複数ページに変換される場合も、変換後にPDFバイトが生成され、まったく同じコードパスで分割されるため、同様の動作になります。単一画像のアップロードはスカラー文字列を返します。document_idが常に文字列であると想定するクライアントコードは、複数ページのアップロードで動作しなくなります — 送信するファイルが複数ページを生成する可能性があるかどうかを確認し、レスポンスの形状に応じて分岐するか、常に画像を送信してスカラーのケースに依存しないようにしてください。右側の2つのレスポンス例を参照してください。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
missing_parameter — fileとurlのどちらも送信されていません。
invalid_parameter (param: "file") — 無効または破損した画像/PDF、パスワード保護されていてロック解除できなかったPDF（passwordフィールドも保存済みのEmail Inboxパスワードも使用不可）、50ページ制限を超えたPDF、変換に失敗した.docx/.txtファイル（非対応のレガシー.docファイルを含む。まず.docxとして保存してください）。
invalid_parameter (param: "url") — fileとurlの両方が送信された、URLが公開アドレスに解決しない、ダウンロードが失敗またはタイムアウトした、ダウンロードしたファイルが30MBを超えている。
invalid_parameter (param: "batch_name") — バッチがすでにプランの最大バッチサイズに達しています。
invalid_parameter (param: "template_id") または template_not_found。
rate_limit_exceeded — アカウントに未処理（キュー済み）のドキュメントが多すぎます。先に処理するか削除してください。

ドキュメントの取得

単一ドキュメントの現在のステータスと、抽出成功後の再整形されたline_itemsを取得します。これはバッチ結果の取得の単一ドキュメント版です。同じ整形ルールが適用されますが、?include=bboxオプションはありません（これはバッチレベルの結果エンドポイントのみで使用可能です）。

GET /api/v1/documents/{document_id}

パラメータ

名前	場所	型	説明
`document_id`	path	string	`POST /documents`で返されたドキュメントID（PDFページの場合はその配列の1エントリ）。

statusは常にqueued、processing、succeeded、failed、canceledのいずれかです。ステートマシンについては非同期モデルガイドを参照してください。completed_atはドキュメントが終端状態（succeeded、failed、canceled）に達したときに設定され、それ以前はnullのままです。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがアカウントに存在しません。

ドキュメント画像の取得

ドキュメントのページ画像を返します。デフォルトでは全ページ、?crop=を使用すると正規化された切り抜き、?size=thumbを使用するとリスト/グリッド表示を高速化するための小さな事前生成サムネイルを返します。?crop=は、位置情報のみのフィールドのimage_urlを提供します（バッチ結果の取得を参照）。また、独自の座標を指定して直接呼び出すこともできます。

GET /api/v1/documents/{document_id}/image

パラメータ

名前	場所	型	説明
`document_id`	path	string	ドキュメントID。
`crop`	query, optional	string	`"x1,y1,x2,y2"` — API内の他のすべての`bbox`オブジェクトと同じ正規化座標規則に従う、0から1の間の4つの浮動小数点数。省略すると、切り抜きなしの全ページ画像を取得します。
`size`	query, optional	string	`thumb`を指定すると、フル解像度のページではなく、小さな事前生成バージョンを取得します。`crop`も指定されている場合は無視されます。このドキュメントにサムネイルが生成されていない場合（小さな画像はサムネイル化する価値がない場合があります）、フル画像にフォールバックします。エラーにはなりません。

レスポンスは生の画像バイト（Content-Type: image/jpeg）であり、JSONではありません。このエンドポイントの右側にはレスポンスJSONの例はなく、リクエストのみが表示されます。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがないか、元の画像ファイルが利用できなくなりました（例：アカウントの自動削除保持期間を過ぎた場合）。
invalid_parameter (param: "crop") — crop値の形式が不正、座標が0～1の範囲外、または画像境界にクランプした後にトリミング領域が空になっています。

bboxアノテーションをトリガー

抽出された各フィールドの値がページ上のどこに物理的に位置するかを特定する、オプションの有料セカンドパスジョブを明示的に開始します。これは抽出自体とは別の課金対象アクションです。これを組み込む前に、バウンディングボックスガイド、特にアカウントのauto_annotate_bbox設定により、このエンドポイントを呼び出さなくても同じジョブが自動的にトリガー（および課金）される可能性がある点を参照してください。

POST /api/v1/documents/{document_id}/bbox

パラメータ

名前	場所	型	説明
`document_id`	path	string	抽出データが存在する`succeeded`状態のドキュメントである必要があります。抽出が完了していないドキュメントにはアノテーションを付与できません。
`Idempotency-Key`	header, optional	string	推奨 — このアクションはクレジットを消費します。冪等キーを参照してください。

新しいbboxジョブがキューに入れられた場合は202を、このドキュメントに対するbboxジョブがすでに実行中の場合（already_running: true）は200を返します。つまり、この同じエンドポイントを以前にこのドキュメントに対して一度呼び出しており、その以前のbboxジョブがまだ完了していないことを意味します。これはドキュメント自体の抽出が完了しているかどうかとは無関係です。bboxはすでにsucceeded状態のドキュメントに対してのみトリガーできるため（以下の「発生しうるエラー」を参照）、このエンドポイントを呼び出せる時点で抽出は完了しています。already_runningは、抽出ジョブではなく、同じドキュメントに対する2回目のbboxジョブに関するものです。いずれの場合も（202または200）、200のパスでは新しい処理は開始されず、課金もされません。結果を取得するには、返されたgroup_batch_idを使用してbboxアノテーションを取得をポーリングしてください。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがアカウントに存在しません。
insufficient_credits — このアノテーションパスを実行するためのクレジットが不足しています。
invalid_parameter — ドキュメントがまだこの処理を実行できる状態ではありません（処理中であるか、ボックスを配置するための抽出データがありません）。

bboxアノテーションの取得

ドキュメントに対してトリガーされた最新のbboxアノテーションジョブのステータスをポーリングし、結果を取得します。このドキュメントに対してジョブが一度もトリガーされていない場合、existsはfalse、status/group_batch_idはnullになります。これは正常で一般的なレスポンスであり（ほとんどのドキュメントではbboxはトリガーされません）、エラーではありません。

GET /api/v1/documents/{document_id}/bbox

パラメータ

名前	場所	型	説明
`document_id`	path	string	ドキュメントID。

rowsは、行インデックス（文字列、例："0"）を、フィールド名から正規化されたbboxオブジェクト（または、そのフィールドの位置がページ上で見つからなかった場合はnull）へのマップにマッピングします。statusは、APIの他の場所と同じクローズドな5値の列挙型を使用します。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがアカウントに存在しません。