Preparación y entrega

Andrea Ramos compró dos polos. Tu sistema asigna la ubicación que despacha, registra el envío con su seguimiento y marca la entrega con Admin API.

Requisitos

• Un token de Admin con el scope api_admin. Ver Integración con ERP.
• Una aplicación con los permisos shipment:read, shipment:update y order:update. Para listar ubicaciones, también settings:read.
• Un pedido confirmado con productos que requieren envío. Recíbelo con Pedidos entrantes.
• Node.js 18 o superior y Python 3 con requests, para los ejemplos.

export ECOMIQ_TOKEN="<token>"

Lee las órdenes de preparación

Cada pedido nace con sus órdenes de preparación: una por ubicación que despacha, solo con los productos que requieren envío.

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

[
  {
    "id": "7204558912004325310",
    "orderId": "7204558912004325301",
    "orderNumber": "ORD-2026-0001",
    "locationId": null,
    "locationName": null,
    "status": "pendingAssignment",
    "items": [
      {
        "orderItemId": "7204558912004325302",
        "title": "Polo clásico Azul / M",
        "sku": "POL-CL-AZ-M",
        "quantity": 2,
        "shippedQuantity": 0,
        "remainingQuantity": 2,
        "committedQuantity": 0
      }
    ],
    "shipments": [],
    "version": 4821
  }
]

Los ejemplos siguientes reusan API y las cabeceras. Si ninguna ubicación puede despachar, la orden queda en pendingAssignment.

Campos completos en Listar órdenes de preparación.

Asigna una ubicación

Envía el id de la ubicación que va a despachar. Debe estar activa y habilitada para preparación (isActive y useForFulfillment). Búscala en Listar ubicaciones logísticas.

curl -X POST https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/assign \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "locationId": "7204558912004325378" }'

{
  "id": "7204558912004325310",
  "orderNumber": "ORD-2026-0001",
  "locationId": "7204558912004325378",
  "locationName": "Almacén Lima",
  "status": "pending",
  "items": [
    {
      "orderItemId": "7204558912004325302",
      "sku": "POL-CL-AZ-M",
      "quantity": 2,
      "remainingQuantity": 2,
      "committedQuantity": 2
    }
  ],
  "version": 4822
}

La orden pasa a pending con el stock reservado en Almacén Lima. Si falta stock en esa ubicación, la API rechaza la asignación.

Puedes reasignar una orden en pendingAssignment o pending; el stock de la ubicación anterior se libera. Cuando la preparación empieza, ya no se puede reasignar.

Prepara el paquete

Marca la orden en preparación e imprime el comprobante de empaque. Marcarla es opcional y solo aplica a órdenes en pending.

curl -X POST https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/in-progress \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

curl https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/packing-slip \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -o comprobante.html

Al marcarla, el pedido pasa a inProgress y el cliente recibe un correo de estado.

El comprobante es HTML. Trae el destinatario, la ubicación de origen y los artículos. Para ORD-2026-0001 muestra a Andrea Ramos, Av. Larco 1234, Miraflores, Lima.

Antes del envío incluye todos los artículos; después, sale un comprobante por envío. Para varias órdenes, usa Obtener comprobantes en lote.

Registra el envío

Cuando el paquete sale, registra el envío con los datos de tu transportista. Con origin: "manual", solo se guardan esos datos, sin llamar a un transportista.

curl -X POST https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/ship \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "manual",
    "itemSelection": "all",
    "trackingNumber": "PE1234567890",
    "trackingLink": "https://courierlima.pe/seguimiento/PE1234567890",
    "carrierName": "Courier Lima"
  }'

{
  "id": "7204558912004325310",
  "orderNumber": "ORD-2026-0001",
  "locationName": "Almacén Lima",
  "status": "shipped",
  "trackingNumber": "PE1234567890",
  "shipments": [
    {
      "id": "7204558912004325320",
      "originKind": "manual",
      "trackingNumber": "PE1234567890",
      "trackingLink": "https://courierlima.pe/seguimiento/PE1234567890",
      "carrierName": "Courier Lima",
      "items": [
        {
          "orderItemId": "7204558912004325302",
          "sku": "POL-CL-AZ-M",
          "quantity": 2
        }
      ]
    }
  ],
  "version": 4824
}

