# OpenAPI specification and example schemas for courier APIs

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

VW Tiguan R · 320 PS 4MOTION · discreet · direct

EXPRESS COURIER · DIRECT · MON–SUN

Courier service Switzerland.
Express courier. Direct.
Also overnight.

x25pronto Switzerland takes goods direct to the destination. Small loads go by car. Larger loads go by van or Van XL. Direct, express and overnight trips run Monday to Sunday when a slot is free. Free times are shown in the booking calendar. This keeps the plan clear.

[Calculate price](https://x25pronto.ch/en/#quote)[How overnight works](https://x25pronto.ch/en/overnight.html)

Direct Mon–Sun Overnight Mon–Sun Car & van up to 1,000 kg

COURIER INSIGHTS

# OpenAPI specification and example schemas for courier APIs

Ready-to-use OpenAPI template with example create-order requests, webhook payloads and error responses. Designed for easy integration and testing in Switzerland.

25 September 2026

## Quick answer

Below is a compact OpenAPI template with example requests and responses for create-order, typical webhook payloads and standardized error responses. It is designed for quick integration and testing with Swiss business systems.

## What this template provides

The template defines a minimal OpenAPI 3.0 contract for common courier actions. It includes: a create-order endpoint with request/response examples, two webhook examples (order.updated, order.delivered) and an error schema with standard codes. It helps integrate ERP, WMS or webshop systems in Switzerland.

## Top-level structure (overview)

openapi: 3.0.3. Info block with title, version and contact. Servers array with base URLs for staging and production (e.g. https://api.x25pronto.ch). Components for schemas, securitySchemes (API-Key header) and common responses. Paths for POST /orders and POST /webhooks/listen.

## Example: create-order request & response

Request: JSON with sender, recipient, package (weight, volume), service (overnight|same-day), pickup_time. Response: orderId, status, estimatedPickupWindow. Concrete example values help tests and mocks.

## Example: webhook payloads

Webhook events deliver eventType, orderId, timestamp and eventData. Examples: order.updated (status like 'in_transit') and order.delivered (includes signee and deliveredAt). Use a signature header (HMAC) for verification.

## Error handling and status codes

Standardized error responses include code, message and optional details. Recommended HTTP status codes: 400, 401, 404, 422, 500. Example payloads make error handling consistent across systems.

## Integration tips for Swiss companies

Use a staging environment. Test webhooks with replay tools. Validate address formats for CH cities like Zurich, Basel, Geneva. Verify HMAC signatures on your server and log payloads securely.

## Frequently asked questions

Which authentication does the template use? The template uses a simple API-Key in the header (x-api-key). For stronger security, use HMAC signatures for webhooks and TLS for all endpoints.

How do I test webhooks locally? Use tools like ngrok or a relay service to expose a temporary public endpoint. Run replay tests and validate the signature headers.

Are there example package dimensions? Yes. The examples include weight in kg, length/width/height in cm and declaredValue in CHF. Use these values as mock data for end-to-end tests.

Can I extend the template for compliance? Yes. Add fields for data minimisation, retention or specific Swiss rules in the components/schemas. The OpenAPI structure stays compatible.

## Plan a courier trip in Switzerland

x25pronto Switzerland carries small and well packed shipments by car. Businesses can choose a direct courier trip or overnight service. Route, timing and shipment details can be entered online before booking. The guide price is then shown for the planned courier order.

[Direct courier →](https://x25pronto.ch/en/direct-courier.html)[Overnight →](https://x25pronto.ch/en/overnight.html)[Services →](https://x25pronto.ch/en/services.html)[Calculate guide price →](https://x25pronto.ch/en/#quote)

### At a glance: OpenAPI specification and example schemas for courier APIs

Key points from this article. Follow the links to read each explanation.

What this template provides The template defines a minimal OpenAPI 3.0 contract for common courier actions. [Read this section](https://x25pronto.ch/en/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-1)

Top-level structure (overview) Info block with title, version and contact. [Read this section](https://x25pronto.ch/en/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-2)

Example: create-order request & response Request: JSON with sender, recipient, package (weight, volume), service (overnight|same-day), pickup_time. [Read this section](https://x25pronto.ch/en/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-3)

Example: webhook payloads Webhook events deliver eventType, orderId, timestamp and eventData. [Read this section](https://x25pronto.ch/en/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-4)

Error handling and status codes Standardized error responses include code, message and optional details. [Read this section](https://x25pronto.ch/en/blog/openapi-spezifikation-und-beispiel-schemas-fur-kurier-apis.html#courier-article-step-5)

More on this topic Check which service suits your shipment. [Direct or overnight](https://x25pronto.ch/en/direct-courier-vs-overnight.html)