Partnerprogramm: viele Shops verwalten

Mit dem Partnerprogramm verwaltest du viele Nembol-Shops (einen pro Kundenunternehmen) mit einem einzigen Schlüssel. Deine Kunden melden sich nie bei Nembol an und erhalten keine E-Mail von uns: Du steuerst alles über die API, und wir rechnen einmal im Monat für alle zusammen zu deinen ausgehandelten Konditionen mit dir ab.

Der Partnerzugang wird von Nembol nach der Partnervereinbarung freigeschaltet: Schreib an developer@nembol.com. Dein Schlüssel braucht dann die Berechtigung accounts:manage.

In der Sandbox starten

Dein Partnerkonto startet in der Sandbox: bis zu 3 offene Unternehmen, echte Kanäle, Webhooks und Bestellungen, und nichts wird abgerechnet. Baue und teste dort die gesamte Integration; wenn du bereit bist, klicke auf Live gehen unter Einstellungen → Partner (bei Zahlung per Karte zuerst eine Karte): Die Abrechnung beginnt an diesem Tag, und derselbe Schlüssel und dieselben Unternehmen gehen live. Siehe Teste deine Integration.

Dein Schlüssel und das Dashboard

Zwei Dashboard-Seiten sind wichtig, im eigenen Nembol-Login des Partnerkontos:

• Einstellungen → Entwickler: Erstelle den API-Schlüssel. Wähle Live (in der Sandbox führt ein Live-Schlüssel alles echt aus und nichts wird abgerechnet; ein Test-Schlüssel simuliert Aufrufe nur und kann keine echten Unternehmen anlegen). Die Vorgabe Lesen & Schreiben enthält accounts:manage, das für jeden Partner-Endpoint nötig ist; das Formular listet jede Berechtigung auf, die der Schlüssel erhält.
• Einstellungen → Partner: deine Unternehmen (mit einem Umschalter Unternehmen / Abrechnung), die Monatsabrechnung pro Plan, deine Zahlungsmethode und ein Sandbox-Hinweis, solange das Konto in der Sandbox ist. Die Seite zeigt dieselben Daten wie GET /accounts, GET /partner/statement und GET /partner/billing.

Deine Händler nutzen das Dashboard nie: Alles für ihre Unternehmen läuft über die API.

1. Ein Unternehmen anlegen

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 oder enterprise_plus. Das Unternehmen erhält die Limits dieses Plans (Produkte, Kanalkonten, Funktionen).
• Abrechnung ab heute, anteilig. Keine Testphase. Wechsle den Plan jederzeit mit PATCH /accounts/{id} (ebenfalls anteilig).

2. Innerhalb eines Unternehmens arbeiten

Füge jeder Anfrage Nembol-Account hinzu. Der Rest der API funktioniert genau so, als hätte das Unternehmen seinen eigenen Schlüssel:

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

Rate-Limits und Idempotency-Keys werden pro Unternehmen gezählt, sodass ein ausgelastetes Unternehmen die anderen nie ausbremst.

3. Die Kanäle des Unternehmens verbinden

Erstelle einen Verbindungslink und schick ihn dem Verkäufer. Er meldet sich nur bei seinem Kanalkonto an:

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

Manche Kanäle fragen nach dem Login des Verkäufers, welches Konto verbunden werden soll (Amazon mit mehreren Marktplätzen, Google Merchant Center, Facebook Catalog mit mehreren Unternehmen). Die Verbindung wird dann needs_choice mit choices: Zeig sie in deiner App an (oder lass einen Agenten wählen) und sende die Auswahl:

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

Registriere deine return_url einmal in deinem eigenen Shop (POST /redirect_urls): Jedes Unternehmen verwendet sie (GET /redirect_urls innerhalb eines Unternehmens listet sie mit inherited: true auf).

Nach dem Login landet der Browser des Verkäufers auf deiner return_url, mit diesen Parametern im Query-String (deine eigenen bleiben erhalten, setz also deine eigene Unternehmens-ID dort ein):

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

Auch Links, die nicht verwendet werden können, führen hierher zurück (abgelaufen, bereits verwendet oder abgelehnt). Der Verkäufer landet also immer in deiner App, nie auf einer Nembol-Fehlerseite.

Der Rückkehrlink enthält nur Nembol-IDs, nie die Codes oder Tokens des Kanals. Der Marktplatz sendet seinen Autorisierungscode an Nembol, das die Tokens austauscht, aufbewahrt und für dich mit dem Kanal kommuniziert. Du arbeitest weiter mit deinem Schlüssel und Nembol-Account.

Der Query-String sagt nur dem Browser, was passiert ist: Jeder kann deine return_url mit erfundenen Parametern öffnen. Bevor du den Kanal in deiner App als verbunden markierst, bestätige von deinem Server aus mit GET /channel_connections/{connection_id} (und Nembol-Account), dass status gleich connected ist, oder warte auf den Webhook channel_account.connected.

Ein Verbindungslink funktioniert einmal und eine Stunde lang. Erneut oder nach Ablauf der Stunde geöffnet, schickt er den Verkäufer mit error=link_already_used oder error=link_expired zurück zu deiner return_url (ohne return_url sieht der Verkäufer eine Nembol-Seite). Erstelle dann eine neue Verbindung. Kanäle, die mit API-Schlüsseln verbunden werden (Kaufland, OnBuy, PrestaShop, Subito), brauchen keinen Link: POST /channel_connections mit den Schlüsseln in params antwortet sofort mit connected oder mit channel_credentials_rejected und dem Grund des Kanals.

