Entenda a janela de incerteza
O servidor pode concluir uma operação e a resposta não chegar ao consumidor. Um timeout, portanto, não comprova que a emissão falhou. Repetir a mesma chamada sem investigação pode gerar outro registro. O integrador precisa distinguir falha anterior ao envio, rejeição explícita e resultado desconhecido. Essa classificação permite escolher a próxima ação sem transformar toda dificuldade de rede em uma nova emissão.
Crie uma referência controlada na origem
Relacione a tentativa à transação e à revisão do documento no seu sistema. Conserve o estado da tentativa e o identificador retornado quando houver sucesso. Essa referência não substitui garantias do fornecedor, mas ajuda a reconciliar a operação. Antes de usar idempotência no servidor, confirme se a API a oferece, como a chave é interpretada e por quanto tempo o comportamento é mantido. Não invente um cabeçalho esperando que ele funcione.
Defina quando a intervenção humana é necessária
Alguns resultados podem exigir consulta ou análise do histórico disponível. Crie uma fila identificável de pendências, com dados mínimos e sem armazenar segredos nos logs. O operador deve saber o que já foi tentado e qual evidência falta. Evite mecanismos que repetem indefinidamente sem limite ou transformam uma mensagem de erro em sucesso para liberar o restante do fluxo.
Teste a falha depois do processamento
Um teste útil interrompe a recepção da resposta após o envio e verifica como o consumidor se recupera. Observe se o documento aparece uma ou duas vezes e se a referência comercial permanece correta. Ao integrar a Atestiva, use o contrato público vigente e valide as capacidades de consulta com a equipe. O objetivo de contratação é um fluxo reconciliável, não apenas uma taxa alta de respostas positivas em condições ideais.
Checklist para aplicar na sua operação
- Distinga rejeição explícita de resultado desconhecido na máquina de estados.
- Associe tentativas à transação e à revisão do documento na origem.
- Teste perda de resposta sem pressupor idempotência não documentada.