Zum Inhalt

Fehler & Sicherheit

HTTP-Statuscodes

Code Bedeutung
400 Validierungsfehler (fehlendes Feld, ungültige shop_id, usw.)
401 Fehlender/ungültiger API-Schlüssel oder Bearer-Token
403 Org-Mismatch oder fehlender Integrations-Bereich
404 Ressource nicht gefunden
500 Serverfehler

Fehler-Body-Format

{ "error": "human-readable message" }

Erweiterte Fehler:

{
  "error": "org_mismatch",
  "message": "Token org_id does not match URL orgId"
}

{
  "error": "insufficient_scope",
  "message": "Missing scope: orders.read"
}

Manche Unauthorized-Antworten nutzen dieses Format:

{ "message": "Unauthorized", "request_id": "…" }

{ "message": "No API key found in request", "request_id": "…" }

Sicherheitsmodell

Schutz der Requests

Schritt Schutz
API-Schlüssel Erforderlich für Token-Tausch und v1 order-requests
JWT Bearer-Token auf allen v2-Routen
Org-Pfad URL {orgId} muss org_id im Token entsprechen
Bereiche Integrations-JWT pro Route begrenzt

Wichtige Regel

Niemals Org-A-Schlüssel für Org-B-URLs verwenden. Requests werden abgelehnt, wenn der Schlüssel nicht zur Organisation im Pfad gehört.

Token-Lebensdauer

Integrations-JWTs laufen nach 1 Stunde ab. Erneut /auth/token aufrufen. Nicht länger als expires_in cachen.

Geheimnisse

Geheimnis Speicherung
PharmaOne API-Schlüssel Secret Manager / Env — nie in Git
Webhook-Signing-Secret Einmal bei Abonnement-Anlage
JWT Nur im Speicher — als Bearer-Credential behandeln

Manager-UI-Konfiguration

Diese Einstellungen werden in PharmaOne Manager verwaltet (nicht über PharmaOne API-Schlüssel):

Zweck Wo in Manager
API-Schlüssel anlegen / widerrufen Org Settings → Integrations → External API keys
Webhook-Abonnements Org Settings → Integrations → Webhook subscriptions
Webhook-Test Webhook-Abonnement → Send test event

Sicherheits-Checkliste für Integratoren

  • Nur HTTPS (Produktions-Hosts erzwingen TLS).
  • API-Schlüssel in Secrets, nicht im Quellcode.
  • Webhook X-PharmaOne-Signature bei jeder Zustellung prüfen.
  • Idempotenz-Keys (external_reference, external_id) für Retries.
  • Nur benötigten Zugriff anfordern (siehe Bereiche).
  • Nach Go-Live Smoke-Test: Token tauschen, dann einen Lese-Endpunkt aufrufen.

Audit & Protokollierung

  • Bestandsanpassungen schreiben Historie mit Akteur und Grund.
  • Webhook-Zustellungen mit HTTP-Status und Retry-Zähler protokolliert.
  • Bestellstatus-Änderungen über externe API können abonnierte Webhook-Ereignisse auslösen.