Calcutron bietet eine umfangreiche REST-API (Version 1.0.0, OpenAPI 3.0) für externe Integrationen mit Automatisierungstools, ERP-Systemen und Drittsystemen. Mit über 78 Endpunkten deckt die API nahezu alle Geschäftsbereiche ab – von der Angebotserstellung über die Projektverwaltung bis zur Produktrecherche im Katalog.

API-Dokumentation

Drei Formate stehen zur Verfügung:

Die Swagger UI (unter /api/v1/schema/swagger/) bietet eine interaktive Oberfläche zum direkten Testen von Endpunkten im Browser. Für die Authentifizierung klicken Sie auf „Authorize" und geben Ihren API-Key ein. Voraussetzung ist eine aktive Django-Session – loggen Sie sich also zuerst im Admin-Panel ein.

ReDoc (unter /api/v1/schema/redoc/) bietet eine durchsuchbare, übersichtliche Referenzdokumentation aller Endpunkte mit Parametern und Beispiel-Responses. Auch hier ist eine Django-Session erforderlich.

Das OpenAPI-Schema ist unter /api/v1/schema/ als JSON oder YAML abrufbar und eignet sich für die automatische Code-Generierung oder den Import in API-Clients wie Postman oder Insomnia.

Zusätzlich steht ein Health-Check-Endpunkt unter /api/v1/health/ zur Verfügung, der keine Authentifizierung erfordert und sich ideal für Monitoring-Systeme und Uptime-Checks eignet.

Authentifizierung

Die API verwendet Bearer-Token-Authentifizierung mit API-Keys. Senden Sie Ihren Key im Authorization-Header jedes Requests:

Authorization: Bearer calc_xxxxxxxxxxxxxxxxxxxx

API-Keys tragen immer das Präfix calc_ und werden im Django-Admin unter Gateway → API Clients erstellt und verwaltet. Jeder API-Client kann individuell konfiguriert werden mit eigenen Berechtigungen, Rate Limits und IP-Beschränkungen.

API-Key-Verwaltung im Admin-Panel:

Unter Gateway → API Clients legen Sie neue API-Clients an. Dabei konfigurieren Sie den Client-Namen (zur Identifikation), die gewünschten API Permissions (Scopes), die Webhook Permissions (separat von API-Scopes), optionale Rate-Limit-Überschreibungen und eine optionale IP-Allowlist zur Zugriffsbeschränkung.

Permission-System (Scopes)

Calcutron verwendet zwei getrennte Permission-Systeme: API Permissions für REST-Endpunkte und Webhook Permissions für Event-Abonnements. Beide werden unabhängig pro API-Client konfiguriert.

Die 13 API-Scopes im Überblick:

Scope

Berechtigung

quotations:read

Angebote und Positionen lesen, Fertigungseinheiten auflisten

quotations:write

Positionen erstellen, aktualisieren und löschen, Status von Fertigungseinheiten ändern

quotations:export

PDF-, XLSX- und xi:OPD-Exporte generieren

projects:read

Projektdaten und Protokolle lesen

projects:write

Projekte erstellen, aktualisieren und GAEB-X83-Dateien importieren

customers:read

Kundendaten lesen und durchsuchen

customers:write

Kunden erstellen, aktualisieren und löschen

groups:read

Gruppen-Templates und Favoriten lesen

groups:write

Template- und Favoriten-Status von Gruppen ändern

users:read

Benutzerliste abrufen (nur Lesen)

storage_products:read

Katalogprodukte durchsuchen und Details abrufen

presets:read

ETIM-Feature-Presets auflisten und anzeigen

webhooks:manage

Webhook-Abonnements verwalten

Die Scopes werden automatisch aus dem URL-Pfad und der HTTP-Methode abgeleitet. Ein GET-Request auf /api/v1/quotations/ erfordert z. B. den Scope quotations:read, während ein POST-Request auf denselben Pfad quotations:write benötigt.

Rate Limiting

Jeder API-Request wird durch Rate Limiting geschützt. Die Standardlimits betragen 60 Requests pro Minute und 1.000 Requests pro Stunde. Diese Werte können pro API-Client individuell im Admin-Panel angepasst werden.

