Listar órdenes

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <tu_api_key>

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

GET

api

fire

external

orders

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <tu_api_key>

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

Devuelve todas las órdenes del account + vendor asociados a tu API key. Soporta paginación, un conjunto amplio de filtros y projection de campos (elegís qué campos devuelve cada orden). Para listar las órdenes de una sola tienda, usá Listar órdenes de tienda.

Autenticación

string

requerido

Tu API key de Fire con scope orders:read. La key debe ser vendor-scoped (binding account + vendor) — las keys sin vendorId se rechazan con 403.

Query params

El account y el vendor se derivan de tu API key (vendor-scoped) — no se envían por query.

string

Lista de campos a devolver separados por coma (projection). Ver Projection de campos. Omitir para devolver todos los campos. Un campo desconocido da 400.

string

OPEN, COMPLETED, FORCE_CLOSED, CANCELLED.

string

PENDING, SUCCEEDED, FAILED.

string

Día de negocio exacto, YYYY-MM-DD.

string

Inicio del rango, YYYY-MM-DD.

string

Fin del rango, YYYY-MM-DD.

string

predeterminado:"business_day"

business_day o created_at.

string

predeterminado:"+00:00"

Offset de timezone (+HH:MM) usado con dateFilterMode=created_at.

string

Código de canal (APP, KIOSK, …).

string

Código de servicio de fulfillment.

string

Código de método de pago (ej. CASH).

string

Match parcial sobre order code.

string

UUID exacto, o match parcial sobre external order id / order code.

integer

predeterminado:"1"

Número de página (base 1).

integer

predeterminado:"20"

Tamaño de página (1–100).

Petición

GET https://api.fire.rest/api/v1/fire/external/orders?fields=id,orderCode,status,totals&page=1&size=20
x-api-key: <tu_api_key>

Projection de campos

El consumidor decide qué campos devuelve cada orden, similar al projection de MongoDB o al parámetro _source de Elasticsearch.

Sin fields → se devuelven todos los campos.
fields=id,orderCode,totals → solo esos campos.
Un campo fuera del catálogo → 400 con la lista de campos permitidos.

Campos disponibles: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal.

channel es el id de catálogo de la orden (orders.catalog_id), expuesto bajo el nombre channel.

Los snapshots JSONB (totals, orderLines, paymentMethods, store, customer, fulfillment, metadata, fiscal) se devuelven en el formato de persistencia interno de Fire (por ejemplo, los montos de totals van a escala ×10000).

Progreso del cobro: `settlement` y `payments`

Cuando una orden se cobra después de abrirse, status y paymentStatus solo te dicen si se cobró. Dicen OPEN y PENDING tanto para una orden que nadie intentó cobrar como para una a la que le rechazaron la tarjeta dos veces — y son situaciones muy distintas para quien está mirando.

la orden	`status`	`paymentStatus`	`settlement.status`
abierta, sin intentar nada	`OPEN`	`PENDING`	`pending`
una pieza se rechazó	`OPEN`	`PENDING`	`declined`
cobrada por completo	`COMPLETED`	`SUCCEEDED`	`settled`

Leé settlement para saber si y cómo se cobró, y payments para saber con qué. El cobro es todo o nada (ver Confirmar pago), así que paidSoFar vale 0 o el total completo — nunca algo intermedio.

Mientras la orden está abierta, paymentMethods es lo que el POS declaró al crearla — no lo que se cobró. Se sobrescribe con las piezas reales recién cuando la orden salda. Sumarlo para calcular el progreso da un número equivocado. Usá settlement.paidSoFar.

order.settlement (shape)

{
  "settlement": {
    "status": "settled",
    "origin": "ledger",
    "paidSoFar": "359000",
    "total": "359000",
    "currencyCode": "BRL",
    "tenderCount": 2,
    "declinedCount": 1,
    "amountMismatch": false,
    "declaredMethods": ["IFOOD"]
  }
}

