Collega un canale

POST /channel_connections esegue lo stesso flusso di collegamento della dashboard di Nembol, sul primo slot libero per quel canale. Un secondo account eBay diventa un secondo account del canale. La tua chiave deve avere lo scope channels:connect.

Canali OAuth: invia un link al venditore

eBay, Etsy, Shopify, WooCommerce, TikTok Shop, Temu, Amazon, Google Merchant Center, Facebook Catalog, Square, Squarespace, Faire, Wix, Facebook, Pinterest e Tumblr richiedono che il venditore acceda al canale e autorizzi Nembol. Ricevi un link monouso, valido 1 ora:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "shopify", "params": {"shop": "acme-vintage"},
       "return_url": "https://app.example.com/nembol/callback?user=42"}'

{
  "id": "conn_66f0a1",
  "object": "channel_connection",
  "status": "pending",
  "connect_url": "https://api.nembol.com/rest/v1/connect/…",
  "expires_at": "2026-10-07T16:00:00.000Z"
}

Apri connect_url nel browser del venditore. Quando ha finito arriva sul tuo return_url con l'esito aggiunto alla query string:

https://app.example.com/nembol/callback?user=42&connection_id=conn_66f0a1&status=connected&channel_account_id=chac_6aa12cab

Anche un link che non si può usare torna al tuo return_url: scaduto (status=expired&error=link_expired), già usato (lo status attuale e error=link_already_used) o rifiutato (status=failed e il motivo, ad esempio plan_not_eligible). Mostra un tuo messaggio e crea un nuovo link se serve. Il venditore non vede mai una pagina di errore di Nembol.

Non fidarti solo della query string. Verifica con GET /channel_connections/{id} (connected / failed / expired) o con il webhook channel_account.connected.

Agenti AI e script: ometti return_url. Il venditore arriva su una pagina di Nembol che gli dice che può chiudere la scheda, e l'agente interroga la connessione.

Registra prima i tuoi URL di ritorno

return_url deve iniziare con un URL registrato per lo store. Questo impedisce di usare il flusso di login di Nembol per mandare le persone su siti arbitrari:

curl -X POST https://api.nembol.com/rest/v1/redirect_urls \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/nembol/callback"}'

C'è corrispondenza con la stessa origine e un percorso che inizia con quello registrato; qualsiasi query string è ammessa. Il venditore può gestire l'elenco anche in Impostazioni → Sviluppatori → URL di reindirizzamento.

Canali con chiavi API: collegamento immediato

Kaufland, OnBuy, PrestaShop e Subito si collegano con credenziali, e la risposta è già connected o failed:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "kaufland", "params": {"client_key": "…", "secret_key": "…"}}'

Le chiavi vengono passate al canale e non vengono mai salvate sulla connessione.

Canali che chiedono quale account collegare

Amazon, Google Merchant Center e Facebook Catalog si collegano con un link come gli altri. Dopo il login il venditore può avere più account tra cui scegliere (più account Merchant Center, più attività). La connessione diventa allora needs_choice, i suoi choices elencano le opzioni, e la completi con POST /channel_connections/{id}/choose e il value scelto. Se c'è una sola opzione Nembol la sceglie e la connessione è subito connected.

Scollega

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/disconnect \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Scollegare interrompe ogni sincronizzazione con quell'account e non si può annullare tramite l'API (per ricollegarlo serve di nuovo il login del venditore), quindi prima viene chiesta una conferma:

1. La prima richiesta risponde 409 confirmation_required con una descrizione delle conseguenze e un confirmation.token.
2. Mostra le conseguenze al venditore. Se è d'accordo, ripeti la stessa richiesta con l'header Nembol-Confirmation: <token>. Il token vale una sola volta e scade dopo 10 minuti.

Vedi Conferme e annullamento.

Dopo il collegamento: importazioni e interruttori di sincronizzazione

Tramite l'API una nuova connessione non importa nulla: il catalogo è gestito dalla tua app. Chiedi ciò che ti serve quando crei la connessione:

I nuovi ordini vengono sincronizzati dal momento in cui l'account è collegato, qualunque cosa tu scelga. (La dashboard importa sempre entrambi: il venditore vuole vedere subito il suo negozio.) Puoi anche importare in seguito con POST /imports.

Un account appena collegato ha tutti gli interruttori di sincronizzazione spenti: le modifiche in Nembol non arrivano al canale e le vendite del canale non cambiano lo stock altrove finché non li accendi con PATCH /channel_accounts/{id}. Vedi Modificare un prodotto: cosa arriva ai canali.