Die aktuellen Limits und den Verbrauch sehen Sie in den Response-Headers:

Header

Beschreibung

X-RateLimit-Limit

Maximale Anzahl erlaubter Requests im Zeitfenster

X-RateLimit-Remaining

Verbleibende Requests im aktuellen Zeitfenster

X-RateLimit-Reset

Unix-Timestamp, wann das Limit zurückgesetzt wird

Bei Überschreitung des Limits erhalten Sie einen 429 Too Many Requests-Response. Implementieren Sie in Ihrer Integration ein exponentielles Backoff, um Limits nicht dauerhaft zu überschreiten.

Response-Format

Alle API-Responses verwenden JSON mit camelCase-Namenskonvention. Die Konvertierung zwischen Python-seitigem snake_case und JSON-seitigem camelCase erfolgt automatisch (via djangorestframework-camel-case). Sie senden und empfangen also immer camelCase-Felder wie quotationId, createdAt oder totalPrice.

Paginierung:

Listenendpunkte verwenden standardmäßig seitenbasierte Paginierung mit folgender Struktur:

{

"page": 1,

"pages": 5,

"hasNext": true,

"hasPrev": false,

"totalObjectsQuantity": 243,

"objects": [...]

}

Navigieren Sie mit dem Query-Parameter page durch die Ergebnisseiten. Einige Endpunkte (z. B. Kunden-Suche) verwenden Infinite-Scroll-Paginierung, und der Endpunkt für Fertigungseinheiten nutzt Cursor-basierte Paginierung mit dem Parameter cursor (UUID des letzten Elements).

Fehler-Responses folgen dem DRF-Standard mit feldspezifischen Fehlermeldungen:

{

"name": ["Dieses Feld darf nicht leer sein."],

"email": ["Geben Sie eine gültige E-Mail-Adresse ein."]

}

Performance: Die API nutzt orjson für die JSON-Serialisierung, was eine ca. 6-fach schnellere Verarbeitung gegenüber dem Standard-JSON-Encoder ermöglicht. Besonders bei großen Datenmengen (z. B. Angebotsitems) macht sich dies deutlich bemerkbar.

Verfügbare API-Bereiche

Im Folgenden finden Sie eine Übersicht aller API-Bereiche mit ihren wichtigsten Endpunkten und Besonderheiten.

Angebote (Quotations)

Der umfangreichste API-Bereich mit Endpunkten für die vollständige Angebotsverwaltung.

CRUD-Operationen: Angebote auflisten (GET /api/v1/quotations/), Details abrufen (GET /api/v1/quotations/{id}/), erstellen (POST /api/v1/quotations/), aktualisieren (PATCH /api/v1/quotations/{id}/) und löschen (DELETE /api/v1/quotations/{id}/).

Positionen abrufen: GET /api/v1/quotations/{id}/items/ liefert alle Positionen eines Angebots ohne Paginierung in einer einzigen Antwort. Dieser Endpunkt nutzt optimierte Raw-SQL-Queries und liefert auch bei 2.000+ Positionen Ergebnisse in unter 0,5 Sekunden. Für sehr große Angebote (4.000+ Positionen) wurde die Performance von 11–13 Sekunden auf unter 1 Sekunde optimiert – eine Verbesserung von 93 %.

Export-Funktionen:

POST /api/v1/quotations/{id}/pdf/ generiert eine PDF-Datei. Hierbei ist der Parameter isPreview wichtig: Mit isPreview: true wird ein Vorschau-PDF ohne Seiteneffekte erstellt – ideal für Entwürfe und Prüfungen. Mit isPreview: false wird das Angebot als finales Dokument exportiert, wobei das Angebot anschließend den Status READONLY erhält und ein Follow-up-Projekt erstellt wird.

Weitere Exporte: POST /api/v1/quotations/{id}/xlsx/ für Excel-Export und POST /api/v1/quotations/{id}/xi-opd/ für den xi:OPD-Export.

