{"info":{"_postman_id":"ad7585be-eedf-45a2-879f-469e79c2a362","name":"Generic Courier API Integration","description":"

Picup supports generic courier integration endpoints for interfacing with other ERP/WMS or courier software.

\n

The generalised process is as follows:

\n
    \n
  1. Create shipment via the Create Shipment method
    2. \n
  2. Indicate success or failure via synchronous response
    3. \n
  3. Update on Order state via generic webhook structure
    4. \n
\n\n

Authentication

\nWe support two authentication methods here.\nIn both of the below cases, authentication details will be passed as HTTP headers.\n
\n
API KEY
\nApi-Key via a key:value pair structure.\nBoth the key and the value can be set as custom.
\nEg. \"api-key\": \"ABC123\" or \"apikey\": \"ABC123\"\n\n
Username and Password
\nStandard basic type (Basic: \"username:password\") authentication.
\nEg.Basic: \"picuppete:picup123\"\n\n

Tracking and Order Updates

\nTracking and order updates are to be sent via generic webhook structure.\nDetails can be found here","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"Tracking and Order Updates","slug":"tracking-and-order-updates"}],"owner":"4577361","collectionId":"ad7585be-eedf-45a2-879f-469e79c2a362","publishedId":"TzRUBSrP","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-05-12T13:15:01.000Z"},"item":[{"name":"Create Shipment","id":"1e20aba1-bc87-454f-aff4-446b19365b6b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_request\": {\n \"bucket_details\": {\n \"delivery_date\": \"2021-05-18T00:00:00\", // Intended Collection Date\n \"shift_start\": \"09:00:00\" // Intended Colletion Time\n },\n \"shipments\": [\n {\n \"waybill_number\": \"PCW000723842\", // Unique Order Identifier, to be used as primary order key\n \"business_reference\": \"#2804\", // Client customer identifier - May be non unique. Show on waybill if possible.\n \"service_type\": \"ONX\",\n \"sender\": { // Details for the collection contact\n \"address\": {\n \"address_line_1\": \"63 Peter Place\",\n \"address_line_2\": \"Bryanston\",\n \"address_line_3\": \"Sandton\",\n \"address_line_4\": \"2191\",\n \"formatted_address\": \"63 Peter Place, Bryanston, Sandton, 2191, South Africa\",\n \"latitude\": -26.08123,\n \"longitude\": 28.02736,\n \"postal_code\": \"2191\",\n \"suburb\": \"Bryanston\",\n \"unit\": \"Unit 33\",\n \"building\": \"De Velde Block 4\"\n },\n \"contact\": {\n \"customer_name\": \"Warehouse Manager Dave\",\n \"customer_phone\": \"086 999 0393\",\n \"email_address\": \"info@picup.co.za\"\n }\n },\n \"receiver\": { // Details for the delivery contact\n \"parcels\": [\n {\n \"parcel_waybill\": \"PCW000723842_1\", // Unique Parcel Identifier, to be used as primary parcel key\n \"parcel_reference\": \"#2804.1\",\n \"tracking_number\": \"#2804.1\",\n \"length_mm\": 20,\n \"width_mm\": 20,\n \"height_mm\": 20,\n \"weight_kg\": 2\n }\n ],\n \"address\": {\n \"address_line_1\": \"293 Moduba Cres\",\n \"address_line_2\": \"Marapong\",\n \"address_line_3\": \"Lephalale\",\n \"address_line_4\": \"0556\",\n \"city\": \"Lephalale\",\n \"formatted_address\": \"293 Moduba Cres, Marapong, Lephalale, 0556, South Africa\",\n \"latitude\": -23.65739,\n \"longitude\": 27.6236,\n \"postal_code\": \"0556\",\n \"suburb\": \"Marapong\"\n },\n \"contact\": {\n \"customer_name\": \"John Doe\",\n \"customer_phone\": \"0831234567\",\n \"email_address\": \"cleintemail@gmail.com\",\n \"special_instructions\": \"Please call when outside\"\n }\n }\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-request","description":"

NB: Primary Identifier/Courier Reference

\nWhen it comes to creating primary identifiers, it is preferred that the integration party consumes the supplied waybill_number(eg. PCW00001). This assists clients with linking orders across multiple systems.\n\n

If however, this is not possible, we will create a mapping based on the responses received in the /create-shipment call.

\n

This courier_reference will need to be used as the primary key in all future order updates.

\n","urlObject":{"protocol":"https","path":["example-request"],"host":["your-url","com"],"query":[],"variable":[]}},"response":[{"id":"0834f100-3858-4daf-8e37-17dd9f11a405","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_request\": {\n \"bucket_details\": {\n \"delivery_date\": \"2021-05-18T00:00:00\" // Intended Collection Date\n },\n \"shipments\": [\n {\n \"waybill_number\": \"PCW000723842\", // Unique Order Identifier, to be used as primary order key\n \"business_reference\": \"#2804\", // Client customer identifier - May be non unique. Show on waybill if possible.\n \"service_type\": \"ONX\",\n \"sender\": { // Details for the collection contact\n \"address\": {\n \"address_line_1\": \"63 Peter Place\",\n \"address_line_2\": \"Bryanston\",\n \"address_line_3\": \"Sandton\",\n \"address_line_4\": \"2191\",\n \"formatted_address\": \"63 Peter Place, Bryanston, Sandton, 2191, South Africa\",\n \"latitude\": -26.08123,\n \"longitude\": 28.02736,\n \"postal_code\": \"2191\",\n \"suburb\": \"Bryanston\",\n \"unit\": \"Unit 33\",\n \"building\": \"De Velde Block 4\"\n },\n \"contact\": {\n \"customer_name\": \"Warehouse Manager Dave\",\n \"customer_phone\": \"086 999 0393\",\n \"email_address\": \"info@picup.co.za\"\n }\n },\n \"receiver\": { // Details for the delivery contact\n \"parcels\": [\n {\n \"parcel_waybill\": \"PCW000723842_1\", // Unique Parcel Identifier, to be used as primary parcel key\n \"parcel_reference\": \"#2804.1\",\n \"tracking_number\": \"#2804.1\",\n \"length_mm\": 20,\n \"width_mm\": 20,\n \"height_mm\": 20,\n \"weight_kg\": 2\n }\n ],\n \"address\": {\n \"address_line_1\": \"293 Moduba Cres\",\n \"address_line_2\": \"Marapong\",\n \"address_line_3\": \"Lephalale\",\n \"address_line_4\": \"0556\",\n \"city\": \"Lephalale\",\n \"formatted_address\": \"293 Moduba Cres, Marapong, Lephalale, 0556, South Africa\",\n \"latitude\": -23.65739,\n \"longitude\": 27.6236,\n \"postal_code\": \"0556\",\n \"suburb\": \"Marapong\"\n },\n \"contact\": {\n \"customer_name\": \"John Doe\",\n \"customer_phone\": \"0831234567\",\n \"email_address\": \"cleintemail@gmail.com\",\n \"special_instructions\": \"Please call when outside\"\n }\n }\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example-url.com/example-request"},"code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{ \n \"is_success\":true,\n \"courier_reference\":\"PCW000723842\", // If custom identifier is supported, this will read the same as the \"waybill_number\" specified in request. If not, we will use this as identifier for status tracking\n \"courier_code\": \"PIC\",\n \"additional_waybill_meta\": \"Route Code: D1 Vehicle Code: 12\", // Should operational teams need extra waybill content, this string will be printed on the Picup Waybill\n \"waybill_img_url\": \"https://waybillurl.com/waybill.jpg\" // A link to the waybill physical image (PNG/JPG/PDF supported) for client download\n}"},{"id":"7b8f5d68-2ed9-497b-ad94-e7525d00655b","name":"Failure","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_request\": {\n \"bucket_details\": {\n \"delivery_date\": \"2021-05-18T00:00:00\" // Intended Collection Date\n },\n \"shipments\": [\n {\n \"waybill_number\": \"PCW000723842\", // Unique Order Identifier, to be used as primary order key\n \"business_reference\": \"#2804\", // Client customer identifier - May be non unique. Show on waybill if possible.\n \"service_type\": \"ONX\",\n \"sender\": { // Details for the collection contact\n \"address\": {\n \"address_line_1\": \"63 Peter Place\",\n \"address_line_2\": \"Bryanston\",\n \"address_line_3\": \"Sandton\",\n \"address_line_4\": \"2191\",\n \"formatted_address\": \"63 Peter Place, Bryanston, Sandton, 2191, South Africa\",\n \"latitude\": -26.08123,\n \"longitude\": 28.02736,\n \"postal_code\": \"2191\",\n \"suburb\": \"Bryanston\",\n \"unit\": \"Unit 33\",\n \"building\": \"De Velde Block 4\"\n },\n \"contact\": {\n \"customer_name\": \"Warehouse Manager Dave\",\n \"customer_phone\": \"086 999 0393\",\n \"email_address\": \"info@picup.co.za\"\n }\n },\n \"receiver\": { // Details for the delivery contact\n \"parcels\": [\n {\n \"parcel_waybill\": \"PCW000723842_1\", // Unique Parcel Identifier, to be used as primary parcel key\n \"parcel_reference\": \"#2804.1\",\n \"tracking_number\": \"#2804.1\",\n \"length_mm\": 20,\n \"width_mm\": 20,\n \"height_mm\": 20,\n \"weight_kg\": 2\n }\n ],\n \"address\": {\n \"address_line_1\": \"293 Moduba Cres\",\n \"address_line_2\": \"Marapong\",\n \"address_line_3\": \"Lephalale\",\n \"address_line_4\": \"0556\",\n \"city\": \"Lephalale\",\n \"formatted_address\": \"293 Moduba Cres, Marapong, Lephalale, 0556, South Africa\",\n \"latitude\": -23.65739,\n \"longitude\": 27.6236,\n \"postal_code\": \"0556\",\n \"suburb\": \"Marapong\"\n },\n \"contact\": {\n \"customer_name\": \"John Doe\",\n \"customer_phone\": \"0831234567\",\n \"email_address\": \"cleintemail@gmail.com\",\n \"special_instructions\": \"Please call when outside\"\n }\n }\n }\n ]\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://example-url.com/example-request"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{ \"is_success\":false,\"error\":\"Incorrect Destination Town\"}\n"}],"_postman_id":"1e20aba1-bc87-454f-aff4-446b19365b6b"},{"name":"Cancel Shipment","id":"42723577-c89c-4bcc-8a64-8b1e30e988f9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW00000001\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-cancel","description":"

Picup will require a generic endpoint for cancelling orders prior to fulfilment. Depending on the strategy as used about, we will send through the courier_reference of each order.

\n","urlObject":{"protocol":"https","path":["example-cancel"],"host":["your-url","com"],"query":[],"variable":[]}},"response":[{"id":"f31d2c1c-1d95-413e-b354-8af70d96538d","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW00000001\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-request"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"is_success\": true\n}"},{"id":"4558ce17-eec0-4288-a8d3-9e61a74ed917","name":"Failure","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW00000001\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-request"},"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"is_success\": false,\n \"error\": \"Order Cannot Be Found\"\n}"}],"_postman_id":"42723577-c89c-4bcc-8a64-8b1e30e988f9"},{"name":"Tracking Update","id":"57a6a370-62aa-4c80-b71b-2bff593e38d3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW100775285\",\n \"timestamp\": \"2021-05-18T00:00:00\",\n \"parcel_waybill_number\": null,\n \"courier_code\": \"RTT\",\n \"event_code\": \"23\",\n \"event_description\": \"DriverAssigned\",\n \"event_arg1\": \"Example Meta Arg\",\n \"event_arg2\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"{{picup-url}}/{{picup-version}}/courier-webhook/generic/tracking-event","description":"

How to use:

\nPlease find tracking details here","urlObject":{"path":["{{picup-version}}","courier-webhook","generic","tracking-event"],"host":["{{picup-url}}"],"query":[],"variable":[]}},"response":[{"id":"d49d68ba-fec7-411a-b4d2-c8f461e93e60","name":"Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW100775285\",\n \"timestamp\": \"2021-05-18T00:00:00\",\n \"parcel_waybill_number\": null,\n \"courier_code\": \"RAM\",\n \"event_code\": \"23\",\n \"event_description\": \"DriverAssigned\",\n \"event_arg1\": \"Example Meta Arg\",\n \"event_arg2\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-request"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":""},{"id":"ea14ea93-a334-4609-b482-005f6cb90a0b","name":"Failure","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"courier_reference\": \"PCW100775285\",\n \"timestamp\": \"2021-05-18T00:00:00\",\n \"parcel_waybill_number\": null,\n \"courier_code\": \"RAM\",\n \"event_code\": \"23\",\n \"event_description\": \"DriverAssigned\",\n \"event_arg1\": \"Example Meta Arg\",\n \"event_arg2\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-url.com/example-request"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":""}],"_postman_id":"57a6a370-62aa-4c80-b71b-2bff593e38d3"}]}