Chr. Carstensen Logistics API
Logistics Integration Platform

Automatisierung für
Carstensen Aufträge

REST-API für die Integration mit dem Carstensen-Portal. Auftragserfassung, Tracking, Dokumente und Labeldruck — alles über eine einheitliche, versionierte Schnittstelle.

API-Dokumentation öffnen Endpoints ansehen
10 Aktive Endpoints
Redis Rate-Limit Backend
JWT Bearer-Token Auth via Cookie
API-Referenz

Verfügbare Endpoints

Alle produktiven Endpoints — getestet und freigegeben. Experimentelle Routen sind in der Swagger-UI ausgeblendet.

POST /login

Anmeldung am Portal. Gibt einen Bearer-Token als httpOnly-Cookie zurück.

Auth
POST /logout

Session beenden und Token-Cookie invalidieren.

Auth
GET /api/orders/list

Auftragsliste des aktuellen Kunden abrufen. Unterstützt Filter und Paginierung.

Aufträge
GET /api/orders/detail

Detailansicht eines einzelnen Auftrags inklusive aller Positionen.

Aufträge
POST /api/orders/create

Neuen Auftrag im Portal anlegen. Akzeptiert saubere JSON-Nutzdaten.

Aufträge
POST /api/orders/update

Bestehenden Auftrag ändern. Optionale Patch-Felder werden direkt an das Portal übergeben.

Aufträge
GET /api/orders/tracking

Tracking-Status und Ereignisse zu einem Auftrag abfragen.

Tracking
GET /api/orders/print-label

Versandlabel als PDF-Byte-Stream herunterladen (application/pdf).

Dokumente
POST /api/documents/attach

Dokument (PDF, Bild) an einen bestehenden Auftrag anhängen.

Dokumente
GET /api/orders/catalog/create-order-fields

Vollständige Liste aller Portal-Feldnamen für die Auftragserstellung.

Katalog
Architektur

Wie die API funktioniert

Der API-Server übersetzt saubere JSON-Anfragen in die nativen Portal-Formularaufrufe von service.carstensen.eu — transparent und zuverlässig.

Proxy-Architektur
FastAPI übersetzt REST-Requests in Formular-Posts an das Portal. Der Client kommuniziert immer nur mit api.carstensen.eu.
Redis Rate Limiter
Tagesbasiertes Kontingent pro Kunde und Endpoint. Fail-open-Design: bei Redis-Ausfall werden Anfragen nicht blockiert.
Zweistufige Konfiguration
Lokales config.json speichert nur die Kunden-ID. Endpoints, Limits und Basis-URL kommen per GitHub-JSON pro Kunde.
Sauberes JSON-Interface
Clients senden schlanke, gut dokumentierte Payloads. Die Übersetzung in Portal-Feldnamen übernimmt der Proxy intern.
Selektive Swagger-Sichtbarkeit
Nur getestete Endpoints erscheinen in der Swagger-UI. Experimentelle Routen sind ausgeblendet oder geben 404 zurück.
IIS + ARR Reverse Proxy
Windows Server SRV-WWW mit IIS leitet HTTPS-Traffic an uvicorn weiter. Let's Encrypt-Zertifikat via win-acme.
Sicherheit

Authentifizierung

Alle Anfragen erfordern einen gültigen Bearer-Token, der nach dem Login automatisch als httpOnly-Cookie gesetzt wird.

1
POST /login aufrufen
Credentials als JSON-Body übergeben. Der Server authentifiziert gegen das Carstensen-Portal.
2
Cookie wird gesetzt
Bei Erfolg gibt der Server einen httpOnly-Cookie mit dem Bearer-Token zurück. Kein manuelles Token-Handling nötig.
3
Folgeaufrufe automatisch autorisiert
Browser und HTTP-Clients senden den Cookie bei jedem Request. Der Middleware prüft die Gültigkeit transparent.
4
POST /logout zum Beenden
Session schließen und Token invalidieren. Der Cookie wird serverseitig gelöscht.
HTTP · Example
# 1. Login POST https://api.carstensen.eu/login Content-Type: application/json { "username": "kunde123", "password": "••••••••" } # → 200 OK Set-Cookie: token=…; HttpOnly # 2. Auftrag erstellen (Cookie wird auto gesendet) POST https://api.carstensen.eu/api/orders/create Content-Type: application/json { "recipient": "Muster GmbH", "zip": "20095", "city": "Hamburg", "pieces": 1, "weight_kg": 12.5 }
Nutzungsgrenzen

Rate Limiting

Anfragen werden pro Kunde, Endpoint und Tag gezählt. Limits sind in der GitHub-Konfiguration des jeweiligen Kunden definiert.

Redis
Tagesbasierte Zähler gespeichert in Redis. Automatischer Reset um Mitternacht.
429HTTP
Rückgabecode wenn das Tageslimit überschritten wurde. Header enthält verbleibende Anfragen.
Fail open
Bei Redis-Ausfall werden Anfragen nicht blockiert. Der Dienst bleibt verfügbar.
Demnächst verfügbar

OCR-Importmodul

Automatische Datenextraktion aus hochgeladenen Dokumenten — Lieferscheine, CMRs, Frachtbriefe — direkt in Aufträge umgewandelt. Template-Editor, Batch-Import und vollständige REST-Schnittstelle.

Beta-Zugang
In Entwicklung
Geplante Features
  • → Tesseract OCR + pdf2image
  • → Canvas-basierter Zonen-Editor
  • → Bulk-Import per Ordnerauswahl
  • → POST /api/import (headless)