> 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/buenas-practicas.md).

# Boas práticas

### Estratégia de polling

Consultar o estado por sondagem em fases, já que o tempo de resolução pode variar significativamente entre transações:

* **Fase 1 (sondagem rápida, primeiros \~10 segundos)**: sondar a cada 1 segundo. Cobre o caso habitual, em que a transação é resolvida rapidamente.
* **Fase 2 (backoff exponencial, a partir de \~10 segundos se ainda não houver estado terminal)**: aumentar o intervalo progressivamente (por ex. 2s → 4s → 8s → 15s), com um limite de entre 15 e 20 segundos entre sondagens. Cobre os casos que exigem uma análise adicional e podem demorar substancialmente mais.
* Definir um tempo máximo de espera do lado do consumer (por ex. vários minutos). Se for excedido, tratar o caso como indeterminado e tentar novamente mais tarde ou entrar em contato com o suporte.
* Não assumir um tempo de resposta fixo: a duração pode variar substancialmente entre transações, já que algumas exigem uma análise adicional interna antes de serem resolvidas.

### Tratamento de estados

* `COMPLETED`: ler `diagnostic` e, se for `DECLINED`, `rejectionReason`/`diagnostics[]` para informar o usuário final.
* `ERROR` / `FAILED`: tratar como erro de Integração ou do serviço. Revisar os dados enviados e tentar novamente, se aplicável.
* `FAILED` com `failureReason = Validation could not be completed`: falha transitória do processamento (inclui timeouts internos da análise). É seguro tentar novamente iniciando uma nova transação com os mesmos assets (ver [Consultar o estado](/docs.facephi-pt-br/api-rest/midapi-v2/daf/consultar-estado.md)). Para os demais valores de `failureReason`, consultar a tabela em [Consultar o estado](/docs.facephi-pt-br/api-rest/midapi-v2/daf/consultar-estado.md#failurereason).

### Segurança

* Não armazenar o Token OAuth2 no cliente. Renová-lo conforme sua expiração (ver [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md)).
* Usar um `operation-id` consistente entre o envio de assets e o início da validação, de forma que as `fileKeys` possam ser resolvidas.
* Tratar `transactionId` como um identificador opaco. Não inferir informações do seu formato.

### Rastreabilidade para suporte

Para investigar um caso específico com o suporte, conserve e informe os seguintes identificadores:

* **`transactionId`**: identificador principal da transação (retornado por `POST /v2/daf/validate` e em cada consulta de estado). É o dado-chave para localizar um caso.
* **Cabeçalho de resposta `X-Trace-Id`**: identificador da requisição que a API devolve em cada resposta; permite ao suporte correlacionar a chamada exata. Recomenda-se salvá-lo junto ao `transactionId`.
* **`timestamp`** da transação (formato ISO-8601) e os identificadores que você fornece nos cabeçalhos: `operation-id` e `consumer-id`.

Ao abrir um chamado, inclua sempre o `transactionId` (e o `X-Trace-Id` se você o tiver registrado). Consulte com a Facephi os prazos de retenção aplicáveis à sua Integração.