Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Boas práticas

Estratégia de sondagem

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, no qual 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 (p. ex. 2s → 4s → 8s → 15s), com um limite entre 15 e 20 segundos entre sondagens. Cobre os casos que exigem uma análise adicional e podem levar significativamente mais tempo.

  • Definir um tempo máximo de espera do lado do consumidor (p. 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.

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 = A validação não pôde ser concluída: falha transitória do processamento (inclui timeouts internos da análise). É seguro tentar novamente iniciando uma nova transação com os mesmos ativos (ver Consultar estado). Para os demais valores de failureReason, consulte a tabela em Consultar estado.

Segurança

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

  • Usar um operation-id consistente entre o envio de ativos 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 sobre seu formato.

Rastreabilidade para o suporte

Para investigar um caso específico com o suporte, mantenha e forneça 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. Recomendado 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 você o tiver registrado). Consulte com Facephi os prazos de retenção aplicáveis à sua Integração.

Atualizado