Notizen: Angebote unterstützen Notizen (GET/POST/PATCH/DELETE /api/v1/quotations/{id}/notes/) mit Erwähnungsfunktion. Über das Feld mentionedUsers (Array von UUIDs) können Benutzer erwähnt werden, die automatisch eine Benachrichtigung erhalten. Notizen erscheinen auch in der Projekt-Timeline unter den Projekt-Logs.

Angebotspositionen (Quotation Items)

Positionen innerhalb eines Angebots werden über separate Endpunkte verwaltet. Es gibt vier Positionstypen: Gruppen (Groups), Produkte (Products), Dienstleistungen (Services) und Platzhalter (Placeholders).

Erstellen: Für jeden Typ gibt es einen eigenen Endpunkt, z. B. POST /api/v1/quotations/{id}/items/groups/, POST /api/v1/quotations/{id}/items/products/, POST /api/v1/quotations/{id}/items/services/ und POST /api/v1/quotations/{id}/items/placeholders/.

Aktualisieren: Calcutron bietet 13 spezialisierte PATCH-Endpunkte für granulare Updates. Statt eine gesamte Position zu aktualisieren, können Sie gezielt einzelne Eigenschaften ändern – z. B. nur den Rabatt einer Gruppe (PATCH .../groups/{id}/discount/), den ETIM-Klassen-Status (POST/DELETE .../groups/{id}/etim-class/) oder den manuellen Verkaufspreis (PATCH .../groups/{id}/manual-sales-price/).

Bulk-Operationen: Positionen können kopiert (POST .../items/copy/), verschoben (POST .../items/move/) und gelöscht (DELETE .../items/) werden. Beim Kopieren und Verschieben können mehrere Positionen gleichzeitig verarbeitet werden.

Produkt-spezifisch: Produkte können ersetzt (POST .../products/{id}/replace/), Alternative-Angebote getauscht (POST .../products/{id}/swap-alternative/) und bevorzugte Lieferantenangebote ausgewählt (POST .../products/{id}/select-offer/) werden.

Projekte (Projects)

CRUD-Operationen: Projekte auflisten, erstellen, aktualisieren und löschen über die Standard-Endpunkte unter /api/v1/projects/.

GAEB-X83-Import: Beim Erstellen eines Projekts (POST /api/v1/projects/) kann optional eine GAEB-X83-Datei mitgesendet werden. Die Datei wird als Base64-codierter String im Feld fileData übertragen, zusammen mit dem Dateinamen im Feld fileName. Weitere optionale Parameter sind preferredManufacturers (Array von UUIDs in Prioritätsreihenfolge für die Produktzuordnung), selectedCategories (X83-Kategorie-IDs, leer = alle) und selectedItems (spezifische Item-IDs, leer = alle).

Der Parameter skipAiGeneration steuert den Verarbeitungsmodus: Mit true wird die Datei synchron sofort verarbeitet und die Response enthält die quotationId direkt. Mit false (Standard) erfolgt die Verarbeitung asynchron – die Response enthält processingStatus: "processing" und die quotationId ist zunächst null.

Projekt-Logs: GET /api/v1/projects/{id}/logs/ liefert eine zusammengeführte Timeline aus automatischen Events und manuellen Notizen. Mit dem Query-Parameter scope filtern Sie: ALL (Standard) zeigt Events und Notizen, EVENTS nur automatische Ereignisse, NOTES nur manuelle Notizen.

Adressen und Status: Projektadressen und -status können über eigene Endpunkte aktualisiert werden. Status-Änderungen lösen automatisch Webhook-Events aus.

Kunden (Customers)

CRUD und Suche: Kunden können erstellt, gelesen, aktualisiert und gelöscht werden über /api/v1/customers/. Die Kundenliste unterstützt Infinite-Scroll-Paginierung für eine flüssige Suche mit automatischem Nachladen.

Fertigungseinheiten (Production Units)

Auflisten: GET /api/v1/production-units/ verwendet Cursor-basierte Paginierung. Der Parameter cursor ist die UUID der letzten Fertigungseinheit der vorherigen Seite, limit bestimmt die Seitengröße (Standard: 50, Maximum: 100). Über den Parameter statusId können Sie nach einem bestimmten Fertigungsstatus filtern.

