Onlineshop-API und Webhooks: Lagerbestand und Bestellungen mit Ihrem ERP abgleichen

Ihr Onlineshop steht nicht allein. Der Bestand ändert sich im Geschäft, die Buchhaltung wartet auf die Bestellungen, und ein ERP oder ein Marktplatz braucht die richtigen Preise. Damit diese Programme miteinander sprechen, ohne dass Sie etwas doppelt erfassen, brauchen Sie eine API und Webhooks. Dieser Leitfaden erklärt, wozu sie dienen, was die API von Eazyclick kann, was sie noch nicht abdeckt und wie Sie einen Lagerbestand mit einem ERP abgleichen.

Das Wichtigste in Kürze

• Eine Onlineshop-API erlaubt einem anderen Programm, Produkte, Bestand und Bestellungen Ihres Shops zu lesen und zu ändern.
• Ein Webhook benachrichtigt dieses Programm, sobald etwas passiert, ohne dass es den Shop ständig abfragen muss.
• Die API von Eazyclick (v1) deckt Produkte, Bestand und Bestellungen ab, mit Lese- oder Schreibschlüsseln.
• Zwei signierte Webhooks: order.placed (Bestellung aufgegeben) und stock.updated (Bestand geändert).
• Veröffentlichte Limits: 120 Anfragen pro Minute zum Lesen und 30 zum Schreiben, pro Schlüssel.

Was ist eine Onlineshop-API?

Eine Onlineshop-API ist ein technischer Zugang zu Ihrem Shop. Sie erlaubt einem anderen Programm, etwa einem ERP oder einem Marktplatz, Katalog, Bestand und Bestellungen zu lesen und manchmal zu ändern, ohne den Umweg über die Verwaltungsoberfläche. Die Daten werden als JSON ausgetauscht, über HTTP-Anfragen, die mit einem Schlüssel geschützt sind.

Konkret erspart eine API manuelle CSV-Exporte und doppelte Erfassung. Ein Entwickler oder Ihr Integrator schreibt die Verbindung zwischen den beiden Programmen einmal, danach fliessen die Daten von selbst. Das nennt man eine Integration oder eine API-Anbindung.

API oder Webhook: Was ist der Unterschied?

API und Webhook arbeiten in entgegengesetzter Richtung. Mit der API stellt Ihr Programm dem Shop eine Frage, wenn es sie braucht, zum Beispiel «Wie hoch ist der Bestand dieses Produkts?». Mit einem Webhook meldet sich der Shop bei Ihrem Programm, sobald etwas passiert, etwa eine neue Bestellung. Ein zuverlässiger Abgleich nutzt beides.

Was die API von Eazyclick kann

Die offene API von Eazyclick, Version 1, deckt drei Bereiche des Shops ab: Produkte mit ihren Varianten, den Bestand und die Bestellungen. Produkte lassen sich lesen, anlegen und ändern. Der Bestand lässt sich lesen, festlegen und mit Bewegungen versehen. Bestellungen lassen sich lesen, auch nach Änderungsdatum. Die API gehört zum Modul E-Commerce komplett.

Was Version 1 nicht abdeckt, damit Sie keine Überraschung erleben:

• Kunden, CRM und Rechnungen sind über die API nicht zugänglich.
• Bestand pro Geschäft: Die API liefert den Bestand jeder Variante über alle Lagerorte zusammen, ohne Aufteilung nach Geschäft.
• Kein fertiger Connector für ein bestimmtes ERP: Mit API und Webhooks lässt sich einer bauen.

Lese- und Schreibschlüssel

Der Zugang zur API läuft über einen Schlüssel, den Sie in den Shop-Einstellungen anlegen. Ein Leseschlüssel ruft Daten ab, ein Schreibschlüssel kann zusätzlich Produkte anlegen und den Bestand festlegen. Der Schlüssel wird nur einmal angezeigt, lässt sich mit einem Klick widerrufen und handelt im Namen des Kontoinhabers, der jede Änderung im Protokoll findet.

Einige Regeln mit gesundem Menschenverstand:

• Ein Schlüssel pro Integration: Entziehen Sie einem Dienstleister den Zugang, trifft es nur ihn.
• Der kleinste ausreichende Umfang: Ein Preisvergleichsdienst braucht nur Lesezugriff.
• Der Schlüssel bleibt auf einem Server, nie in einer Webseite oder in einem Code-Repository: Er gibt Zugriff auf die Bestellungen und Adressen Ihrer Kunden.

Signierte Webhooks: order.placed und stock.updated

Eazyclick sendet zwei Ereignisse an die Adresse Ihrer Wahl. order.placed wird bei jeder neuen Bestellung ausgelöst. stock.updated wird ausgelöst, sobald sich der Bestand einer Variante ändert, sei es durch einen Verkauf, eine Änderung über die API oder eine Korrektur im Backoffice. Jede Sendung ist signiert, damit Ihr Server prüfen kann, dass sie wirklich von Eazyclick stammt.

• HMAC-SHA256-Signatur im Header Eazyclick-Signature, berechnet über Zeitstempel und Rohdaten mit dem Geheimnis des Empfangspunkts. Weisen Sie Zeitstempel zurück, die älter als 5 Minuten sind.
• Stabile Ereignis-ID (Eazyclick-Event-Id): Dasselbe Ereignis kann zweimal ankommen, entfernen Sie Duplikate anhand dieser ID.
• Automatische neue Versuche, wenn Ihr Server nicht antwortet: nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden, also 6 Versuche über 8 Stunden und 36 Minuten.
• Versandprotokoll, erneutes Senden und eine Schaltfläche «Testen» im Backoffice, um eine Integration zu prüfen, ohne auf eine echte Bestellung zu warten.

