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.
Schnittstellen & Reporting: API‑Bestimmungen für Kurierpiloten
Praktische technische Checkliste für Tracking‑APIs, Webhooks und Reporting während eines Kurierpiloten in der Schweiz. Fokus: Datenformate, Events, Sicherheit.
Kurzantwort
Diese Checkliste fasst die minimalen API‑Anforderungen für einen Kurierpiloten zusammen. Sie hilft IT‑Teams in Zürich, Bern oder Basel, Tracking‑APIs, Webhooks und Reporting schnell zu prüfen und zu integrieren.
Ziel und Geltungsbereich
Diese technische Checkliste beschreibt Anforderungen an Schnittstellen und Reporting während eines Kurierpiloten. Sie gilt für genehmigte Sendungen, die mit einem Personenwagen transportiert werden. Ziel ist ein klarer Mindeststandard für Tracking, Status‑Events, Webhooks, Datenformate und Sicherheit.
Grundlegende API‑Funktionen
Eine Pilot‑API muss mindestens folgende Funktionen bereitstellen: Authentifizierung (API‑Key oder OAuth2), Endpunkte zum Anlegen und Aktualisieren von Sendungen, Statusabruf, Echtzeit‑Positionsdaten und eine Historie der Statusänderungen. Antworten sollten konsistente Statuscodes (200, 201, 400, 401, 404, 500) und klare Fehlermeldungen liefern.
Tracking Events und Statusmodell
Definieren Sie ein schlankes, eindeutiges Statusmodell. Beispiele: created, picked_up, in_transit, out_for_delivery, delivered, exception, cancelled. Jedes Event braucht Zeitstempel (ISO 8601), Standort (lat/lon), optional Fahrer‑ID und Fotos oder Dokumente als URL. Stellen Sie sicher, dass Statusübergänge nachvollziehbar bleiben.
Webhook‑Design und Retry‑Strategie
Webhooks sind Pflicht für Live‑Updates. Anforderungen: JSON‑Payloads, HMAC‑Signaturheader, eindeutige Event‑ID, idempotente Verarbeitung und Statuscode‑Handling (2xx = akzeptiert). Implementieren Sie eine Retry‑Strategie: exponential backoff mit 5 Retries über 24 Stunden. Liefern Sie einen Endpunkt zur Bestätigung (handshake) und ein Test‑Event zur Validierung.
Datenformate und Felddefinitionen
Nutzen Sie JSON als Primärformat. Legen Sie verpflichtende Felder fest: shipment_id, external_reference, status, timestamp, location {lat, lon, accuracy}, estimated_delivery_window. Optionale Felder: recipient_sign, photo_urls, vehicle_type. Beschreiben Sie Feldlängen und erlaubte Werte klar.
Fehler‑ und Ausnahmehandling
Dokumentieren Sie Fehlercodes und mögliche Ursachen. Beispiele: "invalid_location", "missing_mandatory_field", "auth_failed". Bei Exceptions (z. B. Unzustellbarkeit) muss der Webhook eine klare next_steps‑Empfehlung enthalten. Loggen Sie alle Events minimal 30 Tage zum Debugging.
Häufige Fragen
Welche Authentifizierung empfiehlt sich?
Für Pilotprojekte reicht oft ein sicherer, rotierender API‑Key. Für Produktionsreife empfiehlt sich OAuth2 mit kurzen Tokenlaufzeiten. Wichtig ist HMAC‑Signatur für Webhooks.
Wie detailliert müssen Positionsdaten sein?
Liefern Sie lat/lon mit einer Genauigkeit in Metern, plus accuracy‑Feld. Für stadtnahe Kurierfahrten genügen horizontale Koordinaten mit 5–20 m Genauigkeit.
Wie teste ich die Webhooks vor dem Pilotstart?
Nutzen Sie einen Test‑Endpoint und senden Sie signierte Test‑Events mit Replay‑IDs. Prüfen Sie Idempotenz, Retry‑Verhalten und die Verifikation der HMAC‑Signatur.
Welche Reportingintervalle sind sinnvoll?
Für Live‑Tracking: Positionsupdates alle 30–120 Sekunden während aktiver Fahrt. Für Statusereignisse genügt ein Push pro Statusänderung.