Status aktualisieren: PATCH /api/v1/production-units/{group_id}/ aktualisiert den Status einer Fertigungseinheit. Die Felder productionUnitStatus (neue Status-ID) und triggeredBy (auslösender Benutzer/System) werden erwartet.

Katalogprodukte (Storage Products)

Volltextsuche: GET /api/v1/storage-products/ nutzt PostgreSQL Full-Text Search mit Relevance Ranking. Der Parameter search akzeptiert kommaseparierte Suchbegriffe (UND-Verknüpfung). Die Ergebnisse werden nach Relevanz sortiert zurückgegeben.

Produktdetails: GET /api/v1/storage-products/{gtin}/ liefert umfangreiche Details zu einem Produkt, einschließlich DATANORM-Lieferantenangebote (offers[]), ETIM-Klassifizierung (etimProduct), Produkteinstellungen und Produktbilder in verschiedenen Auflösungen (srcSet: sm, md, lg, xl, xxl, original).

Presets (ETIM-Feature-Presets)

Dynamische ETIM-Feature-Presets (Calcugrid) können aufgelistet und angezeigt werden. Diese Presets definieren vorkonfigurierte Merkmalskombinationen für die schnelle Produktkonfiguration.

Favoriten-Gruppen und Gruppen-Templates

Favoriten-Gruppen: CRUD-Operationen für als Favorit markierte Gruppen und deren Template-Verwaltung. Gruppen können als Favorit oder Template markiert bzw. demarkiert werden.

Gruppen-Templates: Vordefinierte Gruppenvorlagen, die in neuen Angeboten wiederverwendet werden können.

Webhooks

Webhook-Abonnements, Zustellungshistorie und Test-Funktionalität werden über die API verwaltet. Details finden Sie im Artikel „Webhooks einrichten und nutzen".

Benutzer (Users)

GET /api/v1/users/ liefert eine schreibgeschützte Liste aller Benutzer der Instanz. Dieser Endpunkt erfordert den Scope users:read.

Wichtige Endpunkte im Überblick

Endpunkt

Methode

Beschreibung

/api/v1/health/

GET

Health Check (keine Auth erforderlich)

/api/v1/quotations/

GET/POST

Angebote auflisten und erstellen

/api/v1/quotations/{id}/items/

GET

Alle Positionen eines Angebots (ohne Paginierung, optimiert)

/api/v1/quotations/{id}/pdf/

POST

PDF-Export (isPreview-Parameter beachten)

/api/v1/quotations/{id}/xlsx/

POST

Excel-Export

/api/v1/quotations/{id}/notes/

GET/POST

Angebotsnotizen mit Erwähnungen

/api/v1/projects/

GET/POST

Projekte auflisten und erstellen (mit optionalem GAEB-X83-Import)

/api/v1/projects/{id}/logs/

GET

Projekt-Timeline (Events + Notizen, scope-Filter)

/api/v1/customers/

GET/POST

Kunden auflisten und erstellen (Infinite Scroll)

/api/v1/production-units/

GET

Fertigungseinheiten (Cursor-Paginierung)

/api/v1/production-units/{id}/

PATCH

Status einer Fertigungseinheit aktualisieren

/api/v1/storage-products/

GET

Katalogprodukte durchsuchen (Volltextsuche)

/api/v1/storage-products/{gtin}/

GET

Produktdetails mit DATANORM, ETIM und Bildern

/api/v1/webhooks/subscriptions/

GET/POST

Webhook-Abonnements verwalten

/api/v1/webhooks/test/

POST

Test-Webhook senden

Erste Schritte

1. API-Key erstellen: Navigieren Sie im Admin-Panel zu Gateway → API Clients und erstellen Sie einen neuen Client mit den benötigten Scopes.

2. Dokumentation laden: Öffnen Sie die Swagger UI unter /api/v1/schema/swagger/ und autorisieren Sie sich mit Ihrem API-Key.

3. Health Check testen: Senden Sie einen GET-Request an /api/v1/health/, um die grundlegende Konnektivität zu prüfen.

4. Ersten Request senden: Starten Sie mit GET /api/v1/quotations/, um Ihre Angebote abzurufen.