Nada disso é inventado: são chamadas reais entre o FIRE e um provedor fiscal em
funcionamento, com os identificadores trocados. Elas servem para contrastar uma
implementação com algo que já funciona, em vez de com uma descrição.
Numerar uma venda
A requisição é a mesma para os dois países —mesmos campos, mesma ordem—; o que muda é o
que cada provedor usa e o que devolve em document. Os corpos abaixo estão reduzidos ao que
é preciso para ler o exemplo; a requisição completa, campo a campo, está no
contrato.
Equador (EC) — SRI
Colômbia (CO) — DIAN
O que enviamos
storeFiscalConfig.metadata vai vazio: no Equador o estabelecimento e o ponto de emissão
você resolve do seu lado, no seu catálogo, a partir de store.code e device.uid.O que o provedor devolveu
document fala equatoriano. claveAcceso, secuencial, ambiente — os nomes do
SRI, não uma tradução. E não há campos de outros países: o cufe colombiano
simplesmente não existe aqui.- O número visível chega pronto em
numeroComprobante (005-004-000000052). Quem o
monta é você, que conhece a regra —art. 18 do Regulamento— e o FIRE o imprime tal
como veio, sem reformatar. As três partes continuam trafegando à parte, como o SRI as
define, mas servem para conciliar: ninguém volta a juntá-las.
graphic.qr coincide com document.claveAcceso. No Equador é assim, e a redundância
é deliberada: a alternativa é o ponto de venda ter de saber o que se codifica em cada
país.ambiente: "2" é homologação — no SRI. Na DIAN o 2 é o contrário; veja a aba da
Colômbia.
O que enviamos
Aqui storeFiscalConfig.metadata traz dados sim —a chave técnica e a faixa que a DIAN
entrega junto com a resolução— e os valores de totals não são informativos: entram no
hash do CUFE.O que o provedor devolveu
document fala colombiano, e não se parece em nada com o do Equador: não há
claveAcceso nem secuencial, há cufe, prefijo e numeroDian.graphic vem em null. Na Colômbia o QR é a URL do catálogo da DIAN e trafega
dentro de document.qrCode, então não se duplica fora.numeroComprobante e numeroDian não são a mesma coisa: o primeiro é o número
visível já montado (prefixo + consecutivo), o segundo é só o consecutivo. Os dois vêm
resolvidos; o FIRE não concatena nada.ambiente: "2" é homologação na DIAN — o código é o do próprio fisco, sem
normalizar, e por isso significa o contrário do Equador.
accountId, nem vendorId —o tenant
sai da API key—, nem códigos do fisco, nem referência ao catálogo do provedor.
E duas coisas comuns aos dois países:
authorizationMode e issuedAt ficam na raiz, fora de document: são comuns a todos
os países, então não pertencem ao bloco do país.status: "INVOICED", não "PENDING". Recém-numerado, o documento está sempre pendente
de autorização — é a condição normal, não um estado a informar.
Quando falha
Por que este erro está bem construído:
retryable é o que decide o que acontece depois. Com false interrompemos e a venda fica
sem comprovante fiscal, com o motivo registrado. Com true a solicitação fica aberta e
pode ser retomada.Sem esse campo é preciso adivinhar pelo código HTTP — e adivinhar errado significa retentar
enquanto o cliente espera, ou abandonar uma venda que podia ser numerada.
O que fazemos com cada resposta
O estado que o FIRE expõe aos seus canais é derivado do que o provedor devolve. O
provedor não conhece esses estados nem precisa emiti-los:
PENDING não pode vir do provedor por definição: dizê-lo implicaria ter
respondido. É o estado de “não houve resposta”, e é o mais delicado — o provedor pode
ter numerado e consumido um sequencial sem que fiquemos sabendo.Por isso a sua deduplicação tem que ser por orderCode: a retentativa chega com o mesmo
orderCode e deve devolver o mesmo documento com reused: true, em vez de numerar outro.Não a baseie em um header de idempotência: não mandamos nenhum para você. A chamada ao
provedor leva apenas x-api-key e Content-Type. A chave natural
— país + orderCode + operação — é a única coisa que liga uma retentativa à tentativa
original, nas duas pontas.
