API und Webhooks des Shops

Der Tab „Développeurs“ (Entwickler) der Rubrik „Boutique“ (Online-Shop) ermöglicht es einer anderen Software (Lagerverwaltung, Kasse, Buchhaltung, individuell entwickelte Website), Ihren Shop zu lesen und zu aktualisieren und wichtige Ereignisse in Echtzeit zu empfangen: aufgegebene Bestellung, geänderter Lagerbestand, angeforderte Rücksendung. Zum Ansehen des Bildschirms genügt es, den Shop lesen zu dürfen; zum Anlegen, Ändern oder Widerrufen müssen Sie ihn bearbeiten dürfen. Siehe auch den Online-Shop.

Häufige Arbeitsschritte

Einen API-Schlüssel anlegen

1. Öffnen Sie Boutique, Tab Développeurs, Rubrik „Clés d'API“ (API-Schlüssel) und dann „Nouvelle clé“ (Neuer Schlüssel).
2. Geben Sie einen „nom“ (Namen) an, der sagt, wofür der Schlüssel dient (zum Beispiel „Kassensoftware“).
3. Haken Sie die nötigen „droits“ (Rechte) an oder verwenden Sie die Voreinstellungen „Lecture seule“ (Nur Lesen) und „Lecture et écriture“ (Lesen und Schreiben). Haken Sie nur das unbedingt Nötige an.
4. Stellen Sie bei Bedarf das „limite de débit“ (Ratenlimit) ein (standardmäßig 120 Anfragen pro Minute, von 10 bis 1.200) und ein „date d'expiration“ (Ablaufdatum) (höchstens ein Jahr).
5. Klicken Sie auf „Créer la clé“ (Schlüssel anlegen).

Der vollständige Schlüssel, der mit shk_ beginnt, wird nur einmal in einem eigenen Kasten angezeigt. Kopieren Sie ihn sofort mit der Schaltfläche „Copier“ (Kopieren) und legen Sie ihn im Passwortspeicher des Tools ab, das ihn verwenden wird. Sobald der Kasten geschlossen ist, kann SheepOS ihn nicht mehr anzeigen: In der Liste bleibt nur sein Anfang sichtbar. Wenn Sie ihn verloren haben, widerrufen Sie ihn und legen Sie einen neuen an.

Die Rechte eines Schlüssels

Jedes Recht betrifft eine Ressource, lesend oder schreibend: Produkte, Lagerbestand, Bestellungen, Kunden. Ein Schreibrecht gibt auch das Leserecht für dieselbe Ressource. Ein Schlüssel, der zum Beispiel nur den Lagerbestand synchronisiert, braucht nur „Lire le stock“ (Lagerbestand lesen) und „Modifier le stock“ (Lagerbestand ändern): Selbst wenn er in falsche Hände gerät, gibt er weder Zugriff auf die Bestellungen noch auf die Kunden. Die Rechte eines Schlüssels lassen sich nachträglich ändern, ohne den Schlüssel zu wechseln.

Sicherheitsempfehlungen

• Legen Sie einen Schlüssel pro Integration an: So wissen Sie, welcher Schlüssel was nutzt (Spalte „Dernière utilisation“ (Letzte Nutzung)), und können einen widerrufen, ohne die anderen anzutasten.
• Widerrufen Sie sofort einen Schlüssel, der in falsche Hände geraten ist oder dessen Tool nicht mehr verwendet wird. Der Widerruf wirkt sofort und ist unumkehrbar.
• Legen Sie einen Schlüssel niemals in eine Website, eine Seite oder eine mobile App: Jeder Besucher könnte ihn lesen. Er darf nur auf einem eigenen Server liegen.
• Senden Sie ihn nicht per E-Mail oder Messenger, setzen Sie ihn nicht in die Adresse einer Anfrage und committen Sie ihn nicht in ein Code-Repository.
• Versehen Sie temporäre Schlüssel (Dienstleister, Test) mit einem Ablaufdatum.
• Beobachten Sie das „Journal d'accès“ (Zugriffsprotokoll): Wiederholte Ablehnungen mit 401 oder 403 oder Anfragen zu ungewöhnlichen Zeiten sind ein Warnsignal.

Einen ersten Aufruf machen

Die API hat die Basisadresse https://IHR-SERVER/api/v1/shop, die in der Rubrik „Documentation“ (Dokumentation) angezeigt wird. Jede Anfrage trägt den Schlüssel im Header Authorization.

Um zu prüfen, ob der Schlüssel funktioniert: curl "https://IHR-SERVER/api/v1/shop" -H "Authorization: Bearer shk_IHR_SCHLUESSEL"

Um die Produkte aufzulisten (Recht „Lire les produits“ (Produkte lesen)): curl "https://IHR-SERVER/api/v1/shop/products?limit=50" -H "Authorization: Bearer shk_IHR_SCHLUESSEL"

Um den Lagerbestand eines Produkts festzulegen (Recht Modifier le stock): curl -X PUT "https://IHR-SERVER/api/v1/shop/stock/PRODUKT_ID" -H "Authorization: Bearer shk_IHR_SCHLUESSEL" -H "Content-Type: application/json" -d '{"quantity": 12}'

Die Beträge sind ganze Zahlen in Cent. Die Preise der Produkte verstehen sich ohne Steuer, die Summen von Bestellungen inklusive aller Steuern. Die Listen sind seitenweise aufgebaut: Übergeben Sie den Wert nextCursor der erhaltenen Seite im Parameter cursor, um die nächste zu erhalten, und updatedSince, um nur zu holen, was sich geändert hat. Die Rubrik Documentation des Bildschirms listet alle Routen, ihre Parameter, ihren Body und ein curl-Beispiel auf.

