API CARRIER SERVICE

I. Chuẩn bị

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

II. Api nhà vận chuyển request tới Haravan

- Những api để phía nhà vận chuyển liên kết với Haravan gửi request đến.

1. Api lấy danh sách nhà vận chuyển

- API Lấy danh sách các nhà vận chuyển đã tạo kết nối với Haravan

- Bao gồm :

+ Những nhà vận chuyển mặc định.

+ Những nhà vận chuyển mà bạn thêm vào.

1.1 Request

Method

URL

GET

https://apis.haravan.com/com/carrier_services.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

1.2 Response

Status

Response

200

{
    "carrier_services": [
       {
            "id": 8175831,
            "carrier_service_id": 0,
            "carrier_name": "Khác",
            "carrier_code": "other",
            "is_connected": true,
            "view_before_items": false,
            "view_dimension": false,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175813,
            "carrier_service_id": 11,
            "carrier_name": "Giao Hàng Nhanh",
            "carrier_code": "ghn2018",
            "is_connected": false,
            "view_before_items": true,
            "view_dimension": true,
            "view_coupon_code": true,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175846,
            "carrier_service_id": 15,
            "carrier_name": "ViettelPost2018",
            "carrier_code": "viettelpost2018",
            "is_connected": false,
            "view_before_items": true,
            "view_dimension": false,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        },
        {
            "id": 8175843,
            "carrier_service_id": 8,
            "carrier_name": "Ninja Van",
            "carrier_code": "ninjavan",
            "is_connected": true,
            "view_before_items": false,
            "view_dimension": true,
            "view_coupon_code": false,
            "view_sender_name": false,
            "view_sender_phone": false,
            "view_insurance": false,
            "view_drop_off": false,
            "transport_types": []
        }   
    ]
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

STT

Thuộc tính

Mô tả

1

id (number)

id nhà vận chuyển

2

carrier_service_id (number)

Mã nhà vận chuyển

3

carrier_name (string)

Tên nhà vận chuyển

4

carrier_code (string)

Mã nhà vận chuyển

5

is_connected (bool)

Trạng thái kết nối:
true: đã kết nối
false: chưa kết nối

2. Api lấy thông tin kết nối với nhà vận chuyển

- API lấy thông tin nhà vận chuyển đã kết nối với Haravan theo id

2.1 Request

Method

URL

GET

https://apis.haravan.com/com/carrier_services/#{id}.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

id

Tham số carrier_service_id nhận được từ API lấy danh sách nhà vận chuyển

2

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2.2 Response

Status

Response

200

{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://ad913c3a.ngrok.io/tracking_url",
        "create_order_url": "https://ad9133c8a.ngrok.io/create_order_url",
        "get_order_detail_url": "https://ad9133c8a.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://ad2913c8a.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://ad9131c8a.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://ad913c8a.ngrok.io/get_by_external_code_url",				
        "name": "nam 12322",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T08:02:49.047Z",
        "updated_at": "2019-06-07T08:02:49.047Z",
        "id": 10115763,
        "options": {
            "has_drop_off": false,
            "has_insurance": false,
            "has_view_before": false,
            "has_payment_method": false,
            "has_dimension": false,
            "has_transport_type": false,
            "has_use_coupon_code": false
        }
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

STT

Thuộc tính

Mô tả

1

active (bool)

Có được hiển thị hay không

2

tracking_url (string)

Link xem chi tiết vận đơn

3

create_order_url (string)

Link tạo vận đơn

4

get_order_detail_url (string)

Link lấy chi tiết vận đơn

5

get_shipping_rate_url (string)

Link lấy danh sách gói vận chuyển

6

cancel_order_url (string)

Link hủy vận đơn

7

get_by_external_code_url(string)

Link lấy chi tiết vận đơn theo external_code

8

name (string)

Tên nhà vận chuyển

9

carrier_service_type (string)

Loại nhà vận chuyển
(default là api, không sửa được)

10

service_discovery (bool)

Có cho truyền dữ liệu để test API nhà vận chuyển hay không ( tạm thời lưu db chứ chưa dùng đến).

Truyền vào: false

11

created_at (datetime)

Ngày tạo

12

updated_at (datetime)

Ngày

13

id (long)

Id

3. Api tạo kết nối với nhà vận chuyển

- API tạo kết nối với nhà vận chuyển không có trong danh sách kết nối với Haravan

- Lưu ý :

+ Mỗi access_token chỉ có thể tạo kết nối với một nhà vận chuyển.

+ Nếu muốn tạo kết nối với nhà vận chuyển khác với xóa kết nối đã tạo trước đó.

3.1 Request

Method

URL

POST

https://apis.haravan.com/com/carrier_services.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token} 
Request raw json:
{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://ad913c8a.ngrok.io/tracking_url",
        "create_order_url": "https://ad913c8a.ngrok.io/create_order_url",
        "get_order_detail_url": "https://ad913c8a.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://ad913c8a.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://ad913c8a.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://ad913c8a.ngrok.io/get_by_external_code_url",
        "name": "demo Express",
        "carrier_service_type": "api",
        "service_discovery": false
    }
}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

active (bool)

Có được hiển thị hay không

3

tracking_url (string)

Link xem chi tiết vận đơn

4

create_order_url (string)

Link tạo vận đơn

5

get_order_detail_url (string)

Link lấy chi tiết vận đơn

6

get_shipping_rate_url (string)

Link lấy danh sách gói vận chuyển

7

cancel_order_url (string)

Link hủy vận đơn

8

get_by_external_code_url(string)

Link lấy chi tiết vận đơn theo external_code

9

name (string)

Tên nhà vận chuyển

10

carrier_service_type (string)

Loại nhà vận chuyển
(default là api, không sửa được)

11

service_discovery (bool)

Có cho truyền dữ liệu để test API nhà vận chuyển hay không ( tạm thời lưu db chứ chưa dùng đến).

Truyền vào: false

3.2 Response

Status

Response

200

{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://ad913c8a.ngrok.io/tracking_url",
        "create_order_url": "https://ad913c8a.ngrok.io/create_order_url",
        "get_order_detail_url": "https://ad913c8a.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://ad913c8a.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://ad913c8a.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://ad913c8a.ngrok.io/get_by_external_code_url",
        "name": "demo Express",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T09:02:29.6164737Z",
        "updated_at": "2019-06-07T09:02:29.6164848Z",
        "id": 10116264,
        "options": {
            "has_drop_off": false,
            "has_insurance": false,
            "has_view_before": false,
            "has_payment_method": false,
            "has_dimension": false,
            "has_transport_type": false,
            "has_use_coupon_code": false
        }
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

4. Api cập nhật kết nối với nhà vận chuyển

- API cập nhật thông tin nhà vận chuyển đã kết nối với Haravan theo id.

- Lưu ý :

+ Mỗi access_token chỉ cập nhật được kết nối với nhà vận chuyển được tạo bởi access_token.

4.1 Request

Method

URL

PUT

https://apis.haravan.com/com/carrier_services/#{id}.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}
Request raw json:
{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://ad913c8a.ngrok.io/tracking_url",
        "create_order_url": "https://ad913c8a.ngrok.io/create_order_url",
        "get_order_detail_url": "https://ad913c8a.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://ad913c8a.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://ad913c8a.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://ad913c8a.ngrok.io/get_by_external_code_url",
        "name": "demo Express update",
        "carrier_service_type": "api",
        "service_discovery": false
    }
}

STT

Thuộc tính

Mô tả

1

id

Tham số carrier_service_id nhận được từ API lấy danh sách nhà vận chuyển

2

access_token (string)

Lấy được khi cài ứng dụng và get access_token

3

active (bool)

Có được hiển thị hay không

4

tracking_url (string)

Link xem chi tiết vận đơn

5

create_order_url (string)

Link tạo vận đơn

6

get_order_detail_url (string)

Link lấy chi tiết vận đơn

7

get_shipping_rate_url (string)

Link lấy danh sách gói vận chuyển

8

cancel_order_url (string)

Link hủy vận đơn

9

get_by_external_code_url(string)

Link lấy chi tiết vận đơn theo external_code

10

name (string)

Tên nhà vận chuyển

11

carrier_service_type (string)

Loại nhà vận chuyển
(default là api, không sửa được)

12

service_discovery (bool)

Có cho truyền dữ liệu để test API nhà vận chuyển hay không ( tạm thời lưu db chứ chưa dùng đến).

Truyền vào: false

4.2 Response

Status

Response

200

{
    "carrier_service": {
        "active": true,
        "tracking_url": "https://ad913c8a.ngrok.io/tracking_url",
        "create_order_url": "https://ad913c8a.ngrok.io/create_order_url",
        "get_order_detail_url": "https://ad913c8a.ngrok.io/get_order_detail_url",
        "get_shipping_rates_url": "https://ad913c8a.ngrok.io/get_shipping_rates_url",
        "cancel_order_url": "https://ad913c8a.ngrok.io/cancel_order_url",
        "get_by_external_code_url": "https://ad913c8a.ngrok.io/get_by_external_code_url",
        "name": "demo Express update",
        "carrier_service_type": "api",
        "service_discovery": false,
        "created_at": "2019-06-07T09:51:12.832Z",
        "updated_at": "2019-06-07T09:55:29.8186851Z",
        "id": 10116582
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

5. Api xóa kết nối với nhà vận chuyển

- API xóa nhà vận chuyển đã kết nối với Haravan theo id.

- Lưu ý :

+ Mỗi access_token chỉ xóa được kết nối với nhà vận chuyển được tạo bởi access_token.

5.1 Request

Method

URL

DELETE

https://apis.haravan.com/com/carrier_services/#{id}.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

id

Tham số carrier_service_id nhận được từ API lấy danh sách nhà vận chuyển

2

access_token (string)

Lấy được khi cài ứng dụng và get access_token

5.2 Response

Status

Response

200

[]

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

6. Cập nhật trạng thái đang đi lấy

6.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/picking.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

6.2 Response

Status

Response

200

{
        "created_at": "2019-07-30T04:45:16.397Z",
        "id": 1010223926,
        "order_id": 1001471925,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444374,
                "price": 20000.0000,
                "product_id": null,
                "quantity": 10,
                "requires_shipping": true,
                "sku": null,
                "title": "vavfav",
                "variant_id": null,
                "variant_title": "",
                "vendor": null,
                "name": "vavfav",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": false
            }
        ],
        "province": "Hồ Chí Minh",
        "province_code": "HC",
        "district": "Quận 11",
        "district_code": "HC476",
        "ward": "Phường 15",
        "ward_code": "27208",
        "cod_amount": 200000.0000,
        "carrier_status_name": "Đang đi lấy",
        "carrier_cod_status_name": "Chưa nhận",
        "carrier_status_code": "picking",
        "carrier_cod_status_code": "codpending",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T04:45:16Z",
        "picking_date": "2019-07-30T06:54:46.2947436Z",
        "delivering_date": "2019-07-30T05:30:28Z",
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

STT

Thuộc tính

Type

Mô tả

1

created_at

DateTime

Ngày tạo

2

id

long

Id giao hàng

3

order_id

long

Id đơn hàng được giao

4

receipt

string

 

5

status

string

Trạng thái giao hàng

6

tracking_company

string

Tên công ty vận chuyển.

7

tracking_company_code

string

Mã NVC.

8

tracking_numbers

Array

Danh sách các mã theo dõi. Được cung cấp bởi công ty vận chuyển.

9

tracking_number

string

Mã theo dõi

10

tracking_url

String

Link tìm kiếm bản đồ vận chuyển

11

tracking_urls

String

List link tìm kiếm bản đồ vận chuyển

12

updated_at

Long

Thời điểm cập nhật vận chuyển

13

province

String

Tỉnh thành

14

province_code

String

Mã tỉnh thành

15

district

String

Quận/Huyện

16

district_code

String

Mã Quận/Huyện

17

ward

String

Phường/Xã

18

ward_code

String

Mã Phường/Xã

19

cod_amount

Number

Tiền thu hộ

20

carrier_status_name

String

Tên trạng thái giao hàng

21

carrier_cod_status_name

String

Tên trạng thái thu tiền COD

22

carrier_status_code

String

Mã trạng thái giao hàng

23

carrier_cod_status_code

String

Mã trạng thái thu tiền COD

24

location_id

Number

Mã chi nhánh lấy hàng

25

Note

String

Ghi chú

26

carrier_service_package

Number

Gói vận chuyển

27

carrier_service_package_name

String

Tên gói vận chuyển

28

is_new_service_package

Boolean

Nếu sử dụng gói mặc định => False, ngược lại là True

29

coupon_code

String

Mã khuyễn mãi

30

ready_to_pick_date

DateTime

Thời điểm chuyển qua trạng thái “Sẵn sàng giao”

31

picking_date

DateTime

Thời điểm chuyển qua trạng thái “Chọn giao hàng”

32

delivering_date

DateTime

Thời điểm chuyển qua trạng thái “Đang giao hàng”

33

delivered_date

DateTime

Thời điểm chuyển qua trạng thái “Đã giao hàng”

34

return_date

DateTime

Thời điểm chuyển qua trạng thái “Trả hàng”

35

not_meet_customer_date

DateTime

Thời điểm chuyển qua trạng thái “Không gặp khách hàng”

36

waiting_for_return_date

DateTime

Thời điểm chuyển qua trạng thái “Chờ chuyển hoàn”

37

cod_paid_date

DateTime

Thời điểm chuyển qua trạng thái “Chờ nhận tiền thu hộ COD”

38

cod_receipt_date

DateTime

Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD”

39

cod_pending_date

DateTime

Thời điểm chuyển qua trạng thái “Đợi thu hộ COD”

40

cod_not_receipt_date

DateTime

Thời điểm chuyển qua trạng thái “Không đối soát tiền thu hộ COD”

41

is_view_before

Boolean

Được xem hàng trước

42

country

String

Quốc gia

43

country_code

String

Mã quốc gia

44

zip_code

String

Mã zip code quốc gia

45

City

String

Thành phố

46

real_shipping_fee

Number

Phí vận chuyển thực

47

shipping_notes

String

Ghi chú vận chuyển

48

total_weight

Number

Tổng khối lượng

49

package_length

Number

Chiều dài gói hàng

50

package_width

Number

Chiều rộng gói hàng

51

package_height

Number

Chiều cao gói hàng

52

boxme_servicecode

String

Gói giao hàng của Shipchung.vn(chỉ sử dụng khi giao bằng Shipchung.vn)

53

transport_type

Number

Phước thức vận chuển

1: đường bộ

2: đường bay

Default: 1

54

address

String

Địa chỉ giao hàng

55

sender_phone

String

SĐT người gửi

56

sender_name

String

Tên người gửi

57

carrier_service_code

String

Mã NVC

58

line_items

Array

List sản phẩm được vận chuyển

58.1

fulfillable_quantity

Number

Số lượng sản phẩm giao hàng

58.2

fulfillment_service

String

Dịch vụ giao hàng: “Thủ công”

58.3

fulfillment_status

String

Trạng thái giao hàng:

  • _null: Không giao hàng
  • _not_fulfilled: Chưa hoàn thành
  • _partial: Hoàn thành một phần
  • _fulfilled: Đã hoàn thành

58.4

grams

Number

Khối lượng của sản phẩm

58.5

id

String

Id Line Item

58.6

price

Number

Giá của sản phẩm trong line item

58.7

product_id

String

Id sản phẩm

58.8

quantity

Number

Số lượng sản phẩm

58.9

requires_shipping

Boolean

True: Có giao hàng

False: Không giao hàng

58.10

sku

String

Mã SKU của sản phẩm

58.11

title

String

Tên của sản phẩm

58.12

variant_id

String

Id biến thể của sản phẩm

58.13

variant_title

String

Tên biến thể của sản phẩm

58.14

vendor

String

Nhà sản xuất của sản phẩm

58.15

name

String

Tên sản phẩm và tên biến thể của sản phẩm

58.16

variant_inventory_management

 

Quản lý tồn kho biến thể của sản phẩm

58.17

properties

String

Thuộc tính của sản phẩm

58.18

product_exists

Boolean

True: Còn sản phẩm

False: Hết sản phẩm

7. Cập nhật trạng thái đang giao hàng

7.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/delivering.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

7.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T04:45:16.397Z",
        "id": 1010223926,
        "order_id": 1001471925,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444374,
                "price": 20000.0000,
                "product_id": null,
                "quantity": 10,
                "requires_shipping": true,
                "sku": null,
                "title": "vavfav",
                "variant_id": null,
                "variant_title": "",
                "vendor": null,
                "name": "vavfav",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": false
            }
        ],
        "province": "Hồ Chí Minh",
        "province_code": "HC",
        "district": "Quận 11",
        "district_code": "HC476",
        "ward": "Phường 15",
        "ward_code": "27208",
        "cod_amount": 200000.0000,
        "carrier_status_name": "Đang giao hàng",
        "carrier_cod_status_name": "Chưa nhận",
        "carrier_status_code": "delivering",
        "carrier_cod_status_code": "codpending",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T04:45:16Z",
        "picking_date": "2019-07-30T06:54:46Z",
        "delivering_date": "2019-07-30T10:33:14.4252116Z",
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

