API-DokumentationÜbersicht & Grundlagen

API – Übersicht & Grundlagen

Die ZENTORY REST-API ermöglicht die programmatische Integration in eigene Systeme, ERP-Software oder Automatisierungsplattformen.

Basis-URL

https://app.zentory.ch/api/v1

Grundprinzipien

  • REST: Ressourcenorientierte Endpunkte
  • JSON: Alle Requests und Responses verwenden Content-Type: application/json
  • HTTPS: Alle Verbindungen müssen über HTTPS erfolgen
  • UTF-8: Alle Strings sind UTF-8 kodiert
  • ISO 8601: Datums- und Zeitangaben im Format 2025-03-18T10:30:00Z

Rate Limiting

PlanRequests pro MinuteRequests pro Tag
Starter305 000
Business12050 000
Enterprise500500 000

Bei Überschreitung wird HTTP 429 Too Many Requests zurückgegeben. Der Header Retry-After enthält die Wartezeit in Sekunden.

Pagination

Listenendpunkte sind paginiert. Parameter:

  • page (Standard: 1)
  • per_page (Standard: 50, max: 200)

Response-Header:

X-Total-Count: 1234
X-Page: 1
X-Per-Page: 50
X-Total-Pages: 25

Fehler-Format

Alle Fehler geben folgenden JSON-Body zurück:

{
  "error": {
    "code": "not_found",
    "message": "Material mit ID 'mat_xyz' nicht gefunden.",
    "details": {}
  }
}

HTTP-Statuscodes

CodeBedeutung
200OK
201Erstellt
204Kein Inhalt (z.B. nach DELETE)
400Ungültige Anfrage (Validierungsfehler)
401Nicht authentifiziert
403Keine Berechtigung
404Ressource nicht gefunden
422Nicht verarbeitbar (semantischer Fehler)
429Rate Limit überschritten
500Interner Serverfehler

Versionierung

Die aktuelle API-Version ist v1. Breaking Changes werden als neue Version veröffentlicht (v2). Ältere Versionen werden mindestens 12 Monate nach Einführung einer neuen Version unterstützt.

Abkündigungen werden per E-Mail an API-Nutzer und im Changelog kommuniziert.

OpenAPI / Swagger

Die vollständige API-Spezifikation im OpenAPI 3.0-Format ist unter folgendem Endpunkt verfügbar:

GET https://app.zentory.ch/api/docs

Sie können die Spezifikation in Tools wie Postman, Insomnia oder Swagger UI importieren.

Schichtübergabe-ZusammenfassungAuthentifizierung