Create Order with Clickpost

Integration Process:

1. Clickpost provides universal API, which enables customers to activate any logistics
   partner using just a configuration change
2. API documentation: ​https://docs.Clickpost.ai/docs/order-creation-v3-1
3. Once the courier partner is allocated to an order, the client calls Clickpost Create Order
   API by passing pickup_info, drop_info, shipment_details, gst_info, additional_info
   1. For each transporter, Clickpost has a unique combination of
      courier_partner_id (​https://track.Clickpost.in/courier_partner)​ and account_code.
   2. Account Code can be checked from your dashboard: ​https://dashboard.Clickpost.in/#/settings​ → Courier Partner Settings.
   3. Please store the mapping of your transporters, Clickpost courier_partner_id and account_code in your system.
4. There are cases where the logistics partners have scheduled downtimes. During these times, the manifestation will fail. In such cases, make sure you have a configuration to retry such orders on Clickpost later again.

Guidelines:

• API Success check: HTTP status = 200 and In Clickpost response : “meta” → “status_code” should be either 200 (success), 323 (Order already placed)
• If API fails keep log of data in file and upload on permanent storage (ex. AWS S3)
• Implement retries:​ Retry at least 3 times before giving up on any AWB register
• Share the failed AWB with payload, URL and response from Clickpost.
• Ask Clickpost to send yesterday registered shipment report, match the counts with your
  database, if you see any discrepancies - find such AWB, and share their payload,
  response with ​[email protected]
• Also get the “Order Creation API failure” report activated by Clickpost team to receive
  logs of Clickpost server for failed API requests

Tracking Shipments:

Via Webhooks (Clickpost POSTING DATA ON YOUR SERVER)

Integration Process:

Clickpost offers unified webhooks to its clients, where the client exposes an end point and Clickpost pushes data on that end point whenever there is a state change in shipment journey.

1. Expose the end point and register that end point on Clickpost. API doc:
   https://docs.Clickpost.ai/docs/tracking-a-shipment-using-webhook

2. Once you register your end point, you can update it later by using PUT API over the same register-webhook URL

3. Clickpost offers 2 services for webhook:
   a. Push all courier partner status data on your system: Whenever courier partner
   post any status for a shipment, that status webhook is triggered to your server
   b. Push only specific event data on your system: Here Clickpost pushes only
   specific webhook to your server
   Let us know which service, you would like to opt for.

Guidelines:

• Order of status data Clickpost is not guaranteed

• Api should be fast with timeout of 2 second

• If you consider these as events for SMS etc, check latest_time_stamp field, if its
  difference with current timestamp is more than 1 day , do not send the sms or other event, it meant there was a delay either from courier company api or Clickpost side. Sending notifications on this might mislead the end customer.

• POST API for webhook should give 200 status only if you have written webhook payload from Clickpost in your database.

• Make post method atomic transaction - if DB call fails, you will not lose the data.

• Make WEBHOOK Api idempotent, even if a status is sent multiple times, you should take
  only first instance, for later updates for the same status - just return 200 and do not update in your database. Store id (​order_status_id​) field sent in payload in database, before storing check if this id is present or not.

• Clickpost send any status update 3 times, if your server is down for that time- you might lose all three retries. Clickpost does not keep track if your server is up or not

• As a backup, integrate track-order API from Clickpost, hit for all AWB which are not yet delivered and update in your DB. This should be done at least once a day.

• Ask your Clickpost POC to activate failed webhooks report for the tech team to debug any issue

  • Via Polling (Hitting Clickpost server for latest status)
    Since webhooks are transactional in nature, there might be cases when your system is not able to receive the status of shipments.
  • To cater such cases, we recommend to implement polling API as well, which you can hit once every day for all open shipments in forward supply chain and update your system accordingly.

• API doc ​https://docs.Clickpost.ai/docs/tracking-shipment-using-polling#url

General Guidelines for seamless integration

• Clickpost APIs are idempotent - if you post something multiple times, Clickpost ignores & take the data from the first call only
• Do not integrate the API like polling/status update on frontend, or directly on the customer page
• For all APIs, store the shipments ready to be pushed in the models and write job to pick up the shipments and register on Clickpost
• Its preferred to maintain no of retries in case of any API failure and keep things like success=t/f and no_of_retries, keep at least 3 retries in case of any API failure
• In case of failure, maintain the payload and response from the API in log files - It help Clickpost team debug any discrepancies in data pushed to Clickpost
• At the end of the day, pull all failure AWB and max retries, their payload, responses and share with Clickpost team, send this report to Clickpost for every such API every day
• All of your API are recommended to be HA (highly available)