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.
Best Practices für Idempotenz und Event‑Versionierung in Kurier‑APIs
Praktische Muster für Idempotency‑Keys, Duplikatserkennung, Event‑Versionierung und sichere Migrationspfade in Kurier‑APIs. Fokus: zuverlässige Buchungen und Reconciliation.
Kurzantwort
Kurz: Verwenden Sie strukturierte Idempotency‑Keys, serverseitige Deduplication mit deterministischen Prüfungen und ein klar versioniertes Event‑Schema mit Migrationspfaden. Das verhindert doppelte Buchungen, vereinfacht Fehlerbehandlung und schützt Integrationen von Zürcher bis Genfer Systemen.
Warum Idempotenz und Versionierung wichtig sind
Kurier‑APIs verarbeiten kritische Aktionen: Pickup‑Bestellungen, Route‑Updates und Storno. Fehler, Netzwerkausfälle oder wiederholte Client‑Versuche können zu doppelten Buchungen und Inkonsistenzen führen. Idempotenz vermeidet doppelte Wirkung. Event‑Versionierung macht Schemaänderungen rückwärtskompatibel und erlaubt sichere Migrationen über interne Systeme und externe Integrationen hinweg.
Pattern für Idempotency‑Keys
Nutzen Sie einen strukturierten Key: {client_id}:{operation}:{hash(payload)}. Beispiel: customer42:createBooking:3f8a7b. client_id trennt Mandanten, operation stellt die Aktion klar und hash(payload) fängt relevante Felder ein. Setzen Sie eine konfigurierbare Lebensdauer (z. B. 24–72 Stunden). Speichern Sie Key, Ergebnis‑Status und Server‑Response. Auf wiederholte Requests mit demselben Key geben Sie denselben HTTP‑Status und dieselbe Response zurück.
Serverseitige Deduplication und Prüfungen
Vertrauen Sie nie nur auf den Key. Validieren Sie deterministisch: prüfbare Felder wie Abholadresse, Empfänger, Paketgrössen und Zeitfenster. Erstellen Sie eine Fingerprint‑Spalte in der Datenbank, z. B. SHA256 über die relevanten Felder. Wenn Fingerprint und key übereinstimmen, behandeln Sie den Request als Duplikat. Legen Sie feste Regeln für «ähnliche» Requests fest, etwa Toleranzen bei Zeitfenstern.
Event‑Versionierung: Strategie und Formate
Versionieren Sie Events explicit: event.type, event.version, event.schema. Verwenden Sie MAJOR.MINOR (z. B. 1.0, 2.0). MAJOR‑Sprünge sind inkompatibel; MINOR‑Änderungen sind additive. Transportieren Sie ein Schema‑Identifierfeld (z. B. schema_uri oder schema_id). Nutzen Sie JSON Schema oder Avro für Validierung. Bewahren Sie alte Schemata im Repository auf, damit Konsumenten rehydration und Backward‑Parsers bauen können.
Migrationspfade und Kompatibilitätsregeln
Definieren Sie Regeln: 1) Additive Felder sind sicher. 2) Entfernen oder Umbenennen ist breaking. 3) Führen Sie Feature Flags für Konsumenten ein. Planen Sie eine Deprecation‑Phase: Notifizieren Sie Integrationen via Webhook und Dashboard mindestens 30–90 Tage vor einem MAJOR‑Change. Bieten Sie ein Opt‑in für neue Versionen, bis alle Konsumenten migriert sind.
Fehlerbehandlung und Reconciliation
Loggen Sie idempotency‑Events, Fingerprints und Entscheidungspfade. Implementieren Sie eine Reconciliation‑API, mit der Partner wiederkehrend den Status abfragen und Divergenzen melden können. Erstellen Sie ein manuelles Interventionstool für Operations‑Teams, um Duplikate zu fusionieren oder Konflikte zu lösen. Achten Sie auf auditierbare Änderungen für Compliance und Streitfälle.
Häufige Fragen
Wie lange soll ein Idempotency‑Key gültig sein?
Typisch sind 24–72 Stunden. Wählen Sie eine Dauer passend zum Geschäftsvorgang. Für Pickup‑Buchungen reicht oft 48 Stunden; für Langzeittransaktionen setzen Sie längere Fristen.
Was, wenn Payload‑Felder sich während Retries ändern?
Bei Änderungen prüfen Sie die Fingerprint‑Differenz. Kleine Änderungen (z. B. Kommentartexte) können akzeptiert werden; kritische Felder (Zieladresse, Paketmasse) sollten ein Duplikatbruch auslösen und eine neue Buchung erfordern.
Wie handhabt man inkompatible Event‑Änderungen?
Führen Sie eine MAJOR‑Version ein, benachrichtigen Sie alle Konsumenten, bieten Sie ein Übergangsende und lassen Sie alte Events noch lesbar. Implementieren Sie Adapters oder Transformationsschichten in Ihrem Event‑Broker.
Welche Felder gehören in den Idempotency‑Key Hash?
Relevante Geschäfts‑Felder wie Abhol‑/Lieferadresse, Empfänger‑ID, Paketmasse, gewünschtes Zeitfenster und Service‑Typ. Schliessen Sie nicht‑relevante Metafelder wie Timestamps aus.