Boas práticas de integração

Uma integração fiscal precisa estar preparada para falha de rede, resposta externa lenta, rejeição e reprocessamento. Nenhuma dessas é exceção — todas acontecem toda semana.

As dez que mais evitam problema

1. Gere e persista uma referencia_externa por operação, antes de enviar.
2. Armazene o job_id assim que ele chegar.
3. Trate a emissão como assíncrona. 202 não é autorização.
4. Implemente webhooks de forma idempotente — o mesmo evento pode chegar duas vezes.
5. Nunca reenvie uma nota só porque houve timeout. Localize primeiro.
6. Registre erros e rejeições sem armazenar segredos.
7. Monitore certificados — vencido derruba todas as emissões da empresa.
8. Confira a numeração antes de emitir; rejeitada não consome número.
9. Use backoff nas retentativas técnicas.
10. Nunca transforme retentativa técnica em duplicação fiscal.

Antes de escalar volume

• Uma emissão completa validada de ponta a ponta
• Uma rejeição provocada de propósito e tratada pelo seu código
• Webhook recebido, validado por assinatura e processado
• Recuperação testada: derrube o webhook e reconcilie por consulta
• XMLs sendo armazenados no seu ambiente
• Logs com correlação, sem segredo
• Alerta de certificado a vencer

Distinga o que pode ser repetido

A pergunta certa não é "deu erro?", é "o que aconteceu com a operação?"

Repetir uma consulta é inofensivo. Repetir uma emissão pode gerar duas notas para o mesmo fato gerador. Antes de qualquer retentativa de emissão, descubra o estado real — GET /v1/jobs/localizar existe para isso.