GET /orders devuelve los pedidos de tu organización, paginados por cursor y
ordenados del más reciente al más antiguo por defecto. Requiere el scope orders:read.
Filtros
Combina cualquiera de estos parámetros de query:Orden
Las fechas deben incluir zona horaria (offset o
Z). Una fecha sin zona se rechaza con 400
para que un punto de sincronización no se corra por la zona horaria del servidor.Sincronización incremental
Para mantener una copia al día sin volver a leer todo, ordena porupdatedAt ascendente y filtra
desde la última fecha que procesaste (tu watermark).
- Lee desde tu watermark con
updatedAfter. - Recorre todas las páginas con
nextCursor(revisa Paginación). - Guarda el
updatedAtmás alto que viste como nuevo watermark.
updatedAt se expone justamente para este patrón.
Líneas de paquetes (bundles)
Cuando una línea corresponde a un paquete, su campocomponents trae la composición del paquete
congelada al momento del pedido — aunque el paquete cambie después, el pedido conserva lo que se
vendió. En líneas de productos normales, components es un arreglo vacío.
Cada componente incluye quantityPerBundle: las unidades dentro de un paquete. Para saber las
unidades totales a preparar para la línea, multiplícalo por el quantity de la línea (en el
ejemplo: 6 × 2 = 12 gaseosas).
Transacciones de pago
El campotransactions trae el historial de cobros con pasarela del pedido, ordenado del intento
más antiguo al más reciente. Los pedidos pagados por medios manuales (efectivo, transferencia
registrada por el comercio) traen un arreglo vacío — ese pago se refleja en paymentStatus,
paidAt y amountPaid.
Cada transacción incluye el tipo de operación (kind: SALE, AUTHORIZATION), su resultado
(status: SUCCESS, FAILURE, PENDING, ERROR), el monto en unidades mayores (misma moneda
del pedido) y, para cobros con tarjeta, los datos enmascarados: cardBrand, cardLast4 y
cardType (CREDIT, DEBIT, PREPAID, UNKNOWN).
gatewayTransactionId (el identificador del cobro en la
pasarela). En intentos fallidos, errorCode trae un código normalizado independiente de la
pasarela (por ejemplo INSUFFICIENT_FUNDS, EXPIRED_CARD, CARD_DECLINED) y
gatewayResultCode conserva el código crudo del proveedor.
Un pedido
GET /orders/{id} devuelve un solo pedido por su UUID. Si no existe en tu organización, responde
404 con code RESOURCE_MISSING.