Gestión de pedidos

Cada mañana, una tienda de Lima revisa los pedidos de ayer con Admin API: busca los que siguen sin pagar, etiqueta los urgentes y archiva los entregados.

Requisitos

• Un token de Admin en ECOMIQ_TOKEN. Ver Inicio rápido.
• Los permisos order:read, para buscar, leer y exportar, y order:update, para todo lo demás.
• Node.js 18 o Python con requests, para los ejemplos.

Busca pedidos

GET /v1/orders filtra por estado, fecha, etiqueta y texto. Este ejemplo trae los pedidos de ayer que tienen saldo por cobrar.

curl "https://api.ecomiq.pe/api/v1/orders?task=toCollect&dateFrom=2026-10-05T05:00:00Z&dateTo=2026-10-06T04:59:59Z&limit=50" \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

{
  "data": [
    {
      "id": "7204558912004325301",
      "orderNumber": "ORD-2026-0142",
      "firstName": "Andrea",
      "lastName": "Ramos",
      "status": "new",
      "state": "open",
      "currencyCode": "PEN",
      "total": 178,
      "paymentAt": null,
      "tags": null,
      "assignee": null,
      "archivedOn": null,
      "orderDate": "2026-10-05T19:42:10Z"
    }
  ],
  "hasNextPage": false,
  "nextCursor": null,
  "totalCount": 1
}

Los pasos siguientes reutilizan ADMIN, headers y HEADERS.

• Repite un parámetro para pedir varios valores: status=new&status=confirmed.
• Sin archived, la lista incluye los archivados. task deja fuera los archivados, cancelados e inválidos.
• Ordena con sortBy (orderDate, orderNumber, total o updatedOn) y sortDirection. Por defecto, del más reciente al más antiguo. Ver Paginación.

Lee un pedido

Con include=trackings, la respuesta trae el historial del pedido, del más reciente al más antiguo.

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

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0142",
  "status": "new",
  "state": "open",
  "email": "andrea.ramos@example.com",
  "total": 178,
  "notes": null,
  "tags": null,
  "assignee": null,
  "archivedOn": null,
  "updatedOn": "2026-10-05T19:42:10.512344Z",
  "financialSummary": {
    "paidAmount": 0,
    "refundedAmount": 0,
    "balanceDue": 178,
    "refundableAmount": 0
  },
  "trackings": [
    {
      "type": "new",
      "title": "Order Created",
      "content": "Order created successfully.",
      "createdOn": "2026-10-05T19:42:10Z"
    }
  ]
}

Guarda updatedOn: lo necesitas para cambiar la nota.

Anota y asigna

PATCH /v1/orders/{orderId}/notes cambia la nota interna y el responsable del pedido. Responde 204.

curl -X PATCH https://api.ecomiq.pe/api/v1/orders/7204558912004325301/notes \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Entregar en portería. La clienta trabaja de día.",
    "assignedMemberId": "7204558912004320011",
    "expectedUpdatedOn": "2026-10-05T19:42:10.512344Z"
  }'

• La operación reemplaza los dos campos. assignedMemberId: null quita al responsable; para conservarlo, envía el assignee.memberId actual.
• El responsable debe ser un miembro activo de la tienda.
• Envía updatedOn tal como lo leíste, sin convertirlo a fecha. Si el pedido cambió, responde 409: vuelve a leerlo y reintenta.

Comenta el pedido

La nota es un solo texto. Los comentarios se suman al historial, con tu usuario y la hora.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/comments \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Llamé a Andrea: paga hoy por transferencia." }'

Responde 204. El comentario aparece en trackings con type: "note". Admite hasta 2000 caracteres, attachmentUrls y hasta 20 mentionedMemberIds para avisar a tu equipo.

Etiqueta pedidos

PATCH /v1/orders/{orderId}/tags reemplaza todas las etiquetas. Lee tags, agrega la tuya y envía la lista completa.

curl -X PATCH https://api.ecomiq.pe/api/v1/orders/7204558912004325301/tags \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": "urgente,regalo" }'

• Separa las etiquetas con comas, sin espacios. El texto completo admite hasta 500 caracteres. Vacío o null las borra.
• Luego filtra con tags=urgente. El filtro ignora mayúsculas.
• Un token de vendedor no puede etiquetar ni comentar: responde 403.

