API und Webhooks

Über die allverto API tauschen Shops, Lagerdienstleister, Buchhaltungs- oder eigene Programme Daten mit allverto aus: Artikel, Bestände, Kunden, Aufträge, Zahlungen, Versand, Retouren, Verkaufskanäle, Rechnungen und Einkauf. Webhooks melden Änderungen sofort an eine Adresse deiner Wahl – etwa „Auftrag erstellt“ oder „Bestand geändert“.

Alles richtest du unter Einstellungen → API & Webhooks ein. Dort steht auch die vollständige Dokumentation aller Endpunkte.

#Bevor du anfängst

• API-Schlüssel und Webhooks verwalten Rollen mit dem Recht API-Schlüssel und Webhooks verwalten – in der Regel Inhaber und Administration. Siehe Benutzer und Rollen.
• Ein Schlüssel bekommt höchstens die Rechte, die du selbst hast. Verlierst du später ein Recht, verliert es auch der Schlüssel.
• Für Webhooks gilt dasselbe: Du kannst nur Ereignisse abonnieren, deren Daten du selbst lesen darfst – „Kunde geändert“ etwa nur mit „Kunden ansehen“, „Rechnung erstellt“ nur mit „Belege ansehen“. Ereignisse ohne passendes Recht blendet allverto aus.

#API-Schlüssel erstellen

1. Öffne Einstellungen → API & Webhooks, Reiter API-Schlüssel.
2. Klick auf Schlüssel erstellen.
3. Gib einen Namen ein, an dem du das Fremdsystem erkennst (z. B. „Shopify-Anbindung“).
4. Wähle die Rechte, z. B. „Aufträge lesen“ und „Aufträge importieren“. Nimm nur, was das Fremdsystem wirklich braucht.
5. Optional: Beschränke den Schlüssel auf eine Firma (dann sieht und schreibt er nur Aufträge und Belege dieser Firma), setze ein Ablaufdatum und das Anfragelimit je Minute.
6. Klick auf Schlüssel erstellen. allverto zeigt den Schlüssel (av_…) genau einmal – kopiere ihn mit Kopieren und hinterlege ihn im Fremdsystem.

Im Menü der Zeile kannst du das Präfix kopieren (so findest du den Schlüssel im Fremdsystem wieder) und den Schlüssel jederzeit widerrufen. Danach lehnt die API ihn sofort ab. In der Liste siehst du, wann ein Schlüssel zuletzt benutzt wurde und von welcher IP-Adresse.

#Anfragen an die API

Jede Anfrage trägt den Schlüssel in der Kopfzeile Authorization: Bearer av_…. Die Endpunkte liegen unter /api/v1, zum Beispiel:

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Listen liefern { data, page: { nextCursor, hasMore } }. Die nächste Seite holst du mit cursor=<nextCursor>. Mit updatedSince=2026-10-01T00:00:00Z kommen nur Einträge, die seitdem angelegt oder geändert wurden – ideal für regelmäßige Abgleiche.
• Fehler haben immer die Form { error, message, fields } mit passendem HTTP-Status (400 Eingabe, 401 Schlüssel, 403 Recht fehlt, 404 nicht gefunden, 409 Konflikt, 429 Limit).
• Idempotenz: Schicke bei POST-Anfragen eine eindeutige Kopfzeile Idempotency-Key. Wiederholst du die Anfrage (z. B. nach einem Netzwerkfehler), bucht allverto nichts doppelt, sondern liefert 24 Stunden lang dieselbe Antwort.
• Anfragelimit: Standard sind 120 Anfragen je Minute und Schlüssel. Wird es überschritten, antwortet die API mit 429 und Retry-After (Sekunden).
• Retouren und Verkaufskanäle: GET /api/v1/returns und /returns/{id} liefern Retouren mit Positionen, Gründen und Erstattung (Recht „Retouren lesen“), GET /api/v1/channels die Verkaufskanäle – das Gegenstück zu channelId in Aufträgen und Retouren.

Änderungen über die API stehen im Änderungsprotokoll als „API: Name des Schlüssels“.

#Webhooks einrichten

1. Reiter Webhooks, Klick auf Webhook hinzufügen.
2. Gib Name und Adresse (https://…) des Empfängers ein und wähle die Ereignisse, z. B. „Auftrag erstellt“, „Zahlung eingegangen“, „Bestand geändert“. Bei mehreren Firmen kannst du den Webhook auf eine Firma beschränken – dann gehen Aufträge, Belege, Retouren und Bestellungen anderer Firmen nicht an diese Adresse.
3. Klick auf Speichern. allverto zeigt das Secret zum Prüfen der Signatur – auch dieses nur einmal.
4. Mit Test senden prüfst du die Verbindung. Das Ergebnis steht im Zustellprotokoll.
5. Neue Webhooks sind inaktiv. Erst mit Aktivieren sendet allverto echte Ereignisse – wie bei allen Abgleichen.

Ereignisse entstehen in derselben Transaktion wie die Änderung: Wird eine Buchung abgebrochen, geht auch kein Webhook raus. Der Inhalt (data) hat dasselbe Format wie die API (z. B. GET /api/v1/orders/{id}, bei Retouren GET /api/v1/returns/{id}).

Bei jeder Zustellung prüft allverto die aktuellen Rechte der Person, die den Webhook angelegt bzw. zuletzt geändert hat. Fehlt ihr das Leserecht für ein Ereignis oder hat sie keinen aktiven Zugang mehr, geht keine Nutzlast raus; das Zustellprotokoll zeigt die Zustellung als fehlgeschlagen mit dem Grund. Wer den Webhook danach speichert, wird die verantwortliche Person.

#Signatur prüfen

Jeder Aufruf trägt die Kopfzeile allverto-signature: t=<Unix-Zeit>,v1=<Signatur>. Die Signatur ist HMAC-SHA256 mit dem Secret über t + "." + Body. Prüfe sie über den unveränderten Body und verwirf Aufrufe, deren Zeit mehr als 5 Minuten abweicht.

#Fehlgeschlagene Zustellungen

Antwortet der Empfänger nicht mit 2xx, versucht allverto es erneut – nach 1 Minute, 5 Minuten, 30 Minuten, 2, 6, 12 und 24 Stunden. Nach 20 Fehlschlägen in Folge wird der Webhook automatisch deaktiviert; du bekommst eine Benachrichtigung. Im Zustellprotokoll (Zeitraum standardmäßig „Letzte 30 Tage“) siehst du Status, Antwortcode und Dauer jeder Zustellung und kannst sie erneut senden.

Webhooks dürfen nur öffentliche Adressen aufrufen – interne Ziele wie localhost oder private Netze sind gesperrt.