Pedidos manuales

Andrea escribe por WhatsApp desde Trujillo y pide dos polos. Armas su pedido con Admin API, le envías un enlace y ella paga en tu tienda.

Requisitos

• Un token de Admin con los permisos draft:create, draft:read y draft:update en ECOMIQ_TOKEN. Para registrar un pago, también order:update y payment:create. Ver Inicio rápido.
• La ruta /drafts/{shareToken} en tu tienda. Los temas de Ecomiq ya la traen. En una tienda headless, la creas tú.
• Node.js o Python con requests, para los ejemplos.

Crea el borrador

Un pedido manual empieza como borrador. Envía la moneda y los datos del cliente.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currencyCode": "PEN",
    "email": "andrea.ramos@example.com",
    "firstName": "Andrea",
    "lastName": "Ramos",
    "phone": "+51987654321",
    "source": "whatsapp"
  }'

Responde 201 con el id del borrador. Los pasos siguientes reutilizan ADMIN, headers y HEADERS.

• Sin customerId, envía email, firstName y lastName. Con él, el borrador copia los datos del cliente y su dirección principal.
• El borrador nace en draft y recibe un número de la tienda: D1, D2…
• GET /v1/order-drafts ordena por draftDate descendente. Cambia el orden con sortBy (draftDate, draftNumber, total, createdOn o updatedOn) y sortDirection (asc o desc).

Agrega los productos

Agrega una variante del catálogo con su cantidad. discount es el descuento de toda la línea, en negativo, o 0 sin descuento. shipping suma el envío de cada línea y el de los métodos de envío seleccionados.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/items \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "catalogVariant",
    "variantId": "7204558912004321180",
    "quantity": 2,
    "discount": -20
  }'

{
  "items": [
    {
      "id": "7204558912004323771",
      "title": "Polo de algodón",
      "quantity": 2,
      "discount": -20.0,
      "total": 158.0
    }
  ],
  "tax": 24.1,
  "total": 158.0
}

• unitPrice cambia el precio solo en este borrador. Para algo fuera del catálogo, usa "kind": "custom" con title y unitPrice.
• El impuesto de los productos del catálogo se calcula solo.
• Cambia una línea con PATCH /v1/order-drafts/{draftId}/items/{itemId}. Con quantity: 0 o con DELETE, la quitas.

Agrega la dirección y el envío

Envía la dirección de envío. PATCH solo cambia lo que envías.

curl -X PATCH https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "name": "Andrea Ramos",
      "address1": "Av. España 1520",
      "city": "Trujillo",
      "countryCode": "PE"
    }
  }'

Luego pide las opciones de envío para esa dirección.

curl https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/shipping-options \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

Cada opción trae displayName, price, shippingMethodId, target, targetId y rateId. Asigna una con esos cuatro últimos valores; el borrador queda con shipping: 12 y total: 170.

curl -X PUT https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/shipping-method \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shippingMethodId": "7204558912004328810", "target": "automatic" }'

• Envía billingAddress igual: convertir exige las dos, cada una con name, address1, city y countryCode.
• Si cambias la dirección de envío o los productos, vuelve a asignar el envío. DELETE /v1/order-drafts/{draftId}/shipping-method lo quita.
• Con varios vendedores o perfiles de envío, cada grupo lleva su envío: indica sellerId o shippingProfileId.

Comparte el enlace de pago

Crea el enlace y envíaselo al cliente por WhatsApp. shareExpiresAt es opcional y debe ser futuro; sin él, el enlace no vence.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/share \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "shareExpiresAt": "2026-10-09T05:00:00Z" }'

{
  "shareToken": "Jm2xQ9vT4pLk8sWb1nZr6cYh0uEa3dFg",
  "sharePath": "/drafts/Jm2xQ9vT4pLk8sWb1nZr6cYh0uEa3dFg"
}

El enlace es el dominio principal de tu tienda más sharePath. Ver Listar dominios.

• El borrador pasa a sent. Cada llamada crea un token nuevo y el anterior deja de funcionar.
• Con "allowAnonymousShareAccess": false, el cliente debe iniciar sesión en tu tienda.
• Para enviarlo por correo, usa Enviar factura del borrador.

Cobra en tu tienda

En /drafts/{shareToken}, tu tienda muestra el borrador con Storefront API. Al confirmar, lo convierte en pedido.

El GET devuelve lo que ve el comprador: número y estado del borrador, contacto, direcciones, artículos con shipping, tax y warranty, importes y métodos de envío con su precio y fechas de entrega. Las notas, etiquetas y metadatos internos no se incluyen.

curl https://storefront.ecomiq.pe/v1/order-drafts/share/<share-token> \
  -H "x-Store-Domain: mi-tienda"

curl -X POST https://storefront.ecomiq.pe/v1/order-drafts/share/<share-token>/checkout \
  -H "x-Store-Domain: mi-tienda" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceType": "ticket" }'

El checkout responde orderPaths, con rutas /orders/{statusToken}. Lleva al cliente allí: paga el saldo como en Checkout y pago.

• Abrirlo pasa el borrador a viewed, y el checkout a converted. Revísalo con GET /v1/order-drafts/{draftId} o lista los vistos con GET /v1/order-drafts?status=viewed.
• Si ya se convirtió, GET responde con orderPaths: redirige al cliente.
• Se crea un pedido por vendedor y perfil de envío, con una ruta cada uno.

O cobra desde el admin

Si el cliente ya pagó por Yape, convierte el borrador tú mismo.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/convert \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceType": "ticket" }'

{
  "orderIds": ["7204558912004325350"],
  "order": {
    "orderNumber": "ORD-2026-0001",
    "status": "new",
    "financialSummary": { "balanceDue": 170.0 }
  }
}

Luego registra el pago en cada pedido de orderIds, por su balanceDue.

curl -X POST https://api.ecomiq.pe/api/v1/orders/7204558912004325350/payments \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "method": "yape", "currencyCode": "PEN", "amount": 170,
        "reference": "Operación 845120", "idempotencyKey": "D1-yape" }'

• Convertir exige artículos, ambas direcciones y un envío por grupo.
• Si el borrador ya se convirtió, responde 200 con los mismos pedidos.
• Cuando el pago cubre el total, el pedido pasa a confirmed.

Cancela un borrador

Un borrador no se elimina: se cancela.

curl -X POST https://api.ecomiq.pe/api/v1/order-drafts/7204558912004324769/cancel \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "La clienta compró en tienda." }'

• El borrador pasa a cancelled y su enlace deja de funcionar.
• reason es obligatorio, con un máximo de 500 caracteres. Se guarda en cancelReason del detalle administrativo; las notas del borrador se conservan.
• Un borrador converted no se cancela: cancela su pedido.

Errores

Siguientes pasos

• Checkout y pago
• Estados del pedido
• Borradores de pedido