Đặc tả RESTFUL API V2.3.2

Đặc tả kết nối giữa hệ thống CNV LOYALTY và hệ thống của đối tác

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

- 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

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)

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

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

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

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

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

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

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

- 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

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

order_billing_address

Địa chỉ thanh toán (mô tả ở Thông tin địa chỉ)

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

total_price

Tổng tiền

payment_method

Phương thức thanh toán

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

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

order_items

Các sản phẩm của đơn hàng (mô tả ở Thông tin chi tiết đơn hàng)

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

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

value

Giá trị giảm

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

image_path

Hình ảnh sản phẩm

Không

quantity

Số lượng

price

Giá sản phẩm

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

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

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

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

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

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

collection_id

Mã danh mục sản phẩm

- 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

collection_id

Mã danh mục sản phẩm bên CNV

- Kết quả:

{

"message": "ok"

}