Express Kurier. Direkt.
Auch Overnight.
x25pronto Schweiz bringt Ware direkt ans Ziel. Für kleine Ware fährt ein Auto. Für mehr Platz gibt es Transporter oder XL. Direkt, Express und Overnight fahren von Montag bis Sonntag. Freie Zeiten stehen im Kalender.
API-Integration: Echtzeit-Buchungsdaten zwischen Kurier und ERP
So verbinden Sie Ihr ERP mit einem Kurierdienst: Datenmodell, Authentisierung, Webhooks und Fehlerbehandlung für sichere, schnelle Echtzeit-Buchungsdaten in der Schweiz.
Kurzantwort
Verbinden Sie Ihr ERP per REST-API und Webhooks mit dem Kurierdienst, um Buchungsdaten in Echtzeit zu synchronisieren. Nutzen Sie sichere Authentisierung (z. B. OAuth2 oder API-Keys), ein schlankes JSON-Datenmodell für Sendungs- und Abholinformationen, idempotente Endpunkte, strukturierte Fehlercodes und Retry-Strategien. Implementieren Sie Webhooks für Status-Updates (Abholung, Unterwegs, Zugestellt) und absichern Sie diese mit Signaturen. Das reduziert Eingabefehler und beschleunigt Abläufe in Zürich, Basel oder Genf.
Was Sie zuerst klären müssen
Starten Sie mit den Use-Cases. Benötigen Sie Echtzeit-Status, automatische Buchungen oder Retouren-Management? Legen Sie die Datenfelder fest: Abholadresse, Empfängeradresse, Paketmasse, Zeitfenster, Servicelevel, Referenznummern und Kontaktinfos. Entscheiden Sie, ob Ihr ERP aktive Buchungen auslöst (REST POST) oder nur Status empfängt (Webhooks).
Vorschlag für ein leichtes JSON-Datenmodell
Ein schlankes Modell reduziert Fehler und Integrationsaufwand. Beispielfelder: booking_id, client_reference, pickup {name, street, city, postal_code, country, earliest, latest}, delivery {name, street, city, postal_code, country, contact_phone}, parcels [{weight_kg, length_cm, width_cm, height_cm}], service_code, special_instructions. Verwenden Sie ISO-8601 für Zeiten und ISO-Länderkennungen (CH, DE, FR).
Authentisierung und Sicherheit
Nutzen Sie OAuth2 Client Credentials oder kurzlebige API-Keys mit IP-Restriktion. Verschlüsselung via TLS 1.2+ ist Pflicht. Signieren Sie Webhook-Payloads (HMAC-SHA256) mit einem Shared Secret, damit Ihr ERP eingehende Events validieren kann. Loggen Sie API-Aufrufe mit Request-IDs zur Nachverfolgung.
Webhooks: Design und Best-Practices
Webhooks liefern Status-Events (accepted, pickup_scheduled, picked_up, in_transit, delivered, failed). Sorgen Sie für idempotenz: jedes Event trägt eine unique event_id und timestamp. Bestätigen Sie Empfang mit HTTP 2xx. Implementieren Sie ein Retry-Backoff beim Kurier, falls Ihr ERP 500/Timeout zurückgibt. Dokumentieren event-schemas klar und versioniert.
Idempotenz, Versionsverwaltung und Fehlercodes
Idempotente POST- oder PATCH-Endpunkte verhindern doppelte Buchungen. Verwenden Sie eindeutige client_reference vom ERP. Pflegen Sie API-Versionspfade (/v1/, /v2/) statt Breaking Changes in Payloads. Standardisieren Sie Fehlercodes: 4xx für Validierung, 401 für Auth, 429 für Rate-Limit, 5xx für Serverfehler. Senden Sie in Fehlerantworten machine-readable details.
Monitoring, Tests und Deployment
Testen Sie Integrationen in einer Sandbox mit Replay-Möglichkeiten für Webhooks. Nutzen Sie Contract-Tests (z. B. OpenAPI/Swagger), Postman-Collections und automatisierte End-to-End-Tests. Ein Dashboard für fehlgeschlagene Webhooks und Metriken (Latenz, Fehlerquote) hilft bei Betrieb in Zürich, Basel oder Lausanne.
Häufige Fragen
Welche Events sollten Webhooks mindestens senden?
Mindestens: booking_created, booking_confirmed, pickup_scheduled, picked_up, in_transit, delivered, delivery_failed. Jedes Event braucht event_id, booking_id und timestamp.
Wie verhindern wir doppelte Buchungen?
Ihr ERP sendet eine unique client_reference pro Auftrag. API-Endpunkte prüfen diese Reference und machen POST idempotent oder geben einen 409 mit bestehender booking_id zurück.
Wie sichern wir Webhook-Aufrufe ab?
Signieren Payloads mit HMAC-SHA256 und Shared Secret. Validieren Signatur plus Timestamp, lehnen alte oder wiederholte Anfragen ab.
Welche Limits sind sinnvoll?
Setzen Sie Rate-Limits pro API-Key, z. B. 1000 Anfragen pro Minute pro Kunde. Kommunizieren Sie Limits via Headers und liefern Sie 429 mit Retry-After.