> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riqra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leer pedidos

> Filtrar, ordenar y sincronizar pedidos de forma incremental.

El endpoint `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:

| Parámetro                       | Descripción                                                                                                                                                                             |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                        | Estado del pedido: `PLACED`, `CANCELLED`.                                                                                                                                               |
| `paymentStatus`                 | Estado de pago: `UNPAID`, `PARTIALLY_PAID`, `PAID`, `PENDING` (hay un intento de cobro abierto, se resuelve solo), `ERROR` (no se resolvió; el comercio debe verificar en la pasarela). |
| `fulfillmentStatus`             | Estado de preparación: `UNFULFILLED`, `IN_PROGRESS`, `FULFILLED`, `DELIVERED`.                                                                                                          |
| `invoiceStatus`                 | Estado de facturación: `NOT_INVOICED` (la cola de pedidos que aún necesitan comprobante), `INVOICED`.                                                                                   |
| `source`                        | Origen del pedido: `STOREFRONT`.                                                                                                                                                        |
| `customerId`                    | Pedidos de un cliente (UUID).                                                                                                                                                           |
| `number`                        | Número de pedido. Acepta el entero o el formato `#123`.                                                                                                                                 |
| `createdAfter`, `createdBefore` | Rango por fecha de creación (ISO-8601 con zona horaria).                                                                                                                                |
| `updatedAfter`, `updatedBefore` | Rango por fecha de actualización (ISO-8601 con zona horaria).                                                                                                                           |

## Orden

| Parámetro | Valores                  | Por defecto |
| --------- | ------------------------ | ----------- |
| `sort`    | `createdAt`, `updatedAt` | `createdAt` |
| `order`   | `asc`, `desc`            | `desc`      |

<Note>
  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.
</Note>

## Sincronización incremental

Para mantener una copia al día sin volver a leer todo, ordena por `updatedAt` ascendente y filtra
desde la última fecha que procesaste (tu *watermark*).

```bash theme={null}
curl "https://api-v2.riqra.com/public/v1/orders?sort=updatedAt&order=asc&updatedAfter=2026-06-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer rq_live_tu_api_key"
```

En cada corrida:

1. Lee desde tu watermark con `updatedAfter`.
2. Recorre todas las páginas con `nextCursor` (revisa [Paginación](/desarrolladores/api/pagination)).
3. Guarda el `updatedAt` más alto que viste como nuevo watermark.

El campo `updatedAt` se expone justamente para este patrón.

## Líneas de paquetes (bundles)

Cuando una línea corresponde a un paquete, su campo `components` 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).

```json theme={null}
{
  "productName": "Six-pack Gaseosa",
  "quantity": 2,
  "components": [
    {
      "productName": "Gaseosa 500ml",
      "variantSku": "GAS-500",
      "quantityPerBundle": 6
    }
  ]
}
```

## Transacciones de pago

El campo `transactions` 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`).

```json theme={null}
{
  "kind": "SALE",
  "status": "SUCCESS",
  "amount": "159.90",
  "provider": "OPENPAY",
  "gatewayTransactionId": "trzt8m4kqxxi3yzptkm2",
  "cardBrand": "visa",
  "cardLast4": "4242",
  "cardType": "DEBIT",
  "installments": 6,
  "installmentsInterest": "WITHOUT_INTEREST",
  "authorizationCode": "801585",
  "gatewayResultCode": null,
  "errorCode": null,
  "test": false,
  "processedAt": "2026-07-30T14:03:40Z",
  "createdAt": "2026-07-30T14:03:39Z"
}
```

Para conciliar contra la pasarela usa `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í que
`payment.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`.