status es uno de pending, declined, settled. paidSoFar y total usan la misma escala ×10000 que totals — arriba, 35,90 cobrados en dos piezas, después de un rechazo anterior. tenderCount cuenta solo las piezas aprobadas; las rechazadas van en declinedCount. amountMismatch es siempre false: un cobro que no suma el total se rechaza de entrada, así que una orden saldada siempre cuadra. El campo se mantiene por compatibilidad. origin te dice de dónde sale paidSoFar, y los dos no tienen el mismo respaldo: ledger significa que las piezas se contaron una por una a medida que llegaron; intake significa que la orden se creó declarándose pagada y Fire le creyó. settlement es null en las órdenes creadas antes de que existiera este campo. declaredMethods es con qué dijo la orden que se iba a pagar, al crearse. Comparalo con paymentMethods para ver si pagaron con lo que anunciaron: una orden creada como IFOOD y cobrada con CREDIT muestra declaredMethods: ["IFOOD"] y paymentMethods con CREDIT. Es el único lugar donde sobrevive el medio declarado, porque al saldar se pisa paymentMethods con las piezas reales. Solo viajan los códigos: los montos declarados vienen del POS en unidades ("35.9") mientras que paidSoFar va ×10000, y mezclar las dos escalas en un mismo objeto se presta a errores.

`payments` — las piezas, una por una

Los pedazos del cobro, del más viejo al más nuevo. Las piezas rechazadas se incluyen: settlement.declinedCount dice cuántas hubo, payments dice cuáles y por qué.

"payments": [
  {
    "status": "approved",           // solo las piezas aprobadas suman a paidSoFar
    "amount": "200000",             // ×10000, la misma escala que totals
    "currencyCode": "BRL",
    "method": "CASH",               // una de las dos piezas de un cobro repartido
    "transactionId": "POS-0001",    // la clave de idempotencia del POS
    "occurredAt": "2026-07-30T16:20:04.000Z"
  },
  {
    "status": "declined",
    "amount": "159000",
    "currencyCode": "BRL",
    "method": "CREDIT",
    "transactionId": "POS-0002",
    "declineReason": "51",                      // código crudo del adquirente
    "declineReasonCode": "INSUFFICIENT_FUNDS",  // ausente cuando no matcheó el catálogo
    "declineGroup": "FUNDS",
    "occurredAt": "2026-07-30T16:22:47.000Z"
  }
]

Una orden que nunca pasó por Confirmar pago — una prepaga, por ejemplo — devuelve payments: [], nunca null. completedAt es el momento en que el cobro cerró la orden, y es null mientras sigue abierta.

El bloque `fiscal` por país

Cuando una orden tiene un documento fiscal, el campo fiscal lleva su estado actual. Su sub-objeto metadata contiene los campos comunes más solo los identificadores correspondientes a fiscal.countryCode — los identificadores de los otros países no se incluyen. Leé fiscal.countryCode para saber qué identificadores esperar.

order.fiscal (shape)

{
  "id": "7e2b8c10-…",
  "status": "COMPLETED",
  "fiscal": {
    "status": "authorized",
    "countryCode": "CO",
    "company": { "govIdType": "NIT", "govIdNumber": "9001234561", "legalName": "…", "tradeName": "…" },
    "store":   { "code": "CO-BOG-001", "name": "…", "govIdType": "NIT", "govIdNumber": "900123456-7" },
    "buyer":   { "isFinalConsumer": true, "name": null, "govIdType": null, "govIdNumber": null },
    "metadata": { "…": "see per-country tabs below" }
  }
}

status te dice dónde está la orden fiscalmente. Agrupalo por lo que podés hacer al respecto:

