Sincronizza stock e prezzi in blocco

Per le sincronizzazioni ricorrenti da un ERP o da un magazzino, POST /inventory/batch è l'endpoint su cui costruire: individua le varianti per SKU, quindi non devi salvare nessun id di Nembol.

curl -X POST https://api.nembol.com/rest/v1/inventory/batch \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-sync-2026-07-30T22:00" \
  -d '{"items": [
    {"sku": "VDJ-M-001", "quantity": 12},
    {"sku": "VDJ-L-001", "quantity": 0, "price": "44.90"}
  ]}'

La scrittura in Nembol è immediata; la propagazione ai canali è asincrona. La risposta è un'operazione. Gli elementi che non trovano corrispondenza tornano in rejected_items con un motivo (sku_not_found, sku_ambiguous) senza far fallire gli altri, e compaiono anche come voci failed in results: l'operazione termina partial, così uno SKU rinominato nel tuo sistema finisce nei tuoi avvisi invece di interrompere in silenzio la sua sincronizzazione. Se nessun elemento può essere applicato, la chiamata risponde 422 no_items_applied (motivi in error.details.rejected_items) e non cambia nulla.

results[] contiene una voce per ogni SKU e per ogni canale su cui il prodotto è attivo, con il suo channel_account_id e listing_id:

• pending: salvato in Nembol, il canale non ha ancora risposto;
• succeeded: quel canale ha il nuovo stock / prezzo;
• failed: quel canale l'ha rifiutato, con il suo messaggio in error. L'operazione diventa partial.

Un rifiuto temporaneo (ad esempio il "this product is currently being modified" di Shopify quando due scritture raggiungono insieme lo stesso prodotto, o un rate limit) viene prima ritentato da Nembol: durante i tentativi il risultato resta pending, e solo un invio che continua a fallire termina failed.

Così sai sempre se ogni negozio ha ricevuto lo stock, ed è questo che evita l'overselling: attendi il webhook operation.completed (o interroga GET /operations/{id}) e intervieni sulle voci fallite. Un prodotto non attivo su alcun canale riceve una sola voce con channel_account_id: null, già succeeded: salvato in Nembol, niente da inviare.

Upsert dell'intero catalogo

Per creare o aggiornare prodotti interi (contenuti inclusi), usa POST /products/batch. Ha la stessa corrispondenza per SKU (uno SKU ambiguo fallisce con sku_ambiguous, senza scrivere nulla), fino a 100 elementi, esiti per elemento, status: "partial" quando solo alcuni falliscono e 422 no_items_applied quando nessuno viene applicato. Gli SKU senza corrispondenza vengono creati (titolo obbligatorio), quelli con corrispondenza vengono aggiornati.

Azioni in blocco sulle inserzioni

POST /listings/batch esegue una action (publish, delist, resync o retry) su un massimo di 100 coppie (prodotto, account del canale), ad esempio per copiare un catalogo su un secondo account eBay:

curl -X POST https://api.nembol.com/rest/v1/listings/batch \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: copy-to-ebay2-page-1" \
  -d '{"action": "publish",
       "items": [{"product_id": "prod_66a1f0", "channel_account_id": "chac_6aa12cab"},
                 {"product_id": "prod_66a1f1", "channel_account_id": "chac_6aa12cab"}]}'

Ogni coppia ha il proprio risultato nell'operazione: pending finché il canale non risponde, skipped quando è già nello stato richiesto (ad esempio already_listed), altrimenti failed con un codice. I risultati tornano nello stesso ordine dei tuoi items, e ognuno ripete il product_id e il channel_account_id che hai inviato, compresi quelli sconosciuti, così sai sempre a quale coppia si riferisce un risultato. Per cataloghi più grandi procedi a pagine di 100 coppie alla volta, con una Idempotency-Key diversa per ogni pagina.

Variazioni di prezzo in blocco

POST /inventory/price_adjustment alza o abbassa tutte le varianti di un massimo di 100 prodotti di una percentuale o di un importo (con arrotondamento opzionale a .99) e invia i nuovi prezzi ai canali attivi:

curl -X POST https://api.nembol.com/rest/v1/inventory/price_adjustment \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": ["prod_66a1f0", "prod_66a1f1"], "mode": "percentage", "value": -15, "rounding": true}'

Il risultato di ogni variante riporta previous_price e price. Per annullare, rinvia i prezzi precedenti:

POST /inventory/batch
{"items": [{"sku": "TEE-M", "price": "19.99"}, {"sku": "TEE-L", "price": "21.99"}]}

Da sapere

• Una Idempotency-Key per ogni esecuzione batch. Se ritenti un batch andato in timeout con la stessa chiave, ottieni l'esito salvato invece di applicarlo due volte.
• Gli aggiornamenti batch non accettano immagini. Un elemento con corrispondenza e images[] fallisce (per elemento). Aggiorna le immagini con PATCH /products/{id}.
• quantity: 0 è un valore reale. Rende la variante esaurita ovunque.
• Ascolta operation.completed invece di interrogare a ripetizione se sincronizzi spesso.
• I prezzi sono stringhe ("44.90"), sempre nella valuta base dello store.
• Un canale può mostrare meno unità di quelle che hai (o "esaurito" su Google Merchant Center): i venditori possono impostare un limite di quantità per canale (inventory in GET /channel_accounts).
• Le regole di prezzo del canale si applicano in aggiunta ai prezzi che imposti o modifichi (pricing sull'account del canale).

Ultimo aggiornamento il 20 ottobre 2026