Nach dem Verbinden

• Nichts wird importiert, außer du hast es angefordert (import_products, import_orders bei POST /channel_connections); dein ERP veröffentlicht seine eigenen Produkte.
• Ein Konto getrennt und willst denselben Shop erneut verbinden? Die nächste Verbindung dieses Kanals bringt es zurück (reconnects_shop); für einen anderen Shop sende new_account: true. Siehe Einen Kanal verbinden.
• Jeder Sync-Schalter startet ausgeschaltet: Setze die, die der Händler möchte, mit PATCH /channel_accounts/{id} (z. B. sync.quantity_from_orders: true, damit ein Verkauf auf dem Kanal den Bestand überall senkt).

4. Webhooks oder Polling

Registriere deine Endpoints einmal, in deinem eigenen Shop: Sie empfangen die Events all deiner Unternehmen, jeweils mit account_id.

Lieber Polling, oder willst du ein Sicherheitsnetz? GET /events?created_after=… mit deinem Schlüssel und ohne Nembol-Account liefert deine eigenen Events und die all deiner Unternehmen in einem Feed (jeweils mit account_id); füge account=acct_… für ein einzelnes Unternehmen hinzu. Events werden 30 Tage aufbewahrt.

Eine typische ERP-Integration

1. Unternehmen: POST /accounts, wenn sich ein Kunde in deinem ERP registriert; speichere die acct_… neben deiner eigenen Kunden-ID (reference enthält deine).
2. Kanäle: POST /channel_connections → Link senden → der Verkäufer kommt zu deiner return_url zurück (siehe oben).
3. Produkte: Suche ein Produkt über die SKU (GET /products?sku=…), dann PATCH /products/{id} oder POST /products. Jede Variante braucht eine eigene SKU, und Produkte mit Optionen brauchen jede Kombination (S/M × Rot/Blau = 4).
4. Veröffentlichen: POST /listings (oder /listings/batch für viele) mit dem Kanalkonto. Ein Produkt braucht mindestens ein Bild. Verfolge den Status mit dem Webhook listing.status_changed.
5. Bestand: POST /inventory/batch mit SKU + Menge (bis zu 100 Artikel).
6. Bestellungen: Webhook order.created, mit GET /orders als Sicherheitsnetz (siehe unten). Eine Bestellung enthält alle ihre Positionen.
7. Versand: POST /orders/{id}/fulfillment mit der Sendungsverfolgung.

Regeln, die die Integration kennen sollte, sind gesammelt unter Regeln und Limits.

5. Abrechnung

• Eine Rechnung pro Monat für alle deine Unternehmen: jedes in seinem Plan, zu deiner Kondition (ein Rabatt auf unseren Listenpreis oder ein Pauschalpreis pro Plan).
• GET /partner/statement?month=2026-10 listet jedes Unternehmen auf, seinen Plan, die abrechenbaren Tage und den Betrag. Es entspricht der Rechnung.
• Zahle per Karte (automatisch belastet) oder per Rechnung (30 Tage). Du kannst auch Monate im Voraus zahlen (z. B. per Überweisung): Das Guthaben wird mit den nächsten Rechnungen verrechnet, GET /partner/billing zeigt den Rest (credit_balance).
• 14 Tage nach einer unbezahlten Rechnung werden deine Unternehmen schreibgeschützt (Bestellungen und Bestand werden weiter synchronisiert, nichts wird gelöscht), bis sie bezahlt ist.

6. Ein Unternehmen schließen

POST /accounts/{id}/close beendet seine Abrechnung ab heute. Seine Angebote bleiben auf den Kanälen und seine Daten werden aufbewahrt, wie bei jedem Nembol-Nutzer, der geht. Es kann nicht wieder geöffnet werden.

Das Schließen lässt sich nicht rückgängig machen, daher wird zuerst eine Bestätigung verlangt:

1. Die erste Anfrage antwortet mit 409 confirmation_required, einer Beschreibung der Folgen und einem confirmation.token.
2. Zeig der Person die Folgen. Wenn sie zustimmt, wiederhole dieselbe Anfrage mit dem Header Nembol-Confirmation: <token>. Der Token funktioniert einmal und läuft nach 10 Minuten ab.

Siehe Bestätigungen und Rückgängigmachen.

Was Unternehmen nicht können

• /billing bei einem Unternehmen antwortet mit 409 billed_by_partner.
• Schreibvorgänge bei einem gesperrten oder geschlossenen Unternehmen antworten mit 409 account_suspended / account_closed; Lesen funktioniert weiterhin, du kannst also die Produkte, Bestellungen und Kunden eines geschlossenen Unternehmens exportieren.
• Der Header Nembol-Account funktioniert nur mit einem Schlüssel, der accounts:manage hat. Jeder andere Schlüssel erhält 403 insufficient_scope bei jeder Anfrage mit diesem Header, bevor irgendetwas gelesen wird: Gib einem Reporting- oder Einzweck-Schlüssel kein accounts:manage, dann erreicht er kein Unternehmen.
• Das Anlegen von Produkten über das Limit des Plans hinaus antwortet mit 409 product_limit_reached.

Zuletzt aktualisiert am 22. Oktober 2026