1.2 Authentifizierung & Request-Format

Authentifizierung & Request‑Format

Übersicht

Die API verwendet JWT (JSON Web Tokens) für die Authentifizierung. Alle produktiven Integrationen müssen JWT verwenden. Jeder Request muss entweder ein gültiges Access‑Token im HTTP‑Header Authorization: Bearer <access_token> enthalten oder (nur für multipart/form-data Uploads, wenn Header‑Auth nicht möglich) das Feld access_token im JSON‑Objekt data mitsenden.

Antworten folgen einem einheitlichen Envelope:

{
  "status": "success",
  "data": { ... }
}

oder

{
  "status": "error",
  "error_code": "<code>",
  "error_reason": "..."
}

Fehlercode 5 (ERROR_TOKEN) signalisiert Probleme mit Token (fehlend, ungültig, widerrufen oder abgelaufen).

1) JWT — empfohlen (Access + Refresh)

• Initialer Login:
  • Aktion: auth_login
  • Methode: POST
  • Beschreibung: Authentifizieren mit E‑Mail & Passwort, Rückgabe von access_token (Kurzlebig) und refresh_token (länger gültig).
  • Beispiel Request (body.data = URL-kodiertes JSON / bei POST als data-Parameter):

{
  "email": "user@example.com",
  "password": "secret",
  "os": "android"
}

• Erfolg (Beispiel):

{
  "status": "success",
  "data": {
    "access_token": "<jwt.access.token>",
    "expires_in": 3600,
    "refresh_token": "<long.refresh.token>",
    "refresh_expires_in": 5184000,
    "user": {
      "id": 555,
      "email": "user@example.com",
      "name": "Max",
      "lastname": "Mustermann",
      "type": "driver"
    }
  }
}

• Verwendung des Access‑Tokens:

  • Setze im HTTP Header: Authorization: Bearer <access_token>
  • Alternativ (nur wenn Header nicht möglich, z.B. manche multipart Uploads): Im data‑Objekt: { "access_token": "<jwt.access.token>", ... }
  • Wichtig: Lege das Token nie in der URL (Query string).

• Token‑Erneuerung:

  • Aktion: auth_refresh
  • Body:

{ "refresh_token": "<refresh.token>" }

• Erfolg liefert neues access_token und expires_in.

• Ungültiger/abgelaufener/widerrufener Refresh → Fehlercode 5 (ERROR_TOKEN).

• Logout / Widerruf:

  • Aktion: auth_logout
  • Erfordert Auth (Bearer Header oder access_token in data).
  • Optional: { "refresh_token": "<refresh.token>" } — wird dann gezielt widerrufen.
  • Ohne refresh_token werden alle Refresh‑Tokens des Benutzers gelöscht (globaler Logout).

2) Request‑Format (action + data)

• Basis‑Schema:

  • Jeder Request ruft die zentrale URL auf: https://<env>.fahrservicemeybaum.de/api.htm
  • Parameter:
    • action (string, Pflicht): Name der API‑Aktion, z. B. orders, order_create, auth_login.
    • data (JSON, Pflicht): JSON‑Objekt mit Payload; muss URL‑kodiert übermittelt werden, wenn als Query-Parameter genutzt.

• HTTP‑Methoden:

  • GET: action & data können als URL‑Parameter übergeben werden: GET /api.htm?action=<action>&data=<url_kodiertes_json>
  • POST: action und data im Request‑Body (z. B. application/x-www-form-urlencoded oder multipart/form-data für Datei‑Uploads). Bei JSON‑APIs ist das data‑Feld weiterhin das JSON‑Objekt (url‑kodiert oder als form‑Feld).

• Header:

  • Empfohlen: Accept: application/json Accept-Charset: utf-8
  • Authentifizierung: Authorization: Bearer <access_token>

• Kodierung & Sicherheit:

  • UTF‑8 für alle Inhalte.
  • Das gesamte data‑Objekt muss URL‑kodiert übergeben werden, wenn es in der URL steht.
  • Alle Aufrufe sind über HTTPS durchzuführen.
  • Tokens dürfen nicht in URLs (Querystring) transportiert.

• Multipart / Datei‑Uploads:

  • Bei Uploads (multipart/form-data) kann das access_token in data gesetzt werden, falls es nicht möglich ist, Header zu setzen.
  • Für idempotente Uploads werden optionale Felder unterstützt:
    • idempotency_key (string, max 64)
    • filesize (integer, bytes)
  • Wenn idempotency_key mit einer existierenden Upload‑Session übereinstimmt, liefert die API die bereits gespeicherte image_id und markiert duplicate = 1.

3) Fehlercodes (relevant für Auth)

• 4 — ERROR_AUTH: Falsche Zugangsdaten bei auth_login.
• 5 — ERROR_TOKEN: Token fehlt, ungültig, widerrufen oder abgelaufen.
• 6 — ERROR_ACCESS_DENIED: Zugriff verweigert (z. B. Rollenberechtigungen).
• 3 — ERROR_DATA_JSON_DECODE: data ist kein gültiges JSON.
• 1 — ERROR_NO_ACTION: Unbekannte oder fehlende Aktion.
• 2 — ERROR_EXTERNAL: Business/Validations‑Fehler.

Hinweis: Bei Fehlercode 5 rufe zuerst auth_refresh mit dem Refresh‑Token auf; bei Erfolg wiederhole die ursprüngliche Aktion mit neuem Access‑Token.

4) Praktische Beispiele (Kurz)

• auth_login (POST): POST /api.htm?action=auth_login data={ "email":"test@domain.de", "password":"secret", "os":"android" }

• Aufruf einer Aktion mit Header‑JWT (GET): GET /api.htm?action=orders&data={} Header: Authorization: Bearer <access_token> Accept: application/json

• Upload (multipart/form-data) mit access_token im data‑Feld: POST /api.htm?action=order_upload_image Header: Authorization: Bearer <access_token> // wenn möglich Content-Type: multipart/form-data Form‑Felder: data = { "order_id":9070, "title":"Beleg", "access_token":"<access_token>" }