Regras de integração

Doze regras. Cada uma evita um problema real de integração.

1. Mande Idempotency-Key em POST /v1/nfse e POST /v1/lotes. Não é obrigatório, mas sem ele um timeout seguido de retentativa pode criar uma segunda nota. Veja Idempotência.
2. Ao repetir a mesma tentativa, use a MESMA Idempotency-Key. Gere uma por nota, guarde junto do pedido e reaproveite. Chave nova é nota nova.
3. Mande referencia em toda nota (o número do seu pedido, por exemplo). Ela é única por empresa e ambiente: uma segunda nota com a mesma referencia é recusada (409 referencia_duplicada). É a proteção que continua valendo depois dos 30 dias em que a Idempotency-Key fica guardada.
4. 202 não é erro. A nota existe e está transmitindo. Acompanhe; não emita de novo.
5. Em produção, prefira webhook a consulta repetida. Assine NFSE_AUTORIZADA, NFSE_REJEITADA e NFSE_FALHA_TRANSMISSAO.
6. Se consultar, consulte com calma. O limite é de 120 requisições por minuto por chave, e a nota em transmitindo não muda a cada segundo. Uma consulta a cada 30 segundos por nota basta.
7. Dinheiro e alíquota vão como texto com ponto decimal: "1500.00", "2". Número JSON é recusado (tipo_invalido).
8. Programe em cima de codigo, nunca de mensagem. A mensagem é para gente e pode mudar de texto; o codigo é estável.
9. Guarde X-Request-Id (ou requisicao_id) de toda chamada que deu errado. Com ele você acha a chamada em Integrações › Log da API.
10. Trate cursor como valor opaco. Guarde e devolva exatamente como veio, sem interpretar nem montar. Veja Paginação e limites.
11. Só repita o que pode dar certo repetido. Repita quando o erro traz retentavel: true, em 429, 5xx e timeout, sempre com a mesma Idempotency-Key. Não repita 400, 401, 403, 404, 409, 412 nem 422 sem corrigir antes. Veja a receita de retentativa.
12. Diante de falha_transmissao, leia falha.dps_enviada antes de emitir de novo. Com "desconhecido", a nota pode ter sido emitida: confira no Emissor Nacional primeiro.