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.
IT‑Integration: REST‑APIs für Kurierbuchung aus Ihrem ERP
Wie Sie mit einer REST‑API Kurieraufträge direkt aus Ihrem ERP an x25pronto übermitteln: Datenfelder, Authentifizierung, Fehlerbehandlung und Best Practices für stabile Integrationen.
Kurzantwort
Eine stabile REST‑API-Integration ermöglicht das automatische Erstellen von Kurieraufträgen aus Ihrem ERP an x25pronto. Kernelemente sind ein klar definiertes JSON‑Payload, sichere Authentifizierung (API‑Key oder OAuth2), sinnvolle Validierung der Felder, idempotente Requests und transparente Fehlercodes. Halten Sie Adresse, Zeitfenster, Paketdetails und Empfängerinfos standardisiert, prüfen Sie Adressformate für CH‑Postleitzahlen und nutzen Sie Webhooks für Status‑Updates.
Ziel und Einsatzszenarien
Ziel ist eine automatisierte, zuverlässige Übermittlung von Kurieraufträgen aus ERP‑Systemen wie SAP, Microsoft Dynamics oder Abacus an x25pronto. Typische Szenarien sind Eilzustellungen, Ersatzlieferungen, Muster‑Versand und returns. Die Schnittstelle ersetzt manuelle Eingaben und reduziert Fehler sowie Aufwand.
Authentifizierung und Sicherheit
Nutzen Sie sicherheitsbewährte Methoden: API‑Key für Server‑zu‑Server‑Kommunikation oder OAuth2 (Client Credentials) für feinere Kontrolle. Alle Endpunkte über HTTPS. Begrenzen Sie API‑Keys auf IPs falls möglich. Rotieren und loggen Sie Keys. Geben Sie keine sensiblen Daten im URL‑Querystring weiter.
Grundlegende API‑Ressourcen und Endpunkte
Minimal benötigte Endpunkte: POST /orders (Auftrag erstellen), GET /orders/{id} (Status abfragen), PATCH /orders/{id} (Änderung vor Abholung), DELETE /orders/{id} (Stornierung, sofern noch möglich) und POST /webhooks (Webhook‑Registrierung). Jeder Endpunkt liefert standardisierte Statuscodes und ein JSON‑Schema im Response.
Empfohlenes JSON‑Payload für POST /orders
Beispiel‑Felder: clientOrderId (string, idempotenz), pickup {name, street, postalCode, city, country, contact{name, phone, email}, readyAt}, delivery {name, street, postalCode, city, country, contact{name, phone, email}, requiredBy}, packages [{weightKg, lengthCm, widthCm, heightCm, description, fragile}], serviceLevel (sameDay, nextMorning, standard), specialInstructions, declaredValueCHF. Markieren Sie alle Pflichtfelder und Validierungsregeln (z. B. postalCode 1000–9658 für CH, weight >0).
Idempotenz, Validierung und Konfliktvermeidung
Senden Sie clientOrderId für idempotente POSTs. Bei wiederholten Anfragen mit derselben clientOrderId muss die API denselben Auftrag zurückgeben. Validieren Sie Adressen vor Senden (z. B. über ein Adressprüfungs‑Service). Akzeptieren Sie nur erlaubte ServiceLevel‑Kombinationen und prüfen Sie Zeitfenster gegen Betriebszeiten.
Fehlercodes und Fehlerbehandlung
Verwenden Sie klare HTTP‑Codes: 201 Created, 200 OK, 400 Bad Request (fehlende oder ungültige Felder), 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict (z. B. widersprüchliche Daten), 422 Unprocessable Entity (validierungsfehler), 500 Server Error. Geben Sie im Response ein Fehlerobjekt mit code, message und optional details zurück. Loggen Sie Request/Response‑Paare lokal für Troubleshooting.
Häufige Fragen
Wie registriere ich einen API‑Key?
Fordern Sie in der x25pronto Developer‑Konsole einen API‑Key an. Hinterlegen Sie IP‑Restriktionen und Ablaufdatum. Testen Sie den Key zuerst in der Sandbox‑Umgebung.
Wie sende ich Dokumente wie Lieferbon oder Rechnung mit?
Dokumente können als base64‑encodierte Strings im JSON oder per multipart/form‑data hochgeladen werden. Achten Sie auf maximale Dateigrössen und MIME‑Typen.
Wie bekomme ich Echtzeit‑Statusupdates?
Registrieren Sie einen Webhook‑Endpoint. x25pronto sendet Status‑Events (accepted, pickedUp, inTransit, delivered, canceled) per POST. Prüfen Sie Signaturen oder HMAC für die Integrität.
Was tun bei wiederholten Fehlermeldungen 422?
Prüfen Sie die Validierungsdetails im Response. Meist fehlen Pflichtfelder oder Werte liegen ausserhalb erlaubter Bereiche. Validieren Sie das Payload vor dem Senden gegen das bereitgestellte JSON‑Schema.