# OpenAPI-Spezifikation und Beispiel-Schemas für Kurier-APIs

Canonical: https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html

VW Tiguan R · 320 PS 4MOTION · diskret · direkt unterwegs

EXPRESS KURIER · DIREKT · MO–SO

Kurierdienst Schweiz.
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.

[Preis berechnen](https://x25pronto.ch/de/#quote)[So funktioniert Overnight](https://x25pronto.ch/de/overnight.html)

Direktfahrt Mo–So Overnight Mo–So Auto & Transporter bis 1’000 kg

KURIERWISSEN

# 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.

25. September 2026

## 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.

## Kurierfahrt in der Schweiz planen

x25pronto Schweiz fährt kleine und gut verpackte Sendungen mit dem Auto. Firmen können eine direkte Kurierfahrt oder Overnight wählen. Strecke, Termin und Sendung lassen sich vor der Buchung online erfassen. Danach sehen Sie den Richtpreis für die geplante Kurier-Buchung.

[Direktkurier →](https://x25pronto.ch/de/direktkurier.html)[Overnight →](https://x25pronto.ch/de/overnight.html)[Leistungen →](https://x25pronto.ch/de/leistungen.html)[Richtpreis berechnen →](https://x25pronto.ch/de/#quote)

### Kurz erklärt: OpenAPI-Spezifikation und Beispiel-Schemas für Kurier-APIs

Die wichtigsten Punkte aus diesem Beitrag. Über die Links gelangen Sie direkt zur Erklärung.

Was diese Vorlage liefert Die Vorlage definiert einen minimalen OpenAPI-3.0-API-Contract für gängige Kurierfunktionen. [Im Beitrag lesen](https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-1)

Top-Level-Struktur (Kurzüberblick) Info mit Titel, Version und Kontakt. [Im Beitrag lesen](https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-2)

Beispiel: create-order Request & Response Request: JSON mit fields wie sender, recipient, package (gewicht, volumen), service (overnight|same-day), pickup_time. [Im Beitrag lesen](https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-3)

Beispiel: Webhook-Payloads Webhook-Events liefern eventType, orderId, timestamp und eventData. [Im Beitrag lesen](https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-4)

Fehlerbehandlung und Statuscodes Standardisierte Fehlerantworten mit code, message und optional details. [Im Beitrag lesen](https://x25pronto.ch/de/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-5)

Weiterlesen zum Thema Prüfen Sie die passende Fahrtart für Ihre Sendung. [Direktfahrt oder Overnight](https://x25pronto.ch/de/direktkurier-oder-overnight.html)