eBay: Business Policies

Per pubblicare su eBay l'account deve usare le Business Policies di eBay (ogni inserzione ha le sue regole di spedizione, pagamento e reso). La maggior parte dei venditori le usa già. Il collegamento non cambia mai questa impostazione, perché l'adesione modifica in modo definitivo l'account eBay del venditore. Se l'account non ha aderito, eBay rifiuta la prima pubblicazione; attivale esplicitamente, con l'accordo del venditore:

curl -X POST https://api.nembol.com/rest/v1/channel_accounts/chac_6aa12cab/enable_business_policies \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Richiede la conferma in due passaggi. La risposta è ready (regole impostate, la pubblicazione funziona) o pending (eBay sta migrando l'account: richiama tra qualche minuto). Un account che ha già aderito risponde ready e non cambia nulla.

Scollega, poi ricollega lo stesso negozio

Un account scollegato mantiene il suo posto con il nome del suo ultimo negozio, così le sue inserzioni possono ritrovarlo. La successiva POST /channel_connections per quel canale lo riporta indietro: la risposta contiene reconnects_shop (il negozio che aveva), e il venditore accede a quello stesso negozio.

• Per collegare invece un negozio diverso, invia "new_account": true: occupa un nuovo posto.
• Se il venditore accede a un altro negozio senza new_account, la connessione fallisce con different_channel_account e non cambia nulla.

Ricollega un login scaduto

Il login a un marketplace può scadere o essere revocato (una password cambiata, un'app rimossa sul canale). L'account allora mostra errori e smette di sincronizzarsi. Per risolvere senza la dashboard, ricollega quello stesso account:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"channel_account_id": "chac_6aa12cab",
       "return_url": "https://app.example.com/nembol/callback"}'

Funziona come una nuova connessione (un connect_url per il venditore, poi return_url), con tre differenze:

• L'account mantiene il suo id (chac_…) e tutte le inserzioni collegate; non viene creato un nuovo account del canale e non serve uno slot libero.
• Se il venditore accede a un negozio o a un account diverso da quello che si sta ricollegando, non cambia nulla e la connessione fallisce con different_channel_account.
• channel è facoltativo; se lo invii deve essere il canale dell'account.

Stesse regole della dashboard

L'API esegue lo stesso flusso di collegamento della dashboard, quindi valgono tutte le regole di Nembol. Niente di ciò che fa un'integrazione può andare oltre ciò che il venditore potrebbe fare in Nembol:

• Un account marketplace, uno store Nembol. Un account eBay (Etsy, Shopify…) già collegato a un qualsiasi store Nembol non può essere collegato di nuovo; la connessione termina failed con il messaggio del canale.
• Serve un abbonamento attivo, verificato come fa la dashboard (compreso un controllo in tempo reale con il fornitore di pagamento): altrimenti 402 subscription_inactive.
• L'account tramite cui lo store paga Nembol (fatturazione Shopify, WooCommerce o Wix) non può essere scollegato: 422 channel_not_disconnectable.
• Tutto viene ricontrollato all'apertura del link. Se nel frattempo lo slot è stato occupato, il piano è cambiato o l'abbonamento è scaduto, il link viene rifiutato e la connessione termina failed.

Da sapere

• Un link, un solo uso. Un link già aperto o scaduto non si può riutilizzare. Crea una nuova connessione.
• Login scaduto o account scollegato. Un account il cui login è scaduto esiste ancora: ricollegalo con channel_account_id (mantiene il suo id). Un account scollegato torna con la successiva connessione di quel canale (stesso posto e stesse inserzioni, un nuovo id chac_: il vecchio id risponde 404 channel_account_not_found e le sue inserzioni ora hanno il nuovo id in channel_account_id); vedi sopra.
• Etsy, secondo negozio: il venditore deve uscire dal primo negozio su etsy.com prima di aprire il link, altrimenti Etsy lo farà accedere di nuovo allo stesso negozio.
• Gli slot si esauriscono. Ogni canale ha un numero limitato di account per store: 422 channel_slots_full significa che prima devi scollegarne uno.
• Valgono i limiti del piano come nella dashboard: 403 plan_channel_not_included quando il piano non include il canale.
• Nessuna importazione automatica tramite l'API. Una connessione creata dalla dashboard avvia la consueta prima importazione; una creata tramite l'API importa solo ciò che chiedono import_products / import_orders.

Ultimo aggiornamento il 20 ottobre 2026