Grundkonzepte

Fünf Objekte erklären die gesamte API.

Produkt

Der zentrale Katalogartikel, verwaltet von Nembol. Er umfasst alle Verkaufsdaten: Titel, Beschreibung (der eine Text, den jeder Kanal veröffentlicht, HTML erlaubt; short_description ist nur ein veralteter Alias dafür), Marke, category, Tags, mpn, vat_rate, weight/dimensions, images[] (bis zu 20) und variants[] (jeweils mit SKU, Preis, msrp (durchgestrichener Preis auf Kanälen, die das unterstützen), Menge, Barcode, grams (Versandgewicht pro Variante) und variantenspezifischen images). Preise sind Dezimal-Strings in der Basiswährung des Shops (GET /store → currency).

Varianten mit options (z. B. Farbe/Größe) müssen jede Kombination der Optionswerte abdecken. Kanäle erzeugen die vollständige Matrix, daher werden lückenhafte Sets vorab abgelehnt, statt fehlerhafte Angebote zu veröffentlichen.

Ein Produkt kann lokal existieren, ohne auf einem Kanal zu sein, sogar ohne Bilder (es bleibt ein lokaler Entwurf, bis es veröffentlicht wird).

Angebot (Listing)

Die Abbildung eines Produkts auf einem Kanalkonto. Es ist eine eigenständige Ressource mit eigener ID (list_…), status (listed, imported, ongoing, error, delisted), id_on_channel, url_on_channel und issues[], das die eigene Fehlermeldung des Kanals enthält, wenn etwas fehlschlägt.

POST   /rest/v1/listings              {product_id, channel_account_id}   # publish
PATCH  /rest/v1/listings/{id}         {}                                 # re-sync
DELETE /rest/v1/listings/{id}                                            # delist

Das Veröffentlichen ist pro Paar (product_id, channel_account_id) idempotent, und GET /listings?status=error ist die Abfrage, die deine Wiederholungslogik ausführen sollte.

Zwei Verhaltensweisen auf Kanalseite solltest du kennen: Manche Händler konfigurieren pro Kanal Preisregeln (eine prozentuale oder feste Anpassung), sodass der Preis auf dem Kanal berechtigterweise vom Produktpreis abweichen kann; und bei WooCommerce kann der Händler festgelegt haben, Produkte als Entwürfe anzulegen. In diesem Fall existiert ein Angebot mit listed im Shop, seine URL ist aber noch nicht öffentlich.

Kanalkonto

Ein verbundenes Konto auf einer Verkaufsplattform. GET /channel_accounts listet sie mit stabilen, opaken IDs (chac_…). Hat ein Händler zwei eBay-Konten, ist jedes ein eigenes Kanalkonto, und eine ID verweist nie auf ein anderes Konto. Die ID bleibt erhalten, wenn eine abgelaufene Anmeldung neu verbunden wird (channel_account_id). Trennen entfernt sie: Wird dieses Konto erneut verbunden, erhält es eine neue ID, die alte antwortet mit 404 channel_account_not_found, und die Angebote des Kontos tragen nun die neue ID in channel_account_id (Angebote gehören zum Platz des Kontos, nicht zur ID). Speichere IDs, und lies bei channel_account.connected GET /channel_accounts und deine Angebote erneut. Das Feld channel enthält die Basisplattform (shopify, amazon, ebay, etsy, woocommerce, tiktok, …). Neue Werte kommen hinzu, wenn Nembol Integrationen ergänzt, toleriere also unbekannte Werte.

Bestellung

Eine normalisierte Bestellung, die von einem beliebigen Kanal übernommen wird: currency pro Bestellung, normalisierter status und fulfillment_status, Sendungsverfolgung, Positionen und Käuferdaten einschließlich der vollständigen Lieferadresse (hinter dem Scope orders:read). Mit orders:write markiert POST /orders/{id}/fulfillment sie als versendet, hängt die Sendungsverfolgung an und benachrichtigt (standardmäßig, wenn eine Sendungsnummer vorhanden ist) den Ursprungsmarktplatz.

Operation

Der Tracker für asynchrone Arbeit auf den Kanälen. Das Wichtigste, was du über Schreibvorgänge in Nembol verstehen musst:

1. Der lokale Schreibvorgang ist synchron. POST/PATCH geben die aktualisierte Ressource sofort zurück, du bekommst also genau das zurück, was du geschrieben hast.
2. Die Weitergabe an die Kanäle ist asynchron. Sie läuft über Nembols Kanal-Worker, die die Rate Limits jedes Kanals einhalten. Der Block sync der Antwort liefert dir eine operation_id; GET /operations/{id} meldet results[] pro Kanal (succeeded, failed, channel_rate_limited, simulated), und eine Operation kann mit partial enden.

Statt Operations abzufragen, abonniere den Webhook operation.completed.

Wie sich die Synchronisierung verhält

• Schreibvorgänge über die API werden hinter bestellungsgesteuerten Aktualisierungen und Dashboard-Aktionen eingereiht, sodass eine Integration die Bestellsynchronisierung nie ausbremsen kann.
• Wenn ein Kanal drosselt, wartet Nembol und versucht es erneut; die Operation zeigt in der Zwischenzeit channel_rate_limited.
• Das Löschen eines Produkts berührt nie die Kanäle: Solange es noch auf einem live ist, antwortet DELETE /products/{id} mit 422 product_still_listed, delist also zuerst jedes Angebot (läuft ein Delisting noch, antwortet es mit 409 listing_operation_in_progress: warte, bis es fertig ist, dann löschen). Ein gelöschtes Produkt lässt sich mit POST /products/{id}/restore zurückholen; seine Fotos bleiben 30 Tage erhalten, danach kommt es ohne sie zurück. Siehe Delisten und aufräumen.

Zuletzt aktualisiert am 22. Oktober 2026