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.
OpenAPI-Spezifikation und Beispiel-Schemas für Kurier-APIs
Konkrete OpenAPI-Vorlage mit Beispiel-Requests und Responses für create-order, Webhooks und Fehler. Schnell integrieren, sicher testen, in CH-Umfeld anwenden.
Kurzantwort
Hier finden Sie eine schlanke OpenAPI-Vorlage mit Beispiel-Requests und Responses für create-order, typische Webhook-Payloads und standardisierte Fehlerantworten. Die Vorlage ist auf einfache Integration und Tests in Schweizer Geschäftsanwendungen ausgelegt.
Was diese Vorlage liefert
Die Vorlage definiert einen minimalen OpenAPI-3.0-API-Contract für gängige Kurierfunktionen. Enthalten sind: ein create-order-Endpoint mit Request/Response-Beispielen, zwei Webhook-Beispiele (order.updated, order.delivered) und ein Fehler-Schema mit standardisierten Codes. Ziel ist eine schnelle Anbindung von ERP-, WMS- oder Webshop-Systemen in der Schweiz.
Top-Level-Struktur (Kurzüberblick)
openapi: 3.0.3. Info mit Titel, Version und Kontakt. Serverliste mit Basis-URL für Staging und Produktion (z. B. https://api.x25pronto.ch). Komponenten für Schemas, SecuritySchemes (API-Key in Header) und standardisierte Responses. Pfade für POST /orders und POST /webhooks/listen.
Beispiel: create-order Request & Response
Request: JSON mit fields wie sender, recipient, package (gewicht, volumen), service (overnight|same-day), pickup_time. Response: orderId, status, estimatedPickupWindow. Beispielwerte erleichtern Tests und Mocks.
Beispiel: Webhook-Payloads
Webhook-Events liefern eventType, orderId, timestamp und eventData. Beispiele: order.updated (neuer Status wie 'in_transit') und order.delivered (mit signees und deliveredAt). Signaturheader (HMAC) zur Verifizierung wird empfohlen.
Fehlerbehandlung und Statuscodes
Standardisierte Fehlerantworten mit code, message und optional details. Empfohlene HTTP-Statuscodes: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 422 (Validation Error), 500 (Server Error). Payload-Beispiele unterstützen konsistente Fehlerlogs.
Integrationstipps für Schweizer Firmen
Nutzen Sie eine Staging-Umgebung. Testen Sie Webhooks mit Replay-Tools. Validieren Sie Adressformate für CH-Orte wie Zürich, Basel, Genf. Führen Sie HMAC-Signaturprüfungen auf Ihrem Server aus und loggen Sie Payloads sicher.
Häufige Fragen
Welche Authentifizierung nutzt die Vorlage?
Die Vorlage beschreibt einen einfachen API-Key im Header (x-api-key). Für höhere Sicherheit empfehlen wir HMAC-Signaturen für Webhooks und TLS für alle Endpunkte.
Wie teste ich Webhooks lokal?
Verwenden Sie Tools wie ngrok oder einen Relay-Service, um einen temporären öffentlichen Endpoint bereitzustellen. Achten Sie auf Replay-Tests und prüfen Sie Signaturheader.
Gibt es Beispielwerte für Paketdimensionen?
Ja. Die Beispiele enthalten gewicht in kg, length/width/height in cm und declaredValue in CHF. Nutzen Sie diese Werte als Mock-Daten für End-to-End-Tests.
Kann ich die Vorlage für Compliance-Anforderungen anpassen?
Ja. Ergänzen Sie zusätzliche Felder für Daten minimierung, Retention oder spezifische CH-Bestimmungen in Komponenten/Schemas. Die OpenAPI-Struktur bleibt kompatibel.