Gestionar el envío de pedidos

El ciclo de pedidos para una integración WMS/ERP (requiere orders:read + orders:write):

Cada pedido incluye number, el número que el comerciante ve en el canal (Shopify "#1011" → "1011"): busca y muestra los pedidos por ese número. Cuando el canal lo proporciona, el pedido también tiene su desglose de importes: subtotal, shipping, discount, tax, tax_remitted_by (marketplace cuando el canal recauda y paga el impuesto) y el total del canal, las mismas cifras que la exportación de pedidos. Contabiliza el envío, los descuentos y los impuestos a partir de estos campos; cuando son null, el canal no dio ningún desglose y total es la suma de las líneas.

1. Recibir los pedidos a medida que llegan

Suscríbete a order.created o consulta periódicamente:

curl "https://api.nembol.com/rest/v1/orders?limit=50" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Todos los pedidos se normalizan a una misma forma sea cual sea el canal: status, fulfillment_status, lines[], tracking y buyer, incluida la dirección de envío (buyer.address).

2. Enviarlo

curl -X POST https://api.nembol.com/rest/v1/orders/{id}/fulfillment \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ship-EBAY-12345" \
  -d '{
    "mark_shipped": true,
    "tracking": {"number": "1Z999...", "carrier": "UPS", "url": "https://..."}
  }'

Si hay seguimiento, Nembol también avisa al marketplace de origen por defecto (eBay, Etsy, Shopify, WooCommerce, Amazon, TikTok Shop, OnBuy, Square, Squarespace), y el comprador recibe la notificación de envío propia del canal. Desactívalo con "notify_channel": false.

Stock y cancelaciones

Cuando un pedido se cancela en su canal antes del envío y su venta había descontado las unidades del stock de Nembol, Nembol las devuelve, una vez por línea de pedido, y envía la nueva cantidad a todos los canales en los que está el producto (igual que hace una venta). Recibes inventory.updated con data.source: "order", data.reason: "order_canceled", data.channel, data.order_id_on_channel, data.variant_id, data.sku y un data.quantity_change positivo.

No se repone stock cuando:

• la venta no cambió el stock de Nembol: "cantidad desde pedidos" (sync.quantity_from_orders) estaba desactivada para esa cuenta, el pedido vino de la primera importación de pedidos anteriores o lo gestionó Amazon (FBA);
• el pedido ya se había enviado o entregado;
• los cambios de cantidad propios del canal se sincronizan con Nembol (sync.quantity_from_channel_edits activado: Shopify, WooCommerce, Amazon): la reposición del canal llega a través de esa sincronización, y añadirla otra vez contaría las unidades dos veces;
• el pedido solo está reembolsado: un reembolso no indica que la mercancía haya vuelto. Ajusta tú el stock (POST /inventory/batch) cuando llegue una devolución.

Los pedidos recibidos antes del 2026-10-17 no se reponen automáticamente.

Puntos a tener en cuenta

• Un pedido por cada pedido del canal. Un pedido con varias líneas es un solo pedido (todas sus lines, el total completo); el envío incluye todas sus líneas.
• Sin seguimiento, no hay aviso. mark_shipped por sí solo actualiza únicamente Nembol. Envía el seguimiento (ahora o más tarde) para avisar al marketplace.
• Un seguimiento no se puede corregir a través de Nembol una vez que el marketplace ya tiene uno: el nuevo número se guarda en Nembol y la respuesta indica channel_already_notified. Corrígelo en el marketplace.
• Reenviar es seguro. El mismo seguimiento otra vez no envía nada (un solo email al comprador, nunca más): la respuesta indica attempted: false, already_notified_same_tracking. Los campos que omites conservan su valor.
• url debe ser una URL http(s), o la llamada responde 422.
• Los campos de seguimiento que superan su límite se rechazan (number y carrier 64, url 512 caracteres), nunca se recortan.
• Las cancelaciones hechas en el canal llegan en menos de 10 minutos (estado canceled, order.status_changed).
• El aviso al marketplace es una vez por pedido, estrictamente idempotente. Reintentar la llamada nunca avisa (ni envía un email) al comprador dos veces.
• Los pedidos en estado final rechazan el envío: los pedidos cancelados o reembolsados devuelven 422 order_not_fulfillable.
• Los datos del comprador son datos personales (PII). Están protegidos por orders:read; trátalos conforme a la ley y no guardes más de lo necesario.
• channel_notification en la respuesta te dice exactamente qué ha pasado: {attempted, delivered, error}.

Última actualización el 20 de octubre de 2026