Recuerda el pago

POST /v1/orders/{orderId}/payment-reminder envía un correo al cliente con el saldo pendiente.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/payment-reminder \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "recordatorio-ORD-2026-0142-1",
    "dueDate": "2026-10-08"
  }'

• Responde 202. Si repites la idempotencyKey, el cliente recibe un solo correo. Usa hasta 50 caracteres.
• dueDate es opcional y aparece en el correo.
• El pedido necesita email y saldo pendiente. No puede estar cancelado ni ser inválido.

Cancela un pedido

Si el cliente no pagó, cancela el pedido. notifyCustomer: false evita el correo de cancelación.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325301/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelReason": "No recibimos el pago.",
    "cancelReasonType": "sin-pago",
    "notifyCustomer": false
  }'

Responde 200 con el pedido. Los estados y eventos están en Estados del pedido.

• Los pagos autorizados y sin capturar se liberan, salvo que el mismo pago cubra otro pedido activo.
• Cancelar no devuelve el dinero ya capturado. Revisa financialSummary.refundableAmount y reembolsa con Devoluciones y reembolsos.
• Para cancelar y reembolsar en un paso antes del envío, usa Cancelar pedido con reembolso. Requiere también payment:create.

Archiva pedidos

Archivar saca el pedido de tu lista diaria. No cambia su estado ni sus pagos.

curl -X PUT https://api.ecomiq.pe/api/v1/orders/7204558912004325301/archive \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

• Responde 204. Envía "archived": false para restaurarlo.
• Para hallar los entregados que siguen a la vista, busca con status=delivered&archived=false.
• Cancelar un pedido también lo archiva. Con orderProcessing.autoArchiveDeliveredOrders en los ajustes de la tienda, los entregados y pagados se archivan solos.

Cambia en lote

POST /v1/orders/batch/status lleva varios pedidos al mismo estado. Este ejemplo cancela tres pedidos sin pagar.

curl -X POST https://api.ecomiq.pe/api/v1/orders/batch/status \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetStatus": "cancelled",
    "ids": ["7204558912004325301", "7204558912004325302", "7204558912004325303"],
    "cancelReason": "No recibimos el pago en 48 horas.",
    "cancelReasonType": "sin-pago"
  }'

{
  "results": [
    {
      "index": 0,
      "id": "7204558912004325301",
      "status": "updated",
      "errors": []
    },
    {
      "index": 1,
      "id": "7204558912004325302",
      "status": "updated",
      "errors": []
    },
    {
      "index": 2,
      "id": "7204558912004325303",
      "status": "failed",
      "errors": [
        {
          "field": "id",
          "code": "Orders.NotFound",
          "message": "Order not found."
        }
      ]
    }
  ]
}

Cada pedido se procesa por separado. Revisa el status de cada resultado.

• Envía ids (hasta 100) o filters, no ambos. Con filters responde 202 con una operación; síguela con Obtener operación.
• Un filters vacío selecciona todos los pedidos de la tienda. Acótalo con statuses, tags, dateFrom, dateTo u orderIds.
• targetStatus acepta confirmed, inProgress, invoiced, readyToPickUp (con trackingNumber), inTransit, delivered, cancelled, returned, closed e invalid. Al cancelar en lote, el cliente siempre recibe el aviso.

Exporta pedidos

POST /v1/orders/exports arma un archivo con los pedidos que elijas. Responde 202 con una operación.

curl -X POST https://api.ecomiq.pe/api/v1/orders/exports \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "statuses": ["delivered"],
    "dateFrom": "2026-09-01T05:00:00Z",
    "dateTo": "2026-10-01T04:59:59Z"
  }'

{
  "id": "7204558912004325410",
  "status": "pending",
  "resource": "orders",
  "format": "csv",
  "createdOn": "2026-10-06T13:05:00Z"
}

• Los filtros van en el cuerpo y en plural: statuses, states, fulfillmentStatuses, tags, orderIds y orderNumbers.
• format acepta csv, xlsx o jsonl. Por defecto, xlsx.
• Consulta GET /v1/operations/{id}. Con status: "completed", resultUrl trae el archivo.

Errores

Siguientes pasos

• Estados del pedido: confirma, envía y entrega.
• Devoluciones y reembolsos: devuelve el dinero capturado.
• Pedidos: todas las operaciones.