Zum Hauptinhalt springen

API-Dokumentation für Entwickler

Diese Sektion erklärt Konzepte und Patterns der SpeamCore-REST-API für Entwickler und Integrationen. Endanwender finden ihre Anleitungen unter Anwender.

API-Cluster​

Auth

Authentifizierung & Sessions

API
  • Login mit Mail+Passwort
  • JWT / OAuth-Token
  • Session-Erneuerung
CRUD

CRUD-Patterns

API
  • GET / POST / PATCH / DELETE
  • Pagination + Filter
  • Bulk-Operationen
Berechtigung

CASL in der API

API
  • 403-Errors verstehen
  • Subjects + Actions
  • Conditions
Events

Webhooks

API
  • Event-Typen
  • Konfiguration + Signatur
  • Retry-Verhalten
Actions

Custom-Aktionen (do:)

API
  • Approve / Reject
  • Bulk-Imports
  • Beleg-Lifecycle-Übergänge
Limits

Rate-Limits & Quotas

API
  • Standard-Limits
  • 429-Errors handhaben
  • Bulk-Pattern für viele Calls

Schnellstart​

Voraussetzungen​

  • Mandanten-Account mit API-User-Rolle
  • API-Token (per Admin im Permission-Editor erzeugt)
  • HTTPS-fähiger Client

Erstes Beispiel​

curl -X GET 'https://your-tenant.speamcore.com/api/customers' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

API-Konventionen​

Base-URL pro Mandant​

https://<tenant>.speamcore.com/api

Standard-Header​

  • Authorization: Bearer <token> — Pflicht
  • Accept: application/json — Pflicht
  • Content-Type: application/json — bei POST/PATCH
  • X-Tenant-ID: <uuid> — optional, sonst aus Token abgeleitet

Response-Format​

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42
  }
}

Fehler-Format​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Action 'delete' on subject 'Customer' not allowed",
    "details": {...}
  }
}

Standard-CRUD pro Resource​

HTTPEndpointCASL-Subject
GET /api/customersList + Filterview:Customer
GET /api/customers/:idDetailview:Customer
POST /api/customersAnlegencreate:Customer
PATCH /api/customers/:idÄndernupdate:Customer
DELETE /api/customers/:idLöschen (Soft-Delete)delete:Customer
POST /api/customers/:id/restoreAus Papierkorbdo:RestoreCustomer

Paginierung​

Standard-Pagination via Query-Parameter:

  • ?page=1 — 1-basiert
  • ?limit=20 — Standard 20, max 200
  • ?sort=createdAt:desc — Sortierung

Response-meta enthält total, page, limit, pages.

Filter​

Standard-Filter via Query-Parameter:

  • ?status=active
  • ?createdAt[gte]=2026-01-01
  • ?name[contains]=Müller

Komplexe Filter via POST-Body:

POST /api/customers/search
{
  "filter": {
    "status": "active",
    "OR": [
      { "name": { "contains": "Müller" } },
      { "ustId": "DE123" }
    ]
  },
  "sort": [{ "field": "createdAt", "order": "desc" }],
  "page": 1,
  "limit": 50
}

CASL-Errors verstehen​

Bei 403 Forbidden zeigt error.details:

{
  "missingAbility": [{
    "action": "create",
    "subject": "Customer"
  }],
  "userId": "...",
  "userRoles": ["Innendienst"]
}

→ User-Rolle prüfen, ggf. Custom-Rolle mit dem fehlenden Subject erstellen.

Audit pro API-Aktion​

Jede CRUD-Aktion landet im Audit-Log mit:

  • API-Endpoint + HTTP-Method
  • User + Token-ID
  • IP-Adresse + User-Agent
  • Vorher/Nachher

Mehr in Audit-Trail-Architektur.

Verwandte Doku​