Evadi gli ordini

Il ciclo degli ordini per un'integrazione WMS/ERP (richiede orders:read + orders:write):

Ogni ordine ha number, il numero che il venditore vede sul canale (Shopify "#1011" → "1011"): cerca e mostra gli ordini con questo numero. Quando il canale lo fornisce, l'ordine ha anche il dettaglio degli importi: subtotal, shipping, discount, tax, tax_remitted_by (marketplace quando è il canale a riscuotere e versare l'imposta) e il total del canale, gli stessi numeri dell'esportazione degli ordini. Registra spedizione, sconti e imposte da questi campi; quando sono null il canale non ha fornito un dettaglio e total è la somma delle righe.

1. Ricevi gli ordini quando arrivano

Iscriviti a order.created, oppure interroga:

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

Ogni ordine è normalizzato in un'unica forma, qualunque sia il canale: status, fulfillment_status, lines[], tracking e buyer compreso l'indirizzo di spedizione (buyer.address).

2. Spediscilo

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://..."}
  }'

Se c'è un tracking, Nembol per impostazione predefinita avvisa anche il marketplace di origine (eBay, Etsy, Shopify, WooCommerce, Amazon, TikTok Shop, OnBuy, Square, Squarespace), e l'acquirente riceve la notifica di spedizione del canale stesso. Disattivalo con "notify_channel": false.

Stock e annullamenti

Quando un ordine viene annullato sul suo canale prima della spedizione e la sua vendita aveva tolto le unità dallo stock di Nembol, Nembol le rimette, una volta per ogni riga d'ordine, e invia la nuova quantità a ogni canale su cui c'è il prodotto (come fa una vendita). Ricevi inventory.updated con data.source: "order", data.reason: "order_canceled", data.channel, data.order_id_on_channel, data.variant_id, data.sku e un data.quantity_change positivo.

Lo stock non viene ripristinato quando:

• la vendita non ha cambiato lo stock di Nembol: "quantità dagli ordini" (sync.quantity_from_orders) era spento per quell'account, l'ordine arrivava dalla prima importazione degli ordini passati, oppure è stato evaso da Amazon (FBA);
• l'ordine era già stato spedito o consegnato;
• le variazioni di quantità del canale si sincronizzano in Nembol (sync.quantity_from_channel_edits attivo: Shopify, WooCommerce, Amazon): il ripristino del canale arriva tramite quella sincronizzazione, e aggiungerlo di nuovo conterebbe le unità due volte;
• l'ordine è solo rimborsato: un rimborso non dice che la merce è tornata. Correggi lo stock tu stesso (POST /inventory/batch) quando arriva un reso.

Gli ordini ricevuti prima del 2026-10-17 non vengono ripristinati automaticamente.

Da sapere

• Un ordine per ogni ordine del canale. Un ordine con più righe è un solo ordine (tutte le sue lines, il total completo); l'evasione spedisce tutte le sue righe.
• Niente tracking, niente notifica. mark_shipped da solo aggiorna solo Nembol. Invia il tracking (subito o più tardi) per avvisare il marketplace.
• Un tracking non si può correggere tramite Nembol quando il marketplace ne ha già uno: il nuovo numero viene salvato in Nembol e la risposta riporta channel_already_notified. Correggilo sul marketplace.
• Rinviare è sicuro. Lo stesso tracking inviato di nuovo non invia nulla (una sola email all'acquirente, sempre): la risposta riporta attempted: false, already_notified_same_tracking. I campi che ometti mantengono il loro valore.
• url deve essere un URL http(s), altrimenti la chiamata risponde 422.
• I campi di tracking oltre il limite vengono rifiutati (number e carrier 64, url 512 caratteri), mai troncati.
• Gli annullamenti fatti sul canale arrivano entro 10 minuti (stato canceled, order.status_changed).
• La notifica al marketplace avviene una volta per ordine, con idempotenza rigida. Ritentare la chiamata non avvisa (né scrive) mai due volte all'acquirente.
• Gli ordini in stato finale rifiutano l'evasione: gli ordini annullati/rimborsati restituiscono 422 order_not_fulfillable.
• I dati dell'acquirente sono dati personali. Sono protetti da orders:read; trattali in modo lecito e non conservarne più del necessario.
• channel_notification nella risposta ti dice esattamente cosa è successo: {attempted, delivered, error}.

Ultimo aggiornamento il 20 ottobre 2026