> 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/midapi-v2/document-services/document-validation.md).

# Validação de documentos

**Document Validation** é o serviço que analisa o Documento de identidade (e, opcionalmente, uma selfie) e determina se são autênticos e consistentes entre si. O serviço se integra como parte do ecossistema de APIs de Facephi.

A partir do documento (e, se fornecida, a selfie), o serviço executa um conjunto de validações antifraude e devolve um diagnóstico único:

* **APPROVED**: o documento (e, se for o caso, a correspondência com a selfie) supera as validações.
* **DECLINED**: é detectada uma inconsistência, manipulação ou descumprimento de qualidade/formato que impede validar o documento.
* **DOUBTFUL**: a análise não é conclusiva. O documento não é confirmado como autêntico nem é rejeitado, e a decisão fica a cargo do consumidor. Só aparece na modalidade automática.

### Natureza assíncrona

Document Validation é um serviço assíncrono: a chamada que inicia a validação não bloqueia aguardando o resultado. Responde imediatamente com um identificador de transação (`transactionId`) e o consumidor obtém o resultado por meio de consultas de estado (polling).

### Modalidades do serviço

Document Validation é oferecido em duas modalidades, definidas no cadastro do serviço e não escolhidas por requisição:

* **Automática**: o diagnóstico é emitido integralmente pelo motor antifraude de Facephi. Quando a análise não chega a uma conclusão, a transação termina com `diagnostic = DOUBTFUL` e seu `rejectionReason` correspondente.
* **Híbrida**: quando a análise inicial não é conclusiva, o caso passa por uma verificação adicional escalonada antes de ser resolvido. O diagnóstico final é **sempre `APPROVED` ou `DECLINED`: esta modalidade não retorna `DOUBTFUL`**. Os códigos de razão 600 a 603 aparecem apenas aqui.

Se você não sabe qual a sua integração tem, consulte o suporte.

### Fluxo de integração

A inicialização (Token, operação e upload de assets) é comum a todos os serviços que trabalham por referência e está desenvolvida em [Fluxo comum](/docs.facephi-pt-br/api-rest/midapi-v2/flujo-comun.md). A partir daí:

1. Concluir os passos prévios do [Fluxo comum](/docs.facephi-pt-br/api-rest/midapi-v2/flujo-comun.md), incluindo a [subida dos assets](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md) do documento e, opcionalmente, a selfie.
2. [Iniciar a validação](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/iniciar-validacion.md) enviando as `fileKeys` obtidas tal como estão, com o `operationId` no cabeçalho `operation-id`. O serviço responde imediatamente com um `transactionId`.
3. [Consultar o estado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/consultar-estado.md) da transação por meio de polling até obter um estado terminal.

```mermaid
sequenceDiagram
    actor C as Consumer
    participant API as MIDAPI v2

    Note over C,API: Etapas prévias: Token, operação e upload de assets (ver Fluxo comum)

    C->>API: POST /document/validate (fileKeys + operation-id)
    API-->>C: 202 transactionId, status PROCESSED

    loop Polling até estado terminal
        C->>API: GET /document/validate/{transactionId}
        API-->>C: status IN_PROGRESS
    end

    C->>API: GET /document/validate/{transactionId}
    API-->>C: COMPLETED + diagnostic + rejectionReason + diagnostics[] + ocr
```

A cadência de sondagem recomendada está em [Boas práticas](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/buenas-practicas.md), e o detalhe da resposta terminal em [Resposta de resultado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md).

{% hint style="info" %}
Document Validation trabalha **exclusivamente por referência**: não aceita o conteúdo dos assets em linha. O modelo de referência comum a toda a API está em [Armazenamento](/docs.facephi-pt-br/api-rest/midapi-v2/storage.md).
{% endhint %}

{% hint style="warning" %}
**Mudança de rotas.** A validação documental agora é publicada em `/document/validate`. As rotas anteriores continuam sendo atendidas para não quebrar as integrações existentes, mas estão obsoletas e deixarão de ser documentadas:

O contrato não muda: mesmos cabeçalhos, mesmo corpo da requisição e mesmas respostas. Só muda a rota.
{% endhint %}

| Rota anterior              | Rota atual                               |
| -------------------------- | ---------------------------------------- |
| `POST /daf/validate`       | `POST /document/validate`                |
| `GET /daf/{transactionId}` | `GET /document/validate/{transactionId}` |
| `POST /daf/fraud-report`   | `POST /document/validate/fraud-report`   |