# ShaQ Express API Client cURL Reference This document provides sample **cURL** commands for the ShaQ Express Public API endpoints to assist with client-side integration. ## Environment Details - **Base URL:** `https://test-partner.shaqexpress.com/api/v1` - **Default Headers:** - `Content-Type: application/json` - `Accept: application/json` - `Authorization: Bearer ` --- ## 1. Login (`POST /auth/login`) Get an authentication token for subsequent requests. Tokens are valid for 7 days. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/auth/login" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "identifier": "your_identifier", "secret": "your_secret" }' ``` --- ## 2. Get Packages (`GET /packages`) Get all packages with pagination support. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/packages?page=1&limit=15" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 3. Get Single Package (`GET /packages/{partnerRef}`) Get details for a specific package by its partner reference ID. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/packages/FGVHKJ567" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 4. Create Single Package (`POST /packages`) Create a single package. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/packages" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d '{ "partner_ref": "UNIQUE-REF-001", "customer_name": "Kwaku Ananse", "customer_phone_1": "+233244100200", "source_address_line_1": "Accra Spintex", "destination_region": "Greater Accra", "destination_city": "Accra", "destination_address_line_1": "UPSA Hall, Room 3", "description": "iPhone 16 pro max black edge silver back casing", "units": 1, "type": "box", "handling": "normal", "value": 300.00, "amount_to_collect": 300.00, "items": [ { "name": "iPhone 6", "quantity": 1 }, { "name": "iPhone 14 Pro", "quantity": 2 } ] }' ``` --- ## 5. Create Packages in Bulk (`POST /packages/bulk`) Create multiple packages in a single API request. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/packages/bulk" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d '{ "packages": [ { "partner_ref": "UNIQUE-REF-001", "customer_name": "Kwaku Ananse", "customer_phone_1": "+233244100200", "source_address_line_1": "Accra Spintex", "destination_region": "Greater Accra", "destination_city": "Accra", "destination_address_line_1": "UPSA Hall, Room 3", "description": "iPhone 16 pro max black edge silver back casing", "units": 1, "type": "box", "handling": "normal", "value": 300.00, "amount_to_collect": 300.00, "items": [ { "name": "iPhone 6", "quantity": 1 }, { "name": "iPhone 14 Pro", "quantity": 2 } ] } ] }' ``` --- ## 6. Update Package (`PATCH /packages/{partnerRef}`) Update a specific package. Only include the fields you want to change. ```bash curl -X PATCH "https://test-partner.shaqexpress.com/api/v1/packages/FGVHKJ567" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d '{ "customer_name": "Updated Customer Name", "destination_city": "Kumasi", "value": 350.00, "items": [ { "name": "iPhone 16", "quantity": 1 } ] }' ``` --- ## 7. Delete Pending Package (`DELETE /packages/{partnerRef}`) Delete a package. Only packages with `pending` status can be deleted. ```bash curl -X DELETE "https://test-partner.shaqexpress.com/api/v1/packages/FGVHKJ567" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 8. Cancel Order (`POST /packages/{partnerRef}/cancel`) Cancel a fulfillment order. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/packages/FGVHKJ567/cancel" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 9. Create Package Replacement (`POST /packages/replacement`) Create one or two packages to replace an existing package. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/packages/replacement" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d '{ "rule": "return_deliver", "packages": [ { "action": "deliver", "partner_ref": "GH945214", "customer_name": "Derrick Nti", "customer_phone_1": "+233549632604", "source_country_iso2": "GH", "source_address_line_1": "21 Abiriw Street", "destination_country_iso2": "GH", "destination_region": "Greater Accra", "destination_city": "Kwashieman", "destination_address_line_1": "23 Abiriw Street", "description": "Replacement delivery package", "units": 1, "type": "box", "value": 20.00, "handling": "normal", "items": [ { "name": "Bluetooth", "quantity": 3 } ] }, { "action": "return", "partner_ref": "GH545728", "customer_name": "Kwabena Azaglo", "customer_phone_1": "+233549632604", "source_country_iso2": "GH", "source_address_line_1": "21 Abiriw Street", "destination_country_iso2": "GH", "destination_region": "Greater Accra", "destination_city": "Kwashieman", "destination_address_line_1": "23 Abiriw Street", "description": "Return package", "units": 1, "type": "box", "value": 20.00, "handling": "normal", "items": [ { "name": "Bluetooth", "quantity": 3 } ] } ] }' ``` --- ## 10. Get Package Label (`GET /packages/{partnerRef}/print-label`) Retrieve the shipping label (PDF) for a specific package. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/packages/FGVHKJ567/print-label" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 11. Create Shipment (`POST /shipments`) Create a shipment representing the physical shipment of packages to ShaQ Express. ```bash curl -X POST "https://test-partner.shaqexpress.com/api/v1/shipments" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -d '{ "packages": [ { "partner_ref": "SHIP-REF-001", "customer_name": "Hema Mirpuri", "customer_phone_1": "+233244601165", "source_address_line_1": "Accra spintex basket junction", "destination_region": "Greater Accra", "destination_city": "Tesano", "destination_address_line_1": "OPP total filling station Abeka tesano", "description": "Color Splicing Cotton Rope Storage Basket", "units": 7, "type": "parcel", "handling": "normal", "value": 1468.00, "amount_to_collect": 1468.00, "items": [ { "name": "14cm Alya Glass Cookie Holder - Transparent", "quantity": 4 }, { "name": "Cotton Rope Storage Basket AB-026", "quantity": 1 }, { "name": "6 Pieces Nossa 21cm Cake Plate Set", "quantity": 1 } ] } ] }' ``` --- ## 12. Get Single Shipment (`GET /shipments/{reference}`) Get details of a specific shipment including all packages. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/shipments/PAR-20260322053800" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 13. Track Package (`GET /tracking/{trackingNumber}`) Retrieve tracking history and status updates using a package's tracking number. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/tracking/20250410X51DIQ" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ``` --- ## 14. Get Regions (`GET /setup/regions`) Get all allowable regions. Use the returned `id` values for the `region_id` field when creating packages. ```bash curl -X GET "https://test-partner.shaqexpress.com/api/v1/setup/regions" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" ```