Đặc tả RESTFUL API V2.3.2
Nội dung tài liệu
Thông tin cấp bậc và chính sách ưu đãi của khách hàng
Cập nhật thông tin khách hàng
Tạo/Sửa/Xóa sản phẩm
Tạo và cập nhật đơn hàng
Tạo mới ưu đãi
Tham số | Giá trị |
Accept | application/json |
Content-Type | application/json; charset=UTF-8 |
X-Client-Id | (CNV sẽ cung cấp cho đối tác mã id để có thể truy vấn đến API) |
X-Client-Secret | (CNV sẽ cung cấp cho đối tác mã secret để có thể truy vấn đến API) |
Tham số | Mô tả | Bắt buộc |
phone | Số điện thoại | Có |
- Kết quả:
{
"total_points": 100,
"used_points": 0,
"points": 100,
"level_key": 1,
"level_title": "Mới",
"level_description": "Ưu đãi tặng ngay Voucher 25.000đ áp dụng cho hóa đơn trên 100.000đ tại ABC",
"rewards": [
{
"title": "Ưu đãi db",
"type": "percent",
"value": 50,
"minimum_apply": 100000,
"maximum_discount": 50000
}
]
}
Tham số | Mô tả | Bắt buộc |
ref_id | ID khách hàng của bên đối tác, truyền vào để CNV có thể đối chiếu được khách hàng bên hệ thống đối tác | Không |
first_name | Tên khách hàng | Không |
last_name | Họ khách hàng | Không |
phone | Số điện thoại | Có |
Địa chỉ Email | Không | |
full_address | Địa chỉ đầy đủ | Không |
address | Địa chỉ ngắn | Không |
sex | Giới tính (giá trị: male, female) | Có |
birthday | Ngày sinh (định dạng: Y-m-d) | Không |
avatar_url | Hình ảnh cá nhân | Không |
province | Tỉnh thành phố | Không |
district | Quận/Huyện | Không |
country | Quốc gia | Không |
map_latitude | Vĩ độ | Không |
map_longitude | Kinh độ | Không |
- Body mẫu cho quý đối tác tham khảo:
{
"data":{
“phone”: "09876554321",
“first_name”: "CNV",
“last_name”: "TEST"
}
}
Tạo và cập nhật sản phẩm: - Endpoint: /api/webhook/products - Method: POST - Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
id | ID sản phẩm của CNV, quý đối tác sẽ phải lưu lại ID sản phẩm bên CNV để có thể cập nhật sản phẩm đã có sẵn trên hệ thống CNV, nếu tạo sản phẩm mới, quý đối tác không cần phải truyền ID lên. | Không |
title | Tên sản phẩm | Có |
body_html | Nội dung sản phẩm | Không |
options | Thuộc tính sản phẩm (xem ví dụ response) | Không |
variants | Biến thể của sản phẩm (mô tả ở Thông tin biến thể), ít nhất là một biến thể, biến thể đầu tiên là biến thể mặc định | Không |
type/product_type_id | Loại sản phẩm, truyền tên hệ thống sẽ tự động tạo product_type hoặc truyền lên product_type_id | Không |
collect | Dạng mảng, danh sách các nhóm sản phẩm ví dụ [1, 2, 3] | Không |
vendor | Nhà sản xuất | không |
grams | Gram | Không |
visible | Cho phép hiển thị Truyền vào : true hoặc fasle | Không |
price | Giá tiền, trường hợp sản phẩm không có biến thể | Không |
product_images | Hình ảnh sản phẩm (dữ liệu dạng mảng chưa các object hình ảnh - chi tiết ở mục Thông tin hình ảnh) | Không |
ref_3rd_party_id | Id sản phẩm của quý đối tác | Không |
ref_3rd_party_type | Tên của quý đối tác (viết theo kiểu snake case, ví dụ: kas, kiotviet, ipos, … | Không |
Thông tin biến thể:
Tham số | Mô tả | Bắt buộc |
id | ID biến thể sản phẩm của CNV, quý đối tác sẽ phải lưu lại ID biến thể sản phẩm bên CNV để có thể cập nhật biến thể sản phẩm đã có sẵn trên hệ thống CNV, nếu tạo biến thể sản phẩm mới, quý đối tác không cần phải truyền ID lên. | Không |
barcode | Mã barcode | Không |
sku | Mã sản phẩm | Không |
price | Giá sản phẩm | Có |
compare_at_price | Giá so sánh | Không |
allows_to_buy | Cho phép mua hàng Truyền vào : true hoặc false | Có |
option1 | Tùy chọn 1 | Không |
option2 | Tùy chọn 2 | Không |
option3 | Tùy chọn 3 | Không |
inventory_quantity | Số lượng tồn kho | Có |
inventory_policy | Cho phép đặt sản phẩm khi hết hàng Truyền vào : Cho phép : continue Không cho phép : deny | Có |
ref_3rd_party_id | Id biến thể sản phẩm của quý đối tác | Không |
ref_3rd_party_type | Tên của quý đối tác (viết theo kiểu snake case, ví dụ: kas, kiotviet, ipos, … | Không |
Thông tin hình ảnh
Tham số | Mô tả | Bắt buộc |
src | Đường dẫn hình ảnh | Có |
position | Vị trí hình ảnh (nếu bỏ trống thì tự động bắt đầu là 1 và tăng dần theo số lượng) | Không |
width | Chiều dài (mặc định: 0) | Không |
height | Chiều rộng (mặc định: 0) | Không |
- Body mẫu cho quý đối tác tham khảo: {
"data": {
"id": 270,
"title": "Áo Hoodies",
"body_html": "<p>Test</p>",
"product_images": [
{
"src": "https://gravatar.com/userimage/186621961/c4b1287efd588937dca78a84ba202c1c.png",
"position": 1,
"width": 100,
"height": 100
}
], "ref_3rd_party_id": "string",
"ref_3rd_party_type": "string",
"variants": [
{
"id": 1,
"barcode": "SP2089",
"sku": "SP2089",
"price": 1000000,
"compare_at_price": 1200000,
"inventory_quantity": 10,
"inventory_policy": "continue",
"ref_3rd_party_id": "string",
"ref_3rd_party_type": "string"
}
],
"type": "Áo",
"vendor": "Việt Nam",
"collections": [1, 2, 3],
"visible": true
}
}
Xóa sản phẩm: - Endpoint: /api/webhook/products - Method: DELETE - Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
id | ID sản phẩm bên CNV | Có |
- Body mẫu cho quý đối tác tham khảo: {
"data": {
"id": 168
}
}
Tạo và cập nhật đơn hàng: - Endpoint: /api/webhook/orders - Method: POST - Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
id | ID đơn hàng của CNV, quý đối tác sẽ phải lưu lại ID đơn hàng bên CNV để có thể cập nhật đơn hàng đã có sẵn trên hệ thống CNV, nếu tạo đơn mới, quý đối tác không cần phải truyền ID lên. | Không |
customer_phone | Số điện thoại khách hàng | Có |
name | Mã đơn hàng bên đối tác, nếu không truyền lên, CNV sẽ tự khởi tạo mã đơn hàng. | Không |
note | Ghi chú khách hàng | Không |
source | Nguồn đặt hàng | Không |
promotion_code | Mã giảm giá (mã ưu đãi) | Không |
promotion_note | Ghi chú giảm | Không |
promotion_price | Giá giảm | Không |
reward | Thông tin ưu đãi (mô tả ở Thông tin ưu đãi) | Không |
order_shipping_address | Địa chỉ giao hàng (mô tả ở Thông tin địa chỉ) | Có |
order_billing_address | Địa chỉ thanh toán (mô tả ở Thông tin địa chỉ) | Có |
shipping_note | Ghi chú vận chuyển | Không |
shipping_price | Giá vận chuyển | Không |
subtotal_price | Tổng tạm | Có |
total_price | Tổng tiền | Có |
payment_method | Phương thức thanh toán | Có |
status | Trạng thái đơn hàng Chờ xác nhận: wait_for_confirm Chờ xử lý: wait_for_process Vận chuyển: shipping Đã hoàn thành: completed Đã hủy: cancelled | Có |
payment_status | Trạng thái thanh toán Chờ thanh toán: wait_for_pay Đã thanh toán: paid Thanh toán thất bại: failed | Có |
order_items | Các sản phẩm của đơn hàng (mô tả ở Thông tin chi tiết đơn hàng) | Có |
ref_3rd_party_id | Id đơn hàng của quý đối tác | Không |
ref_3rd_party_type | Tên của quý đối tác (viết theo kiểu snake case, ví dụ: kas, kiotviet, ipos, …) | Không |
Thông tin ưu đãi:
Tham số | Mô tả | Bắt buộc |
title | Tiêu đề ưu đãi | Có |
body_html | Nội dung ưu đãi (có thể lưu dưới dạng thẻ HTML) | Không |
image_path | Ảnh đại diện chương trình ưu đãi | Không |
type | Loại giảm giá Giá trị: value Phần trăm: percent | Có |
value | Giá trị giảm | Có |
Thông tin địa chỉ:
Tham số | Mô tả | Bắt buộc |
name | Họ và tên khách hàng | Không |
phone | Số điện thoại | Không |
full_address | Địa chỉ đầy đủ | Không |
address | Số + tên đường | Không |
ward | Phường/Xã | Không |
district | Quận/Huyện | Không |
province | Tỉnh/Thành Phố | Không |
country | Quốc gia | Không |
map_latitude | Vĩ độ | Không |
map_longitude | Kinh độ | Không |
postal_code | Mã bưu chính | Không |
Thông tin chi tiết đơn hàng:
Tham số | Mô tả | Bắt buộc |
title | Tên sản phẩm | Có |
image_path | Hình ảnh sản phẩm | Không |
quantity | Số lượng | Có |
price | Giá sản phẩm | Có |
discount_value | Chiết khấu | Không |
option1 | Tùy chọn 1 | Không |
option2 | Tùy chọn 2 | Không |
option3 | Tùy chọn 3 | Không |
ref_3rd_party_id | Id biến thể sản phẩm của quý đối tác | Không |
ref_3rd_party_type | Tên của quý đối tác (viết theo kiểu snake case, ví dụ: kas, kiotviet, ipos, …) | Không |
- Body mẫu cho quý đối tác tham khảo:
{
"data": {
"id": null,
"name": "ABCXYZ123",
"note": "Ghi chú test",
"source": "cnv ",
"promotion_code": null,
"promotion_note": null,
"promotion_price": null,
"shipping_note": null,
"shipping_price": null,
"subtotal_price": 2000000.0,
"total_price": 2000000.0,
"payment_method": "cod",
"status": null,
"payment_status": null,
"ref_3rd_party_id": "string",
"ref_3rd_party_type": "string",
"order_shipping_address": {
"name": "CNV TEST",
"phone": "0987654321",
"full_address": "102 NĐC",
"address": "102 NĐC",
"ward": null,
"district": null,
"province": null,
"country": null,
"map_latitude": null,
"map_longitude": null,
"postal_code": null
},
"order_billing_address": {
"name": "CNV TEST 2",
"phone": "0987654321",
"full_address": "102 NĐC",
"address": "102 NĐC",
"ward": null,
"district": null,
"province": null,
"country": null,
"map_latitude": null,
"map_longitude": null,
"postal_code": null
},
"order_items": [
{
"title": "TRIỆT LÔNG",
"image_path": null,
"quantity": 1,
"discount_value": null,
"price": 500000.0,
"ref_3rd_party_id": "string",
"ref_3rd_party_type": "string"
}
]
}
}
- Kết quả:
{
"message": "ok",
"data": {
"id": 84,
"name": "ABCXYZ123",
"note": "Ghi chú test",
"promotion_code": null,
"promotion_note": null,
"promotion_price": 0,
"shipping_note": null,
"shipping_price": 0,
"shipping_id": null,
"discount_value": null,
"discount_percent": null,
"discount_note": null,
"subtotal_price": 2000000,
"total_price": 2000000,
"earned_points": 200,
"rated": null,
"payment_method": "cod",
"payment_method_name": "Cod",
"paid_at": null,
"confirmed_at": null,
"processed_at": null,
"closed_at": null,
"cancelled_at": null,
"cancel_reason": null,
"order_shipping_address": {
"id": 133,
"name": "CNV TEST",
"phone": "0987654321",
"full_address": "102 NĐC",
"address": "102 NĐC",
"ward": null,
"district": null,
"province": null,
"country": null,
"map_latitude": null,
"map_longitude": null,
"postal_code": null
},
"order_billing_address": {
"id": 133,
"name": "CNV TEST 2",
"phone": "0987654321",
"full_address": "102 NĐC",
"address": "102 NĐC",
"ward": null,
"district": null,
"province": null,
"country": null,
"map_latitude": null,
"map_longitude": null,
"postal_code": null
},
"order_shipping_type": null,
"status": "wait_for_confirm",
"payment_status": "wait_for_pay",
"order_items": [
{
"id": 130,
"order_id": 84,
"variant_id": null,
"product_id": null,
"topping_item_id": null,
"parent_id": null,
"children": [],
"title": "TRIỆT LÔNG",
"image_path": "https://gravatar.com/userimage/186621961/c4b1287efd588937dca78a84ba202c1c.png",
"quantity": 1,
"grams": 0,
"original_price": 500000,
"discount_value": 0,
"price": 500000,
"option1": null,
"option2": null,
"option3": null
}
],
"voucher_name": null,
"ref_3rd_party_id": "string",
"ref_3rd_party_type": "string",
"created_at": "2020-09-17T17:12:56+07:00",
"updated_at": "2020-09-17T17:12:56+07:00"
}
}
Tạo mới ưu đãi: - Endpoint: /api/v1/import-rewards - Method: POST - Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
title | Tiêu đề ưu đãi | Có |
started_at | Thời gian bắt đầu áp dụng (Định dạng: Y-m-d H:i:s) | Không |
expired_at | Thời gian kết thúc (Định dạng: Y-m-d H:i:s) | Không |
file | File danh sách các mã ưu đãi, quý đối tác truyền dưới dạng file, chỉ áp dụng file : xls, xlsx Liên hệ CNV để lấy file mẫu. | Không |
- Kết quả:
{
"message": "ok"
}
Danh sách loại sản phẩm: - Endpoint: /api/product-types - Method: GET
- Kết quả:
{
"data": [
{
"id": 1,
"name": “Café”,
"summary": “Café”,
"position": 1,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
{
"id": 2,
"name": “Trà sữa”,
"summary": “Trà sữa”,
"position": 2,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
]
}
Thêm loại sản phẩm:
- Endpoint: /api/webhook/product-types - Method: POST
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
name | Tên loại sản phẩm | Có |
summary | Mô tả loại sản phẩm | Không |
position | Vị trí | Không |
- Kết quả:
{
"message": "ok",
"data": {
"id": 1,
"name": “Café”,
"summary": “Café”,
"position": 1,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
}
Cập nhật loại sản phẩm:
- Endpoint: /api/webhook/product-types - Method: PUT
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
name | Tên loại sản phẩm | Có |
summary | Mô tả loại sản phẩm | Không |
position | Vị trí | Không |
- Kết quả:
{
"message": "ok",
"data": {
"id": 1,
"name": “Café”,
"summary": “Café”,
"position": 1,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
}
Danh sách danh mục sản phẩm: - Endpoint: /api/custom-collections - Method: GET
- Kết quả:
{
"data": [
{
"id": 1,
"title": “Menu chính”,
"body_html": “<p>Menu chính</p>”,
"image_url": “https://via.placeholder.com/150”,
"position": 1,
"is_flash_sale": true,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
{
"id": 2,
"title": “Menu phụ”,
"body_html": “<p>Menu phụ</p>”,
"image_url": “https://via.placeholder.com/150”,
"position": 2,
"is_flash_sale": false,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
},
]
}
Thêm danh mục sản phẩm:
- Endpoint: /api/webhook/custom-collections - Method: POST
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
title | Tiêu đề danh mục sản phẩm | Có |
body_html | Nội dụng danh mục sản phẩm (có thể lưu dưới dạng thẻ HTML) | Không |
image_url | Đường dẫn hình ảnh danh mục sản phẩm | Không |
is_flash_sale | Danh mục flashsale (true, false) | Không |
visible | Ẩn hiện (true, false) | Không |
published_at | Ngày đăng tải | Không |
position | Vị trí | Không |
- Kết quả:
{
"message": "ok",
"data": {
"id": 2,
"title": “Menu phụ”,
"body_html": “<p>Menu phụ</p>”,
"image_url": “https://via.placeholder.com/150”,
"position": 2,
"is_flash_sale": false,
"published_at": “2020-10-15T10:48:58+07:00”,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
}
}
Cập nhật danh mục sản phẩm:
- Endpoint: /api/webhook/custom-collections/{id} - Method: PUT
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
title | Tiêu đề danh mục sản phẩm | Có |
body_html | Nội dụng danh mục sản phẩm (có thể lưu dưới dạng thẻ HTML) | Không |
image_url | Đường dẫn hình ảnh danh mục sản phẩm | Không |
is_flash_sale | Danh mục flashsale (true, false) | Không |
visible | Ẩn hiện (true, false) | Không |
published_at | Ngày đăng tải | Không |
position | Vị trí | Không |
- Kết quả:
{
"message": "ok",
"data": {
"id": 2,
"title": “Menu phụ”,
"body_html": “<p>Menu phụ</p>”,
"image_url": “https://via.placeholder.com/150”,
"position": 2,
"is_flash_sale": false,
"published_at": “2020-10-15T10:48:58+07:00”,
"created_at": “2020-10-15T10:48:58+07:00”,
"updated_at": “2020-10-15T10:48:58+07:00”,
}
}
Thêm 1 sản phẩm vào 1 nhóm sản phẩm:
- Endpoint: /api/webhook/collects - Method: POST
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
product_id | Mã sản phẩm | Có |
collection_id | Mã danh mục sản phẩm | Có |
- Kết quả:
{
"message": "ok"
}
Gỡ bỏ 1 sản phẩm khỏi 1 nhóm sản phẩm:
- Endpoint: /api/webhook/collects - Method: DELETE
- Tham số body cho các đối tác truyền lên:
Tham số | Mô tả | Bắt buộc |
product_id | Mã sản phẩm bên CNV | Có |
collection_id | Mã danh mục sản phẩm bên CNV | Có |
- Kết quả:
{
"message": "ok"
}
