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

# Consultar status (polling)

Consulte o estado de uma transação DAF até obter um estado terminal. Enquanto a transação não tiver sido concluída, a resposta contém apenas o identificador e o estado. Ao alcançar um estado terminal com diagnóstico, inclui também a [resposta de resultado](/docs.facephi-pt-br/api-rest/midapi-v2/daf/respuesta-de-resultado.md) completa.

### Endpoint

```
GET /v2/daf/{transactionId}
```

### Cabeçalhos

| Nome              | Tipo   | Obrigatório | Descrição                                                                                                                    |
| ----------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sim**     | Token de consumer no formato `Bearer <token>` (ver [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/sessão de negócio.                                                                                 |

### Parâmetros de rota

| Parâmetro       | Tipo   | Obrigatório | Descrição                                                         |
| --------------- | ------ | ----------- | ----------------------------------------------------------------- |
| `transactionId` | string | **Sim**     | Identificador da transação retornado por `POST /v2/daf/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/daf/respuesta-de-resultado.md).

### Estados da transação

| Estado        | 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 (`APROVADO` ou `RECUSADO`).                   | 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: o consumer não pode saber nem precisa saber quais validações específicas foram executadas internamente. Diante de `ERROR` ou `FAILED`, não haverá `diagnostic` nem `ocr` na resposta. O estado `FAILED` de fato 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**. O detalhe técnico interno não é exposto; estes são os valores possíveis:

| failureReason                             | Significado / ação recomendada                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Validation could not be completed`       | Falha transitória do processamento (por exemplo, um serviço de análise não respondeu a tempo ou retornou um erro). É seguro **tentar novamente** iniciando uma nova transação com os mesmos assets; se persistir, contate o suporte. |
| `Internal processing error`               | Erro inesperado durante o processamento. Tente novamente mais tarde; se persistir, contate o suporte.                                                                                                                                |
| `Asset not found in storage: <fileKey>`   | Não foi possível resolver um dos assets referenciados. Verifique se as `fileKeys` existem e foram enviados corretamente antes de tentar novamente.                                                                                   |
| `Invalid <front\|back\|face> asset token` | O asset indicado não é um token de captura válido. Capture/envie esse asset novamente e reinicie o processo.                                                                                                                         |

{% hint style="info" %}
`failureReason` é deliberadamente **genérico**: diferentes causas internas (incluindo os timeouts da análise) são agregadas em `Validation could not be completed`. O detalhe concreto fica nos registros internos do serviço; se precisar diagnosticar um caso, compartilhe-o com o suporte junto com o `transactionId`.
{% endhint %}