Referência e reenvio¶
Toda emissão carrega uma referência: o identificador que o seu sistema usa para reconhecer aquele documento depois. É por ela que reenviar uma requisição não vira um segundo documento.
| Dialeto | Campo | Obrigatória? | Escopo da unicidade |
|---|---|---|---|
| ACBrAPI | referencia, no corpo |
não | por conta |
| FocusNFE | ref, na query da emissão e no caminho das demais rotas |
sim | por token, ou seja, por empresa e ambiente |
No FocusNFE, o escopo é o do provedor. A mesma ref no host de produção e no de
homologação são dois documentos, e duas empresas da mesma conta nunca colidem.
No ACBrAPI, referencia é opcional. Quando você não a envia, cada POST é um documento
novo, sem proteção contra duplicidade. Se o seu sistema tem qualquer risco de repetir um
envio (timeout de rede, nova tentativa automática, operador clicando duas vezes), envie
sempre uma referência. As respostas ecoam referencia: null quando você não mandou
nenhuma.
Formato aceito¶
| Dialeto | Alfabeto | Tamanho máximo |
|---|---|---|
| FocusNFE | letras e números | 200 |
| ACBrAPI | livre, exceto o prefixo reservado ~auto: |
50 |
No FocusNFE, a regra vale em todas as rotas: na query da emissão e no caminho da
consulta, do cancelamento e do e-mail. Uma referência fora do alfabeto responde
422 erro_validacao com campo: "ref", sem chegar a procurar documento nenhum.
No ACBrAPI, nós reservamos ~auto: para as referências que geramos internamente quando você
não envia nenhuma. É o que faz o eco responder null em vez de inventar um valor que você
nunca escolheu. Enviar uma referência começando com esse prefixo responde 422.
Reenvio da mesma referência¶
Reenviar não emite de novo: a resposta é o estado atual do documento que aquela referência já identifica.
Estado da ref |
Resposta ao re-POST |
|---|---|
| Em processamento | 422 pending_operation: A nota fiscal ainda está em processamento |
| Autorizado, cancelado ou denegado | 422 already_processed: A nota fiscal já foi autorizada |
erro_autorizacao |
Nova tentativa de emissão, com número novo |
A linha erro_autorizacao é o caminho de correção documentado pelo provedor: corrigir o
corpo e reenviar com a mesma ref. É a única situação em que um reenvio produz um
documento novo, e nós não reaproveitamos o número anterior.
Uma vez autorizada, a ref fica presa àquele documento para sempre, mesmo que ele seja
cancelado depois.
Reenviar uma referencia conhecida responde o estado atual daquele documento, em
qualquer situação (incluindo rejeitado e erro). Não há caminho de reemissão sob a
mesma referência: para tentar de novo depois de uma rejeição, envie uma referência nova.
Essa escolha segue a descrição do provedor (referencia existe para "evitar o envio
duplicado"). Ela está marcada para revisão conforme o retorno das primeiras integrações.
Referência que não existe¶
Se um pedido caiu antes de qualquer coisa durável acontecer (um problema de infraestrutura no meio do caminho), a referência não existe. A consulta responde "não encontrada", e você pode reenviar a mesma referência como um pedido novo, sem risco.
É uma propriedade deliberada, não um descuido. Ou a referência tem um documento com estado próprio, ou ela não existe. No primeiro caso, o documento sempre chega a um desfecho, ainda que pela contingência. Nunca há uma referência presa a meio caminho, que você teria de destravar por suporte.