Auf dieser Seite
Bevor Sie beginnen
Die Open API ist Version 1. Ihre Base URL ist https://app.e-tailize.eu/public/api/v1, sie
spricht nur JSON, und die Liste der Endpunkte mit der Struktur jeder Anfrage und jeder Antwort
finden Sie in Swagger unter https://app.e-tailize.eu/swagger/index.html.
Der Zugang hat zwei Ebenen. Ihr Client, also das Unternehmen oder die Integration, die uns
aufruft, wird einmal von e-tailize freigegeben und weist sich auf den Auth Endpunkten mit dem
Header X-Api-ClientId aus. Ein Schlüsselpaar gehört zu einem Nutzer eines e-tailize Kontos,
und die Endpunkte Connections und Products lesen es aus den Headern X-Api-Key und
X-Api-Secret, die beide Pflicht sind.
Einen Open API Schlüssel erstellen Sie mit API Aufrufen, Sie brauchen also ein Werkzeug, das HTTP Anfragen senden kann, und einen sicheren Ort für ein Secret.
Schritte
Senden Sie
POST /Auth/request-accessohne Header mit Zugangsdaten, mit Ihrem Unternehmensnamen, Ihrer Kontaktadresse, dem Partnernamen und dem Grund der Anfrage. Die Antwort enthält Ihre Client ID und den StatusPending.Speichern Sie diese Client ID und senden Sie sie bei jedem weiteren Auth Aufruf als Header
X-Api-ClientIdmit.Warten Sie, bis e-tailize Ihren Client freigibt. Die Freigabe eines Clients ist ein Schritt auf unserer Seite, und wir geben Ihnen Bescheid.
Senden Sie
POST /Auth/generatemit den Daten des Nutzers, zu dem der Schlüssel gehört. Die Antwort enthält den Schlüssel, das Secret und das Ablaufdatum des Schlüssels.Kopieren Sie das Secret in Ihren eigenen Secret Speicher, bevor Sie die Antwort schließen.
Prüfen Sie das Paar mit
POST /Auth/validate/{apiKey}: Der Schlüssel steht im Pfad, das Secret im Body und nicht in einem Header.Senden Sie
X-Api-KeyundX-Api-Secretbei jedem Aufruf von Connections und Products mit, zusammen mitAccept: */*.
Wie es weitergeht
Das Paar trägt das Konto und das Projekt des Nutzers, für den es erstellt wurde, Ihre Aufrufe lesen und schreiben also die Daten, die dieser Nutzer in der App sieht.
POST /Auth/generate gibt den Schlüssel zurück, den Sie bereits haben, ohne
Secret im Body, Rotieren heißt also erst widerrufen und dann neu erstellen:
POST /Auth/revoke/{apiKey} verwirft das Paar, POST /Auth/generate gibt Ihnen ein neues.
Bewahren Sie das Ablaufdatum aus der Antwort auf generate auf und rotieren Sie, bevor es
erreicht ist.
Sie entwickeln für einen unserer Kunden? POST /Auth/generate/by-project-and-tenant bindet
den Schlüssel an ein Projekt eines Kundenkontos statt an Ihr eigenes.
Häufige Probleme
Ein 400, wo Sie ein 401 erwartet haben. Ein Header mit Zugangsdaten, der fehlt oder falsch
aufgebaut ist, ergibt 400, prüfen Sie also, ob X-Api-Key und X-Api-Secret beide in der
Anfrage stehen.
Ein 401 bedeutet, dass die Header im richtigen Format angekommen sind, aber nicht akzeptiert wurden: Der Client ist nicht freigegeben, der Schlüssel oder das Secret ist falsch, der Schlüssel ist abgelaufen, oder der Inhaber des Schlüssels ist nicht freigegeben.
Ein 406 statt einer lesbaren Fehlermeldung. Fehler kommen als application/problem+json
zurück, ein Client, der Accept: application/json anfordert, sieht die eigentliche Meldung
also nie. Senden Sie stattdessen Accept: */*.
Antwortet POST /Auth/validate/{apiKey} mit 400 und "Invalid or unapproved api key and
secret", deckt das vier Fälle gleichzeitig ab: unbekannter Schlüssel, falsches Secret,
abgelaufener Schlüssel oder ein Nutzer, der nicht freigegeben ist.
Eine Zugangsanfrage, die wegen der Mailadresse abgelehnt wird. Eine Kontaktadresse gehört zu einem Client, und eine Anfrage, die freigegeben oder abgelehnt wurde, kann nicht erneut gesendet werden.
Häufig gestellte Fragen
Wo finde ich meinen Schlüssel in der App?
Open API Schlüssel verwalten Sie mit API Aufrufen, nicht in einer Ansicht: Ein Schlüssel
existiert in der Antwort auf POST /Auth/generate und in dem Speicher, in den Sie ihn gelegt
haben. Nutzer und ihre Rollen sind ein anderes Thema, siehe
Nutzer hinzufügen und ihre Rollen verwalten.
Kann ein Nutzer zwei Schlüssel gleichzeitig haben?
Nein. Ein Nutzer hat jeweils einen aktiven Schlüssel, deshalb lehnt POST /Auth/generate
einen zweiten aktiven Schlüssel ab und antwortet mit 200 und dem Schlüssel, den Sie bereits
haben, ohne Secret im Body. Darum heißt Rotieren: zuerst POST /Auth/revoke/{apiKey} und
danach generate.
Wie sieht ein Fehlerbody aus?
Jeder Fehler hat dieselben drei Felder: title, status und errors. errors enthält die
fehlerhaften Feldnamen, in camelCase, oder den Schlüssel general, wenn das Problem nicht
ein einzelnes Feld betrifft. Es gibt kein detail, instance oder traceId zu lesen.
Ähnliche Artikel
War das hilfreich?