跳转到主要内容
POST
cURL

授权

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。最大上传大小:15 MB(超出将返回 400 拒绝)。支持多页 PDF(延迟可能更高);加密的 PDF 需要提供 document_password。图片在处理前会自动压缩。

document_password
string
write-only

当 document 为加密 PDF 时用于解密的密码。发送未附带(或附带错误)密码的加密 PDF 将返回 400。

expected_address
string

用于与证件核对的地址。系统会对该地址进行地理编码并与提取出的地址进行比对;不匹配(或预期地址无法进行地理编码/验证)将添加 ADDRESS_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 控制。地理编码后的形式将在 expected_details_formatted_address / expected_details_parsed_address 中回显。

示例:

"Av. Monseñor Tavella 1291, Salta, Argentina"

expected_country
string

用于与证件核验的国家/地区(ISO 3166-1 代码,例如 ARG 或 AR)。与证件国家/地区不匹配会添加 POA_COUNTRY_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 控制。

示例:

"ARG"

expected_first_name
string

用于与 name_on_document 进行核验的名(支持音译的模糊匹配)。低于匹配阈值的分数会添加 NAME_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 管控。

示例:

"Sophia"

expected_last_name
string

用于与 name_on_document 比对的姓氏,与 expected_first_name 结合以计算匹配分数。

示例:

"Martinez"

poa_languages_allowed
string

以逗号分隔的所接受证件语言的 ISO 639-1 代码列表(例如 en,es,fr)。省略或为空时,接受所有 51 种受支持的语言。使用列表之外语言的证件会添加 UNSUPPORTED_DOCUMENT_LANGUAGE(由 poa_unsupported_language_action 控制);列表中包含未知代码将返回 400 以及完整的受支持代码集。

示例:

"en,es"

poa_document_age_months
string

以逗号分隔的 key:value 对,用于按证件类型设置最大证件月龄 — 键:utility_bill、bank_statement、government_issued_document、other_poa_document;值:1–120,或 -1 表示无限制(不进行时效检查)。缺省时的默认值:utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12。超出期限的证件将以 POA_DOCUMENT_EXPIRED 拒绝。注意:提供此字段时,请列出您接受的所有类型 — 未列出的类型将被视为不接受(提示信息 POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION),并跳过其时效检查。

示例:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action
enum<string>
默认值:DECLINE

已接受但目前未应用:姓名不匹配警告(NAME_MISMATCH_WITH_PROVIDED)将转而遵循 poa_address_mismatch_action。请设置 poa_address_mismatch_action 以同时控制姓名和地址的不匹配行为。

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

遇到文件完整性问题时的处理操作:实际上该 endpoint 仅生成 DOCUMENT_METADATA_MISMATCH。

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

当怀疑证件被篡改(SUSPECTED_DOCUMENT_MANIPULATION)时的处理操作,例如 PDF 在数字签名后被修改、经由已知 PDF 编辑器处理、存在覆盖文本篡改或 EXIF 日期不一致。同时控制 POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT(文件无法证明其是否发生过更改的重新录入文本字段):DECLINE 同样予以拒绝,NO_ACTION 将其保留为警告。

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

当证件语言不在 poa_languages_allowed 范围内(UNSUPPORTED_DOCUMENT_LANGUAGE)时采取的操作。

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

当提取的详细信息与 expected_* 字段不一致时采取的操作:ADDRESS_MISMATCH_WITH_PROVIDED、NAME_MISMATCH_WITH_PROVIDED 和 POA_COUNTRY_MISMATCH_WITH_PROVIDED 均遵循此操作。

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

当无法在证件上识别出签发公司/组织时的处理操作(ISSUER_NOT_IDENTIFIED)。

可用选项:
DECLINE,
NO_ACTION
save_api_request
boolean
默认值:true

为 true(默认)时,将此次调用持久化为 API 类型的会话:在 Business Console 中可见,可使用返回的 request_id 通过 GET /v3/session/{sessionId}/decision/ 检索,通过 status.updated Webhook 发出通知,并存储上传的证件。为 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"}),它将被解析为对象。

示例:

响应

证件已处理。poa.status 为 Approved 或 Declined;检测到的每个问题都在 poa.warnings 中逐项列出。过期、不匹配或可疑的证件仍会返回 200 并附带 status: "Declined" — 请检查响应体,而不仅仅是 HTTP 状态码。当 save_api_request=true 时,request_id 为持久化的会话 ID。

request_id
string<uuid>

当 save_api_request=true 时持久化的会话 ID(可用于 GET /v3/session/{sessionId}/decision/);否则为一个临时的关联 UUID。

poa
object
vendor_data
string | null

您发送的 vendor_data 回显,或 null。

metadata
object | null

您发送的 metadata 对象回显,或 null。

created_at
string<date-time>

响应生成时的 ISO 8601 时间戳(UTC)。

最后修改于 2026年11月7日