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

# Boas práticas

### Estratégia de sondagem

Consultar o estado por meio de 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 se resolve 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 15 a 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 contatar 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 interna adicional antes de serem resolvidas.

### Gerenciamento de estados

* `COMPLETED`: ler `diagnostic` e, se for `DECLINED` ou `DOUBTFUL`, `rejectionReason`/`diagnostics[]` para informar o usuário final. Um `DOUBTFUL` não é uma rejeição: a análise não foi conclusiva e a decisão fica a seu critério (ver [Modalidades do serviço](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation.md#modalidades-del-servicio)).
* `ERROR` / `FAILED`: tratar como erro de Integração ou do serviço. Revisar os dados enviados e tentar novamente, se for o caso.
* `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/document-services/document-validation/consultar-estado.md)). Para o restante dos valores de `failureReason`, consultar sua tabela em [Consultar o estado](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/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 o mesmo `operationId` no envio de assets e no cabeçalho `operation-id` do início da validação: todas as `fileKeys` de uma requisição devem pertencer a essa mesma operação.
* Criar a operação **quando a captura começa**, não antes: expira em 15 minutos por padrão, e uma operação expirada obriga a criar outra e reenviar os assets.
* Reenviar a cada `fileKey` tal como foi retornada por `POST /storage`, sem compô-la nem interpretá-la. Se precisar recuperá-las, use [Get File Keys](/docs.facephi-pt-br/api-rest/midapi-v2/operations/get-file-keys.md).
* Tratar `transactionId` como um identificador opaco. Não inferir informação de 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 /document/validate` e em cada consulta de status). É 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 guardá-lo junto ao `transactionId`.
* **`timestamp`** da transação (formato ISO-8601) e os identificadores que você informa nos cabeçalhos: `operation-id` e `consumer-id`.

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