Exemplos reais

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

POST {baseUrl}/api/v1/fiscal/ec/prekeys
x-api-key: ••••

{
  "country": "EC",
  "operation": "INVOICE",
  "businessDayDate": "2026-08-13",
  "createdAt": "2026-08-13T20:41:05.512Z",
  "orderCode": "E2E-NUM-B-1786636044723",
  "store": {
    "code": "K004",
    "storeFiscalConfig": {
      "govIdType": "RUC",
      "govIdNumber": "1791415132001",
      "company": {
        "govIdType": "RUC",
        "govIdNumber": "1791415132001",
        "legalName": "INT FOOD SERVICES CORP S.A.",
        "tradeName": "KFC"
      },
      "metadata": {}
    }
  },
  "device": { "uid": "52CAEA5A18D9B75F", "name": "KIOSK", "platform": "android" },
  "client": {
    "name": "CONSUMIDOR",
    "lastName": "FINAL",
    "govIdType": "FINAL_CONSUMER",
    "govIdNumber": "00000000000"
  },
  "totals": [
    {
      "currencyCode": "USD",
      "total": "100000",
      "subtotalWithoutTaxes": "87000",
      "taxValue": "13000",
      "taxes": [{ "name": "IVA", "base": "87000", "rate": "0.15", "amount": "13000" }]
    }
  ],
  "metadata": {}
}

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

HTTP 200

{
  "status": "INVOICED",
  "country": "EC",
  "orderCode": "E2E-NUM-B-1786636044723",
  "reused": false,
  "retryable": false,
  "authorizationMode": "ONLINE",
  "issuedAt": "2026-08-13T15:47:26.057337855Z",
  "document": {
    "numeroComprobante": "005-004-000000052",
    "claveAcceso": "1308202601000000000000110050040000000521234567811",
    "establecimiento": "005",
    "puntoEmision": "004",
    "secuencial": "000000052",
    "ambiente": "2"
  },
  "graphic": {
    "qr": "1308202601000000000000110050040000000521234567811"
  },
  "failure": null,
  "provider": { "name": "hio.fiscalization", "version": "dev" },
  "metadata": { "externalDeviceId": "1", "externalStoreCode": "K004" }
}

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

POST {baseUrl}/api/v1/fiscal/co/prekeys
x-api-key: ••••

{
  "country": "CO",
  "operation": "INVOICE",
  "businessDayDate": "2026-08-16",
  "createdAt": "2026-08-16T14:03:22.145Z",
  "orderCode": "CO-K039-1786901234",
  "store": {
    "code": "K039",
    "storeFiscalConfig": {
      "govIdType": "NIT",
      "govIdNumber": "9001234567",
      "company": {
        "govIdType": "NIT",
        "govIdNumber": "9001234567",
        "legalName": "COMERCIALIZADORA ANDINA S.A.S.",
        "tradeName": "KFC"
      },
      "metadata": {
        "claveTecnica": "fc8eac422eba16e22ffd8c6f94b3f40a6e38162c",
        "rangoFacturacion": {
          "prefijo": "SETP",
          "desde": "990000000",
          "hasta": "995000000",
          "resolucion": "18760000001",
          "vigenteHasta": "2027-08-16"
        }
      }
    }
  },
  "device": { "uid": "52CAEA5A18D9B75F", "name": "CAJA 3", "platform": "android" },
  "client": {
    "name": "Consumidor",
    "lastName": "final",
    "govIdType": "FINAL_CONSUMER",
    "govIdNumber": "00000000000"
  },
  "totals": [
    {
      "currencyCode": "COP",
      "total": "500000000",
      "subtotalWithoutTaxes": "420168100",
      "taxValue": "79831900",
      "taxes": [{ "name": "IVA", "base": "420168100", "rate": "0.19", "amount": "79831900" }]
    }
  ],
  "metadata": {}
}

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

HTTP 200

{
  "status": "INVOICED",
  "country": "CO",
  "orderCode": "CO-K039-1786901234",
  "reused": false,
  "retryable": false,
  "authorizationMode": "ONLINE",
  "issuedAt": "2026-08-16T14:21:03.118Z",
  "document": {
    "numeroComprobante": "SETP990000001",
    "prefijo": "SETP",
    "numeroDian": "990000001",
    "cufe": "9c4f1e…  ← 96 caracteres hexadecimais",
    "qrCode": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=9c4f1e…",
    "ambiente": "2"
  },
  "graphic": null,
  "failure": null,
  "provider": { "name": "hio.fiscalization", "version": "dev" },
  "metadata": { "externalStoreCode": "K039" }
}

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.

