> ## 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.

# 巴西 CNH 二维码与人脸比对（Datavalid）API

> Didit 提供巴西 CNH 二维码与人脸比对：权威巴西数据库核验，按次计费，最低 $0.62 起，无合同、无最低消费。

SERPRO Datavalid v4 pf-facial-qrcode 解码巴西 CNH 驾驶证（实体或电子版，2017 年 5 月起签发）上打印的二维码，将 CPF、姓名和出生日期与 Receita Federal 进行核验，并将实时自拍与存储在 Senatran 的 CNH 证件照进行比对。Didit 通过 `POST /v3/database-validation/` 提供该服务，使您能够将提交的数据与权威来源进行核对，并获得标准化的匹配结果。输入格式：`tax_number` 接受巴西 CPF（恰好 11 位数字）。

## 覆盖范围

* **覆盖范围：** —
* **国家/地区：** 巴西
* **服务 ID：** `bra_cnh_facial_qrcode`
* **数据领域：** 生物识别
* **类别：** DriverLicence

## 输入

| 字段 | 必填 | 示例 |
| - | -: | - |
| `tax_number` | 是 | `11111111111` |
| `selfie` | 是 | `@./selfie.jpg` |
| `cnh_qr_code_image` | 是 | `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB` |
| `first_name` | 否 | `John` |
| `last_name` | 否 | `Doe` |
| `date_of_birth` | 否 | `1990-01-01` |
| `vendor_data` | 否 | `user-1234` |

* **必填输入：** `tax_number`、`selfie`、`cnh_qr_code_image`
* **可选输入：** `first_name`、`last_name`、`date_of_birth`、`vendor_data`
* **同意：** 必填
* **工作流可用性：** 可在工作流中使用
* **覆盖范围：** —
* **价格：** 每次成功查询 \$0.62

## 请求体参数

**issuing\_state** `string` *required* (default: BRA)

此数据库服务的 ISO 3166-1 alpha-3 国家/地区代码。

示例：`BRA`

**services** `string` *required* (default: bra\_cnh\_facial\_qrcode)

包含此服务 ID 的数组。固定该服务可将请求限定在此特定数据库范围内。

示例：`bra_cnh_facial_qrcode`

**consent** `boolean` *required* (default: true)

此服务的终端用户明确同意。

示例：`true`

**tax\_number** `string` *required* (default: 11111111111)

税务或财政识别号。

示例：`11111111111`

**selfie** `file` *required*

用于生物识别数据库核验而上传的自拍图片文件。支持格式：JPEG、PNG 或 WebP。

示例：`@./selfie.jpg`

**cnh\_qr\_code\_image** `string` *required* (default: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB)

此数据库服务所需的 `cnh_qr_code_image` 值。

示例：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB`

**first\_name** `string`

需要验证的名字。

示例：`John`

**last\_name** `string`

需要验证的姓氏。

示例：`Doe`

**date\_of\_birth** `string`

出生日期，格式为 `YYYY-MM-DD`。

示例：`1990-01-01`

**vendor\_data** `string` (default: user-1234)

您为此用户设定的稳定用户标识，例如您内部的用户 ID。Didit 利用它将独立检查关联到同一终端用户，并减少重复检测的干扰。

示例：`user-1234`

## 输入规则与验证说明

* 巴西 CPF（恰好 11 位数字）
* `tax_number` 只能包含数字；发送请求前，请先移除空格、连字符和标点符号。
* `tax_number` 的长度必须恰好为 11 个字符。

## 调用方法

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=BRA" \
  -F "services=bra_cnh_facial_qrcode" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "tax_number=11111111111" \
  -F "selfie=@./selfie.jpg" \
  -F "cnh_qr_code_image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB"
```

每次成功调用都会返回 HTTP `200`。**`outcome_code`** 字段会告诉您实际发生了什么，例如能区分真实的生物识别不匹配（`BIOMETRIC_NO_MATCH`）与无法读取的自拍（`BIOMETRIC_IMAGE_UNUSABLE`）。显示的 `status` 为默认功能状态；您配置的[部分匹配/无匹配操作](https://docs.didit.me/zh/core-technology/database-validation/database-validation-warnings.md)可以覆盖它。

**`MATCH`** — 登记机构确认了身份，且所有已检查字段均匹配。

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "BRA",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "bra_cnh_facial_qrcode",
      "service_name": "Brazil - CNH QR code + face match (Datavalid)",
      "source_data": {
        "cnh_qrcode": "sample_value",
        "date_of_birth": "1990-01-01",
        "face_match_probability": "Altíssima probabilidade",
        "face_match_score": "0.990",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe",
        "name_match_score": "1.000",
        "verifications": {
          "identification_number": true
        }
      },
      "validation": {
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`NO_MATCH`** — 登记机构未返回与所提交数据匹配的结果。

```json 200 OK — NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "bra_cnh_facial_qrcode",
      "service_name": "Brazil - CNH QR code + face match (Datavalid)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`BIOMETRIC_NO_MATCH`** — 人脸比对分数低于接受阈值，自拍与登记机构照片并非同一人。

```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_NO_MATCH",
      "service_id": "bra_cnh_facial_qrcode",
      "service_name": "Brazil - CNH QR code + face match (Datavalid)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`BIOMETRIC_IMAGE_UNUSABLE`** — 无法处理该自拍（为空、未检测到人脸、质量过低，或登记机构无法读取）。请提示用户重新拍摄自拍。

```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
      "service_id": "bra_cnh_facial_qrcode",
      "service_name": "Brazil - CNH QR code + face match (Datavalid)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

## 返回数据

`source_data` 中实际返回的字段取决于登记机构的返回内容。`bra_cnh_facial_qrcode` 生成的示例目前记录了以下标准化结构：

* `cnh_qrcode`
* `date_of_birth`
* `face_match_probability`
* `face_match_score`
* `first_name`
* `identification_number`
* `last_name`
* `name_match_score`

## 定价与 SLA

巴西 CNH 二维码 + 人脸比对（Datavalid）查询，仅在 Didit 从验证来源收到确定性结果时计费。

* **单次调用价格：** \$0.62 USD。
* **计费方式：** 每次成功查询计费。若登记机构无法访问、缺少必填字段，或请求在到达来源之前被拒绝，则不收费。
* **延迟：** 典型 p95 小于 2 秒。
* **可用性：** Didit 方面每季度 99.9%；下游来源的可用性因国家/地区和数据集而异。

## 延伸阅读

* [巴西数据库核验概览](https://docs.didit.me/api-reference/database-validation/brazil.md)
* [数据库核验概览](https://docs.didit.me/zh/core-technology/database-validation/overview.md)
* [结果代码](https://docs.didit.me/zh/core-technology/database-validation/database-validation-outcome-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.