Órdenes

Listar órdenes

GET /api/v1/orders

Filtros: filter[status]=paid, filter[customer_id]=uuid, sort=-created_at

Crear orden

POST /api/v1/orders

{
  "customer_email": "[email protected]",
  "line_items": [
    { "variant_id": "uuid", "quantity": 2, "price": 4900 }
  ],
  "shipping_address": {
    "first_name": "Juan", "last_name": "García",
    "address1": "Av. Javier Prado 1234",
    "city": "Lima", "country_code": "PE", "zip": "15036"
  }
}

Esquema del line-item

Cada objeto dentro de line_items en la respuesta contiene los siguientes campos:

Campo	Tipo	Descripción
id	uuid	ID único del line-item
variant_id	uuid	ID de la variante del producto
product_id	uuid	ID del producto padre
title	string	Nombre del producto al momento de la compra
variant_title	string	Título de la variante (ej. "Talla M / Rojo")
sku	string	SKU del producto
quantity	int	Cantidad pedida
unit_price_amount	int64	Precio unitario en centavos
total_amount	int64	Subtotal del línea (unit_price × quantity) en centavos
requires_shipping	bool	Si el artículo requiere envío físico

Los precios se capturan como snapshot al momento del checkout. Si el producto cambia de precio después, la orden conserva el precio original.

Estados de la orden

Estado	Descripción
pending	Creada, esperando pago
confirmed	Pago confirmado
paid	Pago confirmado + stock reservado
ready_to_ship	Preparada para envío (operador la marcó como lista)
in_transit	Entregada al courier, en camino al cliente
partially_fulfilled	Algunos artículos enviados, otros pendientes
fulfilled	Entregada completamente
cancelled	Cancelada
refunded	Reembolsada

Diagrama de transiciones

pending ──→ confirmed ──→ paid ──→ ready_to_ship ──→ in_transit ──→ fulfilled
                 │                      │                                ↑
                 │                      └────── partially_fulfilled ─────┘
                 │
                 ├──→ cancelled
                 └──→ refunded

Reglas de transición:

• pending → confirmed: al confirmar el pago
• confirmed → paid: pago verificado + stock reservado
• paid → ready_to_ship: operador marca la orden como lista para envío (acepta nota opcional)
• ready_to_ship → paid: reversión si el operador encuentra un problema
• ready_to_ship → in_transit: orden entregada al courier
• in_transit → fulfilled: entrega confirmada al cliente
• paid → fulfilled: salto directo (entrega sin courier intermedio)
• partially_fulfilled → fulfilled: cuando se completan los envíos restantes
• pending | confirmed | paid → cancelled: cancelación (no se puede cancelar una orden fulfilled o refunded)

Endpoints

Obtener orden

GET /api/v1/orders/:id

Listar órdenes

GET /api/v1/orders

Filtros: filter[status]=paid, filter[customer_id]=uuid, filter[customer_email]=email, sort=-created_at, q=texto_libre

Cancelar orden

POST /api/v1/orders/:id/cancel

{
  "reason": "El cliente solicitó la cancelación"
}

Respuestas:

• 200: Orden cancelada exitosamente
• 409: La orden no se puede cancelar en su estado actual (fulfilled, refunded o ya cancelled)

Marcar como lista para envío

POST /api/v1/orders/:id/ready-to-ship

{
  "note": "Todos los artículos verificados y empacados"
}

Transiciona paid → ready_to_ship. La nota es opcional.

Crear fulfillment (envío)

POST /api/v1/orders/:id/fulfillments

{
  "carrier": "Olva",
  "tracking_number": "OLV-123456789",
  "tracking_url": "https://olva.com.pe/tracking/OLV-123456789",
  "line_items": [
    { "variant_id": "uuid", "quantity": 1, "title": "Producto X" }
  ],
  "estimated_delivery": "2026-07-25T00:00:00Z"
}

Permite envíos parciales (split shipments): si solo se envían algunos artículos, la orden pasa a partially_fulfilled. Cuando se registran todos los envíos, transiciona a fulfilled.

Marcar envío como entregado

POST /api/v1/fulfillments/:id/delivered

Confirma la entrega al cliente. Transiciona la orden a fulfilled cuando todos los envíos están entregados.

Listar envíos de una orden

GET /api/v1/orders/:id/fulfillments

Devuelve todos los envíos (shipments) asociados a la orden, incluyendo estado, carrier, tracking y artículos incluidos en cada envío.