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

# Carta de condução da África do Sul - API de verificação

> Verificação de carta de condução na África do Sul numa base de dados oficial via Didit. A partir de $0.80 por chamada, sem contratos.

Verifica uma carta de condução sul-africana junto do registo NATIS / Departamento de Transportes. A Didit disponibiliza este serviço através de `POST /v3/database-validation/`, para que possa validar os dados submetidos com base na fonte oficial e receber resultados de correspondência normalizados.

## Cobertura

* **Cobertura:** —
* **País:** África do Sul
* **ID do serviço:** `zaf_drivers_license`
* **Domínio de dados:** Identidade
* **Categoria:** DriverLicence

## Entradas

| Campo | Obrigatório | Exemplo |
| - | -: | - |
| `national_id` | Sim | `SAMPLE-NID-12345` |
| `last_name` | Sim | `Doe` |
| `initials` | Sim | `JD` |
| `licence_number` | Sim | `LIC123456` |
| `first_name` | Não | `John` |
| `date_of_birth` | Não | `1990-01-01` |
| `vendor_data` | Não | `user-1234` |

* **Entradas obrigatórias:** `national_id`, `last_name`, `initials`, `licence_number`
* **Entradas opcionais:** `first_name`, `date_of_birth`, `vendor_data`
* **Consentimento:** Não é necessário
* **Disponibilidade no fluxo:** Disponível no fluxo com mapeamento de campos
* **Cobertura:** —
* **Preço:** \$0.80 por consulta bem-sucedida

Num fluxo, `initials` e `licence_number` não são impressos num documento de identidade, por isso nenhum passo os produz por si só. Recolha-os a partir de uma resposta de questionário, de um campo extraído pelo Document AI ou de um valor que envie ao criar a sessão, e mapeie cada um deles no passo de Validação de base de dados. Enquanto não estiverem mapeados, o editor de fluxos mostra este serviço desativado e indica o campo em falta. Em execução, um campo em falta faz com que a verificação seja ignorada antes de qualquer consulta, pelo que nunca é cobrada uma base de dados que não pôde ser consultada.

## Parâmetros do corpo

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

Código de país ISO 3166-1 alpha-3 para este serviço de base de dados.

Exemplo: `ZAF`

**services** `string` *required* (default: zaf\_drivers\_license)

Array que contém o ID deste serviço. Fixar o serviço mantém o pedido limitado a esta base de dados exata.

Exemplo: `zaf_drivers_license`

**national\_id** `string` *required* (default: SAMPLE-NID-12345)

Número de identificação nacional para este serviço.

Exemplo: `SAMPLE-NID-12345`

**last\_name** `string` *required* (default: Doe)

Apelido a validar.

Exemplo: `Doe`

**initials** `string` *required* (default: JD)

Valor de `initials` exigido por este serviço de base de dados.

Exemplo: `JD`

**licence\_number** `string` *required* (default: LIC123456)

Valor de `licence_number` exigido por este serviço de base de dados.

Exemplo: `LIC123456`

**first\_name** `string`

Nome próprio a validar.

Exemplo: `John`

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

Data de nascimento no formato `YYYY-MM-DD`.

Exemplo: `1990-01-01`

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

A sua referência estável de utilizador para esta pessoa, como o ID interno do utilizador. A Didit usa-a para associar verificações independentes ao mesmo utilizador final e reduzir o ruído na deteção de duplicados.

Exemplo: `user-1234`

## Regras de entrada e notas de validação

* Envie os campos indicados acima exatamente como foram recolhidos do utilizador ou do documento.
* A Didit valida os campos obrigatórios antes de chamar a base de dados. Os pedidos rejeitados antes da consulta à fonte não são cobrados.

## Como chamar

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=ZAF" \
  -F "services=zaf_drivers_license" \
  -F "vendor_data=user-1234" \
  -F "national_id=SAMPLE-NID-12345" \
  -F "last_name=Doe" \
  -F "initials=JD" \
  -F "licence_number=LIC123456"