Grupo	Valores	Qué significa
Sin documento	`awaiting_payment`, `not_issued`	Nunca se emitió nada. `awaiting_payment` = la orden está abierta y sin pagar, así que todavía no corresponde emitir. `not_issued` = la orden se cerró sin haberse facturado nunca (cancelada antes del pago).
En vuelo	`pending`, `processing`, `contingency`, `cancelling`	Hay una operación en curso y no se conoce su desenlace. No asumas éxito ni fracaso — esperá. `contingency` es un documento legalmente emitido pendiente de transmitir.
Resuelto	`authorized`, `cancelled`	Terminal. Hay documento válido, o fue cancelado.
Fallido	`rejected`, `denied`, `error`	No hay documento válido. `fiscal.error` (`{ code, message }`) también está presente.
Entrega	`fiscal_graphic`	El proveedor está entregando el artefacto imprimible. No es aprobación ni estado terminal.

awaiting_payment y not_issued describen el estado fiscal de la orden, no de un documento — en ninguno de los dos casos hay documento. Existen porque processing significaba dos cosas incompatibles: “hay una emisión en vuelo” y “esta orden todavía no llegó a facturarse”. Aparecen en órdenes abiertas y sin pagar, así que son más frecuentes junto con el pago diferido. No viajan en los eventos de orden; ahí lastKnown.fiscal reporta null.

Los campos comunes de metadata (todos los países): docType, docSubtype, providerDocId, pdfUrl, xmlUrl, emittedAt, cancelledAt, totalAmount, taxAmount, currencyCode. Los identificadores específicos que se muestran abajo se agregan encima, pero metadata lleva solo los identificadores del país del propio documento — los de los otros países no se incluyen.

totalAmount y taxAmount NO van escalados. Llegan tal como los mandó el proveedor fiscal en el callback: 95000 son 95.000 COP, no 9,50.Es la excepción en esta página: totals, paidSoFar y los montos de pago van ×10.000, porque son datos que FIRE calcula y almacena. Los de metadata son del documento del ente y se guardan tal cual.

metadata — CO (DIAN)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/co.pdf",
  "xmlUrl": "https://…/co.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 95000,
  "taxAmount": 15170,
  "currencyCode": "COP",
  "cufe": "633732c7a2a577bfa1828551e64d03f715f0",
  "prefijo": "FE-CO",
  "numeroDian": "1001",
  "numeroComprobante": "FE-CO1001",
  "ambiente": "1"
}

metadata — EC (SRI)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/ec.pdf",
  "xmlUrl": "https://…/ec.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 2450,
  "taxAmount": 315,
  "currencyCode": "USD",
  "claveAcceso": "0102030405060708091011121314151617181920212223242",
  "numeroAutorizacion": "AUT-EC-1001"
}

El qrCode (CO) y el ambiente (EC) del callback no se persisten en fiscal.metadata — solo se guardan los identificadores listados acá.

metadata — CL (SII)

{
  "docType": "invoice",
  "docSubtype": "boleta",
  "pdfUrl": "https://…/cl.pdf",
  "xmlUrl": "https://…/cl.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 18900,
  "taxAmount": 3019,
  "currencyCode": "CLP",
  "folio": 12345,
  "ted": "<TED>…</TED>",
  "tipoDte": 39,
  "trackId": "SII-TRK-998877"
}

metadata — AR (AFIP)

{
  "docType": "invoice",
  "docSubtype": "factura_b",
  "pdfUrl": "https://…/ar.pdf",
  "xmlUrl": "https://…/ar.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 12100,
  "taxAmount": 2100,
  "currencyCode": "ARS",
  "cae": "74256178925412",
  "fechaVtoCae": "2026-05-31",
  "puntoVenta": 1,
  "numeroComprobante": 12345,
  "tipoComprobante": 6
}

metadata — VE (SENIAT)

{
  "docType": "invoice",
  "docSubtype": "factura",
  "pdfUrl": "https://…/ve.pdf",
  "xmlUrl": "https://…/ve.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 480,
  "taxAmount": 76,
  "currencyCode": "VES",
  "numeroControl": "00-00012345",
  "numeroFactura": "12345",
  "rifEmisor": "J-12345678-9"
}

