Pedidos

Cómo se lee el estado de un pedido

Cada pedido trae tres campos sobre su situación:

Campo	Qué es
status	El estado para mostrar al cliente
phase	La etapa del pedido en el ERP, con sus colores, o null
can_cancel	Si el cliente todavía puede anularlo

status se decide en este orden:

1. Si el pedido está anulado: ANULADO.
2. Si no, el nombre de la etapa en la que está en el ERP, por ejemplo «En preparación». Cada empresa configura sus propias etapas.
3. Si aún no tiene etapa: el estado inicial del pedido, normalmente PROCESANDO PEDIDO.

phase trae el color de fondo y de texto de la etapa (bg_color, font_color), para mostrarla igual que en el ERP.

Historial de pedidos

GET /api/v1/ecommerce/orders

Devuelve los pedidos del cliente, del más reciente al más antiguo, en páginas de 25.

Parámetro	Dónde	Obligatorio	Reglas
status	Query	No	Filtra por estado: PENDIENTE DE PAGO, EN PREPARACIÓN, PAGADO, EN CAMINO, ENTREGADO o ANULADO
page	Query	No	Número de página, desde 1

El filtro status usa el estado interno del pedido, no la etapa del ERP. Como la mayoría de los pedidos avanzan por etapas y conservan el estado PROCESANDO PEDIDO, el filtro puede devolver pocos resultados. Para mostrar el avance, usa status y phase de cada pedido.

Respuesta

{
  "success": true,
  "message": "Información procesada de forma correcta.",
  "data": [
    {
      "code": "3f2b8c1e-9d4a-4e7b-8a1c-2b5d6e7f8a90",
      "order": "000123",
      "created_at": "2026-09-20 18:45:10",
      "items": 3,
      "status": "En preparación",
      "phase": { "id": 4, "description": "En preparación", "bg_color": "#FFF4E5", "font_color": "#B54708" },
      "can_cancel": true,
      "cash_order_id": "0057"
    }
  ],
  "links": {
    "first": "https://tienda.ejemplo.com/api/v1/ecommerce/orders?page=1",
    "last": "https://tienda.ejemplo.com/api/v1/ecommerce/orders?page=2",
    "prev": null,
    "next": "https://tienda.ejemplo.com/api/v1/ecommerce/orders?page=2"
  },
  "meta": { "current_page": 1, "from": 1, "last_page": 2, "per_page": 25, "to": 25, "total": 31 }
}

Campo	Tipo	Qué es
code	texto	Identificador del pedido. Úsalo para pedir el detalle
order	texto	Número del pedido para mostrar al cliente
created_at	texto	Fecha del pedido, en formato aaaa-mm-dd hh:mm:ss
items	número	Cantidad total de unidades del pedido
cash_order_id	texto	Número del pedido en el punto de venta del ERP, o 0000 si todavía no tiene

Al filtrar por status, los enlaces de links no conservan el filtro: solo llevan page. Añade tú el status al pedir la página siguiente.

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
422	VALIDATION_ERROR	El estado no existe o la página no es un número válido	Usa uno de los estados de la tabla

Detalle de un pedido

GET /api/v1/ecommerce/orders/{code}

Parámetro	Dónde	Reglas
code	Ruta	El code del pedido, con formato UUID

Respuesta

{
  "success": true,
  "message": "Información procesada de forma correcta.",
  "data": {
    "code": "3f2b8c1e-9d4a-4e7b-8a1c-2b5d6e7f8a90",
    "order": "000123",
    "status": "En preparación",
    "phase": { "id": 4, "description": "En preparación", "bg_color": "#FFF4E5", "font_color": "#B54708" },
    "can_cancel": true,
    "payment_method": "EFECTIVO",
    "quantity": 3,
    "subtotal": 127.12,
    "total_taxes": 22.88,
    "total_shipments": 10,
    "discounts": 0,
    "total": 160,
    "billing": {},
    "customer": {},
    "items": [],
    "shipment": {},
    "document": null,
    "cash_order_id": "0057"
  }
}

Campo	Qué es
payment_method	Código del método de pago con el que se pagó: uno de los code que devuelven los métodos de pago, por ejemplo CONTRAENTREGA o TRANSFERENCIA, o EFECTIVO, que es el que se guarda si al pagar no se envió ninguno. Llega "" si el carrito todavía no se pagó
quantity, subtotal, total_taxes, total_shipments, discounts, total	Importes del pedido
billing	Datos de facturación indicados al pagar
customer	Cliente al que se emite el comprobante
items	Productos del pedido, con su cantidad, importes y una copia del producto en el momento de la compra
shipment	Datos del envío. Nunca llega null. Siempre trae type, weight, subtotal, total, address, extra, postal_code, arrives_from, arrives_to, receives_name, receives_extra y requirements, y además, según type: con TIENDA (recojo en tienda), establishment_id y establishment, una lista con el establecimiento (id, description, address, lead_time en días, logo, latitude, longitude, department, province, district); con AGENCIA, agency_code y agency, que hoy no traen datos útiles de la agencia; con DOMICILIO, details, con price y lead_time en días. La compra actual no guarda el envío, así que los pedidos de hoy traen el valor por defecto: type TIENDA, subtotal y total a 0, y el resto de campos a null
document	El comprobante electrónico, o null mientras no se haya emitido. Trae la serie, el número y las direcciones del PDF y el XML

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
404	NOT_FOUND	El code no tiene formato UUID	Revisa el código
404	ORDER_NOT_FOUND	No existe un pedido con ese código para este cliente	Vuelve a listar los pedidos

Anular un pedido

POST /api/v1/ecommerce/orders/{code}/cancel

Parámetro	Dónde	Reglas
code	Ruta	El code del pedido, con formato UUID

Solo se puede anular mientras can_cancel sea true: antes de que se emita su comprobante y mientras su etapa en el ERP siga admitiendo anulación (por ejemplo, ya no se puede una vez que el pedido está en la etapa «Listo»).

Al anular se libera el stock reservado: la reserva del producto y, si tiene variantes (talla, color…), su stock también vuelve a sumarse.

Respuesta

{ "success": true, "message": "Información procesada de forma correcta.", "data": null }

Si algo sale mal

HTTP	code	Cuándo	Qué hacer
404	ORDER_NOT_FOUND	No existe un pedido con ese código para este cliente	Vuelve a listar los pedidos
409	ORDER_ALREADY_CANCELLED	El pedido ya está en estado ANULADO	—
409	ORDER_CANNOT_BE_CANCELLED	El pedido ya tiene su comprobante emitido, o su etapa en el ERP ya no admite anulación	Comunícate con la tienda