El stock reservado se descuenta y la orden pasa a shipped. El pedido pasa a inTransit, el cliente recibe un correo con el seguimiento y se envía el webhook order.in_transit.

Para un envío parcial, usa itemSelection: "selected" y lista items con orderItemId y quantity. Cada cantidad es entera y no supera remainingQuantity.

Envía también shipmentId con el ID del envío en tu transportista. Si reintentas con el mismo valor, la API devuelve el envío existente. Campos completos en Despachar orden de preparación.

Crea el envío con un transportista

Si la tienda tiene un transportista conectado, usa este paso en lugar de Registra el envío: el envío se crea en el transportista, con su seguimiento y su guía.

curl -X POST https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/shipment \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "itemSelection": "all",
    "packageSelection": "automatic",
    "connectionSelection": "orderDefault"
  }'

curl -L https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/shipments/7204558912004325320/label \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -o guia.pdf

{
  "id": "7204558912004325320",
  "fulfillmentOrderId": "7204558912004325310",
  "orderId": "7204558912004325301",
  "originKind": "connection",
  "orderNumber": "ORD-2026-0001",
  "trackingNumber": "PE1234567890",
  "carrierName": "Courier Lima"
}

orderDefault usa el transportista del pedido. automatic usa el paquete de los artículos o el predeterminado de la tienda. La dirección de envío debe tener código de país.

En la ruta de la guía, {shipmentId} es el id de la respuesta. La guía y los eventos de seguimiento solo existen en envíos de transportista. En un envío manual, la API responde 400.

Si el pedido tiene una sola orden de preparación, también sirve Crear envío del pedido.

Corrige el seguimiento

Si cambia el número o el enlace, actualiza el envío. En expectedVersion envía la version de la orden de preparación, de Registra el envío o de Obtener orden de preparación.

curl -X PATCH https://api.ecomiq.pe/api/v1/fulfillment/orders/7204558912004325310/shipments/7204558912004325320/tracking \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 4824,
    "trackingNumber": "PE1234567891",
    "trackingLink": "https://courierlima.pe/seguimiento/PE1234567891",
    "carrierName": "Courier Lima"
  }'

Envía siempre los tres campos de seguimiento. Usa el id del envío que trae shipments. La respuesta devuelve la orden de preparación con su nueva version.

Si la orden cambió, la API responde 409: vuelve a leerla y reintenta. Solo se corrigen envíos manuales de órdenes no entregadas ni canceladas. El cambio queda en el historial del pedido y no reenvía el correo de envío.

Marca la entrega

Cuando tu transportista confirme la entrega, marca la orden como entregada. Aplica a órdenes en inProgress, readyToPickUp o shipped.

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

{
  "id": "7204558912004325310",
  "orderNumber": "ORD-2026-0001",
  "status": "delivered",
  "trackingNumber": "PE1234567891"
}

Cuando todas las órdenes del pedido están entregadas, el pedido pasa a delivered, el cliente recibe el correo de entrega y se envía el webhook order.delivered. Si solo algunas lo están, el pedido queda en partialDelivered.

Elige el aviso al cliente

El estado del pedido se calcula desde sus órdenes de preparación, y el cliente recibe un aviso solo cuando ese estado cambia.

Los correos van al email del pedido; sin correo, no hay aviso. Para avisar por WhatsApp o no avisar, usa POST /v1/orders/{orderId}/in-transit en lugar de Registra el envío.

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": "PE1234567890",
    "trackingLink": "https://courierlima.pe/seguimiento/PE1234567890",
    "carrierName": "Courier Lima",
    "notifyCustomer": true,
    "notificationChannels": ["email", "whatsApp"]
  }'

{
  "id": "7204558912004325301",
  "orderNumber": "ORD-2026-0001",
  "firstName": "Andrea",
  "lastName": "Ramos",
  "status": "inTransit"
}

La llamada registra un envío manual con todos los artículos de cada orden asignada que aún no sale. WhatsApp usa el phone del pedido. Con notifyCustomer: false, el cliente no recibe aviso.

Para entregar todo de una vez, usa Marcar pedido como entregado. Marca como entregadas las órdenes asignadas y envía el correo de entrega. Más campos en Marcar pedido en tránsito.

Siguientes pasos