metadata — BR (SEFAZ, non-PlugNotas)

{
  "docType": "invoice",
  "docSubtype": "nfce",
  "pdfUrl": "https://…/br.pdf",
  "xmlUrl": "https://…/br.xml",
  "emittedAt": "2026-04-26T14:32:10.000Z",
  "totalAmount": 14290,
  "taxAmount": 1857,
  "currencyCode": "BRL",
  "chaveAcesso": "35260229062609000177650500000000011000000010",
  "protocolo": "141210001176277",
  "numero": 1,
  "serie": 50,
  "modelo": 65,
  "cnpjEmitente": "29062609000177"
}

El bloque `fiscal` trae el recorrido completo del documento

fiscal sigue el mismo patrón que kitchen: el top-level es el estado vigente, y fiscal.history[] lista cada parada del documento fiscal, en orden cronológico.

"fiscal": {
  "countryCode": "BR",
  "status": "cancelled",              // estado vigente
  "occurredAt": "2026-07-21T18:00:00Z",
  "company": { … }, "store": { … },   // emisor + tienda, arrastrados
  "metadata": { … },                  // metadata del estado vigente
  "history": [
    { "status": "processing",     "occurredAt": "…" },
    { "status": "fiscal_graphic", "occurredAt": "…", "metadata": { "pdfUrl": "…" } },
    { "status": "authorized",     "occurredAt": "…", "metadata": { "chaveAcesso": "…" } },
    { "status": "cancelled",      "occurredAt": "…", "metadata": { "protocoloCancelamento": "…" } }
  ]
}

Estados posibles: pending, processing, contingency, fiscal_graphic, error, authorized, rejected, denied, cancelling, cancelled. Ver Callback fiscal para el significado de cada uno. Leer el top-level sigue funcionando igual que antes — history es aditivo. Te sirve cuando necesitás los datos de autorización de un documento que después se canceló: viven en la entrada authorized.

Respuesta

object[]

Array de órdenes, cada una proyectada según fields.

object

Mostrar pagination

integer

Página actual.

integer

Tamaño de página.

integer

Total de órdenes que matchean el query.

integer

Total de páginas.

{
  "orders": [
    {
      "id": "7e2b8c10-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "orderCode": "OC-1024",
      "status": "COMPLETED",
      "totals": [
        { "currencyCode": "USD", "total": 125000 }
      ]
    }
  ],
  "pagination": { "page": 1, "size": 20, "total": 1, "totalPages": 1 }
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Unknown field(s) in projection: totls. Allowed: id, orderCode, orderExternal, accountId, vendorId, storeId, stationId, anonymousCustomerId, customerId, billingId, status, paymentStatus, channel, businessDayDate, createdAt, updatedAt, completedAt, deletedAt, store, customer, billing, fulfillment, orderLines, totals, paymentMethods, settlement, payments, metadata, kitchen, aggregator, fiscal"
}

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "API key is not authorized for the requested vendor"
}

API

APIs de partner

PayBridge

Autenticación

Query params

Petición

Projection de campos

Progreso del cobro: `settlement` y `payments`

`payments` — las piezas, una por una

El bloque `fiscal` por país

El bloque `fiscal` trae el recorrido completo del documento

Respuesta

Relacionado

Listar órdenes de tienda

Obtener orden

​Autenticación

​Query params

​Petición

​Projection de campos

​Progreso del cobro: settlement y payments

​payments — las piezas, una por una

​El bloque fiscal por país

​El bloque fiscal trae el recorrido completo del documento

​Respuesta

​Relacionado

Listar órdenes de tienda

Obtener orden

Autenticación

Query params

Petición

Projection de campos

Progreso del cobro: `settlement` y `payments`

`payments` — las piezas, una por una

El bloque `fiscal` por país

El bloque `fiscal` trae el recorrido completo del documento

Respuesta

Relacionado