Programma partner: gestisci molti store

Il programma partner ti permette di gestire molti store Nembol (uno per ogni azienda cliente) con una sola chiave. I tuoi clienti non accedono mai a Nembol e non ricevono email da noi: gestisci tutto tramite l'API, e ti fatturiamo una volta al mese per tutti loro alle tariffe concordate.

L'accesso partner viene attivato da Nembol dopo l'accordo di partnership: scrivi a developer@nembol.com. La tua chiave deve poi avere il permesso accounts:manage.

Inizia nella sandbox

Il tuo account partner parte in sandbox: fino a 3 aziende aperte, canali reali, webhook e ordini, e non viene fatturato nulla. Costruisci e testa l'intera integrazione lì; quando sei pronto, premi Passa al live in Impostazioni → Partner (prima una carta, se paghi con carta): la fatturazione parte quel giorno e la stessa chiave e le stesse aziende passano al live. Vedi Testa la tua integrazione.

La tua chiave e la dashboard

Contano due pagine della dashboard, nel login Nembol dell'account partner:

• Impostazioni → Sviluppatori: crea la chiave API. Scegli Live (in sandbox una chiave Live esegue tutto davvero e non viene fatturato nulla; una chiave Test simula soltanto le chiamate e non può creare aziende reali). Il preset Lettura e scrittura include accounts:manage, necessario per ogni endpoint partner; il modulo elenca tutti i permessi che riceve la chiave.
• Impostazioni → Partner: le tue aziende (con un selettore Aziende / Fatturazione), il rendiconto del mese per piano, il tuo metodo di pagamento e un avviso Sandbox finché l'account è in sandbox. Mostra gli stessi dati di GET /accounts, GET /partner/statement e GET /partner/billing.

I tuoi venditori non usano mai la dashboard: tutto ciò che riguarda le loro aziende passa dall'API.

1. Crea un'azienda

curl -X POST https://api.nembol.com/rest/v1/accounts \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Srl", "plan": "pro", "country": "IT", "reference": "ERP-123"}'

{ "id": "acct_66f0a1", "object": "account", "name": "Acme Srl", "plan": "pro",
  "status": "active", "product_limit": 2000, "channel_accounts": 0, "products": 0 }

• plan: basic, pro, enterprise o enterprise_plus. L'azienda riceve i limiti di quel piano (prodotti, account dei canali, funzionalità).
• Fatturata da oggi, in proporzione. Nessuna prova. Cambia il piano quando vuoi con PATCH /accounts/{id} (anche questo in proporzione).

2. Lavora dentro un'azienda

Aggiungi Nembol-Account a qualsiasi richiesta. Il resto dell'API funziona esattamente come se l'azienda avesse una sua chiave:

curl https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1"

I rate limit e le Idempotency-Key sono conteggiati per azienda, così un'azienda molto attiva non rallenta mai le altre.

3. Collega i canali dell'azienda

Crea un link di collegamento e invialo al venditore. Deve solo accedere al suo account del canale:

curl -X POST https://api.nembol.com/rest/v1/channel_connections \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1" \
  -H "Content-Type: application/json" \
  -d '{"channel": "amazon", "params": {"country": "US"}, "return_url": "https://erp.example.com/nembol/done"}'

Alcuni canali chiedono quale account collegare dopo il login del venditore (Amazon con più marketplace, Google Merchant Center, Facebook Catalog con più attività). La connessione diventa allora needs_choice con choices: mostrali nella tua app (o lascia scegliere a un agente) e invia la scelta:

curl -X POST https://api.nembol.com/rest/v1/channel_connections/conn_8a12/choose \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Nembol-Account: acct_66f0a1" \
  -H "Content-Type: application/json" \
  -d '{"value": "A2EUQ1WTGCTBG2"}'

