Authentifizierung¶

PharmaOne-Integrationen nutzen API-Schlüssel pro Organisation und kurzlebige JWTs.

Schritt 1 — API-Schlüssel erhalten¶

Als Organisations-Owner in Manager anmelden.
Org Settings → Integrations → External API keys öffnen.
Create key — das Secret wird einmal angezeigt. Sicher speichern.

Maximal 5 aktive Schlüssel pro Organisation.

Schritt 2 — API-Schlüssel gegen JWT tauschen¶

POST /api/v2/public/orgs/{orgId}/auth/token
apikey: {your_api_key}
Content-Type: application/json

Akzeptierte Schlüssel-Positionen:

Position	Beispiel
Header `apikey`	`apikey: abc123…`
Header `X-API-Key`	`X-API-Key: abc123…`
Query `apikey`	`?apikey=abc123…`

Erfolg — `200 OK`¶

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Tokens laufen nach 1 Stunde ab. Endpunkt erneut aufrufen zum Aktualisieren.

JWT-Claims¶

Claim	Wert
`org_id`	Organisations-ID (muss mit URL `{orgId}` übereinstimmen)
`scopes`	Gewährte Berechtigungen (siehe Bereiche)
`iss`	`pharmaone-integration`
`sub`	`integration`

Fehler — `401 Unauthorized`¶

Ungültiger oder fehlender API-Schlüssel:

{ "error": "Invalid or missing API key" }

Manche Antworten nutzen ein generisches Unauthorized-Format:

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

Richtigen Org-Schlüssel verwenden

Ohne den API-Schlüssel der Zielorganisation können Sie keine Tokens für eine andere Organisation erzeugen. {orgId} in der URL muss zur Organisation des Schlüssels passen.

Schritt 3 — v2-Endpunkte aufrufen¶

GET /api/v2/public/orgs/{orgId}/orders?limit=10
Authorization: Bearer {access_token}
Content-Type: application/json

Org-Pfad-Abgleich¶

{orgId} in der URL muss mit JWT org_id übereinstimmen. Bei Abweichung:

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

v1 order-requests (ohne JWT)¶

POST /api/v1/public/orgs/{orgId}/order-requests
apikey: {your_api_key}
Content-Type: application/json

Gleicher JSON-Body wie v2-Bestellanfragen. API-Schlüssel bei jedem Request mitsenden.

Für Telemedizin-Partner, die nur eine Shop-URL erhalten (ohne Manager), siehe Externer Telemedizin-Connector — POST {shop}/api/v1/external-order.