Repare no que não trafega em nenhum dos dois: nem 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

A mesma requisição, com a loja fora do catálogo do provedor

HTTP 422

{
  "orderCode": "E2E-FUEL-FALLA-01",
  "retryable": false,
  "failure": {
    "code": "UNMAPPED_STORE_IDENTITY",
    "message": "identidad fiscal no configurada: EC / la tienda K004 no está cargada en el catálogo de identidades fiscales",
    "details": [
      { "field": "store.code", "issue": "no está en el catálogo de identidades fiscales" }
    ]
  },
  "document": null,
  "graphic": null,
  "provider": { "name": "hio.fiscalization", "version": "" }
}

Por que este erro está bem construído:


HTTP `422`, não `200`	Uma rejeição com `200` e o motivo escondido em um campo é um contrato onde alguém não valida e acredita ter numerado
`retryable: false`	É configuração: retentar no caixa enquanto o cliente espera não vai resolver
`failure.code` estável	`UNMAPPED_STORE_IDENTITY` serve para alertas e documentação de suporte. Um texto livre não
`message` acionável	Diz qual loja e qual catálogo. Dá para consertar sem abrir um ticket
`details[]`	Aponta para o campo exato do request

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.

A mesma requisição, com algo quebrado do seu lado

HTTP 500

{
  "orderCode": "E2E-FUEL-FALLA-02",
  "retryable": true,
  "failure": {
    "code": "INTERNAL_ERROR",
    "message": "erro interno ao calcular o CUFE",
    "details": []
  },
  "document": null,
  "graphic": null,
  "provider": { "name": "hio.fiscalization", "version": "", "reference": "req-01H8XK3M4P" }
}

Por que este erro está bem construído:


HTTP `500`, e o envelope do mesmo jeito	Uma exceção que você não capturou continua sendo a resposta a um pedido de numeração. O corpo padrão do framework —`{"path", "error", "status", "timestamp"}`— não diz se deve tentar de novo nem de que venda se trata
`retryable: true`	Você não sabe o que quebrou, então a leitura segura é que pode ser passageiro. Deixa a solicitação aberta em vez de matar a venda
`provider.reference`	Num `500` é o mais valioso do corpo: é por onde você busca nos SEUS logs quando reportarmos o caso
`failure.code`, mesmo genérico	Sobre `INTERNAL_ERROR` dá para alertar. Sobre um texto livre, não

retryable: true é uma promessa sobre a sua idempotência. Vamos tentar de novo com o mesmo orderCode. Se o erro aconteceu DEPOIS de você consumir o sequencial, essa nova tentativa tem que devolver o documento já numerado com reused: true, não numerar outro.

Faltar configuração NÃO entra aqui. Uma loja sem identidade fiscal, sem resolução de numeração ou sem chave técnica vai falhar igual daqui a uma semana: isso é o 422 acima, com retryable: false. O 5xx é só para o que pode voltar a funcionar sozinho mais tarde.

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:

O que o provedor devolve	Estado que o FIRE expõe
`2xx` com `document`	`GENERATED` — há comprovante
Não-`2xx` com `retryable: false`	`FAILED_FINAL` — não há, e retentar não adianta
Não-`2xx` com `retryable: true`	`FAILED_RETRYABLE` — não há, dá para retentar
Não respondeu (timeout, conexão caída)	`PENDING` — não sabemos se numerou

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.

Primeiros passos

Configuração

Trabalhando com eventos

Guias

Numerar uma venda

O que enviamos

O que o provedor devolveu

O que enviamos

O que o provedor devolveu

Quando falha

A mesma requisição, com a loja fora do catálogo do provedor

A mesma requisição, com algo quebrado do seu lado

O que fazemos com cada resposta

​Numerar uma venda

​O que enviamos

​O que o provedor devolveu

​O que enviamos

​O que o provedor devolveu

​Quando falha

​A mesma requisição, com a loja fora do catálogo do provedor

​A mesma requisição, com algo quebrado do seu lado

​O que fazemos com cada resposta

Numerar uma venda

O que enviamos

O que o provedor devolveu

O que enviamos

O que o provedor devolveu

Quando falha

A mesma requisição, com a loja fora do catálogo do provedor

A mesma requisição, com algo quebrado do seu lado

O que fazemos com cada resposta