Limits und Paginierung

Die API wendet veröffentlichte Limits an, pro Schlüssel und pro Minute: 120 Leseanfragen und 30 Schreibanfragen, getrennt gezählt. Darüber antwortet sie mit 429 rate_limited und dem Header Retry-After, der angibt, wie viele Sekunden Sie warten müssen. Listen werden in Seiten von höchstens 100 Einträgen abgerufen, und alle Beträge stehen als ganze Zahl in Rappen oder Cent.

Diese Limits lassen viel Spielraum für einen normalen Abgleich. Die Dokumentation empfiehlt Webhooks für Echtzeit, eine Nachlese der Bestellungen alle 5 bis 15 Minuten, ein erneutes Lesen des Katalogs jede Stunde und einen vollständigen Bestandsabgleich jede Nacht. Dieser Rhythmus passt bequem in die 120 Leseanfragen pro Minute.

Anwendungsfall: Bestand mit einem ERP abgleichen

Um ein ERP oder eine andere Warenwirtschaft mit dem Shop abzugleichen, bleibt Eazyclick die massgebliche Quelle für den Bestand. Das ERP lädt zuerst den Katalog, erhält dann jede Bestandsbewegung und jede Bestellung per Webhook, meldet seine eigenen Verkäufe über die API und prüft alles jede Nacht. Ein einziger Lese- und Schreibschlüssel genügt für das ganze Szenario.

1. Erstes Laden: GET /products, Seite für Seite, Varianten über die SKU zugeordnet.
2. Bestand in Echtzeit: Abonnement von stock.updated, sofort angewendet.
3. Bestellungen: order.placed in Echtzeit, dazu GET /orders?updatedAfter=… alle 5 bis 15 Minuten, um eine verpasste Sendung nachzuholen.
4. Verkäufe ausserhalb von Eazyclick: POST /variants/{variantId}/stock-movements bei jedem Verkauf.
5. Abgleich: GET /stock jede Nacht, verglichen mit der Datenbank des ERP.

Sind Sie bei der Wahl eines ERP noch unsicher? Unser Leitfaden zu ERP für KMU und unser Vergleich Odoo oder Eazyclick zeigen die Möglichkeiten. Für ein Unternehmen mit mehreren Filialen zeigt die Seite Software für mehrere Filialen, wie der Bestand jeder Filiale und der Onlineshop zusammenspielen.

Dokumentation und OpenAPI-Spezifikation

Die Dokumentation der API ist öffentlich, auf Englisch und Französisch, und wird direkt aus dem Code der API erzeugt: Jede Zahl, die Sie lesen, ist die, welche die API anwendet. Sie enthält eine Einstiegsanleitung, Authentifizierung, Paginierung und Fehler, Limits, Abgleichsrhythmus, Webhooks mit Prüfbeispielen in Node, PHP und Python sowie die vollständige Referenz.

• API-Dokumentation auf Englisch
• API-Dokumentation auf Französisch
• OpenAPI-Spezifikation, zum Import in Postman, Insomnia oder einen Client-Generator.

Die Werkzeuge, die bereits mit den Modulen verbunden sind, finden Sie auf der Seite Integrationen.

Häufige Fragen

Ist die API in Eazyclick enthalten?

Die offene API gehört zum Modul E-Commerce komplett: Sie wird mit diesem Modul freigeschaltet, ohne separates Zusatzmodul. Schlüssel und Webhooks richten Sie in den Shop-Einstellungen ein. Ohne das Modul E-Commerce komplett ist die API nicht verfügbar, weil sie mit den Produkten, dem Bestand und den Bestellungen des Shops arbeitet.

Gibt es einen fertigen Connector für mein ERP?

Nein. Eazyclick liefert keinen fertigen Connector für ein bestimmtes ERP. API und Webhooks bieten alles, um einen zu schreiben: Laden des Katalogs, Bestand in Echtzeit, Bestellungen und externe Verkäufe. Ihr Entwickler oder der Integrator Ihres ERP kann sich auf die Dokumentation und die OpenAPI-Spezifikation stützen, um die Verbindung zu bauen.

Lassen sich Kunden oder Rechnungen über die API lesen?

Nicht in Version 1. Die API deckt Produkte, Varianten, Bestand und Bestellungen ab. Kundendaten, CRM-Daten und Rechnungen sind nicht zugänglich. Eine Bestellung enthält aber die E-Mail-Adresse, den Namen und die Adressen, die zu ihrer Bearbeitung nötig sind, und das genügt für die meisten Abgleiche von Logistik und Bestand.

Was passiert, wenn mein Server nicht erreichbar ist?

Die Webhooks werden automatisch erneut gesendet: sechs Versuche insgesamt, nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden. Nach dem letzten Versuch bleibt die Sendung im Protokoll des Backoffice sichtbar und lässt sich mit einem Klick erneut senden. Für Onlinebestellungen holt ein regelmässiges Lesen mit updatedAfter ein verpasstes Ereignis ebenfalls nach.

Gibt die API den Bestand pro Geschäft an?

Noch nicht. Version 1 liefert pro Variante den Gesamtbestand des Shops über alle Lagerorte: vorhandene, reservierte und verfügbare Menge. Das Backoffice verwaltet bereits einen Bestand pro Geschäft. Braucht Ihr Projekt diese Aufteilung in der API, sagen Sie es uns: Eine solche Ergänzung ist ohne Bruch mit Version 1 möglich.