REST-API

Jede Aktion in der Celerp-Oberfläche ist ein REST-Endpunkt – dieselbe API, die die Oberfläche intern nutzt. Automatisieren Sie Abläufe, binden Sie andere Systeme an oder bauen Sie eigene Werkzeuge. Die API läuft lokal mit Ihren Daten; nichts geht in die Cloud.

Authentifizierung

Celerp verwendet kurzlebige JSON Web Tokens. Melden Sie sich mit Ihrer Celerp-E-Mail-Adresse und Ihrem Passwort an, um ein Zugriffstoken zu erhalten, und schicken Sie es dann bei jeder Anfrage als Bearer-Header mit.

1. Anmelden

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

Die Antwort enthält zwei Token:

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

2. Die API mit dem Token aufrufen

curl http://localhost:8000/items \
  -H "Authorization: Bearer eyJhbGciOiJI..."

• Das Token weist Nutzerkonto, Rolle und Unternehmen aus; Anfragen sind damit automatisch auf dieses Unternehmen begrenzt – ein zusätzlicher Header ist nicht nötig.
• Zugriffstoken sind bis zu 24 Stunden gültig. Wenn eines abläuft, erhalten Sie ein neues Paar, indem Sie Ihr refresh_token per POST an /auth/token/refresh senden.
• Sie gehören zu mehreren Unternehmen? Listen Sie sie mit GET /auth/my-companies auf und holen Sie sich mit POST /auth/switch-company/{company_id} ein Token für ein anderes.

Anfragen stellen

Alle Endpunkte liegen unter der Adresse Ihres API-Servers (http://localhost:8000 bei einer pip-Installation, wie in den Beispielen unten) und liefern JSON. Endpunkte für Listen geben ein items-Array und die Gesamtzahl total zurück:

curl "http://localhost:8000/items?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": "item:...", "sku": "WIDGET-001", "name": "Widget", "quantity": 42 }
  ],
  "total": 142
}

Paginierung: Übergeben Sie ?limit= (Standard 50) und ?offset=. Die meisten Listenendpunkte nehmen zusätzlich einen Suchbegriff q= und Spaltenfilter entgegen (z. B. ?status=available).

Daten erstellen

Legen Sie Datensätze per POST mit JSON an. Schreibvorgänge liefern die id der neuen Entität zurück, dazu die zugrunde liegende event_id – jede Änderung in Celerp ist ein Ereignis.

curl -X POST http://localhost:8000/crm/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "idempotency_key": "acme-2026-06-21"
  }'

Konventionen

• Fehler Nicht-2xx-Antworten geben {"detail": "..."} mit einem Standard-HTTP-Statuscode zurück.
• Anfragelimits Standardmäßig 60 Anfragen pro Minute und IP; die Anmeldung ist auf 10 pro Minute begrenzt. Wird ein Limit überschritten, kommt 429 zurück.
• Berechtigungen Endpunkte sind an Ihre Rolle gebunden: viewer → operator → manager → admin → owner.
• Mandantenbezug Jede Anfrage wirkt auf das Unternehmen im Token; wechseln Sie das Unternehmen, um in einem anderen zu arbeiten.

Häufige Endpunkte

Ein kleiner Ausschnitt für den Einstieg. Jedes Modul bringt eigene Endpunkte mit – die vollständige Liste steht im OpenAPI-Schema weiter unten.

Vollständige Referenz nach Bereich

Jeder Endpunkt der laufenden API, nach Bereich gruppiert. Jede Seite listet Methode, Pfad, Parameter, Anfrage- und Antwortschema sowie einen Beispielaufruf auf.

Die vollständige API erkunden

Die vollständige, stets aktuelle Referenz ist das OpenAPI-3.1-Schema, das Ihre eigene Instanz erzeugt:

GET http://localhost:8000/openapi.json

Laden Sie es in ein beliebiges OpenAPI-Werkzeug – Postman, Insomnia, Swagger UI oder einen Client-Generator –, um jeden Endpunkt und jedes Modell zu durchsuchen, Anfragen auszuprobieren und einen typisierten Client in Ihrer Sprache zu erzeugen. Celerp liefert das Schema selbst statt einer gehosteten Doku-Seite; so bleibt Ihre API-Oberfläche auf Ihre Instanz beschränkt.