CONNECT CARRIER TUTORIAL
1. Target
- Have the app installed and get Haravan’s access_token with right scope.
- Create connection between Haravan and carrier.
- Carrier authentication data from Haravan.
- When the seller choose delivery, sends a request to the carrier for create order fulfillment.
- Carrier can actively update fulfillment status by api.
- When the seller cancel the delivery, sends a request to the carrier for cancel order fulfillment.
- When uninstalled the app, the carrier listen webhook uninstall app and remove the connection between carrier and Haravan.
1. Prepare
1.1 Access_token:
- First , you need Haravan’s access_token to use Haravan’s Api.
- You also need right scope to get Haravan’s access_token.
- Those scope are:
- Scope create/update/delete/read connect with carrier: com.write_shippings, com.read_shippings.
- Scope update status order fulfillment: com.write_orders, com.read_orders.
- Follow URLs below for more information:
- Scope:
- Access_token:
- Webhook (optional, if you use webhook):
1.2 Api carrier service:
- Read the file: https://docs.haravan.com/blogs/api-reference/api-carrier-service
- File content: All information of carrier service api.
1.3 Ngrok (If you don’t have any domain):
- Ngrok (https://ngrok.com/) creates a secure tunnel on your local machine along with a public URL you can use for browsing your local site.
- If you’re running your local web server on port 3000, In terminal, you’d type in: ngrok http 3000.
- Note:
- A url can be available for 8 hours
- Use https://
- Use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040
3. Steps to create and use carrier service:
3.1 Step 1: Create connect with carrier:
- Use Post man:
+ Api and method :
Method | URL |
POST | https://apis.haravan.com/com/carrier_services.json |
+ Header:
STT | Key | value |
1 | Authorization | Bearer + access_token |
+ Body (reference https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields)
+ Response (reference https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields)
3.2 Step 2: Create an environment to listen request form Haravan:
- In this demo, we build a demo app on the nodejs environment as a carrier to listen requests from Haravan.
- Source:
+ Haravan_validate.js: authenticate data from Haravan with X-Haravan-Hmac-SHA256 in request header (reference https://docs.haravan.com/blogs/api-reference/api-carrier-service).
+ App.js
- References:
+ https://docs.haravan.com/blogs/api-reference/api-carrier-service.
+ Source code Carrier_seriver
3.3 Step 3: Create order and use shipping feature:
- Create order and use shipping feature in seller:
- Choose your carrier:
3.4 Step 4: Carrier listen Haravan’s request to get shipping rates.
- Once you've selected a carrier, Haravan will display a list of carriers that have created a connection, and send a request to the carrier (app demo) to get shipping rates via get_shipping_rates_url (POST).
- If you use ngrok, use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040
- The carrier (app demo) receive order data form Haravan’request and response shipping rates.
- Read file https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields.
- Haravan receive shipping rates data and show it on seller.
3.5 Step 5: Choose shipping rate and create fulfillment:
- Choose shipping rate and press shipping button.
- Haravan send a request to the carrier (app demo) via create_order_url (POST).
- If you use ngrok, use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040
- The carrier (app demo) receive order data and product data form Haravan’s request and create order fulfillment on carrier side. After that, response data for Haravan (read file https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields).
- Haravan receive response data and creates fulfillment data on Haravan side. Then displayed at the seller.
3.6 Step 6: Get order fulfillment detail:
- Haravan's often send a request automaticly to get order fulfillment detail for update. So, we will use the postman for this demo.
- Haravan send a request to the carrier (app demo) with tracking_number to get order shipping detail via get_shipping_rates_url (POST).
- Note: Because this step was demo by postman, it will temporarily bypass the authentication data from Haravan.
- Read file https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields.
- Response:
3.7 Step 7: Cancel fulfillment:
- In case the seller updates the delivery status (fulfillment status) to cancel delivery, at the same time Haravan will send a request to the carrier (app demo) with tracking_number via cancel_order_url(DELETE).
- If you use ngrok, use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040
- The carrier (app demo) receive order data form Haravan’request and respond shipping rates.
- Result
- Note: After canceled your fulfillment, you can’t update this fulfillment anymore.
3.8 Step 8: Update fulfillment status
- Carrier can actively update fulfillment status, by sending a request to Haravan’s api.
- Note:
- Create new order if old order has been canceled.
- You need order id and fulfillment id before starting.
- Read file 16_Api_carrier_service.pdf to know the meaning of the fields.
- Error Suggestion:
- Retry at least 3 times.
- If it still doesn’t work, follow the steps below :
- Log error, demo in postman.
- Notify Haravan.
- Share postman and specific data (shop, ord_id, fulfillment_id, access_token….) to check for Haravan.
Header for all demo:
STT | Key | value |
1 | Authorization | Bearer + access_token |
+ Update status order fulfillment status (picking):
- Api:
- Response:
+ Update status order fulfillment status (delivering):
- Api:
- Response:
+ Update status order fulfillment status (delivered):
- Api:
- Response:
+ Update status order fulfillment status (not_meet_customer):
- Api:
- Response:
+ Update status order fulfillment status (waiting_for_return):
- Api:
- Response:
+ Update status order fulfillment status (return):
- Api:
- Response:
+ Update status order fulfillment status (paid):
- Api:
- Response:
+ Update status order fulfillment status (receipt):
- Api:
- Response:
+ Update status order fulfillment status (cancel):
- Api:
- Response:
- Note: When using API update status of fulfillment is cancel. Haravan will send request to cancel the order fulfillment on carrier side similar to step 7.