Public API reference
REST-Endpunkte für Mandanten, die PulseCargo-Daten in ihre eigenen Systeme integrieren — ERP, BI-Tools, Speditionen-Portale, kundenorientierte Apps.
Übersicht
Die PulseCargo Public API stellt ausgehende Endpunkte unter /api/v1/* mit API-Schlüssel-Authentifizierung bereit. Die API ist heute lesefokussiert: Shipments, Aufträge, Container, Zolleinträge, Rechnungen und Dokument-Metadaten. Schreib-Endpunkte sind tier-gated und werden pro Integrations-Partner eingeführt.
Das Developer Portal — Self-Service API Key Issuance, Rate-Limit-Visibility und OpenAPI-Spec-Download — ist auf der Build-Roadmap. Heute erfolgt die API Key Issuance über den Mandanten-Administrator.
Authentifizierung
Alle API-Anfragen erfordern einen gültigen API-Schlüssel, der im X-PulseCargo-Api-Key Header übergeben wird. Schlüssel werden auf zwei Arten begrenzt:
- Tenant API key — vollständiger Lesezugriff auf die Daten des Mandanten. Wird von Mandanten-Administratoren über die Admin-Oberfläche herausgegeben.
- Client API key — beschränkt auf einen einzelnen Client (einer der Kunden des Mandanten). Wird gemäß der Datensichtbarkeitskonfiguration des Mandanten herausgegeben.
curl -H "X-PulseCargo-Api-Key: pcg_live_..." \
https://api.pulsecargo.ai/api/v1/shipmentsSchlüssel werden in TenantApiKeys und ClientApiKeys Tabellen verwaltet. Rotation wird unterstützt; Widerruf ist sofort.
Rate Limits
Standardmäßige Rate Limits pro API-Schlüssel:
- 60 Anfragen pro Minute auf dem öffentlichen Status-Endpunkt (
/api/public-status) — der einzige nicht authentifizierte Endpunkt. - Pro-Mandant ausgehandelte Limits auf authentifizierten Endpunkten. Standard ist großzügig; Pro-Tier-Schwellwerte sind in der Admin-Oberfläche dokumentiert. Kontaktieren Sie Ihren Mandanten-Administrator, um ihn zu erhöhen.
Rate-Limit Response Header (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) werden in jeder Response ausgeliefert.
Endpunkte (Lesezugriff)
| Methode | Pfad | Beschreibung |
|---|---|---|
GET | /api/v1/shipments | Shipments auflisten. Filtert nach Datumsbereich, Lane, Modus, Status. |
GET | /api/v1/shipments/{id} | Einzelner Shipment mit Meilensteinen, Dokumenten, Gebühren. |
GET | /api/v1/orders | Aufträge auflisten. Filtert nach Datumsbereich, Kunde, Status. |
GET | /api/v1/orders/{id} | Einzelner PO mit verknüpften Shipments und ASNs. |
GET | /api/v1/containers | Container-Suche über Shipments hinweg. |
GET | /api/v1/customs | Zolleingangs-Status. |
GET | /api/v1/invoices | Rechnungsliste mit Audit-Status-Flags. |
GET | /api/v1/invoices/{id} | Rechnungs-Detail mit Zeileneinträgen + Audit-Ausnahmen. |
GET | /api/v1/documents | Dokument-Metadaten. Download über signierte URL. |
GET | /api/public-status | Nicht authentifizierte Plattform-Status-Prüfung. |
Endpunkte (Schreib-Zugriff — tier-gated)
Schreib-Endpunkte sind tier-gated und werden pro Integrations-Partner-Vereinbarung ausgeliefert. Heute auf Professional Tier und darüber verfügbar:
| Methode | Pfad | Beschreibung |
|---|---|---|
POST | /api/v1/orders | Erstellen Sie einen Auftrag. Sendet zu CargoWise über eAdaptor. |
PUT | /api/v1/orders/{id} | Aktualisieren Sie einen Auftrag. Letzter Schreiber gewinnt mit Konflikt-Warnung. |
POST | /api/v1/comments | Einen Kommentar zu einem Shipment/Order/Container-Thread posten. Oberflächen im CW eAdaptor ebenfalls. |
POST | /api/v1/products | Erstellen Sie ein Client-Produkt (Phase 2 im Fluss; CW Native Schema). |
Schreib-Endpunkte respektieren dieselbe Authentifizierung, Rate Limits und Audit-Protokollierung wie Lese-Endpunkte. Jeder erfolgreiche Schreib-Vorgang wird im Mandanten-Audit-Log mit Zeitstempel, Benutzer/API-Schlüssel, Quelleinträge und Ergebnis aufgezeichnet.
Webhooks
Die ausgehende Webhook-Bereitstellung wird für geplante Exporte, SIEM Event Egress und PayCargo Vendor-Payment-Events unterstützt. Siehe die Webhook Reference für Payload Schemas, Retry-Richtlinie und Signaturverifizierung.
Audit-Protokollierung
Jeder API-Aufruf wird in OutboundApiLogs mit Zeitstempel, API Key Identifier, Endpunkt, Response Code und Quell-IP protokolliert. Mandanten-Administratoren können das Protokoll über die Admin-Oberfläche abfragen für Konformitätsnachweise (SOC 2 CC4.1 / CC7.2).
Versionierungs-Richtlinie
Die API wird im URL-Pfad versioniert (/api/v1/*). Breaking Changes werden unter einer neuen Version ausgeliefert. Die vorherige Version wird für mindestens 12 Monate nach dem Versand einer Nachfolge-Version unterstützt, mit Deprecation Notices über Response Header (Deprecation, Sunset).
Nicht-Breaking Ergänzungen (neue Felder, neue Endpunkte, erweiterte Enum-Werte) werden in einer Hauptversion ohne Ankündigung ausgeliefert.
SDKs
Offiziell unterstützte SDKs sind noch nicht veröffentlicht. Die OpenAPI-Spec wird mit jedem Release ausgeliefert; Clients können sprachspezifische SDKs daraus generieren. SDK-Verfügbarkeit ist auf der Build-Roadmap; wenn eine bestimmte Sprache Ihre Integration blockiert, kontaktieren Sie uns, um sie zu priorisieren.
Benötigen Sie API-Zugriff?
Mandanten-Administratoren geben API-Schlüssel aus. Wenn Sie Zugriff benötigen, fragen Sie Ihren Mandanten-Administrator oder kontaktieren Sie uns für ein Developer Briefing.