8. Cập nhật trạng thái đã giao hàng

8.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/delivered.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

8.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T04:45:16.397Z",
        "id": 1010223926,
        "order_id": 1001471925,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444374,
                "price": 20000.0000,
                "product_id": null,
                "quantity": 10,
                "requires_shipping": true,
                "sku": null,
                "title": "vavfav",
                "variant_id": null,
                "variant_title": "",
                "vendor": null,
                "name": "vavfav",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": false
            }
        ],
        "province": "Hồ Chí Minh",
        "province_code": "HC",
        "district": "Quận 11",
        "district_code": "HC476",
        "ward": "Phường 15",
        "ward_code": "27208",
        "cod_amount": 200000.0000,
        "carrier_status_name": "Đã giao hàng",
        "carrier_cod_status_name": "Chưa nhận",
        "carrier_status_code": "delivered",
        "carrier_cod_status_code": "codpaid",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T04:45:16Z",
        "picking_date": "2019-07-30T06:54:46Z",
        "delivering_date": "2019-07-30T10:33:14Z",
        "delivered_date": "2019-07-30T10:34:15.0224673Z",
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": "2019-07-30T10:34:15.2462879Z",
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

9. Cập nhật trạng thái hủy giao hàng

- Lưu ý : Khi gọi api cập nhật trạng thái hủy giao hàng, hệ thống Haravan sẽ gửi request hủy vận đơn đến nhà vận chuyển.

