{ "info": { "name": "Qapla' Courier Events API v1.0", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": "Inbound tracking events, from a courier to Qapla'.\nSpecification: https://api.qapla.dev/courier-events/\n\nSETUP — two variables, both intentionally empty:\n endpoint_host the host of your endpoint, without https://. We assign it to you at\n onboarding; it is not a shared public hostname.\n token the bearer token we issue for your courier code.\n\nSet both under the collection's Variables tab, then run GET /v1/ping first.\n\nThe optional payload signature (X-Qapla-Signature) is NOT part of this collection: it\nis an HMAC-SHA256 that has to be computed per request, which a static collection\ncannot do. Requests here authenticate with the bearer token alone, which is what the\nendpoint accepts when the header is absent. See the specification for the signature.\n\nGenerated from the example payloads in the documentation — do not edit by hand, and do\nnot re-export this file after filling in your own values.\nSchema version 1.0." }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{token}}", "type": "string" } ] }, "variable": [ { "key": "endpoint_host", "value": "", "type": "string", "description": "The host of your endpoint, without https://. Assigned at onboarding." }, { "key": "token", "value": "", "type": "string", "description": "Your bearer token, for the environment you are calling." } ], "item": [ { "name": "GET /v1/ping", "request": { "method": "GET", "header": [], "url": { "raw": "https://{{endpoint_host}}/v1/ping", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "ping" ] }, "description": "Start here. Confirms the URL is reachable and the token is valid, and answers with the\ncourier code we know you by, the environment you are talking to, and the schema versions\nwe accept. Nothing is sent and nothing is stored." }, "response": [] }, { "name": "POST /v1/events/validate", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "Validates a payload against the schema and stores nothing. Same authentication and same\npayload as /v1/events, and it answers with the same results[]. This is the endpoint to\ndevelop against, and it is safe to keep in your CI as a payload regression test.\n\nBody: the 01-minimal example.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"d7c2f843-2c4e-42b2-91f1-bd9c05b5a678\",\n \"sentAt\": \"2026-08-24T10:30:05Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-ABC123456789-000042\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-24T10:28:00+02:00\",\n \"status\": {\n \"code\": \"23\",\n \"description\": \"In transit at sorting centre\"\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "POST /v1/events", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events" ] }, "description": "The real ingestion endpoint. It answers 404 until we activate it for your courier code,\nso expect a 404 here until onboarding is complete — that is not a misconfiguration on\nyour side.\n\nBody: the 01-minimal example.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"d7c2f843-2c4e-42b2-91f1-bd9c05b5a678\",\n \"sentAt\": \"2026-08-24T10:30:05Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-ABC123456789-000042\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-24T10:28:00+02:00\",\n \"status\": {\n \"code\": \"23\",\n \"description\": \"In transit at sorting centre\"\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "Payload examples (validate)", "description": "Every example payload from the documentation, ready to run against\n/v1/events/validate. Generated from courier-events/resources/examples/ — if one of\nthese fails to validate, the bug is ours, not yours: write to tech@qapla.it.", "item": [ { "name": "02 full history batch", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "The 02-full-history-batch example, sent to /v1/events/validate so it can be run without\nstoring anything.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"0f8fad5b-d9cb-469f-a165-70867728950e\",\n \"sentAt\": \"2026-08-24T18:05:00Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-ABC123456789-000040\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-23T17:40:00+02:00\",\n \"status\": {\n \"code\": \"11\",\n \"description\": \"Collected from sender\"\n },\n \"location\": {\n \"name\": \"Bergamo\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"24125\"\n },\n \"parcel\": {\n \"trackingNumber\": \"ABC123456789-1\",\n \"index\": 1,\n \"total\": 2\n },\n \"delivery\": {\n \"estimatedDeliveryDate\": \"2026-08-26\"\n }\n },\n {\n \"eventId\": \"ACME-ABC123456789-000042\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-24T10:28:00+02:00\",\n \"status\": {\n \"code\": \"23\",\n \"description\": \"In transit at sorting centre\"\n },\n \"location\": {\n \"name\": \"Milano Roserio\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"20157\"\n }\n },\n {\n \"eventId\": \"ACME-ABC123456789-000047\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-24T15:12:00+02:00\",\n \"status\": {\n \"code\": \"41\",\n \"description\": \"Out for delivery\"\n },\n \"location\": {\n \"name\": \"Milano\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"20121\"\n },\n \"delivery\": {\n \"estimatedDeliveryWindow\": {\n \"from\": \"2026-08-24T15:00:00+02:00\",\n \"to\": \"2026-08-24T19:00:00+02:00\"\n },\n \"attemptNumber\": 1\n },\n \"recipientActionUrl\": \"https://tracking.acme-express.example/manage?t=ABC123456789\",\n \"attributes\": {\n \"driverId\": \"MI-4471\",\n \"routeId\": \"R-20260824-88\"\n }\n },\n {\n \"eventId\": \"ACME-ABC123456789-000051\",\n \"trackingNumber\": \"ABC123456789\",\n \"occurredAt\": \"2026-08-24T17:55:00+02:00\",\n \"status\": {\n \"code\": \"50\",\n \"description\": \"Delivered to recipient\"\n },\n \"location\": {\n \"name\": \"Milano\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"20121\"\n },\n \"delivery\": {\n \"deliveredTo\": \"RECIPIENT\",\n \"signedBy\": \"M. Rossi\",\n \"podUrl\": \"https://api.acme-express.example/pod/ABC123456789.pdf\",\n \"attemptNumber\": 1\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "03 failed attempt and pickup point", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "The 03-failed-attempt-and-pickup-point example, sent to /v1/events/validate so it can be run without\nstoring anything.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"9c858901-8a57-4791-81fe-4c455b099bc9\",\n \"sentAt\": \"2026-08-24T19:00:00Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-XYZ987654321-000018\",\n \"trackingNumber\": \"XYZ987654321\",\n \"occurredAt\": \"2026-08-24T14:20:00+02:00\",\n \"status\": {\n \"code\": \"62\",\n \"description\": \"Delivery attempt failed\"\n },\n \"location\": {\n \"name\": \"Torino\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"10121\"\n },\n \"reason\": {\n \"code\": \"ABS\",\n \"description\": \"Recipient not at home\"\n },\n \"delivery\": {\n \"attemptNumber\": 1\n },\n \"recipientActionUrl\": \"https://tracking.acme-express.example/manage?t=XYZ987654321\"\n },\n {\n \"eventId\": \"ACME-XYZ987654321-000019\",\n \"trackingNumber\": \"XYZ987654321\",\n \"occurredAt\": \"2026-08-24T16:05:00+02:00\",\n \"status\": {\n \"code\": \"71\",\n \"description\": \"Available for collection at pickup point\"\n },\n \"location\": {\n \"name\": \"Torino\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"10121\"\n },\n \"delivery\": {\n \"deliveredTo\": \"PICKUP_POINT\"\n },\n \"pickupPoint\": {\n \"id\": \"PT-10121-004\",\n \"name\": \"Acme Point — Via Roma 12\",\n \"address\": \"Via Roma 12, Torino\",\n \"postalCode\": \"10121\",\n \"countryCode\": \"IT\",\n \"availableUntil\": \"2026-09-03T19:00:00+02:00\"\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "04 tracking number change", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "The 04-tracking-number-change example, sent to /v1/events/validate so it can be run without\nstoring anything.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"sentAt\": \"2026-08-24T09:05:00Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-PARCEL-778899-000001\",\n \"trackingNumber\": \"PARCEL-778899\",\n \"occurredAt\": \"2026-08-24T11:02:00+02:00\",\n \"status\": {\n \"code\": \"11\",\n \"description\": \"Consignment accepted\"\n },\n \"trackingNumberChange\": {\n \"newTrackingNumber\": \"ABC123456789\",\n \"reason\": \"definitive tracking number assigned\"\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "05 return shipment", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "The 05-return-shipment example, sent to /v1/events/validate so it can be run without\nstoring anything.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"b3d2f1a0-6c7d-4e8f-9a0b-1c2d3e4f5a6b\",\n \"sentAt\": \"2026-08-24T08:00:00Z\",\n \"courier\": \"ACME_EXPRESS\",\n \"events\": [\n {\n \"eventId\": \"ACME-RET556677-000003\",\n \"trackingNumber\": \"RET556677\",\n \"occurredAt\": \"2026-08-23T16:30:00+02:00\",\n \"status\": {\n \"code\": \"R23\",\n \"description\": \"Return in transit to sender\"\n },\n \"location\": {\n \"name\": \"Bologna\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"40100\"\n },\n \"isReturn\": true\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] }, { "name": "06 external id only", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "https://{{endpoint_host}}/v1/events/validate", "protocol": "https", "host": [ "{{endpoint_host}}" ], "path": [ "v1", "events", "validate" ] }, "description": "The 06-external-id-only example, sent to /v1/events/validate so it can be run without\nstoring anything.", "body": { "mode": "raw", "raw": "{\n \"schemaVersion\": \"1.0\",\n \"messageId\": \"5b1e5f2c-1d4a-4b8e-9f30-7a2c6d9e4411\",\n \"sentAt\": \"2026-08-24T07:20:00Z\",\n \"courier\": \"OTHER_COURIER\",\n \"events\": [\n {\n \"eventId\": \"OC-ORD-2026-55123-000004\",\n \"externalId\": \"ORD-2026-55123\",\n \"senderAccount\": \"IT-4417329\",\n \"occurredAt\": \"2026-08-24T09:14:00+02:00\",\n \"status\": {\n \"code\": \"TRN\",\n \"description\": \"In transit\"\n },\n \"location\": {\n \"name\": \"Firenze\",\n \"countryCode\": \"IT\",\n \"postalCode\": \"50100\"\n }\n },\n {\n \"eventId\": \"OC-ORD-2026-55124-000009\",\n \"trackingNumber\": \"ABC123456790\",\n \"externalId\": \"ORD-2026-55124\",\n \"senderAccount\": \"IT-4417329\",\n \"occurredAt\": \"2026-08-24T09:31:00+02:00\",\n \"status\": {\n \"code\": \"DLV\",\n \"description\": \"Delivered to recipient\"\n },\n \"delivery\": {\n \"deliveredTo\": \"RECIPIENT\",\n \"signedBy\": \"L. Bianchi\",\n \"attemptNumber\": 1\n }\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [] } ] } ] }