Concetti chiave

Cinque oggetti spiegano l'intera API.

Prodotto

L'elemento centrale del catalogo, di proprietà di Nembol. Contiene tutti i dati di vendita: titolo, descrizione (l'unico testo che ogni canale pubblica, HTML consentito; short_description è solo un suo alias deprecato), marca, category, tag, mpn, vat_rate, weight/dimensions, images[] (fino a 20) e variants[] (ognuna con SKU, prezzo, msrp (prezzo barrato sui canali che lo supportano), quantità, codice a barre, grams (peso di spedizione per variante) e images specifiche della variante). I prezzi sono stringhe decimali nella valuta di base del negozio (GET /store → currency).

Le varianti con options (es. Colore/Taglia) devono coprire ogni combinazione dei valori delle opzioni. I canali generano la matrice completa, quindi gli insiemi incompleti vengono rifiutati subito invece di pubblicare inserzioni rotte.

Un prodotto può esistere localmente senza essere su alcun canale, anche senza immagini (resta una bozza locale finché non viene pubblicato).

Inserzione

La proiezione di un prodotto su un account canale. È una risorsa a tutti gli effetti, con il proprio id (list_…), status (listed, imported, ongoing, error, delisted), id_on_channel, url_on_channel e issues[], che riporta il messaggio di errore del canale quando qualcosa non va.

POST   /rest/v1/listings              {product_id, channel_account_id}   # publish
PATCH  /rest/v1/listings/{id}         {}                                 # re-sync
DELETE /rest/v1/listings/{id}                                            # delist

La pubblicazione è idempotente per coppia (product_id, channel_account_id), e GET /listings?status=error è la query che dovrebbe eseguire la tua logica di retry.

Due comportamenti lato canale da conoscere: alcuni venditori configurano per canale delle regole di prezzo (una maggiorazione percentuale o fissa), quindi il prezzo sul canale può legittimamente differire dal prezzo del prodotto; e su WooCommerce il venditore può aver scelto di creare i prodotti come bozze, nel qual caso un'inserzione listed esiste sul negozio ma il suo URL non è ancora pubblico.

Account canale

Un account collegato su una piattaforma di vendita. GET /channel_accounts li elenca con id stabili e opachi (chac_…). Se un venditore ha due account eBay, ognuno è un account canale a sé, e un id non punta mai a un account diverso. L'id resta lo stesso quando si ricollega un login scaduto (channel_account_id). Scollegare l'account lo rimuove: collegando di nuovo quell'account si ottiene un nuovo id, quello vecchio risponde 404 channel_account_not_found, e le inserzioni che aveva ora riportano il nuovo id in channel_account_id (le inserzioni appartengono alla posizione dell'account, non all'id). Salva gli id, e su channel_account.connected rileggi GET /channel_accounts e le tue inserzioni. Il campo channel indica la piattaforma di base (shopify, amazon, ebay, etsy, woocommerce, tiktok, …). Ne compaiono di nuove man mano che Nembol aggiunge integrazioni, quindi accetta valori sconosciuti.

Ordine

Un ordine normalizzato acquisito da qualsiasi canale: currency per ordine, status e fulfillment_status normalizzati, tracking, righe d'ordine e dati dell'acquirente, incluso l'indirizzo di spedizione completo (dietro il permesso orders:read). Con orders:write, POST /orders/{id}/fulfillment lo segna come spedito, allega il tracking e (per impostazione predefinita, quando il tracking è presente) notifica il marketplace di origine.

Operazione

Il tracker del lavoro asincrono sui canali. La cosa fondamentale da capire sulle scritture in Nembol:

1. La scrittura locale è sincrona. POST/PATCH restituiscono subito la risorsa aggiornata, quindi ciò che hai scritto è ciò che ricevi indietro.
2. La propagazione ai canali è asincrona. Passa dai worker di canale di Nembol, che rispettano i limiti di richieste di ogni canale. Il blocco sync della risposta ti fornisce un operation_id; GET /operations/{id} riporta i results[] per canale (succeeded, failed, channel_rate_limited, simulated), e un'operazione può terminare come partial.

Invece di fare polling delle operazioni, iscriviti al webhook operation.completed.

Come funziona la sincronizzazione

• Le scritture dall'API vengono accodate dopo gli aggiornamenti generati dagli ordini e le azioni dalla dashboard, quindi un'integrazione non può mai bloccare la sincronizzazione degli ordini.
• Quando un canale limita le richieste, Nembol rallenta e riprova; nel frattempo l'operazione mostra channel_rate_limited.
• Eliminare un prodotto non tocca mai i canali: finché è ancora online su uno di essi, DELETE /products/{id} risponde 422 product_still_listed, quindi rimuovi prima ogni inserzione dai canali (se una rimozione è ancora in corso risponde 409 listing_operation_in_progress: attendi che finisca, poi elimina). Un prodotto eliminato si può ripristinare con POST /products/{id}/restore; le sue foto vengono conservate per 30 giorni, dopodiché torna senza. Vedi Rimuovi dai canali e fai pulizia.

Ultimo aggiornamento il 22 ottobre 2026