9.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/cancel.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

9.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T10:38:57.8Z",
        "id": 1010223979,
        "order_id": 1001472219,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444554,
                "price": 0.0000,
                "product_id": 10000524439,
                "quantity": 1,
                "requires_shipping": true,
                "sku": null,
                "title": "B",
                "variant_id": 101604831,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "B",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cà Mau",
        "province_code": "CM",
        "district": "Huyện Ngọc Hiển",
        "district_code": "CM672",
        "ward": "Xã Đất Mũi",
        "ward_code": "32248",
        "cod_amount": 0.0000,
        "carrier_status_name": "Hủy giao hàng",
        "carrier_cod_status_name": "Không",
        "carrier_status_code": "cancel",
        "carrier_cod_status_code": "none",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T10:38:58Z",
        "picking_date": null,
        "delivering_date": null,
        "delivered_date": "2019-07-30T10:39:32Z",
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

10. Cập nhật trạng thái chuyển hoàn

10.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/return.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

10.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T10:44:41.149Z",
        "id": 1010223980,
        "order_id": 1001472222,
        "receipt": null,
        "status": "success",
        "tracking_company": "ViettelPost2018",
        "tracking_company_code": "viettelpost2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://www.viettelpost.com.vn/Tracking?KEY=",
        "tracking_urls": [
            "https://www.viettelpost.com.vn/Tracking?KEY="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444555,
                "price": 0.0000,
                "product_id": 10000524440,
                "quantity": 1,
                "requires_shipping": true,
                "sku": null,
                "title": "C",
                "variant_id": 101604832,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "C",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cần Thơ",
        "province_code": "CN",
        "district": "Huyện Cờ Đỏ",
        "district_code": "CN713",
        "ward": "Xã Đông Thắng",
        "ward_code": "31274",
        "cod_amount": 0.0000,
        "carrier_status_name": "Chuyển hoàn",
        "carrier_cod_status_name": "Không",
        "carrier_status_code": "return",
        "carrier_cod_status_code": "none",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T10:44:41Z",
        "picking_date": null,
        "delivering_date": null,
        "delivered_date": null,
        "return_date": "2019-07-30T10:45:04.8959899Z",
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": "không đồng kiểm",
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

11. Cập nhật trạng thái chuyển hoàn

11.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/not_meet_customer.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

11.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T10:50:45.922Z",
        "id": 1010223982,
        "order_id": 1001472225,
        "receipt": null,
        "status": "success",
        "tracking_company": "ViettelPost2018",
        "tracking_company_code": "viettelpost2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://www.viettelpost.com.vn/Tracking?KEY=",
        "tracking_urls": [
            "https://www.viettelpost.com.vn/Tracking?KEY="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444556,
                "price": 0.0000,
                "product_id": 10000524440,
                "quantity": 1,
                "requires_shipping": true,
                "sku": null,
                "title": "C",
                "variant_id": 101604832,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "C",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cần Thơ",
        "province_code": "CN",
        "district": "Huyện Cờ Đỏ",
        "district_code": "CN713",
        "ward": "Xã Đông Thắng",
        "ward_code": "31274",
        "cod_amount": 0.0000,
        "carrier_status_name": "Không gặp khách",
        "carrier_cod_status_name": "Không",
        "carrier_status_code": "notmeetcustomer",
        "carrier_cod_status_code": "none",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T10:50:46Z",
        "picking_date": "2019-07-30T10:51:36Z",
        "delivering_date": null,
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": "2019-07-30T10:52:24.7976861Z",
        "waiting_for_return_date": null,
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

12. Cập nhật trạng thái chờ chuyển hoàn

12.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/carrier_status/waiting_for_return.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

12.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T10:50:45.922Z",
        "id": 1010223982,
        "order_id": 1001472225,
        "receipt": null,
        "status": "success",
        "tracking_company": "ViettelPost2018",
        "tracking_company_code": "viettelpost2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://www.viettelpost.com.vn/Tracking?KEY=",
        "tracking_urls": [
            "https://www.viettelpost.com.vn/Tracking?KEY="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444556,
                "price": 0.0000,
                "product_id": 10000524440,
                "quantity": 1,
                "requires_shipping": true,
                "sku": null,
                "title": "C",
                "variant_id": 101604832,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "C",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cần Thơ",
        "province_code": "CN",
        "district": "Huyện Cờ Đỏ",
        "district_code": "CN713",
        "ward": "Xã Đông Thắng",
        "ward_code": "31274",
        "cod_amount": 0.0000,
        "carrier_status_name": "Chờ chuyển hoàn",
        "carrier_cod_status_name": "Không",
        "carrier_status_code": "waitingforreturn",
        "carrier_cod_status_code": "none",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T10:50:46Z",
        "picking_date": "2019-07-30T10:51:36Z",
        "delivering_date": null,
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": "2019-07-30T10:52:25Z",
        "waiting_for_return_date": "2019-07-30T10:55:42.3374783Z",
        "cod_paid_date": null,
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

13. Cập nhật trạng thái đã thu COD

- Nhân viên thu hộ COD đã thu tiền từ khách.

13.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/cod_status/paid.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

13.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T11:02:02.381Z",
        "id": 1010223984,
        "order_id": 1001472246,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444565,
                "price": 10000.0000,
                "product_id": 10000525705,
                "quantity": 100,
                "requires_shipping": true,
                "sku": null,
                "title": "LUMIA",
                "variant_id": 101606789,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "LUMIA",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cần Thơ",
        "province_code": "CN",
        "district": "Huyện Long Mỹ",
        "district_code": "CN642",
        "ward": "Huyện Long Mỹ",
        "ward_code": "32278",
        "cod_amount": 1000000.0000,
        "carrier_status_name": "Chờ lấy hàng",
        "carrier_cod_status_name": "Chưa nhận",
        "carrier_status_code": "readytopick",
        "carrier_cod_status_code": "codpaid",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T11:02:02Z",
        "picking_date": null,
        "delivering_date": null,
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": "2019-07-30T11:02:37.2273214Z",
        "cod_receipt_date": null,
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

14. Cập nhật trạng thái đã nhận COD

- Shop đã nhận tiền thu hộ COD

14.1 Request

Method

URL

PUT

https://apis.haravan.com/com/orders/{orderId}/fulfillments/{fulfillId}/cod_status/receipt.json

Header:  Content-Type: application/json
Authorization: Bearer #{access_token}

STT

Thuộc tính

Mô tả

1

access_token (string)

Lấy được khi cài ứng dụng và get access_token

2

orderId (string)

Mã đơn hàng

3

fulfillId (string)

Mã vận đơn

14.2 Response

Status

Response

200

{
    "fulfillment": {
        "created_at": "2019-07-30T11:02:02.381Z",
        "id": 1010223984,
        "order_id": 1001472246,
        "receipt": null,
        "status": "success",
        "tracking_company": "Giao Hàng Nhanh",
        "tracking_company_code": "ghn2018",
        "tracking_numbers": [],
        "tracking_number": null,
        "tracking_url": "https://track.ghn.vn/order/tracking?code=",
        "tracking_urls": [
            "https://track.ghn.vn/order/tracking?code="
        ],
        "updated_at": null,
        "line_items": [
            {
                "fulfillable_quantity": 0,
                "fulfillment_service": "Thủ công",
                "fulfillment_status": "Đã hoàn thành",
                "grams": 0.0000,
                "id": 1001444565,
                "price": 10000.0000,
                "product_id": 10000525705,
                "quantity": 100,
                "requires_shipping": true,
                "sku": null,
                "title": "LUMIA",
                "variant_id": 101606789,
                "variant_title": "Default Title",
                "vendor": "Khác",
                "name": "LUMIA",
                "variant_inventory_management": null,
                "properties": null,
                "product_exists": true
            }
        ],
        "province": "Cần Thơ",
        "province_code": "CN",
        "district": "Huyện Long Mỹ",
        "district_code": "CN642",
        "ward": "Huyện Long Mỹ",
        "ward_code": "32278",
        "cod_amount": 1000000.0000,
        "carrier_status_name": "Chờ lấy hàng",
        "carrier_cod_status_name": "Đã nhận",
        "carrier_status_code": "readytopick",
        "carrier_cod_status_code": "codreceipt",
        "location_id": 485980,
        "note": null,
        "carrier_service_package": 0,
        "carrier_service_package_name": " - ",
        "is_new_service_package": false,
        "coupon_code": null,
        "ready_to_pick_date": "2019-07-30T11:02:02Z",
        "picking_date": null,
        "delivering_date": null,
        "delivered_date": null,
        "return_date": null,
        "not_meet_customer_date": null,
        "waiting_for_return_date": null,
        "cod_paid_date": "2019-07-30T11:02:37Z",
        "cod_receipt_date": "2019-07-30T11:05:12.8557651Z",
        "cod_pending_date": null,
        "cod_not_receipt_date": null,
        "cancel_date": null,
        "is_view_before": null,
        "country": null,
        "country_code": null,
        "zip_code": null,
        "city": null,
        "real_shipping_fee": 0.0000,
        "shipping_notes": null,
        "total_weight": 0.0000,
        "package_length": 0.00,
        "package_width": 0.00,
        "package_height": 0.00,
        "boxme_servicecode": null,
        "transport_type": 0,
        "address": null,
        "sender_phone": null,
        "sender_name": null,
        "carrier_service_code": null,
        "from_longtitude": 0.0,
        "from_latitude": 0.0,
        "to_longtitude": 0.0,
        "to_latitude": 0.0,
        "sort_code": null
    }
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

III. Api Haravan request tới nhà vận chuyển

1. Chứng thực data haravan post vào

- Đầu tiên ta phải có mã app id.

Chứng thực data haravan post vào

- Mã app id ở đây là 270acd3c5f191a85fae7b063335bfec6 .

- Tất cả carrier service của bạn đã được đánh dấu với270acd3c5f191a85fae7b063335bfec6 vì vậy bạn có thể xác minh tính toàn vẹn.

- Tiếp theo, lấy mã X-Haravan-Hmac-SHA256 từ header của request.

Chứng thực data haravan post vào

- Để xác thực data haravan post vào, ta sử dùng hàm băm HMAC với thuật toán "sha256" để mã hóa (data post vào + Mã app id) ra được mã hash, sau đó lấy mã hash mã hóa base64 lần nữa ra được kết quả, xong rồi lấy kết quả mới có được đem đi so sanh với header X-Haravan-Hmac-SHA256 mà data haravan post vào.

Ví dụ code PHP:

<?php
define('Haravan_APP_SECRET', 'my_shared_secret');
function verify_carrier($data, $hmac_header)
{
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, Haravan_APP_SECRET, true));
  return ($hmac_header == $calculated_hmac);
}
$hmac_header = $_SERVER['HTTP_X_Haravan_HMAC_SHA256'];
$data = file_get_contents('php://input');
$verified = verify_carrier ($data, $hmac_header);
//check error.log to see the result
error_log('Verified carrier: '.var_export($verified, true)); 
?>

2. Lấy danh sách gói vận chuyển và phí vận chuyển

- Khi người người dùng bấm nút “Giao hàng”, Haravan sẽ post vào "link lấy danh sách gói vận chuyển" mà nhà vận chuyển truyền vào để lấy danh sách gói vận chuyển và phí vận chuyển

2.1 Request

Method

URL

POST

Link lấy danh sách gói vận chuyển (get_shipping_rate_url)

Header:  
Content-Type: application/json
X-Haravan-Hmac-Sha256: #{hmac_sha256}
Request raw json:
{
  "origin": {
    "country": null,
    "country_code": null,
    "country_name": null,
    “province”: “Hồ Chí Minh”,
    "province_code": "HC",
    "district": "Quận 7",
    "district_code": "HC472",
    "ward": "Phường Tân Phong",
    "ward_code": "27490",
    "address1": null,
    "address2": null,
    "zip": null,
    "city": null,
    "phone": null,
    "name": null
  },
  "destination": {
    "country": null,
    "country_code": null,
    "country_name": null,
    “province”: “Hồ Chí Minh”,
    "province_code": "HC",
    "district": "Quận 11",
    "district_code": "HC476",
    "ward": null,
    "ward_code": null,
    "address1": null,
    "address2": null,
    "zip": null,
    "city": null,
    "phone": null,
    "name": null
  },
  "items": null,
  "cod_amount": 500000,
  "total_grams": 10
}

STT

Thuộc tính

Mô tả

1

hmac_sha256 (string)

Mã xác thực từ haravan post vào, cách chứng thực được miêu tả ở mục đầu.

2

origin (object)

Nơi chuyển

2.1

country (string)

Quốc gia

2.2

country_code (string)

Mã quốc gia

2.3

country_name (string)

Tên quốc gia

2.4

province (string)

Tên tỉnh thành

2.5

province_code (string)

Mã Tỉnh/Thành

2.6

district (string)

Tên Quận/Huyện

2.7

district_code (string)

Mã Quận/Huyện

2.8

ward (string)

Tên Phường/Xã

2.9

ward_code (string)

Mã Phường/Xã

2.10

address1(string)

Địa chỉ 1

2.11

address2 (string)

Địa chỉ 2

2.12

zip (string)

Zip

2.13

city (String)

Thành phố

2.14

phone  (string)

Số điện thoại

2.15

name (string)

Tên

3

destination (object)

Nơi nhận (Ý nghĩa các field trong destination tương tự như origin.)

4

items (array)

List sản phẩm cần vận chuyển

4.1

name (string)

Tên sản phẩm

4.2

sku (string)

Mã SKU

4.3

quantity (int)

 Số lượng

4.4

grams (decimal)

Trọng lượng trên sản phẩm

4.5

price (decimal)

Giá

4.6

product_id (long)

Mã sản phẩm

4.7

variant_id

Mã biến thể của sản phẩm

5

cod_amount (decimal)

Số tiên thu hộ COD

6

total_grams (decimal)

Tổng khối lượng các item

2.2 Response

Status

Response

200

{
“error”: true/false,
“message”: “message lỗi nếu có”,
“data”: {
  "rates": [
    {
      "service_id": 123456,
      "service_name": "test 1",
      "service_code": "test",
      "currency": "vnd",
      "total_price": 1111,
      "phone_required": true,
      "min_delivery_date": new Date(),
      "max_delivery_date": new Date(),
      "description": "description"
    },
    {
      "service_id": 456789,
      "service_name": "test 2",
      "service_code": "test",
      "currency": "vnd",
      "total_price": 1112,
      "phone_required": false,
      "min_delivery_date": null,
      "max_delivery_date": null,
      "description": "description"
    }
  ]
}
}

STT

Thuộc tính

Mô tả

1

service_id (int)

Id gói vận chuyển

2

service_name (string)

Tên gói vận chuyển

3

service_code (string)

Mã gói vận chuyển

4

currency (string)

Loại tiền tệ
Default VNĐ

5

total_price (decimal)

Tổng tiền

6

phone_required (bool)

Có bắt buộc truyền số điện thoại không

7

min_delivery_date (datetime)

Thời gian vận chuyển nhanh nhất
Có thể null

8

Max_delivery_date (datetime)

Thời gian vận chuyển chậm nhất
Có thể null

9

description

Miêu tả

3. Lấy chi tiết vận đơn cho đơn hàng

3.1 Request

Method

URL

POST

Link lấy chi tiết vận đơn (get_order_detail_url)

Header:  Content-Type: application/json
X-Haravan-Hmac-Sha256: #{hmac_sha256}
Request raw json:
{
   tracking_number: "123456"
}

STT

Thuộc tính

Mô tả

1

hmac_sha256 (string)

Mã xác thực từ haravan post vào, cách chứng thực được miêu tả ở mục đầu.

2

tracking_number (string)

Mã vận đơn

3.2 Response

Status

Response

200

{
     "error":false,
     "message”: "",
     "data":{
           "tracking_number: 123456",
           "shipping_fee": 10000,
           "tracking_url": "https://abc.com/tracking_url",
           "cod_amount": 5000,
           "status": "Delivered",           
           "external_code": "1000113763_1001768979_1010281064",
           "external_order_id": 1001768979,
           "external_fulfillment_id": 1010281064,
           "status": "delivered",
           "cod_status": "paid",
           "created_at": "2020-09-09T11:06:11.643Z",
           "ready_to_pick_date": null,
           "picking_date": null,
           "delivering_date": "2020-09-09T11:06:12.643Z ",
           "delivered_date": "2020-09-09T11:06:13.643Z ",
           "return_date": null,
           "not_meet_customer_date": null,
           "waiting_for_return_date": null,
           "cod_paid_date": null,
           "cod_receipt_date": null

         }
     }

STT

Thuộc tính

Mô tả

1

tracking_number (string)

Mã vận đơn

2

shipping_fee  (decimal)

Phí vận chuyển

3

tracking_url (string)

Link xem chi tiết vận đơn

4

cod_amount (decimal)

Số tiền thu hộ COD

5

status (string)

Trạng thái vận đơn:

pending: Chờ xử lý,

ready_to_pick: Chờ lấy hàng,

picking: Đang đi lấy,

delivering: Đang giao hàng,

delivered: Đã giao hàng,

cancel: Hủy giao hàng,

return: Chuyển hoàn,

not_meet_customer: Không gặp khách,

waiting_for_return: Chờ chuyển hoàn

6

cod_status (string)

Trạng thái thu hộ COD:

none: Không thu hộ,

pending: Chờ xử lý,

paid: Nhà vận chuyển đã thu tiền của khách hàng,

receipt: Shop đã nhận được tiền từ nhà vận chuyển,

not_receipt: Chưa nhận tiền

7

external_code (string)

Mã External Code

8

external_order_id (long)

Id đơn hàng trên hệ thống Haravan (unique trên toàn hệ thống Haravan)

9

external_fulfillment_id (long)

Mã vận chuyển

10

created_at (datetime)

Thời điểm tạo giao hàng

11

ready_to_pick_date (datetime)

Thời điểm chuyển qua trạng thái “sẵn sàng giao”
Default: null

12

picking_date (datetime)

Thời điểm chuyển qua trạng thái “chọn giao hàng”
Default: null

13

delivering_date (datetime)

Thời điểm chuyển qua trạng thái “Đang giao hàng”
Default: null

14

delivered_date (datetime)

Thời điểm chuyển qua trạng thái “Đã giao hàng”
Default: null

15

return_date (datetime)

Thời điểm chuyển qua trạng thái “Trả hàng”
Default: null

16

not_meet_customer_date (datetime)

Thời điểm chuyển qua trạng thái “Không gặp khách hàng”
Default: null

17

waiting_for_return_date (datetime)

Thời điểm chuyển qua trạng thái “Chờ chuyển hoàn”
Default: null

18

cod_paid_date (datetime)

Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD”
Default: null

19

cod_receipt_date (datetime)

Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD”
Default: null

4. Lấy chi tiết vận đơn theo external_code

- Khi trả lại data cho api, bắt buộc phải response các phiêu tương ứng như data mẫu bên dưới, nếu không có data thì truyền giá trị default (null, string rỗng, 0, giá trị default của của field đó nếu có)

4.1 Request

Method

URL

GET

Link lấy chi tiết vận đơn theo external_code (get_by_external_code_url)

Header:  Content-Type: application/json
X-Haravan-Hmac-Sha256: #{hmac_sha256}
Request query: external_code: "123456"

Ví dụ: 

https://ad913c8a.ngrok.io/get_by_external_code_url?external_code=2113123512_1000103733_103323121

STT

Thuộc tính

Mô tả

1

hmac_sha256 (string)

Mã xác thực từ haravan post vào, cách chứng thực được miêu tả ở mục đầu.

2

external_code (string)

Mã external_code

4.2 Response

Status

Response

200

{
"error":false,
"message": "",
"data":{
         "tracking_number": "123456",
         "shipping_fee": 123123,
          "tracking_url": https://abc.com/123,
          "cod_amount": 500000,
          "external_code": "1000113763_1001768979_1010281064",
          "external_order_id": 1001768979,
          "external_fulfillment_id": 1010281064,
          "status": "delivered",
          "cod_status": "paid",
          "created_at": "2020-09-09T11:06:11.643Z",
          "ready_to_pick_date": null,
          "picking_date": null,
          "delivering_date": "2020-09-09T11:06:12.643Z ",
          "delivered_date": "2020-09-09T11:06:13.643Z ",
          "return_date": null,
          "not_meet_customer_date": null,
          "waiting_for_return_date": null,
          "cod_paid_date": null,
          "cod_receipt_date": null
   }
}

STT

Thuộc tính

Mô tả

1

tracking_number (string)

Mã vận đơn

2

shipping_fee (decimal)

Phí vận chuyển

3

tracking_url (string)

Link xem chi tiết vận đơn

4

cod_amount (decimal)

Số tiền thu hộ COD

5

status (string)

Trạng thái vận đơn:

pending: Chờ xử lý,

ready_to_pick: Chờ lấy hàng,

picking: Đang đi lấy,

delivering: Đang giao hàng,

delivered: Đã giao hàng,

cancel: Hủy giao hàng,

return: Chuyển hoàn,

not_meet_customer: Không gặp khách,

waiting_for_return: Chờ chuyển hoàn

6

cod_status (string)

Trạng thái thu hộ COD:

none: Không thu hộ,

pending: Chờ xử lý,

paid: Nhà vận chuyển đã thu tiền của khách hàng,

receipt: Shop đã nhận được tiền từ nhà vận chuyển,

not_receipt: Chưa nhận tiền

7

external_code (string)

Mã External Code

8

external_order_id (long)

Id đơn hàng trên hệ thống Haravan (unique trên toàn hệ thống Haravan)

9

external_fulfillment_id (long)

Mã vận chuyển

10

created_at (datetime)

Thời điểm tạo giao hàng

11

ready_to_pick_date (datetime)

Thời điểm chuyển qua trạng thái “sẵn sàng giao”
Default: null

12

picking_date (datetime)

Thời điểm chuyển qua trạng thái “chọn giao hàng”
Default: null

13

delivering_date (datetime)

Thời điểm chuyển qua trạng thái “Đang giao hàng”
Default: null

14

delivered_date (datetime)

Thời điểm chuyển qua trạng thái “Đã giao hàng”
Default: null

15

return_date (datetime)

Thời điểm chuyển qua trạng thái “Trả hàng”
Default: null

16

not_meet_customer_date (datetime)

Thời điểm chuyển qua trạng thái “Không gặp khách hàng”
Default: null

17

waiting_for_return_date (datetime)

Thời điểm chuyển qua trạng thái “Chờ chuyển hoàn”
Default: null

18

cod_paid_date (datetime)

Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD”
Default: null

19

cod_receipt_date (datetime)

Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD
Default: null

5. Tạo vận đơn cho đơn hàng

- Mô tả: khi người dùng đã chọn gói vận chuyển và bấm nút “Hoàn tất”, Haravan sẽ post tạo vận đơn vào “Link tạo vận đơn” cho đơn hàng

- "external_code" dùng để check trùng, Nhà vận chuyển cần lưu unique field này.

- Khi tạo vận đơn, nhà vận chuyển cần check external_code đã tồn tại hay chưa, nếu có rồi thì báo trùng, trả mã lỗi 412.

- Haravan sẽ dùng Link lấy chi tiết vận đơn theo external_code (get_by_external_code_url) để kiểm tra status của vận đơn , đồng thời check trước khi retry tạo lại vận đơn (trong trường hợp create bị timeout, fail)

-Khi trả lại data cho api, bắt buộc phải response các phiêu tương ứng như data mẫu bên dưới, nếu không có data thì truyền giá trị default (null, string rỗng, 0, giá trị default của của field đó nếu có)

5.1 Request

Method

URL

POST

Link tạo vận đơn (create_order_url)

Header:  Content-Type: application/json
X-Haravan-Hmac-Sha256: #{hmac_sha256}
X-Haravan-Shopid: #{shop_id}
Request raw json: 
{
  "origin": {
    "country": null,
    "country_code": null,
    "country_name": null,
    “province”: “Hồ Chí Minh”,
    "province_code": "HC",
    "district": "Quận 7",
    "district_code": "HC472",
    "ward": "Phường Tân Phong",
    "ward_code": "27490",
    "address1": null,
    "address2": null,
    "zip": null,
    "city": null,
    "phone": null,
    "name": null
  },
  "destination": {
    "country": null,
    "country_code": null,
    "country_name": null,
    “province”: “Hồ Chí Minh”,
    "province_code": "HC",
    "district": "Quận 11",
    "district_code": "HC476",
    "ward": "Phường 15",
    "ward_code": "27208",
    "address1": null,
    "address2": null,
    "zip": null,
    "city": null,
    "phone": null,
    "name": null
  },
  "items": [
    {
      "name": "cơn mưa ngang đường bộ đội",
      "sku": "MKNU_001",
      "quantity": 1,
      "grams": 5,
      "price": 500000,
      "product_id": 10000134905,
      "variant_id": 10000035069
    }
  ],
  "cod_amount": 500000, 
  "total_grams": 10, 
  " external_order_id ": 1001768979, 
  " external_fulfillment_id ": 1010281064, 
  "location_id": 0,
  "note": null,
  "shipping_rate_id": 123456,
  "external_code": "1000113763_1001768979_1010281064",
  "insurance_price": 0,
  "payment_method": null,
  "package_length": 0,
  "package_width": 0,
  "package_height": 0,
  "coupon_code": null,
  "is_drop_off": false,
  "is_view_before": false
}

STT

Thuộc tính

Mô tả

1

hmac_sha256 (string)

Mã xác thực từ haravan post vào, cách chứng thực được miêu tả ở mục đầu.

2

shop_id (string)

Id shop tạo vận đơn

3

origin (object)

Nơi chuyển

3.1

country (string)

Quốc gia

3.2

country_code (string)

Mã quốc gia

3.3

country_name (string)

Tên quốc gia

3.4

province (string)

Tên tỉnh thành

3.5

province_code (string)

Mã Tỉnh/Thành

3.6

district (string)

Tên Quận/Huyện

3.7

district_code (string)

Mã Quận/Huyện

3.8

ward (string)

Tên Phường/Xã

3.9

ward_code (string)

Mã Phường/Xã

3.10

address1(string)

Địa chỉ 1

3.11

address2 (string)

Địa chỉ 2

3.12

zip (string)

Zip

3.13

city (String)

Thành phố

3.14

phone  (string)

Số điện thoại

3.15

name (string)

Tên

4

destination (object)

Nơi nhận (Ý nghĩa các field trong destination tương tự như origin.)

5

items (array)

List sản phẩm cần vận chuyển

5.1

name (string)

Tên sản phẩm

5.2

sku (string)

Mã SKU

5.3

quantity (int)

 Số lượng

5.4

grams (decimal)

Trọng lượng trên sản phẩm

5.5

price (decimal)

Giá

5.6

product_id (long)

Mã sản phẩm

5.7

variant_id

Mã biến thể của sản phẩm

6

cod_amount (decimal)

Số tiền thu hộ COD

7

total_grams (decimal)

Tổng khối lượng các item

8

external_order_id (long)

Order id của shop

9

external_fulfillment_id (long)

Mã vận chuyển

10

external_store_id (long)

Mã shop

11

external_code (string)

= external_store_id + ”_” + external_order_id + “_” + external_fulfillment_id

12

note (string)

Ghi chú

13

shipping_rate_id (int)

Là service_id nhận được khi post lấy danh sách gói vận chuyển

14

insurance_price (decimal)

Tiền bảo hiểm:
Đơn vị tính: vnd

15

payment_method (string)

Phương thức thanh toán

16

package_length (int)

Chiều dài gói hàng.
Đơn vị tính: cm

17

package_width (int)

Chiều rộng gói hàng.
Đơn vị tính: cm

18

package_height (int)

Chiều cao gói hàng.
Đơn vị tính: cm

19

coupon_code (string)

Mã khuyến mãi

20

is_drop_off (bool)

Gửi hàng tại điểm:
true: Có
false: Không

21

is_view_before (bool)

Được xem hàng trước:
true: Có
false: Không

5.2 Response

Status

Response

200

// Thành công
{
"error": false,
"message": "",
"data": {
         "tracking_number": "123456",
         "shipping_fee": 123123,
          "tracking_url": "https://abc.com/tracking_url",
          "cod_amount": 500000,
          "external_code": "1000113763_1001768979_1010281064",
          "external_order_id": 1001768979,
          "external_fulfillment_id": 1010281064,
          "status": "delivered",
          "cod_status": "paid",
          "created_at": "2020-09-09T11:06:11.643Z",
          "ready_to_pick_date": null,
          "picking_date": null,
          "delivering_date": "2020-09-09T11:06:12.643Z ",
          "delivered_date": "2020-09-09T11:06:13.643Z ",
          "return_date": null, 
          "not_meet_customer_date": null,
          "waiting_for_return_date": null,
          "cod_paid_date": null,
          "cod_receipt_date": null

 }
}

200

// Thất bại
{
"error": true,
"message": "Đã có lỗi xảy ra ...... ",
"data": null
}

STT

Thuộc tính

Mô tả

1

tracking_number (string)

Mã vận đơn

2

shipping_fee  (decimal)

Phí vận chuyển

3

tracking_url (string)

Link xem chi tiết vận đơn

4

cod_amount (decimal)

Số tiền thu hô COD

5

external_code (string)

Mã External Code

6

external_order_id (long)

Id đơn hàng trên hệ thống Haravan (unique trên toàn hệ thống Haravan)

7

external_fulfillment_id (long)

Mã vận chuyển

8

status (string)

Trạng thái vận đơn:

pending: Chờ xử lý,

ready_to_pick: Chờ lấy hàng,

picking: Đang đi lấy,

delivering: Đang giao hàng,

delivered: Đã giao hàng,

cancel: Hủy giao hàng,

return: Chuyển hoàn,

not_meet_customer: Không gặp khách,

waiting_for_return: Chờ chuyển hoàn

9

cod_status (string)

Trạng thái thu hộ COD:

none: Không thu hộ,

pending: Chờ xử lý,

paid: Nhà vận chuyển đã thu tiền của khách hàng,

receipt: Shop đã nhận được tiền từ nhà vận chuyển,

not_receipt: Chưa nhận tiền

10

created_at (datetime)

Thời điểm tạo giao hàng

11

ready_to_pick_date (datetime)

Thời điểm chuyển qua trạng thái “sẵn sàng giao”
Default: null

12

picking_date (datetime)

Thời điểm chuyển qua trạng thái “chọn giao hàng”
Default: null

13

delivering_date (datetime)

Thời điểm chuyển qua trạng thái “Đang giao hàng”
Default: null

14

delivered_date (datetime)

Thời điểm chuyển qua trạng thái “Đã giao hàng”
Default: null

15

return_date (datetime)

Thời điểm chuyển qua trạng thái “Trả hàng”
Default: null

16

not_meet_customer_date (datetime)

Thời điểm chuyển qua trạng thái “Không gặp khách hàng”

17

waiting_for_return_date (datetime)

Thời điểm chuyển qua trạng thái “Chờ chuyển hoàn”
Default: null

18

cod_paid_date (datetime)

Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD”
Default: null

19

cod_receipt_date (datetime)

Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD”.
Default: null

20

error_code (string)

Mã lỗi

21

error (string)

Lỗi

6. Hủy vận đơn cho đơn hàng

6.1 Request

Method

URL

DELETE

Link hủy vận đơn (cancel_order_url)

Header:  Content-Type: application/json
X-Haravan-Hmac-Sha256: #{hmac_sha256}
Request raw json:
{
   tracking_number: "123456"
}

STT

Thuộc tính

Mô tả

1

hmac_sha256 (string)

Mã xác thực từ haravan post vào, cách chứng thực được miêu tả ở mục đầu.

2

tracking_number (string)

Mã vận đơn

6.2 Response

Status

Response

200

{
     "error":false,
      "message": "",
      "data":{
          "tracking_number": "123456",
          "shipping_fee": 10000,
          "tracking_url": "https://abc.com/tracking_url",
          "cod_amount": 5000,
          "status": "Cancel"
      }
}

200

//trường hợp lỗi
{
      "error": true,
      "message": "message error",
      "data": null
}

STT

Thuộc tính

Mô tả

1

tracking_number (string)

Mã vận đơn

2

shipping_fee (decimal)

Phí vận chuyển

3

tracking_url (string)

Link xem chi tiết vận đơn

4

cod_amount (decimal)

Số tiền thu hô COD

5

status (string)

Trạng thái vận đơn:

Cancel: Hủy giao hàng