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.
Interfaces & Reporting: API Specs for Courier Pilots
A compact technical checklist for tracking APIs, webhooks and reporting during a Swiss courier pilot. Focus on events, JSON formats and security.
Quick answer
This checklist defines minimum API requirements for a courier pilot. It helps IT teams in Zurich, Geneva or Lausanne to validate tracking APIs, webhooks and reporting for rapid integration.
Scope and objective
This technical checklist sets interface and reporting requirements for a courier pilot. It covers tracking, status events, webhooks, data formats and basic security for approved shipments carried in passenger cars.
Core API capabilities
A pilot API should provide: authentication (API key or OAuth2), endpoints to create/update shipments, status retrieval, live position updates, and an event history. Responses must use standard HTTP status codes and clear error messages.
Tracking events and status model
Use a compact, explicit status model such as created, picked_up, in_transit, out_for_delivery, delivered, exception, cancelled. Each event needs an ISO‑8601 timestamp, location (lat/lon), optional driver_id and document/photo URLs. Ensure event ordering is traceable.
Webhook design and retry policy
Webhooks are required for live updates. Requirements: JSON payloads, HMAC signature header, unique event_id, idempotent handling and 2xx acceptance codes. Define a retry policy: exponential backoff with about 5 retries within 24 hours. Provide a handshake test event.
Data formats and field definitions
Use JSON as the primary format. Mandatory fields: shipment_id, external_reference, status, timestamp, location {lat, lon, accuracy}, estimated_delivery_window. Optional: recipient_signature, photo_urls, vehicle_type. Specify field lengths and allowed values.
Error and exception handling
Document error codes and causes, e.g. invalid_location, missing_mandatory_field, auth_failed. For exceptions like failed delivery, the webhook should include next_steps guidance. Keep logs of events for at least 30 days for debugging.
Frequently asked questions
Which authentication should we use?
A rotating API key is sufficient for pilots. For production, prefer OAuth2 with short‑lived tokens. Protect webhooks with HMAC signatures.
How precise should position data be?
Provide lat/lon plus an accuracy field in metres. For urban courier runs, 5–20 m horizontal accuracy is usually adequate.
How to test webhooks before the pilot?
Send signed test events to a staging endpoint. Verify idempotency, retry handling and HMAC verification. Include replayable test IDs.
What reporting intervals make sense?
For live tracking, send position updates every 30–120 seconds during active movement. Send status event pushes for each status change.