> 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/consultar-estado.md).

# Consultar status (polling)

Consulte o status de uma transação de validação até obter um estado terminal. Enquanto a transação não tiver sido finalizada, a resposta contém apenas o identificador e o status. Ao atingir um estado terminal com diagnóstico, inclui também a [resposta de resultado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md) completa.

### Endpoint

```
GET /document/validate/{transactionId}
```

### Cabeçalhos

| Nome              | Tipo   | Obrigatório | Descrição                                                                                                                             |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sim**     | Token de consumer no formato `Bearer <token>` (veja [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md)).         |
| **consumer-id**   | string | **Sim**     | Identificador do consumer.                                                                                                            |
| **operation-id**  | string | **Sim**     | Identificador da [operação](/docs.facephi-pt-br/api-rest/midapi-v2/operations.md) da validação, o mesmo que foi enviado ao iniciá-la. |

### Parâmetros de rota

| Parâmetro       | Tipo   | Obrigatório | Descrição                                                           |
| --------------- | ------ | ----------- | ------------------------------------------------------------------- |
| `transactionId` | string | **Sim**     | Identificador de transação retornado por `POST /document/validate`. |

### Respostas

#### `200` Sucesso (transação em andamento)

```json
{
  "transactionId": "1c7d...e9",
  "status": "IN_PROGRESS"
}
```

#### `200` Sucesso (transação terminal)

Quando a transação atinge um estado terminal com diagnóstico (`COMPLETED`), a resposta inclui também o diagnóstico completo. Veja [Resposta de resultado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md).

### Estados da transação

| Status        | Significado                                                                | Terminal? |
| ------------- | -------------------------------------------------------------------------- | --------- |
| `PROCESSED`   | A transação foi criada e aceita para processamento.                        | Não       |
| `ERROR`       | Não foi possível criar/iniciar a transação (falha na solicitação inicial). | Sim       |
| `IN_PROGRESS` | A validação está em andamento.                                             | Não       |
| `COMPLETED`   | Há um diagnóstico disponível (`APPROVED`, `DECLINED` ou `DOUBTFUL`).       | Sim       |
| `FAILED`      | Falha irrecuperável durante o processamento. Inclui `failureReason`.       | Sim       |

{% hint style="info" %}
O estado terminal `COMPLETED` é único para qualquer resultado com diagnóstico. Diante `ERROR` ou `FAILED`, não haverá `diagnóstico` nem `OCR` na resposta. O status `FAILED` inclui `failureReason` e `timestamp`.
{% endhint %}

### failureReason

Quando `status = FAILED`, o campo `failureReason` descreve a causa da falha com uma mensagem **genérica e estável**. Estes são os valores possíveis:

| failureReason                                      | Significado / ação recomendada                                                                                                                        |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `A validação não pôde ser concluída`               | Falha transitória do processamento. É seguro **tentar novamente** iniciando uma nova transação com os mesmos ativos; se persistir, contate o suporte. |
| `Erro interno de processamento`                    | Erro inesperado durante o processamento. Tente novamente mais tarde; se persistir, contate o suporte.                                                 |
| `Ativo não encontrado no armazenamento: <fileKey>` | Não foi possível resolver um dos ativos referenciados. Verifique se as `fileKeys` existem e foram enviados corretamente antes de tentar novamente.    |
| `Token de ativo <front\|back\|face> inválido`      | O ativo indicado não é um token de captura válido. Capture/enviar novamente esse ativo e reinicie o processo.                                         |

{% hint style="info" %}
`failureReason` é deliberadamente **genérico**: diferentes causas internas (incluindo os timeouts da análise) são agregadas em `A validação não pôde ser concluída`. O detalhe específico fica nos registros internos do serviço; se precisar diagnosticar um caso, compartilhe-o com o suporte junto com o `transactionId`.
{% endhint %}

### Outras respostas

| Código | Descrição                                                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | O cabeçalho `operation-id` está ausente ou vazia.                                                                                                                                         |
| `401`  | Token ausente, inválido ou expirado.                                                                                                                                                      |
| `403`  | O consumer não está provisionado com o serviço `DOCUMENT_ANTIFRAUD`.                                                                                                                      |
| `404`  | A transação não existe ou pertence a outro consumidor.                                                                                                                                    |
| `429`  | O consumer ultrapassou seu limite de taxa de requisições. A resposta inclui `Retry-After` com os segundos de espera, e `X-RateLimit-Limit` e `X-RateLimit-Burst` com os limites vigentes. |
| `503`  | A persistência do serviço não está disponível temporariamente.                                                                                                                            |

O corpo de uma resposta de erro tem o formato descrito em [MIDAPI v2](/docs.facephi-pt-br/api-rest/midapi-v2.md#respuestas-de-error).

{% hint style="warning" %}
O `429` deste endpoint é o do limite de taxa, e convém levá-lo em conta ao escolher a cadência de sondagem: sondar a cada poucos milissegundos o provoca. A estratégia recomendada, por fases e com backoff, está em [Boas práticas](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/buenas-practicas.md).
{% endhint %}