API-Überblick

Basis-URLs

Produktion ist https://api.heyservus.com (die Standard-Basis-URL des SDK); lokale Entwicklung ist http://localhost:5080. Alle Antworten sind JSON.

Vier Auth-Schemata, eines pro Präfix

Ein Request trägt genau das Credential, das seine Route-Gruppe erwartet, und der Tenant wird stets aus dem Credential abgeleitet, nie aus einem Request-Body:

• /auth/** — anonym (Registrierung / Login).
• /portal/** — ein Portal-JWT (Authorization: Bearer <jwt>); Tenant aus dem tenant-Claim des JWT.
• /v1/** — ein tenant-eigener API-Key (X-Api-Key: <key> oder Authorization: Bearer <key>).
• /internal/** — ein gemeinsames internes Token (nur das Gateway; keine öffentliche API).

API-Key-Scopes

API-Keys tragen Scopes als Bitfeld: Send=1, Read=2, Contacts=4, Admin=8. Gewähre das Minimum, das ein Key braucht; ein Key ohne den Scope einer Route bekommt 403. Der rohe Key wird bei der Erstellung einmal angezeigt — speichere ihn dann; nur ein Hash bleibt erhalten.

Enums sind numerische Ordinalwerte

Die API serialisiert ihre Enums als Ganzzahlen auf der Leitung (z. B. channel: 1=WhatsApp, 2=Sms, 3=Email, 4=Telegram, 5=Push). Der @servus/sdk-Client bildet diese auf ergonomische String-Unions ab. Die eine Ausnahme: der channel im message.inbound-Webhook ist der Kanalname.

Vorsicht: Die MessageStatus-Ordinalwerte sind nicht in Lebenszyklus-Reihenfolge (Sending ist 5, Received ist 6, hinten angefügt). Vergleiche mit dem benannten Wert — schließe nie aus Ordinalwerten auf den Fortschritt.

Fehler nach RFC 7807

Fehler sind application/problem+json: { type, title, status, detail, traceId }. Ein /v1-Request mit fehlendem/ungültigem Key scheitert geschlossen mit 401 und einem WWW-Authenticate: ApiKey-Header.