Saltar al contenido principal
GET
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

​
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, revision, 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. 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)
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é.
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. revision es la versión de la orden: arranca en 1 y sube uno cada vez que se corrige. Es lo que mandás como expectedRevision al corregirla. El cobro no la mueve.

​
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)
status te dice dónde está la orden fiscalmente. Agrupalo por lo que podés hacer al respecto:
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)

​
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.
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

​
Relacionado

Listar órdenes de tienda

El mismo listado, acotado a una sola tienda.

Obtener orden

Lee una orden puntual por id.