跳转到主要内容
POST
Python
发送一份证件以及需要从中读取的字段列表。Didit 会使用其默认提取模型处理文件,返回每个带类型的字段(text、number 或 date;日期格式为 YYYY-MM-DD),检测并解码受支持的 QR 码和条形码,检查文件是否被篡改,并可选择将证件上的姓名与您预期的个人或企业进行比对。适用于资金证明、工资单、银行对账单、税务文件、发票,或任何不符合固定模板的证件。 这是托管式 Document AI 步骤的服务器到服务器版本。请求格式为 multipart/form-data:文件放在 document 中,字段定义以单个 JSON 编码数组字符串的形式放在 fields 中。

定义要提取的字段

fields 是一个包含 1 到 30 项的 JSON 数组,以单个字符串形式发送。每一项包含 key(小写字母、数字和下划线,在同一请求中必须唯一)、便于阅读的 name、告诉模型要查找什么的 instruction、type(text、number 或 date),以及两个标志:required 和 is_full_name。
在 multipart 请求中,整个数组是一个表单值:
响应会回显规范化后的 fields,并返回以您的 key 值为键的 extracted_data,模型未找到的内容返回 null。每一项中的 name、instruction 和 type 都是可选的(type 默认为 text);key 为必填。若将 fields 作为方括号形式的表单键(fields[0][key]=...)发送,或发送的不是 JSON 数组,将在任何提取运行之前返回 400,因此不会产生计费。

QR 码与条形码

每个成功的响应都包含 document_ai.detected_codes。每一项包含以下内容: 对于 PDF,该数组涵盖每个已处理页面;未找到受支持的码时为空数组。Didit 从不猜测 payload 内容:损坏的 QR 码可能会返回其位置以及 parsed_payload: null,而码检测失败不会导致 Document AI 请求失败。

姓名匹配

最多在一个字段上标记 is_full_name: true,并传入您预期该证件所属的对象: 两组参数只传一组,不要同时传入。当提取到姓名且存在预期姓名时,响应会包含 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 文件,大小上限为 30 MB。加密的 PDF 将返回 400;请上传已解密的 PDF 或照片。
  • save_api_request(默认 true):请求、提取的字段和检测到的码会显示在 Business Console 的 人工审核 下,供您的团队复核。设置为 false 可跳过保存。
  • vendor_data 和 metadata 会在响应中原样返回,便于您将结果与自己的记录关联。
  • 价格: 每份证件 $0.20,在证件被处理并返回状态时计费。您的套餐折扣同样适用。请参阅 定价。
需要由用户自行上传证件、在一个流程中收集最多 3 份证件、自动翻译上传界面,或将提取的字段与身份证件或问卷数据进行交叉比对?请改用托管的 Document AI 工作流步骤。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 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 编码数组字符串(最大 16 KB)。每个项目:key(必填,^[a-z0-9_]{1,64}$,唯一:在 extracted_data 中返回的键)、name(≤100 个字符,在消息中显示)、instruction(≤500 个字符,模型应读取的内容)、type(默认 text | number | date)、required(布尔值,默认 false)、is_full_name(布尔值,默认 false,每个请求最多一个)。括号风格的表单数组、无效 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

可选的 ISO 3166-1 alpha-2 国家/地区代码(两个 ASCII 字母,例如 FR),用于针对 expected_company_name 调整公司名称规范化。仅与 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

当无法从证件中读取任何字段时的处理操作(DOCUMENT_AI_UNREADABLE_DOCUMENT)。

可用选项:
DECLINE,
REVIEW,
NO_ACTION
document_ai_missing_required_fields_action
enum<string>
默认值:REVIEW

当至少有一个 required 字段无法读取时的处理操作(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 对象。在 multipart 请求中,请将其作为 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月7日