Registra il tuo return_url una sola volta sul tuo store (POST /redirect_urls): lo usano tutte le aziende (GET /redirect_urls dentro un'azienda lo elenca con inherited: true).

Dopo il login il browser del venditore arriva sul tuo return_url, con questi parametri aggiunti alla query string (i tuoi vengono mantenuti, quindi mettici l'id della tua azienda):

https://erp.example.com/nembol/done?company=42&connection_id=conn_8a12&status=connected&channel_account_id=chac_77b0&account_id=acct_66f0a1

Anche i link che non si possono usare tornano qui (scaduti, già usati o rifiutati), così il venditore finisce sempre nella tua app, mai su una pagina di errore di Nembol.

Il link di ritorno contiene solo id di Nembol, mai codici o token del canale. Il marketplace invia il suo codice di autorizzazione a Nembol, che scambia e conserva i token e parla con il canale per te. Tu continui a lavorare con la tua chiave e Nembol-Account.

La query string dice solo al browser cosa è successo: chiunque può aprire il tuo return_url con parametri inventati. Prima di segnare il canale come collegato nella tua app, verifica dal tuo server con GET /channel_connections/{connection_id} (e Nembol-Account) che status sia connected, oppure attendi il webhook channel_account.connected.

Un link di collegamento funziona una sola volta e per un'ora. Se viene riaperto o usato dopo l'ora, rimanda il venditore al tuo return_url con error=link_already_used o error=link_expired (senza un return_url il venditore vede una pagina di Nembol), quindi crea una nuova connessione. I canali collegati con chiavi API (Kaufland, OnBuy, PrestaShop, Subito) non hanno bisogno di un link: POST /channel_connections con le chiavi in params risponde subito connected, oppure channel_credentials_rejected con il motivo del canale.

Dopo il collegamento

• Non viene importato nulla se non lo chiedi (import_products, import_orders su POST /channel_connections); il tuo ERP pubblica i propri prodotti.
• Hai scollegato un account e stai ricollegando lo stesso negozio? La successiva connessione di quel canale lo riporta indietro (reconnects_shop); per un negozio diverso invia new_account: true. Vedi Collega un canale.
• Ogni interruttore di sincronizzazione parte spento: imposta quelli che il venditore vuole con PATCH /channel_accounts/{id} (ad esempio sync.quantity_from_orders: true perché una vendita sul canale abbassi lo stock ovunque).

4. Webhook o polling

Registra i tuoi endpoint una sola volta, sul tuo store: ricevono gli eventi di tutte le tue aziende, ciascuno con account_id.

Preferisci il polling, o vuoi una rete di sicurezza? GET /events?created_after=… con la tua chiave e senza Nembol-Account restituisce i tuoi eventi e quelli di tutte le tue aziende in un unico flusso (ciascuno con account_id); aggiungi account=acct_… per una sola azienda. Gli eventi vengono conservati 30 giorni.

Una tipica integrazione ERP

1. Azienda: POST /accounts quando un cliente si registra nel tuo ERP; conserva l'acct_… accanto al tuo id cliente (reference contiene il tuo).
2. Canali: POST /channel_connections → invia il link → il venditore torna al tuo return_url (sopra).
3. Prodotti: cerca un prodotto per SKU (GET /products?sku=…), poi PATCH /products/{id} o POST /products. Ogni variante deve avere il proprio SKU, e i prodotti con opzioni devono avere tutte le combinazioni (S/M × Rosso/Blu = 4).
4. Pubblicazione: POST /listings (o /listings/batch per molti) con l'account del canale. Un prodotto deve avere almeno un'immagine. Segui lo stato con il webhook listing.status_changed.
5. Stock: POST /inventory/batch con SKU + quantità (fino a 100 elementi).
6. Ordini: webhook order.created, con GET /orders come rete di sicurezza (vedi sotto). Un ordine contiene tutte le sue righe.
7. Spedizione: POST /orders/{id}/fulfillment con il tracking.

Le regole che l'integrazione deve conoscere sono raccolte in Regole e limiti.

5. Fatturazione

• Una fattura al mese per tutte le tue aziende: ognuna con il suo piano, alla tua tariffa (uno sconto sul nostro listino o un prezzo fisso per piano).
• GET /partner/statement?month=2026-10 elenca ogni azienda, il suo piano, i giorni in cui era fatturabile e l'importo. Corrisponde alla fattura.
• Paga con carta (addebito automatico) o con fattura (30 giorni). Puoi anche pagare mesi in anticipo (ad es. con bonifico): il credito viene usato dalle fatture successive e GET /partner/billing mostra quanto ne resta (credit_balance).
• 14 giorni dopo una fattura non pagata le tue aziende passano in sola lettura (ordini e stock continuano a sincronizzarsi, non viene eliminato nulla) finché non viene pagata.

6. Chiudi un'azienda

POST /accounts/{id}/close ne interrompe la fatturazione da oggi. Le sue inserzioni restano sui canali e i suoi dati vengono conservati, come per qualsiasi utente Nembol che se ne va. Non può essere riaperta.

La chiusura non si può annullare, 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 alla persona. 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.

Cosa non possono fare le aziende

• /billing su un'azienda risponde 409 billed_by_partner.
• Le scritture su un'azienda sospesa o chiusa rispondono 409 account_suspended / account_closed; le letture funzionano ancora, quindi puoi esportare prodotti, ordini e clienti di un'azienda chiusa.
• L'header Nembol-Account funziona solo con una chiave che ha accounts:manage. Qualsiasi altra chiave riceve 403 insufficient_scope su ogni richiesta che contiene l'header, prima che venga letto qualsiasi dato: non dare accounts:manage a una chiave per i report o con uno scopo specifico, così non potrà raggiungere nessuna azienda.
• Creare prodotti oltre il limite del piano risponde 409 product_limit_reached.

Ultimo aggiornamento il 22 ottobre 2026