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-Checkliste: Versand- und Trackingdaten integrieren
Konkrete Checkliste für Entwickler: welche Endpunkte, Authentifizierung, Webhooks und Tests Sie brauchen, um Versand- und Trackingdaten in Ihre Systeme zu integrieren.
Kurzantwort
Kurz: eine erfolgreiche Integration braucht klare Endpunkte für Auftragserstellung, Statusabfrage und Tracking, sichere Authentifizierung, zuverlässige Webhooks sowie gründliche Testfälle. Planen Sie Rückfragen, Fehlercodes und Wiederholungsmechanismen ein. Diese Checkliste hilft Ihnen, eine stabile Verbindung zwischen Ihrem ERP/Shop und einem Kurierservice wie x25pronto aufzubauen.
1. Integrationsergebnis definieren
Starten Sie mit klaren Zielen. Legen Sie fest, welche Daten in Echtzeit benötigt werden: Paketaufträge, Sendungsnummern, Statusupdates, Zustellnachweise (z. B. Foto oder Unterschrift) oder nur Basis-Tracking. Bestimmen Sie, welche Systeme angebunden werden (ERP, Shop, WMS) und welche Datenfelder zwingend sind (Absender, Empfänger, Masse, Service-Level).
2. Wichtige Endpunkte
Planen Sie diese Endpunkte: 1) Auftrag anlegen: send-order - übermittelt Absender, Empfänger, Paketdaten, Referenzen; 2) Auftragsstatus abfragen: get-order-status - synchroner Request für Current Status; 3) Tracking-Details: get-tracking - liefert Zeitstempel, Standort, Statuscodes; 4) Auftragsänderung und stornieren: update-order / cancel-order; 5) Raten- und Serviceabfrage: get-rates - optional für Auswahl der Versandoption. Dokumentieren Sie erwartete Felder, Pflichtparameter und Antwortformate (JSON).
3. Authentifizierung und Sicherheit
Verwenden Sie tokenbasierte Auth (z. B. OAuth2 Client Credentials oder kurzlebige API-Keys). Schützen Sie alle Endpunkte mit HTTPS/TLS. Implementieren Sie Roles und Scopes, damit z. B. Schreibrechte für Auftragserstellung getrennt sind von Leserechten für Tracking. Rotieren Sie Schlüssel regelmässig und loggen Sie fehlgeschlagene Auth-Versuche. Begrenzen Sie IPs oder nutzen Sie mTLS, wenn besonders hohe Sicherheit nötig ist.
4. Webhooks und Ereignismodell
Nutzen Sie Webhooks für Echtzeit-Statusupdates (z. B. pickup-confirmed, in-transit, out-for-delivery, delivered, exception). Definieren Sie ein klares Retrieschema (z. B. 3 Versuche mit exponentiellem Backoff) und eine HMAC-Signatur, damit Sie die Echtheit prüfen können. Stellen Sie einen Test-Endpoint bereit und dokumentieren Sie das Payload-Format und empfohlene HTTP-Statusantworten (200 OK bei erfolgreicher Verarbeitung).
5. Fehlercodes, Idempotenz und Wiederholung
Standardisieren Sie Fehlercodes (4xx für Client, 5xx für Server). Implementieren Sie Idempotenz-Keys bei Auftragsanfragen, damit doppelte Submits nicht zu doppelten Sendungen führen. Planen Sie automatische Wiederholungslogik für temporäre Fehler und informative Fehlermeldungen für Entwickler und Support.
6. Testfälle und Testumgebung
Stellen Sie eine Sandbox zur Verfügung. Testen Sie: Auftragserstellung mit gültigen und ungültigen Feldern; Statusänderungen per Webhook; Stornierungen; Rush-/Notfallbestellungen; hohe Last und Rate-Limits; Authentifizierungsfehler. Automatisieren Sie Tests mit CI, um Regressionen früh zu finden. Veröffentlichen Sie Beispiel-Requests/Responses und Postman- oder OpenAPI-Spezifikationen.
Häufige Fragen
Welche Felder sind zwingend bei der Auftragserstellung?
Typisch sind Absender-/Empfängerdaten, Paketmasse/Gewicht, Service-Level, Referenznummer und Sendungsreferenz. Konkrete Pflichtfelder legt der API-Provider fest; dokumentieren Sie diese im Integrationsplan.
Wie verifiziere ich, dass ein Webhook echt ist?
Nutzen Sie eine HMAC-Signatur im Header oder ein gemeinsames Secret. Vergleichen Sie die Signatur mit dem berechneten Hash des Payloads. Akzeptieren Sie nur HTTPS-gesicherte Verbindungen.
Was ist Idempotenz und warum ist sie wichtig?
Idempotenz verhindert doppelte Aufträge bei Netzwerkwiederholungen. Client sendet einen Idempotenz-Key; der Server führt die Aktion nur einmal aus und liefert immer dieselbe Antwort bei wiederholten Requests mit dem gleichen Key.
Wie teste ich Rate-Limits sicher?
Simulieren Sie Last in der Sandbox. Erhöhen Sie Anfragen schrittweise und prüfen Sie, ab wann 429-Responses auftreten. Implementieren Sie Client-seitiges Backoff und Caching, um Limits einzuhalten.