Đặ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
​
Quy ước chung:
- Đối tác cần phải truy vấn những headers mà CNV phải bắt buộc truyền lên:
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)
Thông tin cấp bậc và chính sách ưu đãi của khách hàng:
- Endpoint: /api/v1/customers/points-information
- Method: GET
- Tham số cho các đối tác truyền lên:
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
        }
    ]
}
Cập nhật thông tin khách hàng:
- Endpoint: /api/webhook/customers
- Method: POST
- Tham số body cho các đối tác truyền lên:
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ó
email
Đị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ó
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"
}
Change log - Previous
Back Office
Last modified 1yr ago
Copy link
Contents
Quy ước chung: - Đối tác cần phải truy vấn những headers mà CNV phải bắt buộc truyền lên:
Thông tin cấp bậc và chính sách ưu đãi của khách hàng: - Endpoint: /api/v1/customers/points-information - Method: GET - Tham số cho các đối tác truyền lên:
Cập nhật thông tin khách hàng: - Endpoint: /api/webhook/customers - Method: POST - Tham số body cho các đối tác truyền lên: