メインコンテンツへスキップ
POST
Python
書類を1件と、その書類から読み取りたいフィールドのリストを送信します。Diditはファイルに対してデフォルトの抽出モデルを実行し、すべてのフィールドを型付きで返します(text、number、またはYYYY-MM-DD形式のdate)。さらに、対応するQRコードやバーコードを検出・デコードし、ファイルに改ざんがないかをチェックし、必要に応じて書類上の名前を想定する個人または企業と照合します。資金証明、給与明細、銀行取引明細書、税務書類、請求書など、固定のテンプレートに当てはまらないあらゆる書類に利用できます。 これは、ホスト型のDocument AIステップのサーバー間連携版です。リクエストはmultipart/form-data形式で、ファイルはdocumentに、フィールド定義はJSONエンコードした1つの配列文字列としてfieldsに入れます。

抽出するフィールドを定義する

fieldsは1〜30項目のJSON配列で、1つの文字列として送信します。各項目には、key(小文字の英字、数字、アンダースコアで構成し、リクエスト内で一意)、人間が判読できるname、モデルに何を探すかを指示するinstruction、type(text、number、またはdate)、そしてrequiredとis_full_nameの2つのフラグがあります。
multipartリクエストでは、配列全体が1つのフォーム値になります。
レスポンスでは、正規化されたfieldsがエコーバックされ、指定したkeyの値をキーとするextracted_dataが返されます。モデルが見つけられなかった項目はnullになります。各項目のname、instruction、typeは省略可能で(typeのデフォルトはtext)、keyは必須です。fieldsをブラケット形式のフォームキー(fields[0][key]=...)で送信した場合や、JSON配列以外の形式で送信した場合は、抽出の実行前に400が返されるため、料金は一切発生しません。

QRコードとバーコード

成功したすべてのレスポンスにはdocument_ai.detected_codesが含まれます。各項目の内容は次のとおりです。 この配列はPDFの処理対象となったすべてのページを網羅し、対応するコードが見つからない場合は空になります。Diditがペイロードを推測することはありません。破損したQRコードは位置情報とparsed_payload: nullとともに返される場合があり、コード検出に失敗してもDocument AIリクエスト自体は失敗しません。

名前の照合

is_full_name: trueを指定するフィールドは最大1つとし、書類の名義人として想定する名前を送信します。 どちらか一方のグループのみを送信し、両方を送信しないでください。名前が抽出され、想定する名前が指定されている場合、レスポンスにはname_match_score(0〜100)とname_on_documentが含まれます。スコアがdocument_ai_name_match_score_threshold(デフォルトは80)を下回ると、DOCUMENT_AI_NAME_MISMATCH警告が発生し、document_ai_name_mismatch_actionが適用されます。is_full_nameが指定されたフィールドがない場合、Diditはキーが名前を示す最初のテキストフィールド(name、holder、full_name、account_holder)を代わりに使用します。照合に使う値を制御したい場合は、フィールドを明示的に指定してください。書類上に名前の値が見つからない場合、または想定する名前が送信されていない場合、名前チェックはスキップされ、name_match_scoreはnullになります。

リスクとアクション

以下の各リスクは、リクエストごとに設定できるアクションパラメーター(DECLINE、REVIEW、NO_ACTION)に対応しています。トリガーされたアクションのうち最も厳しいものがdocument_ai.statusを決定し(Declined > In Review > Approved)、トリガーされたすべてのリスクがdocument_ai.warningsに一覧表示されます。デフォルト値はホスト型ワークフローのステップと同じです。各リスクの検出方法については、Document AIのルールと警告を参照してください。

ファイル・保存・請求

  • 対応ファイル: PDF(複数ページに対応)、JPG、JPEG、PNG、TIFF、WebP、または書類を含むZIPで、最大30MBまでです。暗号化されたPDFの場合は400が返されます。代わりに復号済みのPDFまたは写真をアップロードしてください。
  • save_api_request(デフォルトはtrue):リクエスト、抽出されたフィールド、検出されたコードがBusiness ConsoleのManual Checksに表示され、チームでレビューできます。保存しない場合はfalseに設定してください。
  • vendor_dataとmetadataはレスポンスでそのまま返されるため、結果を自社の記録と紐付けることができます。
  • 料金: 書類1件あたり$0.20で、書類が処理されステータスが返された時点で請求されます。ご利用のプランの割引が適用されます。詳しくは料金を参照してください。
ユーザー自身に書類をアップロードしてもらう、1つのフローで最大3件の書類を収集する、アップロード画面を自動翻訳する、または抽出したフィールドを本人確認書類やアンケートのデータと照合する必要がある場合は、代わりにホスト型のDocument AIワークフローステップを使用してください。

承認

x-api-key
string
header
必須

お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権(なし、読み取り、書き込み)、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys

ボディ

multipart/form-data
document
file
必須

読み取る書類です。使用可能な拡張子: tiff、jpg、jpeg、png、pdf、webp、zip。最大アップロードサイズ: 30 MB(これを超えるファイルは400で拒否されます)。複数ページのPDFに対応しています(レイテンシーは長くなります)。暗号化されたPDFは400で拒否されます。画像は処理前に自動的に圧縮されます。

fields
string
必須

