Estados del pedido

Un pedido va de new a closed. Cada paso tiene su operación en Admin API y su evento de webhook.

Estados y eventos

status indica el paso del pedido. Cada paso tiene su operación y su evento de webhook.

partialDelivered, partialReturned y partialCancelled aparecen cuando el cambio afecta solo a algunos artículos. pendingToConfirm indica un pago pendiente en la tienda online.

state resume el pedido en cuatro valores:

status escribe cancelled y state escribe canceled.

Cada evento llega con el cuerpo OrderWebhookModel. Trae state y fulfillmentStatus, sin status: para conocer el paso exacto, lee el pedido.

Requisitos

• Un token de Admin con el scope api_admin. Ver Integración con ERP.
• Los permisos order:read y order:update. Para facturar, también invoice:create.
• Node.js o Python con requests, para los ejemplos.

Lista los pedidos

Filtra por status para ver los pedidos de un paso. Repite el parámetro para pedir varios: status=inProgress&status=invoiced.

curl "https://api.ecomiq.pe/api/v1/orders?status=confirmed&limit=20" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "data": [
    {
      "id": "7204558912004325301",
      "orderNumber": "ORD-2026-0001",
      "firstName": "Andrea",
      "lastName": "Ramos",
      "status": "confirmed",
      "state": "open",
      "fulfillmentStatus": "unfulfilled",
      "currencyCode": "PEN",
      "total": 178,
      "orderDate": "2026-10-04T14:58:03Z"
    }
  ],
  "hasNextPage": false,
  "nextCursor": null,
  "totalCount": 1
}

Los pedidos llegan del más reciente al más antiguo. También puedes filtrar por state, dateFrom, dateTo, customerId, tags o search. Si hasNextPage es true, envía nextCursor como cursor; ver Paginación.

Lee un pedido

Consulta el pedido para ver su status, sus fechas y sus artículos.

curl https://api.ecomiq.pe/api/v1/orders/7204558912004325301 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "confirmed",
  "state": "open",
  "fulfillmentStatus": "unfulfilled",
  "confirmedAt": "2026-10-04T15:02:11Z",
  "currencyCode": "PEN",
  "total": 178,
  "items": [
    {
      "id": "7204558912004325302",
      "title": "Polo de algodón",
      "quantity": 2,
      "orderItemStatus": "confirmed"
    }
  ]
}

Cada paso guarda su fecha: confirmedAt, inProgressAt, invoicedAt, pickupAt, inTransitAt, completedAt, cancelledAt, closedAt e invalidAt. completedAt marca la entrega.

Confirma el pedido

Los pedidos de la tienda online se confirman solos al capturar el pago completo. Mientras tanto quedan en pendingToConfirm. Si el pago falla o se cancela, pasan a invalid.

Confirma los demás pedidos con POST /v1/orders/{orderId}/confirm. La operación no lleva cuerpo.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/confirm \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "confirmed",
  "state": "open",
  "confirmedAt": "2026-10-04T15:02:11Z"
}

Si el pedido ya estaba confirmado, la API responde 200 sin enviar otro evento.

Avanza el pedido

Cada operación devuelve el pedido actualizado. Envía todos los campos de la tabla; los que no tengas van como null, salvo trackingNumber en ready-to-pickup.

• Confirma antes los pedidos de la tienda online, los que vienen de un borrador y los creados con POST /v1/orders/batch.
• Puedes saltar pasos, por ejemplo de confirmed a inTransit. No puedes volver a un paso anterior.
• Si el pedido tiene precios por aprobar, apruébalos con Aprobar precio.
• Un cambio no permitido responde 409.

Este ejemplo marca el pedido en tránsito y avisa a Andrea por correo.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/in-transit \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "PE48213977",
    "trackingLink": "https://mitienda.pe/seguimiento/PE48213977",
    "carrierName": "Courier Lima",
    "notifyCustomer": true,
    "notificationChannels": ["email"]
  }'

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "inTransit",
  "state": "open",
  "fulfillmentStatus": "shipped",
  "inTransitAt": "2026-10-05T10:15:40Z"
}

notifyCustomer es true por defecto. En notificationChannels elige email, whatsApp o ambos. Si usas órdenes de preparación, sus cambios también avanzan el pedido y envían estos eventos.

Para mover muchos pedidos a la vez, usa Actualizar estados en lote. Con hasta 100 ids responde 200 con el resultado de cada pedido. Con filters responde 202 con una operación.

Cancela el pedido

Cancela con POST /v1/orders/{orderId}/cancel mientras el pedido no se entregue. Envía cancelReason y cancelReasonType, o null en cualquiera de los dos.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelReason": "Nos quedamos sin stock del Polo de algodón.",
    "cancelReasonType": "sin-stock"
  }'

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "cancelled",
  "state": "canceled",
  "fulfillmentStatus": "canceled",
  "cancelReason": "Nos quedamos sin stock del Polo de algodón.",
  "cancelledAt": "2026-10-04T17:40:09Z"
}

cancelReason aparece en el aviso de cancelación al cliente. Cancelar también cancela las órdenes de preparación del pedido. Si ya estaba cancelado, la API responde 200 sin enviar otro evento.

Para cancelar y reembolsar en un solo paso, usa Cancelar pedido con reembolso. Solo funciona antes del envío.

Devuelve o cierra

Cerrar no lleva cuerpo.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/close \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "status": "closed",
  "state": "closed",
  "closedAt": "2026-10-12T09:00:00Z"
}

Si hay un reembolso pendiente, el cierre responde 409. Un pedido closed o invalid ya no cambia de estado.

Siguientes pasos