Ejemplos reales

Nada de esto está inventado: son llamadas reales entre FIRE y un proveedor fiscal en funcionamiento, con los identificadores cambiados. Sirven para contrastar una implementación contra algo que ya funciona, en vez de contra una descripción.

Numerar una venta

El request es el mismo para los dos países —mismos campos, mismo orden—; lo que cambia es qué usa cada proveedor y qué devuelve en document. Acá van los cuerpos recortados a lo que hace falta para leer el ejemplo; el request completo, campo por campo, está en el contrato.

Ecuador (EC) — SRI
Colombia (CO) — DIAN

Lo 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 va vacío: en Ecuador el establecimiento y el punto de emisión los resolvés vos contra tu catálogo, a partir de store.code y device.uid.

Lo que devolvió el proveedor

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 habla ecuatoriano. claveAcceso, secuencial, ambiente — los nombres del SRI, no una traducción. Y no hay campos de otros países: el cufe colombiano sencillamente no existe acá.
El número visible viene armado en numeroComprobante (005-004-000000052). Lo componés vos, que conocés la regla —art. 18 del Reglamento— y FIRE lo imprime tal cual, sin reformatearlo. Las tres piezas siguen viajando aparte, como las define el SRI, pero son para conciliar: nadie las vuelve a unir.
graphic.qr coincide con document.claveAcceso. En Ecuador es así, y la redundancia es deliberada: la alternativa es que el punto de venta sepa qué se codifica en cada país.
ambiente: "2" es pruebas — en el SRI. En la DIAN el 2 es al revés; ver la pestaña de Colombia.

Lo 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": {}
}

Acá storeFiscalConfig.metadata sí trae datos —la clave técnica y el rango que la DIAN entrega con la resolución—, y los importes de totals no son informativos: entran al hash del CUFE.

Lo que devolvió el proveedor

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 hexadecimales",
    "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 habla colombiano, y no se parece al de Ecuador: no hay claveAcceso ni secuencial, hay cufe, prefijo y numeroDian.
graphic viene en null. En Colombia el QR es la URL del catálogo de la DIAN y viaja dentro de document.qrCode, así que no se duplica afuera.
numeroComprobante y numeroDian no son lo mismo: el primero es el número visible ya armado (prefijo + consecutivo), el segundo es el consecutivo solo. Los dos se devuelven resueltos; FIRE no concatena nada.
ambiente: "2" es pruebas en la DIAN — el código es el del ente, sin normalizar, y por eso significa lo contrario que en Ecuador.

Fijate en lo que no viaja en ninguno de los dos: ni accountId, ni vendorId —el tenant sale de la API key—, ni códigos del ente, ni referencia al catálogo del proveedor. Y dos cosas comunes a los dos países:

authorizationMode e issuedAt están en la raíz, fuera de document: son comunes a todos los países, así que no pertenecen al bloque del país.
status: "INVOICED", no "PENDING". Recién numerado el documento siempre está pendiente de autorización — es la condición normal, no un estado que informar.

Cuando falla

La misma petición, con la tienda fuera del catálogo del proveedor

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 qué este error está bien construido:


HTTP `422`, no `200`	Un rechazo con `200` y el motivo escondido en un campo es un contrato donde alguien no valida y cree que numeró
`retryable: false`	Es configuración: reintentar en la caja mientras el cliente espera no lo va a arreglar
`failure.code` estable	`UNMAPPED_STORE_IDENTITY` sirve para alertas y documentación de soporte. Un texto libre no
`message` accionable	Dice qué tienda y qué catálogo. Se puede arreglar sin abrir un ticket
`details[]`	Apunta al campo exacto del request

retryable es lo que decide qué pasa después. Con false cortamos y la venta queda sin comprobante fiscal, con el motivo registrado. Con true la solicitud queda abierta y se puede retomar.Sin ese campo hay que adivinar por el código HTTP — y adivinar mal significa reintentar mientras el cliente espera, o abandonar una venta que se podía numerar.

La misma petición, con algo roto de tu lado

HTTP 500

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

Por qué este error está bien construido:


HTTP `500`, y el sobre igual	Una excepción que no atrapaste sigue siendo la respuesta a un pedido de numeración. El cuerpo por defecto del framework —`{"path", "error", "status", "timestamp"}`— no dice si reintentar ni de qué venta habla
`retryable: true`	No sabés qué se rompió, así que la lectura segura es que puede ser pasajero. Deja la solicitud abierta en vez de matar la venta
`provider.reference`	En un `500` es lo más valioso del cuerpo: es por donde buscás en TUS logs cuando te reportemos el caso
`failure.code`, aunque sea genérico	Sobre `INTERNAL_ERROR` se puede alertar. Sobre un texto libre, no

retryable: true es una promesa sobre tu idempotencia. Vamos a reintentar con el mismo orderCode. Si el error ocurrió DESPUÉS de que consumiste el secuencial, ese reintento tiene que devolver el documento ya numerado con reused: true, no numerar otro.

Que falte configuración NO entra acá. Una tienda sin identidad fiscal, sin resolución de numeración o sin clave técnica va a fallar igual dentro de una semana: eso es el 422 de arriba, con retryable: false. El 5xx es solo para lo que puede andar solo más tarde.

Qué hacemos con cada respuesta

El estado que expone FIRE a sus canales se deriva de lo que devuelve el proveedor. El proveedor no conoce estos estados ni tiene que emitirlos:

Lo que devuelve el proveedor	Estado que expone FIRE
`2xx` con `document`	`GENERATED` — hay comprobante
No-`2xx` con `retryable: false`	`FAILED_FINAL` — no hay, y reintentar no sirve
No-`2xx` con `retryable: true`	`FAILED_RETRYABLE` — no hay, se puede reintentar
No respondió (timeout, conexión cortada)	`PENDING` — no sabemos si numeró

PENDING no puede venir del proveedor por definición: decirlo implicaría haber contestado. Es el estado de “no hubo respuesta”, y es el más delicado — el proveedor pudo haber numerado y consumido un secuencial sin que nos enteremos.Por eso tu deduplicación tiene que ser por orderCode: el reintento llega con el mismo orderCode y debe devolver el mismo documento con reused: true, en vez de numerar otro.

No la bases en un header de idempotencia: no te mandamos ninguno. La llamada al proveedor lleva solo x-api-key y Content-Type. La llave natural —país + orderCode + operación— es lo único que liga un reintento con el intento original, en los dos extremos.

Primeros pasos

Configuración

Trabajando con eventos

Guías

Numerar una venta

Lo que enviamos

Lo que devolvió el proveedor

Lo que enviamos

Lo que devolvió el proveedor

Cuando falla

La misma petición, con la tienda fuera del catálogo del proveedor

La misma petición, con algo roto de tu lado

Qué hacemos con cada respuesta

​Numerar una venta

​Lo que enviamos

​Lo que devolvió el proveedor

​Lo que enviamos

​Lo que devolvió el proveedor

​Cuando falla

​La misma petición, con la tienda fuera del catálogo del proveedor

​La misma petición, con algo roto de tu lado

​Qué hacemos con cada respuesta

Numerar una venta

Lo que enviamos

Lo que devolvió el proveedor

Lo que enviamos

Lo que devolvió el proveedor

Cuando falla

La misma petición, con la tienda fuera del catálogo del proveedor

La misma petición, con algo roto de tu lado

Qué hacemos con cada respuesta