API CARRIER SERVICE
- I. Chuẩn bị
- II. Api nhà vận chuyển request tới Haravan
- 1. Api lấy danh sách nhà vận chuyển
- 2. Api lấy thông tin kết nối với nhà vận chuyển
- 3. Api tạo kết nối với nhà vận chuyển
- 4. Api cập nhật kết nối với nhà vận chuyển
- 5. Api xóa kết nối với nhà vận chuyển
- 6. Cập nhật trạng thái đang đi lấy
- 7. Cập nhật trạng thái đang giao hàng
- 8. Cập nhật trạng thái đã giao hàng
- 9. Cập nhật trạng thái hủy giao hàng
- 10. Cập nhật trạng thái chuyển hoàn
- 11. Cập nhật trạng thái không gặp khách hàng
- 12. Cập nhật trạng thái chờ chuyển hoàn
- 13. Cập nhật trạng thái đã thu COD
- 14. Cập nhật trạng thái đã nhận COD
- III. Api Haravan request tới nhà vận chuyển
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:
- https://docs.haravan.com/blogs/omni/create-app-and-connect-api
- https://www.youtube.com/watch?v=gzJ0_qbrvYM&feature=youtu.be
+ 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: |
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 |
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 |
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 |
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:
|
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.
- 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.
- Để 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ệ |
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 |
8 | Max_delivery_date (datetime) | Thời gian vận chuyển chậm nhất |
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” |
12 | picking_date (datetime) | Thời điểm chuyển qua trạng thái “chọn giao hàng” |
13 | delivering_date (datetime) | Thời điểm chuyển qua trạng thái “Đang giao hàng” |
14 | delivered_date (datetime) | Thời điểm chuyển qua trạng thái “Đã giao hàng” |
15 | return_date (datetime) | Thời điểm chuyển qua trạng thái “Trả hàng” |
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” |
18 | cod_paid_date (datetime) | Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD” |
19 | cod_receipt_date (datetime) | Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD” |
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” |
12 | picking_date (datetime) | Thời điểm chuyển qua trạng thái “chọn giao hàng” |
13 | delivering_date (datetime) | Thời điểm chuyển qua trạng thái “Đang giao hàng” |
14 | delivered_date (datetime) | Thời điểm chuyển qua trạng thái “Đã giao hàng” |
15 | return_date (datetime) | Thời điểm chuyển qua trạng thái “Trả hàng” |
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” |
18 | cod_paid_date (datetime) | Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD” |
19 | cod_receipt_date (datetime) | Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD |
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: |
15 | payment_method (string) | Phương thức thanh toán |
16 | package_length (int) | Chiều dài gói hàng. |
17 | package_width (int) | Chiều rộng gói hàng. |
18 | package_height (int) | Chiều cao gói hàng. |
19 | coupon_code (string) | Mã khuyến mãi |
20 | is_drop_off (bool) | Gửi hàng tại điểm: |
21 | is_view_before (bool) | Được xem hàng trước: |
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” |
12 | picking_date (datetime) | Thời điểm chuyển qua trạng thái “chọn giao hàng” |
13 | delivering_date (datetime) | Thời điểm chuyển qua trạng thái “Đang giao hàng” |
14 | delivered_date (datetime) | Thời điểm chuyển qua trạng thái “Đã giao hàng” |
15 | return_date (datetime) | Thời điểm chuyển qua trạng thái “Trả hàng” |
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” |
18 | cod_paid_date (datetime) | Thời điểm chuyển qua trạng thái “Đã nhận tiền thu hộ COD” |
19 | cod_receipt_date (datetime) | Thời điểm chuyển qua trạng thái “Đối soát tiền thu hộ COD”. |
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 |