{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/pudo.2pointapp.com" } ], "info": { "name": "PUDO API \u2013 Developer Documentation", "_postman_id": "2a4dc293-9485-4935-9518-c9e52a4a93d6", "description": "A standalone Pick Up Drop Off (PUDO) platform integration API. Connect your courier, e-commerce, or logistics system directly to our network of local drop-off points.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "PUDO Points", "description": "", "item": [ { "name": "List All PUDO points", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/pudo-points\/all", "query": [ { "key": "branch_ref", "value": "accra-main", "description": "Filter by branch reference.", "disabled": false }, { "key": "cold_storage", "value": "1", "description": "Filter by cold storage availability.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/pudo-points\/all?branch_ref=accra-main&cold_storage=1" }, "method": "GET", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Find all active PUDO points. Use query parameters to filter by branch or cold storage availability." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Shell Station East Legon\",\n \"address\": \"Boundary Road, Accra\",\n \"lat\": \"5.63410000\",\n \"lng\": \"-0.15230000\",\n \"has_cold_storage\": true,\n \"currency\": \"GHS\",\n \"price\": 5.00,\n \"operating_hours\": {\n \"mon\": \"08:00-20:00\",\n \"tue\": \"08:00-20:00\",\n }\n }\n]", "name": "" } ] }, { "name": "List Nearby PUDO points", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/pudo-points", "query": [ { "key": "lat", "value": "5.6037", "description": "Latitude of the search center.", "disabled": false }, { "key": "lng", "value": "-0.187", "description": "Longitude of the search center.", "disabled": false }, { "key": "radius", "value": "25", "description": "Search radius in KM. Default: 10.", "disabled": false }, { "key": "branch_ref", "value": "accra-main", "description": "Filter by branch reference.", "disabled": false }, { "key": "cold_storage", "value": "1", "description": "Filter by cold storage availability.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/pudo-points?lat=5.6037&lng=-0.187&radius=25&branch_ref=accra-main&cold_storage=1" }, "method": "GET", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Find active PUDO points near a location or within a branch." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Shell Station East Legon\",\n \"address\": \"Boundary Road, Accra\",\n \"lat\": \"5.63410000\",\n \"lng\": \"-0.15230000\",\n \"distance\": 2.4,\n \"has_cold_storage\": true\n \"currency\": \"GHS\",\n \"price\": 5.00\n }\n ]\n}", "name": "" } ] }, { "name": "Get PUDO point details", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/pudo-points\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/pudo-points\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The ID of the PUDO point." } ] }, "method": "GET", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [ { "key": "cache-control", "value": "no-cache, private" }, { "key": "content-type", "value": "application\/json" }, { "key": "access-control-allow-origin", "value": "*" } ], "code": 401, "body": "{\"message\":\"Invalid API key\"}", "name": "" } ] } ] }, { "name": "Packages", "description": "", "item": [ { "name": "List packages", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/packages", "query": [ { "key": "status", "value": "ready", "description": "Filter by package status (e.g., pending, dropped, ready, picked_up).", "disabled": false }, { "key": "limit", "value": "10", "description": "Limit the number of results. Default: 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/packages?status=ready&limit=10" }, "method": "GET", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve packages that have been ingested into the PUDO system by your integration." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"data\": {\n \"current_page\": 1,\n \"data\": [\n {\n \"id\": 1,\n \"tracking_number\": \"PUDO-12345678\",\n \"external_booking_ref\": \"BK-9921\",\n \"pudo_point_id\": 1,\n \"customer_name\": \"John Doe\",\n \"status\": \"pending\",\n \"payment_status\": \"unpaid\",\n \"created_at\": \"2024-03-08T10:00:00.000000Z\"\n }\n ],\n \"total\": 1\n }\n}", "name": "" } ] }, { "name": "Get package details", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/packages\/:tracking_number", "query": [], "raw": "{{baseUrl}}\/api\/v1\/packages\/:tracking_number", "variable": [ { "id": "tracking_number", "key": "tracking_number", "value": "PUDO-12345678", "description": "The PUDO tracking number of the package." } ] }, "method": "GET", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Retrieve the details and statuses for a specific package using its tracking number." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"data\": {\n \"id\": 1,\n \"tracking_number\": \"PUDO-12345678\",\n \"external_booking_ref\": \"BK-9921\",\n \"pudo_point_id\": 1,\n \"customer_name\": \"John Doe\",\n \"status\": \"pending\",\n \"payment_status\": \"unpaid\",\n \"created_at\": \"2024-03-08T10:00:00.000000Z\"\n }\n}", "name": "" }, { "header": [], "code": 404, "body": "{\n \"status\": \"error\",\n \"message\": \"Package not found.\"\n}", "name": "" } ] }, { "name": "Ingest a new package", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/packages\/ingest", "query": [], "raw": "{{baseUrl}}\/api\/v1\/packages\/ingest" }, "method": "POST", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"pudo_point_id\":1,\"external_booking_ref\":\"BK-9921\",\"customer_name\":\"John Doe\",\"customer_email\":\"john@example.com\",\"customer_phone\":\"+233240000000\",\"cold_storage\":false,\"notes\":\"Fragile electronics\",\"payment_status\":\"unpaid\",\"payment_method\":\"cod\",\"amount_to_collect\":\"15.50\"}" }, "description": "Submit a package from your system to a PUDO point.\nThe package will start in 'pending' status." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Package ingested successfully\",\n \"data\": {\n \"tracking_number\": \"PUDO-12345678\",\n \"status\": \"pending\"\n }\n}", "name": "" } ] } ] }, { "name": "Webhooks", "description": "", "item": [ { "name": "Register Webhook", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/register", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/register" }, "method": "POST", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"webhook_url\":\"https:\\\/\\\/api.mycompany.com\\\/pudo\\\/webhook\"}" }, "description": "Register a URL to receive status updates when a package status changes.\nWe will POST to this URL with an HMAC signature." }, "response": [ { "header": [], "code": 200, "body": "{\n \"status\": \"success\",\n \"message\": \"Webhook registered successfully\",\n \"data\": {\n \"webhook_url\": \"https:\/\/api.mycompany.com\/pudo\/webhook\"\n }\n}", "name": "" } ] }, { "name": "Handle incoming status webhooks from 2PointLogistics.", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/webhooks\/logistics\/status", "query": [], "raw": "{{baseUrl}}\/api\/v1\/webhooks\/logistics\/status" }, "method": "POST", "header": [ { "key": "X-PUDO-Timestamp", "value": "required Current Unix timestamp in seconds. Example: 1709845200" }, { "key": "X-PUDO-Signature", "value": "required HMAC-SHA256(timestamp + raw_body, api_secret). Example: a3f5c2..." }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"event\":\"architecto\",\"tracking_number\":\"architecto\",\"status\":\"architecto\",\"eta_to_pickup_minutes\":16,\"eta_to_dropoff_minutes\":16}" }, "description": "" }, "response": [] } ] } ], "auth": { "type": "apikey", "apikey": [ { "key": "in", "value": "header", "type": "string" }, { "key": "key", "value": "X-PUDO-Key", "type": "string" } ] } }