> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/morphology/document-validation-v2/document-validation-start-v2.md).

# Início da validação de documento V2

Inicia o processo de validação morfológica de documentos de identidade enviando as **imagens do documento, país e tipo** de documento a analisar.

### Endpoint

```
POST /verify/documentValidation/v2/start
```

### Cabeçalhos

| Nome          | Tipo   | Obrigatório | Descrição                                                     |
| ------------- | ------ | ----------- | ------------------------------------------------------------- |
| **x-api-key** | string | **Sim**     | API Key de autorização de acesso.                             |
| **family**    | string | Não         | Valor: **Onboarding**. Obrigatório com o serviço de Tracking. |

{% hint style="info" %}
Todas as chamadas aos Endpoints para Tracking com **Identity Platform** devem conter o header `family`.
{% endhint %}

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro                  | Tipo   | Obrigatório | Descrição                                                                                                                                                            |
| -------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`                  | string | **Sim**     | Código do país **ISO 3166-1 alpha-3**.                                                                                                                               |
| `idType`                   | string | **Sim**     | Tipo do documento fornecido. Valores possíveis: `PASSPORT`, `DRIVING_LICENSE`, `ID_CARD`, `RESIDENCE_PERMIT`, `VISA`                                                 |
| `documentFrontRawImage`    | string | **Sim**     | Imagem codificada em **Base64**, aberta ou tokenizada, da frente do documento.                                                                                       |
| `documentBackRawImage`     | string | Não         | Imagem codificada em **Base64**, aberta ou tokenizada, do verso do documento. Opcional para documentos de uma única face como `PASSPORT`.                            |
| `tokenRawFrontDocument`    | string | Não         | Token da imagem **tokenizada** da frente do documento, gerado pelo SDK Mobile/Web. Alternativa a `documentFrontRawImage` quando se trabalha com imagens tokenizadas. |
| `tokenRawBackDocument`     | string | Não         | Token da imagem **tokenizada** do verso do documento, gerado pelo SDK Mobile/Web. Alternativa a `documentBackRawImage` quando se trabalha com imagens tokenizadas.   |
| `merchantIdScanReference`  | string | Não         | Referência personalizada da operação. **Comprimento máximo: 100 caracteres.**                                                                                        |
| `documentRawImageMimeType` | string | Não         | Formato MIME da imagem. Valores possíveis: `image/png`, `image/jpeg`                                                                                                 |
| `rastreamento`             | object | Não         | Objeto que representa as informações de Tracking necessárias.                                                                                                        |
| `tracking.extraData`       | string | Não         | Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.                                                                       |
| `tracking.operationId`     | string | Não         | Identificador de operação gerado pelo SDK Mobile/Web.                                                                                                                |

{% hint style="info" %}
As imagens do documento podem ser enviadas de duas formas: como imagem codificada em **Base64** (`documentFrontRawImage` / `documentBackRawImage`) ou como imagem **tokenizada** gerada pelo SDK (`tokenRawFrontDocument` / `tokenRawBackDocument`). Use uma ou outra conforme o modo de captura.
{% endhint %}

#### Exemplo de solicitação

```json
{
  "country": "ESP",
  "idType": "ID_CARD",
  "documentRawImageMimeType": "image/jpeg",
  "documentFrontRawImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABC...",
  "documentBackRawImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABC...",
  "merchantIdScanReference": "custom-ref-123",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

#### Exemplo de solicitação com imagens tokenizadas

```json
{
  "country": "ESP",
  "idType": "ID_CARD",
  "documentRawImageMimeType": "image/jpeg",
  "tokenRawFrontDocument": "BQABAQFront9kLmPqYf7R...",
  "tokenRawBackDocument": "BQABAQFBack9kLmPqYf7R...",
  "merchantIdScanReference": "custom-ref-123",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro       | Tipo   | Descrição                                                       |
| --------------- | ------ | --------------------------------------------------------------- |
| `timestamp`     | string | Carimbo de data/hora (UTC) da resposta no formato **ISO 8601**. |
| `scanReference` | string | **Número de referência** para cada escaneamento.                |
| `type`          | string | ⚠️ Valor **obsoleto**. Será removido em versões futuras.        |

#### Exemplo de resposta

```json
{
  "timestamp": "1970-01-01T00:00:00.000Z",
  "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064",
  "type": "1"
}
```

#### `400` Requisição inválida

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

```json
{
  "message": "Unauthorized"
}
```

#### `403` Acesso negado

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Gateway inválido

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Tempo limite do gateway

```json
{
  "message": "Endpoint request timed out"
}
```