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:

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

Ngrok (If you don’t have any domain)

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:

Create connect with carrier

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)

Create connect with carrier

+ Response (reference https://docs.haravan.com/blogs/api-reference/api-carrier-service to know the meaning of the fields)

reate connect with carrier

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).

Create an environment to listen request form Haravan

+ 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:

Create order and use shipping feature

- Choose your carrier:

Create order and use shipping feature

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).

Carrier listen Haravan’s request to get shipping rates

- If you use ngrok, use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040

Carrier listen Haravan’s request to get shipping rates

- 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.

Carrier listen Haravan’s request to get shipping rates

- Haravan receive shipping rates data and show it on seller.

Carrier listen Haravan’s request to get shipping rates

3.5 Step 5: Choose shipping rate and create fulfillment:

- Choose shipping rate and press shipping button.

Choose shipping rate and create fulfillment

- 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

Choose shipping rate and create fulfillment

- 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).

Choose shipping rate and create fulfillment

- Haravan receive response data and creates fulfillment data on Haravan side. Then displayed at the seller.

Choose shipping rate and create fulfillment

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).

Get order fulfillment detail

- 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.

Get order fulfillment detail

- Response:

Get order fulfillment detail

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).

Get order fulfillment detail

- If you use ngrok, use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040

Get order fulfillment detail

- The carrier (app demo) receive order data form Haravan’request and respond shipping rates.

Get order fulfillment detail

- Result

Get order fulfillment detail

- 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:

Update fulfillment status

STT

Key

value

1

Authorization

Bearer + access_token

+ Update status order fulfillment status (picking):

- Api:

Update status order fulfillment status (picking)

- Response:

Update status order fulfillment status (picking)

+ Update status order fulfillment status (delivering):

- Api:

Update status order fulfillment status (delivering)

- Response:

Update status order fulfillment status (delivering)

+ Update status order fulfillment status (delivered):

- Api:

Update status order fulfillment status (delivered)

- Response:

Update status order fulfillment status (delivered)

+ Update status order fulfillment status (not_meet_customer):

- Api:

Update status order fulfillment status (not_meet_customer)

- Response:

Update status order fulfillment status (not_meet_customer)

+ Update status order fulfillment status (waiting_for_return):

- Api:

Update status order fulfillment status (waiting_for_return)

- Response:

Update status order fulfillment status (waiting_for_return)

+ Update status order fulfillment status (return):

- Api:

Update status order fulfillment status (return)

- Response:

Update status order fulfillment status (return)

+ Update status order fulfillment status (paid):

- Api:

Update status order fulfillment status (paid)

- Response:

Update status order fulfillment status (paid)

+ Update status order fulfillment status (receipt):

- Api:

Update status order fulfillment status (receipt)

- Response:

Update status order fulfillment status (receipt)

+ Update status order fulfillment status (cancel):

- Api:

Update status order fulfillment status (cancel)

- Response:

Update status order fulfillment status (cancel)

- 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.