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,
payment.paidAt y payment.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.
Cuotas
El pedido se crea antes de cobrarse y guarda lo que el comprador eligió, así quepayment.installments es siempre su última selección. Con tarjeta, mientras el pedido no esté
pagado eso es una intención: si el cobro se rechaza y el comprador reintenta con otro número de
cuotas, el pedido pasa a mostrar el nuevo. Una vez pagado, esa selección es la que se cobró.
Es null cuando el pago va en una sola cuota.
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.