1〜30個のフィールド定義を含む、JSONエンコードされた配列文字列1つ(最大16KB)。各項目: key(必須、^[a-z0-9_]{1,64}$、一意。extracted_dataで返されるキー)、name(100文字以内、メッセージに表示)、instruction(500文字以内、モデルが読み取る内容)、type(text(デフォルト)、number、dateのいずれか)、required(真偽値、デフォルトはfalse)、is_full_name(真偽値、デフォルトはfalse、1リクエストにつき最大1つ)。ブラケット形式のフォーム配列、無効なJSON、重複するキー、または複数のis_full_nameがある場合は、処理や課金が行われる前に400が返されます。

例:

"[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]"

expected_first_name
string

書類の氏名フィールドと照合する名です(音訳を考慮したあいまい一致)。expected_last_nameと併用してください。expected_company_nameとは組み合わせられません。

例:

"Sophia"

expected_last_name
string

書類の氏名フィールドと照合する姓。expected_first_nameと組み合わせてname_match_scoreを算出します。

例:

"Martinez"

expected_company_name
string

書類の名前フィールドと照合する会社名(企業の書類の場合)。expected_first_name / expected_last_nameとは併用できません(例の値は意図的に記載していません。生成されるリクエストサンプルでは個人のフィールドを使用しているため、企業の書類を検証する場合はこのフィールドに置き換えてください)。

expected_company_country
string

expected_company_nameの企業名正規化を調整する任意のISO 3166-1 alpha-2国コード(2文字のASCII英字、例: FR)です。expected_company_nameと併用する場合にのみ使用されます。

document_ai_name_match_score_threshold
integer
デフォルト:80

名前が一致したとみなすname_match_scoreの最小値(0〜100)。これより低いスコアの場合はDOCUMENT_AI_NAME_MISMATCHが追加され、その扱いはdocument_ai_name_mismatch_actionで決まります。

必須範囲: 0 <= x <= 100
例:

80

document_ai_unreadable_document_action
enum<string>
デフォルト:REVIEW

書類からフィールドを1つも読み取れなかった場合の処理です(DOCUMENT_AI_UNREADABLE_DOCUMENT)。

利用可能なオプション:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
デフォルト:REVIEW

requiredフィールドのうち少なくとも1つを読み取れなかった場合の処理です(DOCUMENT_AI_MISSING_REQUIRED_FIELDS。該当するフィールドはadditional_data.missing_fieldsに列挙されます)。

利用可能なオプション:
DECLINE,
REVIEW,
NO_ACTION
document_ai_document_tampering_action
enum<string>
デフォルト:DECLINE

PDF/EXIFのフォレンジック分析で改ざんが疑われる場合の処理です。デジタル署名後の変更、既知のPDF編集ソフトの使用、オーバーレイテキストによる改ざん、不審な再エクスポート、画像の異常が対象です(DOCUMENT_AI_SUSPECTED_MANIPULATION)。

利用可能なオプション:
DECLINE,
REVIEW,
NO_ACTION
document_ai_name_mismatch_action
enum<string>
デフォルト:NO_ACTION

name_match_scoreがしきい値を下回る場合の処理です(DOCUMENT_AI_NAME_MISMATCH)。

利用可能なオプション:
DECLINE,
REVIEW,
NO_ACTION
document_ai_unsupported_file_action
enum<string>
デフォルト:REVIEW

アップロードが空である、または処理可能なファイルではない場合(DOCUMENT_AI_UNSUPPORTED_FILE)の対応です。

利用可能なオプション:
DECLINE,
REVIEW,
NO_ACTION
save_api_request
boolean
デフォルト:true

true(デフォルト)の場合、呼び出しはAPIタイプのセッションとして保存されます。このセッションはBusiness Consoleに表示され、返されたrequest_idを使ってGET /v3/session/{sessionId}/decision/で取得でき、アップロードされた書類、抽出された値、フィールド定義、氏名照合のスナップショットが保存されます。falseの場合、何も保存されず、request_idはレスポンスの照合専用の一時的なUUIDになります。この場合も呼び出しは課金されます。

例:

true

vendor_data
string

任意の不透明な文字列(社内のユーザーID、メールアドレス、UUIDなど)です。保存されたセッションに格納され、レスポンスでそのまま返されます。API呼び出しを自社の記録と関連付けたり、後でセッションを絞り込んだりするために使用します。

例:

"user-123"

metadata
object

セッションとともに保存され(save_api_request=trueの場合)、レスポンスでそのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください(例: metadata={"flow":"onboarding"})。オブジェクトとして解析されます。

例:

レスポンス

書類が処理されました。document_ai.statusはApproved、Declined、In Reviewのいずれかで、検出されたすべての問題はdocument_ai.warningsに個別に列挙されます。問題のある書類でも200が返されるため、HTTPコードだけでなくボディを確認してください。save_api_request=trueの場合、request_idは永続化されたセッションIDです。

request_id
string<uuid>

save_api_request=trueの場合は保存されたセッションID(GET /v3/session/{sessionId}/decision/で使用可能)、それ以外の場合は一時的な相関UUIDです。

document_ai
object
vendor_data
string | null

送信したvendor_dataのエコー、またはnull。

metadata
object | null

送信したmetadataオブジェクトのエコー、またはnull。

created_at
string<date-time>

リクエストが処理された日時(UTC、ISO 8601)。

最終更新日 2026年11月1日