Programme partenaires : gérer de nombreuses boutiques

Le programme partenaires vous permet de gérer de nombreuses boutiques Nembol (une par entreprise cliente) avec une seule clé. Vos clients ne se connectent jamais à Nembol et ne reçoivent aucun e-mail de notre part : vous pilotez tout via l'API, et nous vous facturons une fois par mois pour l'ensemble, à vos tarifs négociés.

L'accès partenaire est activé par Nembol après la signature de l'accord de partenariat : écrivez à developer@nembol.com. Votre clé a ensuite besoin de la permission accounts:manage.

Commencer dans la sandbox

Votre compte partenaire démarre en sandbox : jusqu'à 3 entreprises ouvertes, de vrais canaux, webhooks et commandes, et rien n'est facturé. Construisez et testez toute l'intégration dans cet environnement ; quand vous êtes prêt, cliquez sur Passer en production dans Paramètres → Partenaire (d'abord une carte, pour le paiement par carte) : la facturation commence ce jour-là et la même clé et les mêmes entreprises passent en production. Voir Tester votre intégration.

Votre clé et le tableau de bord

Deux pages du tableau de bord comptent, dans la connexion Nembol propre au compte partenaire :

• Paramètres → Développeurs : créez la clé API. Choisissez Live (en sandbox, une clé Live exécute tout pour de vrai et rien n'est facturé ; une clé Test ne fait que simuler les appels et ne peut pas créer de vraies entreprises). Le préréglage Lecture et écriture inclut accounts:manage, nécessaire pour tous les endpoints partenaires ; le formulaire liste toutes les permissions que reçoit la clé.
• Paramètres → Partenaire : vos entreprises (avec un sélecteur Entreprises / Facturation), le relevé du mois par forfait, votre moyen de paiement, et un avis Sandbox tant que le compte est en sandbox. Elle affiche les mêmes données que GET /accounts, GET /partner/statement et GET /partner/billing.

Vos marchands n'utilisent jamais le tableau de bord : tout ce qui concerne leurs entreprises passe par l'API.

1. Créer une entreprise

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 ou enterprise_plus. L'entreprise reçoit les limites de ce forfait (produits, comptes de canal, fonctionnalités).
• Facturée à partir d'aujourd'hui, au prorata. Pas d'essai. Changez de forfait à tout moment avec PATCH /accounts/{id} (au prorata également).

2. Travailler dans une entreprise

Ajoutez Nembol-Account à n'importe quelle requête. Le reste de l'API fonctionne exactement comme si l'entreprise avait sa propre clé :

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

Les limites de débit et les Idempotency-Key sont comptées par entreprise : une entreprise très active ne ralentit donc jamais les autres.

3. Connecter les canaux de l'entreprise

Créez un lien de connexion et envoyez-le au vendeur. Il se connecte seulement à son compte sur le canal :

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"}'

Certains canaux demandent quel compte connecter une fois le vendeur connecté (Amazon avec plusieurs marketplaces, Google Merchant Center, Facebook Catalog avec plusieurs entreprises). La connexion passe alors en needs_choice avec choices : affichez-les dans votre application (ou laissez un agent choisir) et envoyez le choix :

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"}'

Enregistrez votre return_url une seule fois, sur votre propre boutique (POST /redirect_urls) : toutes les entreprises l'utilisent (GET /redirect_urls dans une entreprise la liste avec inherited: true).

Après la connexion, le navigateur du vendeur arrive sur votre return_url, avec ces paramètres ajoutés à sa query string (les vôtres sont conservés, mettez-y donc votre propre id d'entreprise) :

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

Les liens inutilisables reviennent aussi ici (expirés, déjà utilisés ou refusés) : le vendeur termine donc toujours dans votre application, jamais sur une page d'erreur Nembol.

Le lien de retour ne contient que des id Nembol, jamais les codes ou jetons du canal. La marketplace envoie son code d'autorisation à Nembol, qui l'échange, conserve les jetons et communique avec le canal pour vous. Vous continuez à travailler avec votre clé et Nembol-Account.

La query string indique seulement au navigateur ce qui s'est passé : n'importe qui peut ouvrir votre return_url avec des paramètres inventés. Avant de marquer le canal comme connecté dans votre application, confirmez depuis votre serveur avec GET /channel_connections/{connection_id} (et Nembol-Account) que status vaut connected, ou attendez le webhook channel_account.connected.

Un lien de connexion fonctionne une seule fois et pendant une heure. Ouvert à nouveau ou après l'heure, il renvoie le vendeur vers votre return_url avec error=link_already_used ou error=link_expired (sans return_url, le vendeur voit une page Nembol) : créez alors une nouvelle connexion. Les canaux connectés par clés API (Kaufland, OnBuy, PrestaShop, Subito) n'ont pas besoin de lien : POST /channel_connections avec les clés dans params répond connected immédiatement, ou channel_credentials_rejected avec le motif du canal.

Après la connexion

• Rien n'est importé sauf si vous l'avez demandé (import_products, import_orders sur POST /channel_connections) ; votre ERP publie ses propres produits.
• Vous avez déconnecté un compte et reconnectez la même boutique ? La prochaine connexion de ce canal la ramène (reconnects_shop) ; pour une autre boutique, envoyez new_account: true. Voir Connecter un canal.
• Toutes les options de synchronisation démarrent désactivées : activez celles que le marchand souhaite avec PATCH /channel_accounts/{id} (par exemple sync.quantity_from_orders: true pour qu'une vente sur le canal baisse le stock partout).

4. Webhooks ou polling

Enregistrez vos endpoints une seule fois, sur votre propre boutique : ils reçoivent les événements de toutes vos entreprises, chacun avec account_id.

Vous préférez le polling, ou voulez un filet de sécurité ? GET /events?created_after=… avec votre clé et sans Nembol-Account renvoie vos propres événements et ceux de toutes vos entreprises dans un seul flux (chacun avec account_id) ; ajoutez account=acct_… pour une seule entreprise. Les événements sont conservés 30 jours.

Une intégration ERP type

1. Entreprise : POST /accounts quand un client s'inscrit dans votre ERP ; gardez l'acct_… à côté de votre propre id client (reference contient le vôtre).
2. Canaux : POST /channel_connections → envoyez le lien → le vendeur revient sur votre return_url (voir plus haut).
3. Produits : recherchez un produit par SKU (GET /products?sku=…), puis PATCH /products/{id} ou POST /products. Chaque variante a besoin de son propre SKU, et les produits avec options ont besoin de toutes les combinaisons (S/M × Rouge/Bleu = 4).
4. Publication : POST /listings (ou /listings/batch pour plusieurs) avec le compte de canal. Un produit a besoin d'au moins une image. Suivez le statut avec le webhook listing.status_changed.
5. Stock : POST /inventory/batch avec SKU + quantité (jusqu'à 100 éléments).
6. Commandes : webhook order.created, avec GET /orders comme filet de sécurité (voir ci-dessous). Une commande contient toutes ses lignes.
7. Expédition : POST /orders/{id}/fulfillment avec le suivi.

Les règles que l'intégration doit connaître sont rassemblées dans Règles et limites.

5. Facturation

• Une facture par mois pour toutes vos entreprises : chacune sur son forfait, à votre tarif (une remise sur notre prix catalogue ou un prix fixe par forfait).
• GET /partner/statement?month=2026-10 liste chaque entreprise, son forfait, les jours facturables et le montant. Il correspond à la facture.
• Payez par carte (prélèvement automatique) ou sur facture (30 jours). Vous pouvez aussi payer des mois à l'avance : le crédit est utilisé par les factures suivantes, et GET /partner/billing indique ce qu'il reste (credit_balance).
• 14 jours après une facture impayée, vos entreprises passent en lecture seule (les commandes et le stock continuent de se synchroniser, rien n'est supprimé) jusqu'au paiement.

6. Fermer une entreprise

POST /accounts/{id}/close arrête sa facturation aujourd'hui. Ses annonces restent sur les canaux et ses données sont conservées, comme pour tout utilisateur Nembol qui s'en va. Elle ne peut pas être rouverte.

La fermeture est irréversible, elle demande donc d'abord une confirmation :

1. La première requête répond 409 confirmation_required avec une description des conséquences et un confirmation.token.
2. Montrez les conséquences à la personne. Si elle est d'accord, répétez la même requête avec l'en-tête Nembol-Confirmation: <token>. Le jeton ne sert qu'une fois et expire au bout de 10 minutes.

Voir Confirmations et annulation.

Ce que les entreprises ne peuvent pas faire

• /billing sur une entreprise répond 409 billed_by_partner.
• Les écritures sur une entreprise suspendue ou fermée répondent 409 account_suspended / account_closed ; les lectures fonctionnent toujours, vous pouvez donc exporter les produits, commandes et clients d'une entreprise fermée.
• L'en-tête Nembol-Account ne fonctionne qu'avec une clé qui a accounts:manage. Toute autre clé reçoit 403 insufficient_scope sur chaque requête qui porte l'en-tête, avant toute lecture : ne donnez pas accounts:manage à une clé de reporting ou à usage unique, et elle ne pourra atteindre aucune entreprise.
• Créer des produits au-delà de la limite du forfait répond 409 product_limit_reached.

Dernière mise à jour le 22 octobre 2026