ドキュメント
ドキュメントは、処理済みの1ページです。アップロードされた画像、またはアップロードされたPDFからレンダリングされた1ページです。各ドキュメントはバッチ（batch_nameで識別）に属し、実際に処理を開始する単位となります。マルチページPDFをアップロードすると、同じバッチ内にページごとに1つのドキュメントが作成されます。詳細は以下のドキュメントをアップロードを参照してください。
ドキュメントをアップロード
単一ファイル（画像、PDF、Word、またはプレーンテキスト）をバッチにアップロードします。batch_nameを省略すると、自動生成されレスポンスで返されます。アップロードだけでは抽出は開始されません。一緒に処理したいすべてのファイルをアップロードしたら、バッチの処理を開始を呼び出してください。レスポンスのremaining_batch_capacityは、プランの最大バッチサイズ（アカウントのmax_batch_sizeを参照）に達するまで、このバッチにあと何件のドキュメントを受け入れられるかを示します。これは、別途ルックアップを行うことなく、クライアント側でこのバッチに追加を続けるか新しいバッチを開始するかを判断するのに役立ちます。
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
file | body (multipart) | file | url が指定されない限り必須。画像（JPEG/PNGなど）、PDF、Wordドキュメント（.docx のみ — レガシーな .doc バイナリ形式は非対応のため、先に .docx として保存してください）、またはプレーンテキストファイル（.txt）。PDFはアップロード1回につき最大50ページで、ページごとに1ドキュメントに分割されます。.docx/.txt はサーバー側で先にPDFに変換され、その後同じページ単位の分割に従います。 |
url | body (multipart) | string, optional | file の代替 — ファイルを添付する代わりに、サーバーがこのURLからファイルをダウンロードします。file とは排他的で、どちらか一方のみを渡してください。公開された http:// または https:// URLである必要があります（localhost/プライベートネットワークアドレスは不可）。ダウンロードは30MB、読み取りタイムアウトは15秒に制限されています。 |
batch_name | body (multipart) | string, optional | このドキュメントを追加するバッチ名。最大50文字。省略すると新しいバッチ名が自動生成されます（レスポンスで返されます）。複数のアップロードで同じ値を再利用すると、処理前に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配列（ページ順に各ページ1つの文字列）になり、さらに 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") — バッチがすでにプランの最大バッチサイズに達しているか、名前が50文字を超えています。invalid_parameter(param: "template_id") またはtemplate_not_found。rate_limit_exceeded— アカウントに未処理（queued）のドキュメントが多すぎます。先に処理または削除してください。
ドキュメントを取得する
単一ドキュメントの現在のステータスと、抽出が成功した場合の再整形された line_items を取得します。これは バッチ結果の取得の単一ドキュメント版です — 再整形ルールは同じですが、 ?include=bbox オプションはありません（これはバッチレベルの結果エンドポイントのみで利用可能です）。
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
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を提供します（バッチ結果の取得を参照）。また、独自の座標を指定して直接呼び出すこともできます。
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
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設定により、このエンドポイントを呼び出さなくても同じジョブが自動的にトリガー（および課金）される可能性がある点を参照してください。
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
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はトリガーされません）、エラーではありません。
パラメータ
| 名前 | 場所 | 型 | 説明 |
|---|---|---|---|
document_id | path | string | ドキュメントID。 |
rowsは、行インデックス（文字列、例："0"）を、フィールド名から正規化されたbboxオブジェクト（または、そのフィールドの位置がページ上で見つからなかった場合はnull）へのマップにマッピングします。statusは、APIの他の場所と同じクローズドな5値の列挙型を使用します。
発生しうるエラー
missing_api_key/invalid_api_key/plan_required— エラーハンドリングを参照してください。document_not_found— このIDのドキュメントがアカウントに存在しません。