Einen Webhook anlegen

1. Rubrik „Webhooks“, dann „Nouvelle adresse“ (Neue Adresse).
2. Geben Sie die Adresse Ihres Servers ein, die mit https:// beginnen muss, und eine Beschreibung.
3. Wählen Sie die empfangenen „événements“ (Ereignisse) oder alle.
4. Klicken Sie auf „Créer l'adresse“ (Adresse anlegen) und kopieren Sie das Secret whsec_…: Wie ein API-Schlüssel wird es nur einmal angezeigt.
5. Klicken Sie auf „Tester“ (Testen): SheepOS sendet ein Testereignis und zeigt den HTTP-Status, die Dauer und gegebenenfalls den Fehler an.

Die Schaltfläche „Nouveau secret“ (Neues Secret) ersetzt das Secret nach einer Bestätigung: Das alte funktioniert sofort nicht mehr, aktualisieren Sie Ihren Server also umgehend. „Supprimer“ (Löschen) entfernt die Adresse und ihr Zustellprotokoll.

Die Signatur eines Webhooks prüfen

Jede Sendung trägt den Header SheepOS-Signature: t=SECONDES,v1=HEX. Prüfen Sie ihn, bevor Sie handeln, sonst könnte jeder falsche Ereignisse an Ihren Server senden:

1. Lesen Sie den rohen Body der Anfrage, vor jeder JSON-Verarbeitung.
2. Extrahieren Sie t und v1 aus dem Header.
3. Berechnen Sie den HMAC-SHA256 des Textes aus t, einem Punkt und dem rohen Body mit Ihrem Secret whsec_…, in hexadezimaler Form.
4. Vergleichen Sie das Ergebnis in konstanter Zeit mit v1 (und nicht mit einem einfachen Gleichheitsvergleich).
5. Lehnen Sie das Ereignis ab, wenn t um mehr als 300 Sekunden von der aktuellen Uhrzeit abweicht: Das verhindert die Wiedereinspielung einer alten Sendung.
6. Entfernen Sie Duplikate anhand der id des Ereignisses: Sie ist bei jeder Wiederholung identisch, dasselbe Ereignis kann Sie also zweimal erreichen.

Kopierfertige Auszüge in Node.js, PHP und Python finden Sie in der Rubrik Documentation, Abschnitt „Vérifier la signature“ (Signatur prüfen). Antworten Sie so schnell wie möglich (innerhalb von 10 Sekunden) mit einem 2xx-Code und verarbeiten Sie das Ereignis anschließend.

Wiederholungen, Deaktivierung und erneutes Senden

Eine Antwort, die nicht 2xx ist, eine überschrittene Frist oder ein Netzwerkfehler zählt als Fehlschlag. SheepOS versucht es nach dem ersten Senden bis zu sechsmal erneut, nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und dann 24 Stunden. Eine Zustellung, die überall scheitert, erhält den Status „Abandonnée“ (Aufgegeben).

Nach 15 aufeinanderfolgenden Fehlschlägen wird die Adresse automatisch deaktiviert: Eine rote Meldung nennt in der Liste den Grund. Korrigieren Sie Ihren Server und klicken Sie dann auf „Activer“ (Aktivieren): Der Fehlerzähler beginnt wieder bei null. Filtern Sie im „Journal de livraison“ (Zustellprotokoll) nach Adresse oder Status und verwenden Sie „Renvoyer“ (Erneut senden) bei einer fehlgeschlagenen oder aufgegebenen Zustellung.

Das Zugriffsprotokoll ansehen

Die Rubrik Journal d'accès listet die von der API empfangenen Anfragen auf: Schlüssel, Methode, Route, Status, Dauer und Datum, mit einem Filter nach Schlüssel und Status. Das Protokoll wird 30 Tage aufbewahrt.

Limits

• Höchstens 20 Schlüssel pro Shop, 10 Webhook-Adressen.
• Standardmäßig 120 Anfragen pro Minute und Schlüssel, einstellbar von 10 bis 1.200. Darüber hinaus antwortet die API mit 429 und dem Header Retry-After: Warten Sie diese Anzahl von Sekunden.
• Höchstens 100 Elemente pro Seite.
• Zahlung, Erstattung und Streitfälle lassen sich nicht über die API steuern: Sie bleiben im Back-Office.
• Die Zugriffs- und Zustellprotokolle werden 30 Tage aufbewahrt.

Häufige Fragen

Ich habe meinen Schlüssel oder mein Secret verloren, wie finde ich es wieder?

Das ist nicht möglich: SheepOS speichert es nicht im Klartext. Bei einem Schlüssel widerrufen Sie ihn und legen einen neuen an. Bei einem Webhook verwenden Sie Nouveau secret.

Mein Tool erhält einen 401-Fehler

Der Schlüssel fehlt, wurde falsch abgetippt, ist abgelaufen oder widerrufen. Prüfen Sie seinen Status in der Schlüsselliste.

Mein Tool erhält einen 403-Fehler

Dem Schlüssel fehlt das Recht, das die Route verlangt. Ändern Sie die Rechte des Schlüssels im Bildschirm oder verwenden Sie einen anderen Schlüssel.

Ich erhalte keine Ereignisse mehr

Prüfen Sie zuerst, ob die Adresse deaktiviert ist (rote Meldung in der Liste), und dann das Journal de livraison: Der Code und der Fehler zeigen, was Ihr Server geantwortet hat.