Manuals

Deutsch

English

Deutsch

English

Appearance

Authentifizierung ​

Jede Anfrage an die iorder POS API erfordert eine Authentifizierung. Das System verwendet die API-Schlüssel-Authentifizierung, bei der der Schlüssel eine Service-Geräte-Sitzung identifiziert.

API-Schlüssel ​

Der API-Schlüssel ist eine Zeichenkette, die eine Service-Geräte-Sitzung identifiziert. Er muss in jeder API-Anfrage enthalten sein.

So erhalten Sie einen API-Schlüssel ​

API-Schlüssel werden über die iorder Admin-Oberfläche bereitgestellt. Kontaktieren Sie Ihren iorder-Administrator, um ein Service-Gerät zu erstellen und den entsprechenden API-Schlüssel zu erhalten. Die Admin-Oberfläche erstellt Service-Geräte-Sitzungen und stellt den API-Schlüssel der Sitzung für die Integration zur Verfügung.

Senden des API-Schlüssels ​

Übergeben Sie den API-Schlüssel auf eine der beiden folgenden Arten:

Header (empfohlen):

text
api_key: <ihr-api-schluessel>

Query-Parameter:

text
?api_key=<ihr-api-schluessel>

Der Server prüft zuerst den api_key-Header und falls dieser fehlt, den Query-Parameter.

Beispiele ​

Header-basierte Authentifizierung:

bash
curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Query-Parameter-Authentifizierung:

bash
curl -i "https://{host}/orders/location?api_key=abc123-def456-ghi789"

Sitzungslebenszyklus ​

Der API-Schlüssel ist einer serverseitigen Sitzung zugeordnet. Die Sitzung:

  • Hat eine konfigurierbare Timeout-Periode.
  • Ist an einen bestimmten Standort und ein bestimmtes Gerät gebunden.
  • Wird bei jedem API-Aufruf mit dem Schlüssel aktualisiert.
  • Kann nach längerer Inaktivität ablaufen. Wenn eine Sitzung abläuft, gibt die API einen 401-Fehler zurück.
  • Kann bei Sitzungs-Timeout-Ereignissen vom Server explizit gelöscht werden.

Halten Sie die Sitzung durch regelmäßiges Polling aktiv. Der SSE-Benachrichtigungsstrom hält die Sitzung ebenfalls aktiv.

Nicht autorisierte Antworten ​

Es gibt zwei verschiedene 401-Antwortformate, abhängig davon, wie die Anfrage fehlschlägt:

AuthorizationInterceptor (fehlender oder ungültiger API-Schlüssel) ​

Wenn der API-Schlüssel fehlt, leer ist oder keiner aktiven Sitzung entspricht, gibt der AuthorizationInterceptor Folgendes zurück:

http
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

{"error" : "Session not valid."}

Der Server fügt absichtlich eine zufällige Verzögerung zwischen 500 ms und 1499 ms hinzu, bevor er antwortet. Dieser Drosselungsmechanismus macht Brute-Force-Schlüsselerraten unpraktisch. Rechnen Sie bei jedem fehlgeschlagenen Authentifizierungsversuch mit dieser Verzögerung.

GlobalExceptionHandler (abgelaufene oder nicht autorisierte Sitzung) ​

Wenn der API-Schlüssel erkannt wird, die Sitzung aber nicht mehr gültig ist (z. B. abgelaufen oder falscher Sitzungstyp), gibt der UnAuthorizedException-Handler Folgendes zurück:

http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message": "Unauthorized", "uid": null}

Diese Antwort enthält ebenfalls eine zufällige Verzögerung zwischen 500 ms und 1499 ms.

Umgang mit 401-Antworten ​

Prüfen Sie immer auf beide Antwortformate:

bash
curl -i -H "api_key: invalid-key" "https://{host}/orders/location"

Beispielausgabe:

http
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

{"error" : "Session not valid."}

Hinweise zur Ratenbegrenzung ​

Die 401-Drosselung (500-1499 ms zufällige Verzögerung) ist eine weiche Ratenbegrenzung. Um eine zusätzliche Latenz zu vermeiden:

  • Wiederholen Sie die Anfrage nicht sofort bei einem 401. Warten Sie mindestens 2 Sekunden vor dem nächsten Versuch.
  • Implementieren Sie einen exponentiellen Backoff: 2s, 4s, 8s, 16s, gedeckelt bei 60s.
  • Wenn Sie wiederholt 401-Antworten erhalten, ist der API-Schlüssel wahrscheinlich ungültig oder abgelaufen. Erstellen Sie einen neuen über die Admin-Oberfläche.
  • Überwachen Sie Ihre 401-Rate. Eine hohe Rate deutet auf ein Konfigurationsproblem oder einen abgelaufenen Schlüssel hin.

Nächste Schritte ​