> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 数据库核验 API：国家身份证匹配 > Didit 数据库核验 API：通过 POST /v3/database-validation/ 对接 100+ 国家及全球权威数据源，支持 1x1 和 2x2 瀑布式匹配，按次计费。 ## 基于地址的服务 对于验证居住地址或公用事业地址的服务，您可以只发送一个 `address`，Didit 会在处理核验前将其拆分。为获得最佳匹配率，请直接发送 Didit 的结构化地址字段： | 字段 | 含义 | | - | - | | `address_element_1` | 街道地址，包括门牌号和街道类型 | | `address_element_2` | 可选，单元、楼栋、楼层或其他地址行 | | `address_element_3` | 郊区、地区或社区 | | `address_element_4` | 城市、城镇、州、省或地区 | | `address_element_5` | 邮政编码 | 结构化字段会覆盖单独的 `address` 值。`postal_code` 可作为 `address_element_5` 的别名使用。 ## 同意 部分数据库服务要求终端用户明确同意后，才能向服务提供方发起查询。服务目录会在这些服务的行中标记 `requires_consent=true`。 当用户同意适用于所选服务时，请发送 `consent=true`。 如果所选服务需要同意而您未发送该参数，Didit 会在调用任何服务提供方之前、且未产生任何计费事件时拒绝该请求。 ## 文件上传 数据库核验使用 `multipart/form-data`。需要 `selfie` 的生物识别服务会在 API 调试台中将其显示为文件上传字段，您可以直接选择图片，无需粘贴路径或 base64 字符串。 在代码中，请使用标准的 multipart 语法上传文件： ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## 验证错误 Didit 会在调用服务提供方之前，先核验必填字段、地址结构以及特定服务的格式。例如，`chn_national_id` 和 `chn_passport_verification` 等中国登记服务要求 `full_name` 使用原始中文字符。其中，`chn_national_id` 还要求提供有效的 15 位或 18 位中国居民身份证号码，且校验位必须正确。 如果请求无法执行，API 会返回明确的字段错误，并且不产生任何费用。如果服务提供方在预检后失败，响应会包含 `validation_errors`，而已保存的 API 请求会将这些错误存储在数据库核验结果中。 ## 被拒绝的输入与不可用的结果 如果没有任何服务返回可用结果，请先检查每个 `validation_errors` 条目，再决定是否重试。仅凭 HTTP 状态码无法判断重试是否合适。 返回 `400`、且 `code: "provider_rejected_input"` 和 `retryable: false` 表示每次未得到应答的尝试都明确拒绝了该输入。请先更正所提供的数据，再重新尝试。这些尝试不计费。 返回 `502`、且 `code: "empty_provider_response"` 和 `retryable: true` 表示服务因其他原因无法生成可用结果。这包括输入被拒绝后又遇到不可用的备用服务，或备用服务未给出任何说明的情况。请稍后重试；该响应并不表明输入有误。如果某个数据库持续失败，一旦中断持续存在，Didit 会向近期使用过该数据库的企业发送一次邮件；当真实核验确认其已恢复应答时，还会再次发送邮件。参见 [可用性通知](https://docs.didit.me/zh/core-technology/database-validation/overview.md#可用性通知)。 当只有部分所选服务失败时，请求仍会成功：响应为 `200`，失败的服务会列在 `database_validation.errors[]` 中，每项都包含相同的 `code` 和 `retryable` 字段。此时，`database_validation.status` 会依据已应答的服务给出结果，并且可以为 `Approved`。因此，请检查每个响应中的 `errors[]`，而不要只检查 `4xx` 或 `5xx` 响应。列在其中的服务不会出现在 `validations` 和 `services_used` 中，也不计费。请单独重试该服务。 其他 `502` 错误可能需要更正输入。例如，`provider_invalid_input` 和 `provider_validation_error` 表示数据源拒绝了该输入，切勿在不做修改的情况下重试，即使旧版响应中省略了 `retryable` 也是如此。`empty_provider_response` 的重试指引不适用于这些错误代码。明确的无匹配结果属于已完成的核验，而非可用性故障。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/database-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: 数据库核验（独立） description: >- 根据官方政府和登记机构数据源核验个人的身份数据，包括巴西的 CPF、阿根廷的 RENAPER、西班牙和秘鲁的 DNI 登记库、墨西哥的 INE，以及覆盖 60+ 个国家/地区的 100+ 项服务。 **服务选择。** 每个国家/地区公开一个或多个由 `service_id` 标识的目录服务（例如 `bra_cpf`、`arg_renaper`、`pan_cedula_sib`）。通过 `services` 数组指定您需要的服务；如果省略该参数，则仅运行**一个**默认服务（该国家/地区运营时间最长的生产环境服务）。传递 `services` 还会将响应切换为包含 `services_used` 和 `match_score` 的扩展结构。通过 `GET /v1/organization/database-validation-countries/`（本规范中未记录的目录 endpoint）或 Business Console 工作流编辑器发现服务、其必填字段及价格。目录中部分服务被标记为 `requires_consent=true` 并要求 `consent=true`；其他服务在调用前需要为您的组织进行入驻配置。 **输入字段。** `identification_number` 是一个通用字段，会自动映射到特定国家/地区的正确字段（请参见其描述）。在调用任何提供商之前都会强制执行国家/地区格式规则（例如巴西 CPF 必须正好是 11 位数字），格式错误绝不计费。生物识别服务需要上传 `selfie`（仅限 multipart）；阿根廷 RENAPER 还需要 `gender`。 **结果。** 每个服务返回逐字段的 `validation` 映射以及与供应商无关的 `outcome_code`（`MATCH`、`PARTIAL_MATCH`、`NO_MATCH`、`DOCUMENT_NOT_FOUND`、`INVALID_DOCUMENT_FORMAT`、`INVALID_INPUT`、`MINOR_BLOCKED`、`DECEASED`、`BIOMETRIC_NO_MATCH`、`BIOMETRIC_IMAGE_UNUSABLE`、`INCONCLUSIVE`、`DOCUMENT_SUPERSEDED`、`REGISTRY_UNAVAILABLE`、`REGISTRY_ERROR`）。请注意以下区别：`NO_MATCH` 表示明确不匹配；`INCONCLUSIVE` 表示登记库无法确认任一结果（审核，而非拒绝）；`BIOMETRIC_IMAGE_UNUSABLE` 是技术性自拍问题（重新拍摄），与明确的 `BIOMETRIC_NO_MATCH` 不同。总体 `match_type` 跨服务聚合（任意完全匹配 → `full_match`，否则任意部分匹配 → `partial_match`，否则 `no_match`），且 `no_match_action`/`partial_match_action` 将其转换为最终的 `status`。`validation_type` 为派生值：当两个或更多不同服务生成完全匹配（针对证件号码、针对姓名 + 出生日期组合，或针对地址且无冲突）时为 `two_by_two`，否则为 `one_by_one`。 **持久化。** `save_api_request` 默认为 **true**：结果将作为会话保存（`request_id` 可用于 `GET /v3/session/{sessionId}/decision/`），显示在控制台中，并触发 `status.updated` Webhook。它还控制 `validations` 结构：保存时为按服务划分的对象，未保存时为合并后的 `{field: match}` 映射。 **计费。** 按服务计费：每个返回可计费结果的服务均按其自身的目录价格收费。失败或跳过的服务不予计费，被 `400` 拒绝的请求不收取任何费用。预检余额检查涵盖所选服务价格的总和（不足时返回 `403`）。 **失败。** 当所选服务均未返回可用结果时，如果每次未得到回答的尝试均明确拒绝了输入（`provider_rejected_input`，`retryable: false`），API 将返回 `400` 及 `validation_errors`。请在重试前更正输入。否则，API 将返回 `502` 及 `validation_errors`（`empty_provider_response`，`retryable: true`），包括输入被拒绝与备用尝试不可用的混合情况；不收取任何费用（当 `save_api_request=true` 时，仍会记录状态为 `Not Finished` 的会话）。当仅有部分服务失败时，`200` 响应会在 `database_validation.errors` 中携带其失败信息。 **沙盒。** 来自沙盒应用的密钥会跳过登记库调用和计费，并返回静态的 `full_match` 响应。无论 `services` 如何发送，沙盒 payload 始终包含 `services_used` 和 `match_score: 100`，因此不要针对沙盒响应验证生产环境的扩展结构限制或 0.0–1.0 的 `match_score` 小数值。 以 `application/json` 格式发送请求，上传 `selfie` 时以 `multipart/form-data` 格式发送。 operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- 用于验证的目标登记处的 ISO 3166-1 **alpha-3** 国家/地区代码（例如 `BRA`、`ESP`、`COL`）。决定哪些服务可用。不受支持的代码将返回 `400` 及有效选项的完整列表。 example: BRA services: type: array items: type: string description: >- 针对此国家/地区要运行的目录 `service_id` 列表（例如 `["bra_cpf"]`）。也接受单个字符串或以逗号分隔/JSON 编码的字符串。**如果省略或为空，将仅运行一个默认服务** — 即该国家/地区上线时间最长的生产环境服务；较新的、生物识别及按量计费的服务必须显式指定。发送 `services` 会将响应切换为扩展形式（添加 `services_used` 和 `match_score`）。每个 ID 必须存在且对该 `issuing_state` 处于可用状态；需要入驻的服务在为您的组织激活前将返回 `400`。可通过 `GET /v1/organization/database-validation-countries/`（本规范中未记载的目录 endpoint）或 Business Console 工作流编辑器发现每个国家/地区的可用服务。 example: - bra_cpf validation_type: type: string deprecated: true description: >- 已弃用。为向后兼容而接受但会被忽略，响应中的 `validation_type` 现在取决于完全匹配的服务数量。使用 `services` 可固定指定的服务。 consent: type: boolean default: false description: >- 当终端用户明确同意所选验证服务时设为 `true`。目录中标记为 `requires_consent=true` 的服务必须提供 — 若未提供，这些服务将返回 `400` 以及 `services_requiring_consent`。 identification_number: type: string description: >- 通用身份识别号，自动映射到特定国家/地区的正确字段，因此您可以用来代替 `personal_number`/`tax_number`/`document_number`：ARG→document_number (DNI)、BOL→document_number (CI)、BRA→tax_number (CPF，11 位数字)、CHL→personal_number (RUT)、COL→personal_number (Cédula)、CRI→personal_number (Cédula)、DOM→personal_number (Cédula，11 位数字)、ECU→personal_number (Cédula，10 位数字)、ESP→personal_number (DNI/NIE)、GTM→document_number (DPI)、HND→document_number (DNI)、MEX→personal_number (CURP，18 位字符)、PAN→personal_number (Cédula)、PER→personal_number (DNI，8 位数字)、PRY→document_number (CI)、SLV→document_number (DUI)、URY→personal_number (CI)、VEN→document_number (Cédula)。它绝不会覆盖显式提供的特定国家/地区字段。 first_name: type: string description: 个人的名字。某些服务/国家/地区要求必填。 example: John last_name: type: string description: 个人的姓氏。某些服务/国家/地区要求必填。 example: Doe middle_name: type: string description: 中间名，由部分国家/地区服务使用（澳大利亚、新西兰等）。 full_name: type: string description: 姓名 — 部分服务接受以此代替名/姓（例如 CHN 服务，用于比对原生文字系统中的姓名）。 date_of_birth: type: string format: date description: 出生日期，`YYYY-MM-DD`。许多服务均要求提供。 example: '1980-01-01' personal_number: type: string description: >- 政府签发的唯一个人身份标识。适用地区：CHL (RUT)、COL (Cédula)、CRI、DOM、ECU、ESP (DNI/NIE)、MEX (CURP)、PAN (Cédula)、PER (DNI)、URY。建议改用 `identification_number`。 tax_number: type: string description: 税号。适用地区：BRA（CPF，11 位数字）。建议改用 `identification_number`。 document_number: type: string description: >- 证件号码。适用于：ARG (DNI)、BOL (CI)、GTM (DPI)、HND (DNI)、PRY (CI)、SLV (DUI)、VEN (Cédula)。建议改用 `identification_number`。 document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- 正在核验的证件类型：`P` 护照、`DL` 驾驶证、`ID` 国民身份证、`RP` 居留许可（以及 `SSC`、`HIC`、`WP`、`TC`、`VISA`、`PSC`、`BC`、`OTHER`）。某些服务需要此字段（例如 ESP）。 expiration_date: type: string format: date description: 证件到期日期，`YYYY-MM-DD`。ESP（西班牙）核验必填。 example: '2030-01-15' date_of_issue: type: string format: date description: >- 证件签发日期，`YYYY-MM-DD`（fecha de expedición）。COL（哥伦比亚）身份证（cédula）核验必填。 example: '2015-06-20' nationality: type: string description: ISO 3166-1 alpha-3 格式的国籍。某些服务需要此字段。 gender: type: string enum: - M - F - X description: 性别：`M`、`F` 或 `X`（其他/未知）。阿根廷的 RENAPER 核验（`arg_renaper`）必填。 address: description: >- 居住地址。建议使用结构化对象 `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`；仍接受完整的单行字符串。地址验证服务要求必填；当某项服务定义了地址要求时，缺少部分将返回 `400` 以及 `address_fields_required_by`。 oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: 完整的单行地址（旧版）。 address_element_1: type: string description: 街道地址，包括门牌号和道路类型。如果省略，则从 `address` 推导。 address_element_2: type: string description: 公寓、单元、楼栋、楼层或补充地址行。仅在明确掌握该信息时发送。 address_element_3: type: string description: 城市、郊区、区、地方或街区。如果省略，则从 `address` 派生。 address_element_4: type: string description: 州、省、地区或城镇。如果省略，则从 `address` 推导。 address_element_5: type: string description: 邮政编码。接受 `postal_code` 作为别名。 postal_code: type: string description: 基于地址的服务的邮政编码（`address_element_5` 的别名）。 driver_license_number: type: string description: 用于政府证件验证服务（AUS、NZL、IND）的驾照号码。 driver_license_card_number: type: string description: 实体驾照卡号，当与驾照号码（澳大利亚）分开要求时使用。 driver_license_state: type: string description: 驾照签发州或领地（AUS）。 driver_license_version: type: string description: 驾照版本代码（NZL）。 passport_number: type: string description: 用于政府护照核验服务（澳大利亚 AUS、新西兰 NZL、印度 IND、中国 CHN）的护照号码。 passport_expiration_date: type: string format: date description: 护照到期日期，格式为 `YYYY-MM-DD`，用于护照核验服务。 passport_file_number: type: string description: 护照文件编号（IND）。 passport_issue_country: type: string description: 护照验证服务所使用的护照签发国家/地区（ISO 3166-1 alpha-3）。 medicare_card_number: type: string description: Medicare 卡号（澳大利亚）。 immi_card_number: type: string description: 澳大利亚 ImmiCard 号码。 immi_card_expiry_date: type: string format: date description: 澳大利亚 ImmiCard 到期日期。 citizenship_certificate_number: type: string description: 公民身份证书编号（澳大利亚）。 birth_registration_number: type: string description: 出生证明登记号（澳大利亚）。 birth_registration_date: type: string format: date description: 出生证明登记日期（澳大利亚）。 birth_registration_state: type: string description: 出生证明登记州（澳大利亚）。 marriage_certificate_number: type: string description: 结婚证明编号（澳大利亚）。 change_of_name_certificate_number: type: string description: 更名证明编号（澳大利亚）。 first_partner_name: type: string description: 结婚证上配偶的名（澳大利亚）。 last_partner_name: type: string description: 结婚证上配偶的姓氏（澳大利亚）。 voter_id: type: string description: 选民登记号（IND EPIC、IRL）。 epic_card: type: string description: 印度 EPIC 选民卡号。 pan: type: string description: 印度 PAN（永久账号）。 national_id: type: string description: 国民身份证号（CHN、MYS、KEN、KHM、NGA、ZAF、……）。 cic: type: string description: >- 墨西哥 INE/IFE 凭证识别码（CIC，Código de Identificación de Credencial），9 位数字。由墨西哥 INE 凭据有效性核验服务（`mex_ine_vigencia`）使用。 identificador_ciudadano: type: string description: >- 墨西哥 INE 公民标识符（Identificador del Ciudadano，9 位数字）。在 `mex_ine_vigencia` 中与 `cic` 一起用于现代 INE 型号（E/F/G/H）。 ocr: type: string description: >- 墨西哥 INE OCR 编号（13 位数字，卡片背面）。在 `mex_ine_vigencia` 中与 `cic` 一起用于 D 型号。 voter_number: type: string description: >- 墨西哥 INE 选民识别码（Clave de Elector，18 位字符）。在 `mex_ine_vigencia` 中与 `emission_number` 一起用于旧版 IFE 型号（A/B/C）。 emission_number: type: string description: >- 墨西哥 INE 签发编号（Número de Emisión）。在 `mex_ine_vigencia` 中与 `voter_number` 一起用于旧版 IFE 型号（A/B/C）。 bvn: type: string description: 尼日利亚银行验证号码（BVN）。 bank_card_number: type: string description: 银行卡号（中国银行卡验证）。 company_registration_number: type: string description: >- 公司登记机构签发的企业注册号：如巴西的 CNPJ（例如 `11222333000181`）、南非的注册号（例如 `1936/007721/06`）。公司登记和企业董事服务（`bra_company_registry`、`bra_company_directors`、`zaf_company_registry`、`zaf_company_directors`）需要此参数。 company_name: type: string description: 注册公司名称，与登记条目进行交叉比对。对于 `zaf_company_registry` 可选。 initials: type: string description: >- 证件上印制的该人员姓名首字母缩写。`zaf_drivers_license` 必需；`zaf_bank_account_holder` 可接受。 licence_number: type: string description: >- 卡片上印制的驾照号码，适用于 `zaf_drivers_license`。省略时，使用 `document_number`。 refugee_file_number: type: string description: 南非内政部签发的难民档案号。`zaf_refugee` 所需。 bank_name: type: string description: 开户银行名称。`zaf_bank_account_holder` 必填。 bank_account_number: type: string description: >- 银行账号。`zaf_bank_account_holder` 必填；`zaf_fraud_prevention` 可接受。 account_type: type: string description: >- `zaf_bank_account_holder` 的银行账户类型：`current`、`savings`、`transmission`、`subscriptionShare` 或 `notKnown`，不区分大小写。任何其他值返回 `400`。未知类型时请省略：账户类型交叉比对随后将报告为未确认。 phone_number: type: string description: >- 联系手机号码，用于交叉核验可联络性的服务（`zaf_bank_account_holder`、`zaf_fraud_prevention`、`zaf_refugee`）。 right_thumb: type: string description: >- 用于 `zaf_dha_fingerprint_match` 的 Base64 编码右手拇指指纹，可与 `left_thumb` 一起提供或单独提供。 left_thumb: type: string description: >- 用于 `zaf_dha_fingerprint_match` 的 Base64 编码左手拇指指纹，可与 `right_thumb` 一起提供或单独提供。 score_level: type: integer description: '`zaf_criminal_face_screening` 的最低生物识别评分等级。默认为 `3`。' max_matches: type: integer description: '`zaf_criminal_face_screening` 返回的候选匹配项最大数量。默认值为 `1`。' vehicle_register_number: type: string description: >- 车辆登记编号。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_licence_plate` 和 `vin` 一同提供。 vehicle_licence_plate: type: string description: >- 车辆号牌号码。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vin` 一同提供。 vin: type: string description: >- 车辆识别代号（VIN 或车架号）。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vehicle_licence_plate` 一同提供。 ssn: type: string description: 社会安全号码（美国）。 phone: type: string description: 用于电话验证服务的电话号码。 landline: type: string description: 用于电话验证服务的座机号码。 email: type: string format: email description: 用于身份验证服务的邮箱地址。 country_of_residence: type: string description: >- 居住国家/地区的 ISO 3166-1 alpha-2 代码。供全球身份信息增强服务（例如 `glb_identity_enrichment`）用于限定查询范围。 example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- `partial_match` 对 `database_validation.status` 的影响。默认值为 `NO_ACTION`（状态保持为 `Approved`，并附带警告）。 no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- `no_match` 对 `database_validation.status` 的影响。默认值为 `DECLINE`。 save_api_request: type: boolean default: true description: >- 将核验持久化为会话（控制台可见性、决策 endpoint、`status.updated` Webhook）。同时会改变 `validations` 响应的格式：为 `true`（默认）时按服务返回对象，为 `false` 时返回合并的字段映射。 vendor_data: type: string description: 您为已核验用户指定的标识符；将原样返回并与会话一起存储。 metadata: type: object nullable: true description: 随请求一同存储并回显的自由格式 JSON。 example: issuing_state: BRA services: - bra_cpf identification_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' vendor_data: user-1234 multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- 用于验证的目标登记处的 ISO 3166-1 **alpha-3** 国家/地区代码（例如 `BRA`、`ESP`、`COL`）。决定哪些服务可用。不受支持的代码将返回 `400` 及有效选项的完整列表。 example: BRA services: type: array items: type: string description: >- 针对此国家/地区要运行的目录 `service_id` 列表（例如 `["bra_cpf"]`）。也接受单个字符串或以逗号分隔/JSON 编码的字符串。**如果省略或为空，将仅运行一个默认服务** — 即该国家/地区上线时间最长的生产环境服务；较新的、生物识别及按量计费的服务必须显式指定。发送 `services` 会将响应切换为扩展形式（添加 `services_used` 和 `match_score`）。每个 ID 必须存在且对该 `issuing_state` 处于可用状态；需要入驻的服务在为您的组织激活前将返回 `400`。可通过 `GET /v1/organization/database-validation-countries/`（本规范中未记载的目录 endpoint）或 Business Console 工作流编辑器发现每个国家/地区的可用服务。 example: - bra_cpf validation_type: type: string deprecated: true description: >- 已弃用。为向后兼容而接受但会被忽略，响应中的 `validation_type` 现在取决于完全匹配的服务数量。使用 `services` 可固定指定的服务。 consent: type: boolean default: false description: >- 当终端用户明确同意所选验证服务时设为 `true`。目录中标记为 `requires_consent=true` 的服务必须提供 — 若未提供，这些服务将返回 `400` 以及 `services_requiring_consent`。 identification_number: type: string description: >- 通用身份识别号，自动映射到特定国家/地区的正确字段，因此您可以用来代替 `personal_number`/`tax_number`/`document_number`：ARG→document_number (DNI)、BOL→document_number (CI)、BRA→tax_number (CPF，11 位数字)、CHL→personal_number (RUT)、COL→personal_number (Cédula)、CRI→personal_number (Cédula)、DOM→personal_number (Cédula，11 位数字)、ECU→personal_number (Cédula，10 位数字)、ESP→personal_number (DNI/NIE)、GTM→document_number (DPI)、HND→document_number (DNI)、MEX→personal_number (CURP，18 位字符)、PAN→personal_number (Cédula)、PER→personal_number (DNI，8 位数字)、PRY→document_number (CI)、SLV→document_number (DUI)、URY→personal_number (CI)、VEN→document_number (Cédula)。它绝不会覆盖显式提供的特定国家/地区字段。 first_name: type: string description: 个人的名字。某些服务/国家/地区要求必填。 example: John last_name: type: string description: 个人的姓氏。某些服务/国家/地区要求必填。 example: Doe middle_name: type: string description: 中间名，由部分国家/地区服务使用（澳大利亚、新西兰等）。 full_name: type: string description: 姓名 — 部分服务接受以此代替名/姓（例如 CHN 服务，用于比对原生文字系统中的姓名）。 date_of_birth: type: string format: date description: 出生日期，`YYYY-MM-DD`。许多服务均要求提供。 example: '1980-01-01' personal_number: type: string description: >- 政府签发的唯一个人身份标识。适用地区：CHL (RUT)、COL (Cédula)、CRI、DOM、ECU、ESP (DNI/NIE)、MEX (CURP)、PAN (Cédula)、PER (DNI)、URY。建议改用 `identification_number`。 tax_number: type: string description: 税号。适用地区：BRA（CPF，11 位数字）。建议改用 `identification_number`。 document_number: type: string description: >- 证件号码。适用于：ARG (DNI)、BOL (CI)、GTM (DPI)、HND (DNI)、PRY (CI)、SLV (DUI)、VEN (Cédula)。建议改用 `identification_number`。 document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- 正在核验的证件类型：`P` 护照、`DL` 驾驶证、`ID` 国民身份证、`RP` 居留许可（以及 `SSC`、`HIC`、`WP`、`TC`、`VISA`、`PSC`、`BC`、`OTHER`）。某些服务需要此字段（例如 ESP）。 expiration_date: type: string format: date description: 证件到期日期，`YYYY-MM-DD`。ESP（西班牙）核验必填。 example: '2030-01-15' date_of_issue: type: string format: date description: >- 证件签发日期，`YYYY-MM-DD`（fecha de expedición）。COL（哥伦比亚）身份证（cédula）核验必填。 example: '2015-06-20' nationality: type: string description: ISO 3166-1 alpha-3 格式的国籍。某些服务需要此字段。 gender: type: string enum: - M - F - X description: 性别：`M`、`F` 或 `X`（其他/未知）。阿根廷的 RENAPER 核验（`arg_renaper`）必填。 address: description: >- 居住地址。建议使用结构化对象 `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`；仍接受完整的单行字符串。地址验证服务要求必填；当某项服务定义了地址要求时，缺少部分将返回 `400` 以及 `address_fields_required_by`。 oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: 完整的单行地址（旧版）。 address_element_1: type: string description: 街道地址，包括门牌号和道路类型。如果省略，则从 `address` 推导。 address_element_2: type: string description: 公寓、单元、楼栋、楼层或补充地址行。仅在明确掌握该信息时发送。 address_element_3: type: string description: 城市、郊区、区、地方或街区。如果省略，则从 `address` 派生。 address_element_4: type: string description: 州、省、地区或城镇。如果省略，则从 `address` 推导。 address_element_5: type: string description: 邮政编码。接受 `postal_code` 作为别名。 postal_code: type: string description: 基于地址的服务的邮政编码（`address_element_5` 的别名）。 driver_license_number: type: string description: 用于政府证件验证服务（AUS、NZL、IND）的驾照号码。 driver_license_card_number: type: string description: 实体驾照卡号，当与驾照号码（澳大利亚）分开要求时使用。 driver_license_state: type: string description: 驾照签发州或领地（AUS）。 driver_license_version: type: string description: 驾照版本代码（NZL）。 passport_number: type: string description: 用于政府护照核验服务（澳大利亚 AUS、新西兰 NZL、印度 IND、中国 CHN）的护照号码。 passport_expiration_date: type: string format: date description: 护照到期日期，格式为 `YYYY-MM-DD`，用于护照核验服务。 passport_file_number: type: string description: 护照文件编号（IND）。 passport_issue_country: type: string description: 护照验证服务所使用的护照签发国家/地区（ISO 3166-1 alpha-3）。 medicare_card_number: type: string description: Medicare 卡号（澳大利亚）。 immi_card_number: type: string description: 澳大利亚 ImmiCard 号码。 immi_card_expiry_date: type: string format: date description: 澳大利亚 ImmiCard 到期日期。 citizenship_certificate_number: type: string description: 公民身份证书编号（澳大利亚）。 birth_registration_number: type: string description: 出生证明登记号（澳大利亚）。 birth_registration_date: type: string format: date description: 出生证明登记日期（澳大利亚）。 birth_registration_state: type: string description: 出生证明登记州（澳大利亚）。 marriage_certificate_number: type: string description: 结婚证明编号（澳大利亚）。 change_of_name_certificate_number: type: string description: 更名证明编号（澳大利亚）。 first_partner_name: type: string description: 结婚证上配偶的名（澳大利亚）。 last_partner_name: type: string description: 结婚证上配偶的姓氏（澳大利亚）。 voter_id: type: string description: 选民登记号（IND EPIC、IRL）。 epic_card: type: string description: 印度 EPIC 选民卡号。 pan: type: string description: 印度 PAN（永久账号）。 national_id: type: string description: 国民身份证号（CHN、MYS、KEN、KHM、NGA、ZAF、……）。 cic: type: string description: >- 墨西哥 INE/IFE 凭证识别码（CIC，Código de Identificación de Credencial），9 位数字。由墨西哥 INE 凭据有效性核验服务（`mex_ine_vigencia`）使用。 identificador_ciudadano: type: string description: >- 墨西哥 INE 公民标识符（Identificador del Ciudadano，9 位数字）。在 `mex_ine_vigencia` 中与 `cic` 一起用于现代 INE 型号（E/F/G/H）。 ocr: type: string description: >- 墨西哥 INE OCR 编号（13 位数字，卡片背面）。在 `mex_ine_vigencia` 中与 `cic` 一起用于 D 型号。 voter_number: type: string description: >- 墨西哥 INE 选民识别码（Clave de Elector，18 位字符）。在 `mex_ine_vigencia` 中与 `emission_number` 一起用于旧版 IFE 型号（A/B/C）。 emission_number: type: string description: >- 墨西哥 INE 签发编号（Número de Emisión）。在 `mex_ine_vigencia` 中与 `voter_number` 一起用于旧版 IFE 型号（A/B/C）。 bvn: type: string description: 尼日利亚银行验证号码（BVN）。 bank_card_number: type: string description: 银行卡号（中国银行卡验证）。 company_registration_number: type: string description: >- 公司登记机构签发的企业注册号：如巴西的 CNPJ（例如 `11222333000181`）、南非的注册号（例如 `1936/007721/06`）。公司登记和企业董事服务（`bra_company_registry`、`bra_company_directors`、`zaf_company_registry`、`zaf_company_directors`）需要此参数。 company_name: type: string description: 注册公司名称，与登记条目进行交叉比对。对于 `zaf_company_registry` 可选。 initials: type: string description: >- 证件上印制的该人员姓名首字母缩写。`zaf_drivers_license` 必需；`zaf_bank_account_holder` 可接受。 licence_number: type: string description: >- 卡片上印制的驾照号码，适用于 `zaf_drivers_license`。省略时，使用 `document_number`。 refugee_file_number: type: string description: 南非内政部签发的难民档案号。`zaf_refugee` 所需。 bank_name: type: string description: 开户银行名称。`zaf_bank_account_holder` 必填。 bank_account_number: type: string description: >- 银行账号。`zaf_bank_account_holder` 必填；`zaf_fraud_prevention` 可接受。 account_type: type: string description: >- `zaf_bank_account_holder` 的银行账户类型：`current`、`savings`、`transmission`、`subscriptionShare` 或 `notKnown`，不区分大小写。任何其他值返回 `400`。未知类型时请省略：账户类型交叉比对随后将报告为未确认。 phone_number: type: string description: >- 联系手机号码，用于交叉核验可联络性的服务（`zaf_bank_account_holder`、`zaf_fraud_prevention`、`zaf_refugee`）。 right_thumb: type: string description: >- 用于 `zaf_dha_fingerprint_match` 的 Base64 编码右手拇指指纹，可与 `left_thumb` 一起提供或单独提供。 left_thumb: type: string description: >- 用于 `zaf_dha_fingerprint_match` 的 Base64 编码左手拇指指纹，可与 `right_thumb` 一起提供或单独提供。 score_level: type: integer description: '`zaf_criminal_face_screening` 的最低生物识别评分等级。默认为 `3`。' max_matches: type: integer description: '`zaf_criminal_face_screening` 返回的候选匹配项最大数量。默认值为 `1`。' vehicle_register_number: type: string description: >- 车辆登记编号。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_licence_plate` 和 `vin` 一同提供。 vehicle_licence_plate: type: string description: >- 车辆号牌号码。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vin` 一同提供。 vin: type: string description: >- 车辆识别代号（VIN 或车架号）。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vehicle_licence_plate` 一同提供。 ssn: type: string description: 社会安全号码（美国）。 phone: type: string description: 用于电话验证服务的电话号码。 landline: type: string description: 用于电话验证服务的座机号码。 email: type: string format: email description: 用于身份验证服务的邮箱地址。 country_of_residence: type: string description: >- 居住国家/地区的 ISO 3166-1 alpha-2 代码。供全球身份信息增强服务（例如 `glb_identity_enrichment`）用于限定查询范围。 example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- `partial_match` 对 `database_validation.status` 的影响。默认值为 `NO_ACTION`（状态保持为 `Approved`，并附带警告）。 no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- `no_match` 对 `database_validation.status` 的影响。默认值为 `DECLINE`。 save_api_request: type: boolean default: true description: >- 将核验持久化为会话（控制台可见性、决策 endpoint、`status.updated` Webhook）。同时会改变 `validations` 响应的格式：为 `true`（默认）时按服务返回对象，为 `false` 时返回合并的字段映射。 vendor_data: type: string description: 您为已核验用户指定的标识符；将原样返回并与会话一起存储。 metadata: type: object nullable: true description: 随请求一同存储并回显的自由格式 JSON。 selfie: type: string format: binary description: >- 用于生物识别验证服务（例如阿根廷 RENAPER `arg_renaper` 和巴拿马 SIB `pan_cedula_sib`、`pan_cedula_sib_plus`）的自拍图像（`jpg`、`jpeg`、`png`、`webp`；最大 2 MB — 图像在上传至登记处前会压缩至约 1.5 MB）。只要所选服务将其列为必填字段，即为必填项。仅支持通过 `multipart/form-data` 提供。 responses: '200': description: >- 核验已完成：至少有一个选定的服务返回了可用结果。请查看 `database_validation.match_type` 获取汇总结果，查看 `validations` 获取按服务划分的字段比对和 `outcome_code`s，以及查看 `errors`（若存在）获取失败的服务信息。 content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。 database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- 当整体 `match_type` 触发 `DECLINE` 操作时为 `Declined`（`no_match_action` 默认为 `DECLINE`，`partial_match_action` 默认为 `NO_ACTION`）；当没有服务产生可用的比对结果时为 `In Review`，例如唯一选择的服务返回了 `REGISTRY_UNAVAILABLE` 或 `INCONCLUSIVE`；否则为 `Approved`。选择多个服务的请求可能在一个服务匹配成功时为 `Approved`，而另一个服务不可用，因此请同时检查 `errors` 以及每个服务的 `outcome_code`。 issuing_state: type: string description: 用于核验的 ISO 3166-1 alpha-3 国家/地区代码回显。 example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- 根据结果派生：当 ≥2 个不同的服务产生完全匹配时为 `two_by_two`（匹配证件号码、同时匹配姓名 + 出生日期，或匹配地址且无冲突）；否则为 `one_by_one`。（请求中同名字段已被弃用且会被忽略。） screened_data: type: object description: >- 回显发送给所选服务的输入字段（日期已标准化为 `YYYY-MM-DD`；若发送了 `selfie`，则作为预签名 URL 返回；获得同意时会添加 `consent_obtained: true`）。 match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- 跨具有字段级比对的服务聚合的总体结果：任意 `full_match` → `full_match`；否则任意 `partial_match` → `partial_match`；否则 `no_match`。仅返回结果的服务（如生物识别犯罪筛查）可能返回 `null`；请检查 `validations` 中的每个条目以获取其 `outcome_code`。 validations: description: >- 结构取决于 `save_api_request`。**`true`（默认）：** 按服务划分的对象数组（`service_id`、`service_name`、`validation`、`outcome_code`、`outcome_detail`、`source_data`）。**`false`：** 合并所有服务字段级结果的单个扁平对象（`{"full_name": "full_match", ...}`）。 oneOf: - type: array items: type: object description: 逐项服务验证结果（在 `save_api_request=true` 时返回，此为默认值）。 properties: service_id: type: string description: 生成此结果的服务的目录 ID（例如 `bra_cpf`）。 example: bra_cpf service_name: type: string description: 服务在目录中便于人类阅读的名称。 example: Brazil - CPF status check validation: type: object description: >- 您的输入与登记记录之间的逐字段比对。键为规范字段名（`full_name`、`date_of_birth`、`identification_number`、`address` 等）；值为 `full_match`、`partial_match` 或 `no_match`。 additionalProperties: type: string enum: - full_match - partial_match - no_match outcome_code: type: string enum: - MATCH - PARTIAL_MATCH - NO_MATCH - DOCUMENT_NOT_FOUND - INVALID_DOCUMENT_FORMAT - INVALID_INPUT - MINOR_BLOCKED - DECEASED - BIOMETRIC_NO_MATCH - BIOMETRIC_IMAGE_UNUSABLE - INCONCLUSIVE - DOCUMENT_SUPERSEDED - REGISTRY_UNAVAILABLE - REGISTRY_ERROR description: >- 登记处查询的中立结果。`MATCH`/`PARTIAL_MATCH`/`NO_MATCH` 描述比对情况；`DOCUMENT_NOT_FOUND` 表示登记处中不存在该标识符；`INCONCLUSIVE` 表示登记处无法确认任何一种情况（转入人工审核 — 并非不匹配）；`BIOMETRIC_NO_MATCH` 表示明确的人脸不匹配，而 `BIOMETRIC_IMAGE_UNUSABLE` 表示图像技术问题（需重新拍摄自拍照）；`DECEASED`/`MINOR_BLOCKED` 为登记处策略结果；`DOCUMENT_SUPERSEDED` 表示身份匹配，但出示的证件版本与存档的不一致（已签发更新的版本）；`INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` 表示登记处本身拒绝了所发送的数据；`REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` 表示上游服务故障。 outcome_detail: type: string nullable: true description: 支撑结果代码的原始上游状态详情（例如 HTTP 或登记处状态码）。 source_data: type: object nullable: true description: >- 使用规范字段名称（`identification_number`、`first_name`、`last_name`、`date_of_birth`，以及登记机构专有标志）整理并标准化的登记机构记录视图。图像字段（若存在）将作为预签名 URL 返回。 - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: 合并后的字段级结果（无状态 `save_api_request=false` 结构）。 warnings: type: array items: type: object properties: feature: type: string description: 引发该警告的功能。 risk: type: string description: 机器可读的风险标识符。 additional_data: type: object nullable: true description: 警告的额外上下文（若有）。 log_type: type: string description: '`warning`、`information` 或 `error`：风险如何影响结果。' short_description: type: string description: 单行人类可读的摘要。 long_description: type: string description: 完整的人类可读解释说明。 description: >- 适用时为 `DATABASE_VALIDATION_NO_MATCH` 或 `DATABASE_VALIDATION_PARTIAL_MATCH`；完全匹配时为空。 errors: type: array description: >- 仅在部分（但非全部）所选服务失败时存在。每个条目包含 `service_id`、`code`、`message` 和 `retryable`。此处报告的服务不会出现在 `validations` 和 `services_used` 中，且不计费。该数组是其唯一出现的位置，因此即使 `status` 为 `Approved` 也应进行检查。 items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- 当服务未产生响应且稍后重试可能成功时为 `true`；当数据源拒绝了发送的数据且必须先更正输入时为 `false`。 example: true services_used: type: array items: type: string description: 返回了计费结果的服务的目录 ID。**仅在请求显式发送了 `services` 时提供。** match_score: type: number description: >- 产生完全匹配（在证件号码上、姓名与出生日期组合上，或在没有矛盾的地址上）的尝试服务比例（0.0–1.0）。**仅在请求显式发送了 `services` 时存在。** vendor_data: type: string nullable: true description: 回显您发送的 `vendor_data`。 metadata: type: object nullable: true description: 您发送的 `metadata` 回显。 created_at: type: string format: date-time examples: Full match (Approved): summary: 默认 save_api_request=true — 各服务的 `validations` 对象 value: request_id: 7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' Explicit services (extended shape): summary: 发送包含 `services` 的请求 — 响应会添加 `services_used` 和 `match_score` value: request_id: b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] services_used: - bra_cpf match_score: 1 vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' No match (Declined): summary: 公司登记记录不匹配 — 默认 `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: '`validations` 会折叠为合并的字段映射；不存储任何内容' value: request_id: c4d5e6f7-8901-2345-6789-abcdef012345 database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: full_name: full_match date_of_birth: full_match identification_number: full_match warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:32:00.000000+00:00' '400': description: >- 验证错误 - 未产生任何计费。预检字段错误会在执行任何外部调用之前发生。如果所有未响应的尝试均明确拒绝了该输入，则响应将包含 `code: provider_rejected_input` 且 `retryable: false` 的 `validation_errors`；重试前请更正输入。字段级问题使用 DRF 的标准包装格式；目录问题返回 `services` 数组（相关时还会附加 `requires_onboarding` 或 `services_requiring_consent`）；缺少字段的错误包含 `fields_required_by`，用于将每个缺失字段映射到需要它的服务；需要至少一个额外标识符的服务（例如 `usa_states_credit_bureau`，该服务无法仅凭姓名进行验证）将返回 `any_field_required_by`，用于将各服务映射到必须至少提供其中之一的字段；按服务检查的格式问题返回 `invalid_fields_by_service`。 content: application/json: examples: Invalid issuing_state: summary: 不支持的国家/地区 — 消息列出所有有效的 alpha-3 代码 value: error: - >- Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE Missing required fields: summary: 所选服务中必需字段的并集，带有通用字段提示 value: error: - >- Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA) fields_required_by: tax_number: - bra_cpf Unknown service id: summary: '`services` 包含目录中不存在的 id' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: '`services` 指定了来自其他国家/地区的服务（或存根条目）' value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: 服务存在，但尚未为您的组织激活 value: services: - >- Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them. requires_onboarding: - aus_australia_driver_licence Consent missing: summary: 所选服务被标记为 requires_consent=true 且 `consent` 不为 `true` value: consent: - >- Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`. services_requiring_consent: - chn_national_id Country format rule violation: summary: 标识符不符合该国家/地区的格式规则（长度/数字/正则表达式） value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: 字段不符合所选服务自身的格式要求 value: error: - >- One or more fields do not match the format required by the selected service. invalid_fields_by_service: chn_national_id: - national_id_format Input refused by every attempt: summary: 重试前请更正输入 value: error: >- The source refused to run this query with the supplied input. validation_errors: - service_id: bra_cpf code: provider_rejected_input message: >- The source refused to run this query with the supplied input. retryable: false schema: type: object additionalProperties: true properties: error: description: 请求级说明或预检字段错误。 oneOf: - type: string - type: array items: type: string validation_errors: type: array description: 在所有未应答的尝试都在预检后拒绝了输入时存在。 items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: 稍后重试是否能够解决此服务故障。为 False 时表示须先修正所提供的输入。 '403': description: >- 权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{"detail": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{"error": ...}`。 content: application/json: examples: Missing or invalid API key: summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销 value: detail: You do not have permission to perform this action. Not enough credits: summary: 组织余额不足以支付本次调用 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。 content: application/json: examples: Write rate limit exceeded: summary: 当前分钟内的写入请求超过 300 次 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '502': description: >- 所选服务均未返回可用结果。在重试之前请检查每个 validation_errors 条目；仅凭 HTTP 502 无法确定是否为暂时性故障。带有 retryable: true 的 empty_provider_response 表示结果不可用或原因不明，包括主要服务被拒绝且随后的回退服务不可用。相比之下，传统的 provider_invalid_input 和 provider_validation_error 条目需要更正输入，并且可能会省略 retryable。此操作不计费。当 save_api_request=true 时，失败的尝试将被记录为状态为 Not Finished 的会话。部分失败将返回 200 及 database_validation.errors。 content: application/json: schema: type: object properties: error: type: string validation_errors: type: array items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: 稍后重试是否能够解决此服务故障。为 False 时表示须先修正所提供的输入。 examples: Provider returned no result: summary: 所有选定的服务均失败 value: error: >- Database validation could not be performed. The external validation service did not return a result. Please try again later. validation_errors: - service_id: bra_cpf code: empty_provider_response message: >- The provider did not return a database validation result. retryable: true security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "issuing_state": "BRA", "services": ["bra_cpf"], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_cpf"], identification_number="12345678900", first_name="John", last_name="Doe", date_of_birth="1980-01-01", vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_cpf'], 'identification_number' => '12345678900', 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1980-01-01', 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.