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).

• 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). Para o restante dos valores de failureReason, consultar sua tabela em Consultar o estado.

Segurança

• Não armazenar o token OAuth2 no cliente. Renová-lo conforme sua expiração (ver Autenticação).

• 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.

• 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.