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