Pubblica un prodotto

L'intero ciclo è fatto di due scritture e un'attesa.

1. Crea il prodotto

curl -X POST https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-VDJ-001" \
  -d '{
    "title": "Vintage denim jacket",
    "description": "<p>Classic 90s denim jacket.</p>",
    "brand": "Acme",
    "price": "49.90", "quantity": 3, "sku": "VDJ-M-001",
    "images": [{"url": "https://your-cdn.com/jacket.jpg"}]
  }'

La risposta è il prodotto, in modo sincrono. Prendi l'id e gli id delle immagini.

2. Pubblicalo

curl -X POST https://api.nembol.com/rest/v1/listings \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: publish-VDJ-001-shopify" \
  -d '{"product_id": "prod_…", "channel_account_id": "chac_…"}'

202 con status: "ongoing". La pubblicazione passa per i worker dei canali di Nembol. Prendi il channel_account_id da GET /channel_accounts.

3. Scopri quando è online

Iscriviti al webhook listing.status_changed (la soluzione migliore), oppure interroga GET /listings/{id} finché status non è listed. Riceverai id_on_channel e url_on_channel. Su un canale che funziona bene servono secondi, non minuti.

Se il canale la rifiuta ricevi status: "error" e il messaggio del canale in issues[]. Vedi Gestisci gli errori.

Da sapere

• Prima le immagini. I canali rifiutano le inserzioni senza immagini, quindi pubblicare senza immagini fallisce subito con photo_required_for_channel.
• Gli URL delle immagini devono essere pubblici. Nembol scarica ogni url una volta e ne salva una propria copia. Se le tue immagini non sono raggiungibili da internet (un ERP locale, un bucket privato), inviale invece come {"base64": "…"} (max 10 MB ciascuna). Fai puntare url al file dell'immagine, non a una pagina che la mostra: Nembol controlla i byte, quindi un URL che risponde con una pagina HTML riceve 422 unsupported_file_type, e uno che non riesce a scaricare riceve 422 image_unreachable, ciascuno con l'immagine in param. In entrambi i casi non viene creato nulla.
• Testo alternativo. Dai a ogni immagine un alt (accessibilità, SEO), fino a 512 caratteri. Arriva a Shopify, WooCommerce, Etsy, Wix, Squarespace e allo Storefront quando le immagini vengono inviate: alla pubblicazione, e a una modifica quando l'interruttore di invio degli aggiornamenti dell'account è attivo. Etsy mantiene i primi 500 caratteri, Squarespace i primi 200. Importando da quei canali arriva anche il loro testo alternativo. eBay, Amazon, TikTok Shop, Google Merchant Center e Meta non hanno testo alternativo per le immagini, quindi non lo ricevono. Per cambiarlo in seguito, rinvia l'immagine per id con un nuovo alt ("" lo cancella); anche i venditori possono modificarlo nella dashboard (scheda Media, sotto ogni immagine).
• Le varianti devono formare una matrice completa. Con options (ad esempio Colore × Taglia), ogni combinazione deve avere una variante. I canali generano l'intera matrice, quindi un insieme incompleto viene rifiutato con 422 invece di pubblicare varianti difettose.
• Le valute non vengono convertite. I prezzi sono nella valuta dello store (GET /store → currency) e Nembol pubblica il numero così com'è: 19.90 su uno store in EUR diventa 19.90 USD su un negozio Shopify statunitense. Ogni account del canale mostra la valuta in cui vende (currency) e, quando è diversa da quella dello store, un avviso currency_mismatch (sull'account in warnings, sulle sue inserzioni in issues). Risolvi con una regola di prezzo su quell'account (PATCH /channel_accounts/{id} con pricing), oppure collega un negozio nella valuta dello store.
• Il prezzo sul canale può essere diverso dal tuo. I venditori possono configurare regole di prezzo per canale in Nembol (variazione percentuale o fissa), quindi non considerare un bug un prezzo diverso sul canale.
• WooCommerce può pubblicare come bozza. Se il venditore ha impostato Stato del prodotto: bozza nelle impostazioni del canale in Nembol, l'inserzione è listed ma l'URL del prodotto non è pubblico finché non lo pubblica in WooCommerce.
• La pubblicazione è idempotente per (product_id, channel_account_id): rifare la POST restituisce l'inserzione esistente. Se l'inserzione è in errore, rifare la POST ritenta la pubblicazione.

Dopo la pubblicazione

• Modifiche a prezzi e testi: PATCH /products/{id}. Arrivano al canale quando l'interruttore sync.product_edits dell'account è attivo (parte spento): vedi Modificare un prodotto.
• Stock dal tuo sistema: POST /inventory/batch per SKU, vedi Sincronizza stock e prezzi in blocco.
• Vendite e spedizioni: webhook order.created, poi POST /orders/{id}/fulfillment, vedi Evadi gli ordini.

Ultimo aggiornamento il 20 ottobre 2026