```

Todas as chamadas bem-sucedidas devolvem HTTP `200`. O campo **`outcome_code`** indica o que aconteceu de facto, distinguindo, por exemplo, uma divergência biométrica real (`BIOMETRIC_NO_MATCH`) de uma selfie que não pôde ser lida (`BIOMETRIC_IMAGE_UNUSABLE`). O `status` apresentado é o estado predefinido da funcionalidade; as [ações de Correspondência parcial / Sem correspondência](https://docs.didit.me/pt/core-technology/database-validation/database-validation-warnings.md) que tiver configurado podem substituí-lo.

**`MATCH`** — O registo devolveu um registo de carta de condução para este número de carta e os dados submetidos correspondem a esse registo.

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "ZAF",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "zaf_drivers_license",
      "service_name": "South Africa - Driving License Verification",
      "source_data": {
        "expiration_date": "2030-05-31",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe",
        "vehicle_codes": "EB"
      },
      "validation": {
        "full_name": "full_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`NO_MATCH`** — O registo pesquisou a carta e indicou que não é válida. Aplica-se a sua ação para casos sem correspondência.

```json 200 OK — NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "ZAF",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "zaf_drivers_license",
      "service_name": "South Africa - Driving License Verification",
      "source_data": {
        "licence_valid": false
      },
      "validation": {}
    }
  ]
}
```

**`INCONCLUSIVE`** — O registo aceitou a consulta, mas não devolveu nenhum registo de carta com o qual comparar os dados submetidos, pelo que nada sobre a carta fica confirmado e a verificação é enviada para revisão - também quando outro serviço do mesmo pedido correspondeu à pessoa.

```json 200 OK — INCONCLUSIVE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "ZAF",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "INCONCLUSIVE",
      "service_id": "zaf_drivers_license",
      "service_name": "South Africa - Driving License Verification",
      "source_data": {
        "licence_valid": true
      },
      "validation": {}
    }
  ]
}
```

## Dados devolvidos

Os campos exatos apresentados em `source_data` dependem do que o registo devolve. O exemplo gerado para `zaf_drivers_license` documenta atualmente esta estrutura normalizada:

* `expiration_date`
* `first_name`
* `identification_number`
* `last_name`
* `licence_valid`
* `vehicle_codes`

## Preços e SLAs

África do Sul - Verificação de carta de condução: as consultas são cobradas apenas quando a Didit recebe um resultado conclusivo da fonte de validação.

* **Preço por chamada:** \$0.80 USD.
* **Faturação:** por consulta bem-sucedida. Não lhe é cobrado qualquer valor quando o registo está inacessível, quando faltam campos obrigatórios ou quando o pedido é rejeitado antes de chegar à fonte.
* **Latência:** p95 típico \< 2 s.
* **Disponibilidade:** 99.9% por trimestre do lado da Didit; a disponibilidade das fontes a jusante varia consoante o país e o conjunto de dados.

## O que significa cada resultado

Esta verificação consulta o registo de cartas de condução sobre o número da carta que envia, juntamente com o número de identificação sul-africano, o apelido e as iniciais. O resultado depende do que o registo devolve:

* **`MATCH`** - o registo devolveu um registo de carta para este número, e os dados que submeteu correspondem a esse registo. `source_data` contém o registo: `identification_number` (o número da carta), `first_name` e `last_name`, `vehicle_codes` (as categorias da carta, por exemplo `EB`, `C1`) e `expiration_date` (a data de validade do cartão da carta).
* **`INCONCLUSIVE`** - o registo aceitou a consulta, mas não devolveu nenhum registo de carta, pelo que não havia nada com que comparar os dados submetidos. `source_data.licence_valid` é `true`, `validation` está vazio e `match_type` é `null`. Nada sobre a carta fica confirmado, pelo que a verificação é enviada para revisão. Isto acontece mesmo quando outro serviço do mesmo pedido, como a verificação do número de identificação nacional, correspondeu à pessoa, porque isso confirma a pessoa e não a carta.
* **`NO_MATCH`** - o registo procurou a carta e indicou que não é válida (`source_data.licence_valid: false`). Aplica-se a sua ação de não correspondência.
* **`REGISTRY_ERROR`** - o registo não executou a pesquisa, pelo que nada ficou estabelecido sobre a carta. A verificação é enviada para revisão e não é faturada.

**O que nunca é devolvido.** Não existe nenhum campo de suspensão, cancelamento, retirada, averbamento ou pontos de penalização. Por isso, mesmo um `MATCH` não pode ser apresentado aos seus utilizadores como "a carta é válida e está em situação regular". `expiration_date`, quando o registo a devolve, é o único facto próximo da situação regular a que tem acesso. Compare-a com a data da sessão para decidir se a carta expirou, e trate essa comparação como uma regra sua, e não como parte do resultado de correspondência.

Se precisar de o indicar nos termos e condições, formule-o assim: A Didit verifica os dados da carta junto do registo nacional e, quando o registo devolve um registo de carta, as respetivas categorias e a respetiva data de validade, mas não confirma que o titular está habilitado a conduzir hoje.

## Continuar a ler

* [Visão geral da Validação de base de dados na África do Sul](https://docs.didit.me/api-reference/database-validation/south-africa.md)
* [Visão geral da Validação de base de dados](https://docs.didit.me/pt/core-technology/database-validation/overview.md)
* [Códigos de resultado](https://docs.didit.me/pt/core-technology/database-validation/database-validation-outcome-codes.md)


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