Kết nối API
(Ngành Dịch vụ làm đẹp)
KiotViet Public API được phát triển để hỗ trợ việc tích hợp và trao đổi dữ liệu giữa KiotViet và các nền tảng website, CRM…
Phạm vi áp dụng: gian hàng sử dụng gói Cao cấp của KiotViet.
KiotViet Public API cung cấp cơ chế đọc và ghi các đối tượng sau:
Nhóm hàng: lấy danh sách nhóm hàng hóa với các thông tin về tên nhóm hàng và quan hệ giữa các nhóm hàng
Hàng hóa: lấy thông tin sản phẩm, tạo mới, sửa, xóa sản phẩm, thuộc tính của sản phẩm
Danh sách chi nhánh
Bảng giá
- Lưu ý : Các Params có ? ở trong giá trị là những trường có thể không truyền.
- Kiotviet API xác thực dựa trên cơ chế sử dụng client_secret đã được mã hóa. Để kết nối được hệ thống cần phải có thông tin Mã bảo mật.
- Mã API trên KiotViet chỉ hiển thị trên tài khoản có vai trò admin của chủ gian hàng.
- Trên màn hình Quản lý, từ menu Thiết lập, bạn chọn Cửa hàng.
– Bạn chọn Kết nối API. Trên Thông tin kết nối API bạn thao tác như sau:
- Nhấn Chỉnh sửa.
- Nhập Tên kết nối.
- Chọn Trạng thái Hoạt động.
- Nhấn Tạo mã.
- Đọc kỹ Điều khoản sử dụng và tích chọn Tôi đã đọc và đồng ý với điều khoản trên → nhấn Đồng ý.
- Nhấn Lưu.
– Để ngừng hoạt động kết nối API, bạn nhấn Chỉnh sửa → chọn Trạng thái Ngừng hoạt động → nhấn Lưu để hoàn tất.
Mục này mô tả thông tin chi tiết của từng API. Các thông tin bao gồm:
Tên API
Mục đích sử dụng của API
Cấu trúc của API
Chi tiết tham số trong request
Nội dung response trả về
- Kiotviet API xác thực dựa trên cơ chế sử dụng client_secret đã được mã hóa. Để kết nối được hệ thống cần phải có thông tin Mã bảo mật. Thông tin này được truy cập vào mục Thiết lập cửa hàng bằng tài khoản admin → chọn Kết nối API.
- Trong trường hợp không thể lấy được thông tin trên vui lòng liên hệ với bộ phận CSKH để được hỗ trợ.
- Sau khi có được thông tin Mã bảo mật (client_secret). Có thể sử dụng mã này để truy cập api
- Lưu ý: Toàn bộ các API đều phải có header trong request với thông tin:
"PublicApiKey" : mã bảo mật
“Accept” : application/json
Mô tả chi tiết cho các liên quan đến thông tin nhóm hàng hóa như sau:
Lấy danh sách nhóm hàng:
- Mục đích sử dụng: Trả về toàn bộ danh mục hàng hóa (nhóm hàng hóa). Danh sách này được sắp xếp theo thứ tự bảng chữ cái (a-z). Hệ thống chỉ cho phép nhóm hàng hóa có tối đa 3 cấp, và không cho phép xóa nhóm hàng cha nếu đang có chứa nhóm hàng con và không cho phép xóa nhóm hàng con nếu đang được sử dụng.
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/category
- Request: Sử dụng hàm GET với tham số
“pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
“currentItem”: int, // lấy dữ liệu từ bản ghi hiện tại, nếu không nhập thì mặc định là 0
“hierachicalData”: Boolean, // nếu HierachicalData=true thì mình sẽ lấy nhóm hang theo cấp mà không quan tâm lastModifiedFrom. Ngược lại, HierachicalData=false thì sẽ lấy 1 list nhóm hang theo lastModifiedFrom nhưng không có phân cấp
- Response:
Nếu hierachicalData là true
Nếu hierachicalData là fasle
Mô tả chi tiết cho các liên quan đến thông tin hàng hóa như sau:
Lấy danh sách hàng hóa:
- Mục đích sử dụng: Trả về toàn bộ hàng hóa theo cửa hàng đã được xác nhận (authenticated retailer)
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/product
- Request: Sử dụng hàm GET với tham số:
“pageSize”: int, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
“currentItem”: int, // lấy dữ liệu từ bản ghi currentItem
“CategoryIds”: long, //Id nhóm hàng cần filter
"ProductTypes": bool, //loại hàng hóa
"isActive": bool? //Hàng đang kinh doanh,
"name": string //search hàng hóa theo tên
}
Nếu có "OrderDirection", chọn sắp xếp kết quả về theo:
- ASC (Mặc định)
- DESC
“includeRemoveIds”: Boolean //Có lấy thông tin danh sách Id bị xoá dựa trên lastModifiedFrom,
“productTypes”: int? (optional) //Loại hàng hóa
Nếu có "productTypes", giá trị thuộc :
- 1 : hàng combo
- 3: hàng hóa dịch vụ
- 2: các hàng hóa còn lại
“includeMaterial”: Boolean //Có lấy thông tin danh sách hàng thành phần hay không
- Response:
- Mục đích sử dụng: Trả lại danh sách toàn bộ chi nhánh của cửa hàng đã được xác nhận
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/branches
- Request: Sử dụng hàm GET với tham số:
“pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
“currentItem”: int?,
- Response:
5.1. Lấy danh sách bảng giá
- Mục đích sử dụng: Trả về danh sách bảng giá
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/pricebook
- Request: Sử dụng hàm GET với tham số:
“includePriceBookBranch”: Boolean, optional // Có lấy thông tin danh sách chi nhánh áp dụng bảng giá
“includePriceBookCustomerGroups”: Boolean, optional // Có lấy thông tin danh sách nhóm KH áp dụng bảng giá
“includePriceBookUsers”: Boolean, optional // Có lấy thông tin danh sách người dùng áp dụng bảng giá
“currentItem”: int?,
“pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
- Response:
5.2. Lấy chi tiết bảng giá
- Mục đích sử dụng: Trả về thông tin chi tiết của bảng giá theo ID
- Phương thức và URL:
Theo Id : GET https://api-integration-booking.kiotviet.vn/public/pricebook/{id}
Request: Sử dụng hàm GET với tham số:
“id”: long // ID của bảng giá
“currentItem”: int? // lấy dữ liệu từ bản ghi hiện tại, nếu không nhập thì mặc định là 0
“pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
- Response:
- Mục đích sử dụng: Trả về danh sách hóa đơn
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/invoice
- Request: Sử dụng hàm GET với tham số:
- “branchIds”: int[], optional // Lấy theo chi nhánh
- “customerIds”: long[], optional // Id khách hàng
- “customerCode”: string, optional // Mã khách hàng
- “status”: int[], optional // Theo trạng thái hóa đơn
- “includePayment”: Boolean, optional // Có lấy thông tin thanh toán
- “includeSaleChannel”: Boolean, optional // Có lấy thông tin kênh bán
- “lastModifiedFrom”: Datetime, optional // Thời gian cập nhật
- “toDate”: Datetime, optional // Thời gian cập nhật cho đến thời điểm toDate
- “createdDate”: Datetime, optional // Thời gian tạo
- “fromPurchaseDate”: Datetime, optional // Từ ngày giao dịch
- “toPurchaseDate”: Datetime, optional // Đến ngày giao dịch
- “currentItem”: int?,
- “pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
- Response:
{ “total”: int, tổng “pageSize”: int, bao nhiêu dòng / 1 trang dữ liệu “data”: [{ “id”: long // id hóa đơn “code”: string // Mã hóa đơn “purchaseDate”: datetime// Ngày hóa đơn “branchId”: int, // Id chi nhánh “branchName”: string, // Tên chi nhánh “soldById”: long?, // Id thu ngân “soldByName”: string, // Tên thu ngân “customerId”: long?, // Id khách hàng “customerName”: string, // Tên khách hàng “code”: string, // Mã khách hàng “total”: decimal, // Khách cần trả “totalPayment”: decimal, // Khách đã trả “status”: int, // Trạng thái hóa đơn “statusValue”: string, // Trạng thái hóa đơn bằng chữ “createdDate”: datetime, // Ngày tạo “modifiedDate”: datetime, // Ngày cập nhật “payments” :[{ “id”: long, “code”: string, “amount”: decimal, “status”: byte?, “statusValue”: string, “transDate”: datetime, “bankAccount”: string, “accountId”: int?, }], // Thông tin thanh toán “invoiceOrderSurcharges” :[{ “id”: long, “invoiceId”: long?, “surchargeId”: int?, “name”: string, “value”: decimal, “price”: decimal, “createdDate”: datetime, }], // Thông tin thu khác }] “invoiceDetails” :[{ “productId”: long, “productCode”: string, “productName”: string, “quantity”: float?, “price”: decimal?, “discountRatio”: float?, “discount”: decimal?, “note”: string, }], // Chi tiết hóa đơn }] “saleChannels” :[{ “id”: int, “name”: string, “isNotDelete”: bool?, “retailerId”: int?, “position”: int?, “isActive”: bool?, “createdBy”: long?, “createdDate”: datetime?, }], // Thông tin kênh bán }] } |
- Mục đích sử dụng: Trả về chi tiết hóa đơn
- Phương thức và URL:
- GET https://api-integration-booking.kiotviet.vn/public/invoice/{id}
- GET https://api-integration-booking.kiotviet.vn/public/invoice/code/{code}
- Request: Sử dụng hàm GET với tham số:
- “id”: long, optional // Id của hóa đơn
- “code”: string, optional // Mã của hóa đơn
- Response:
{ “total”: int, tổng “pageSize”: int, bao nhiêu dòng / 1 trang dữ liệu “data”: [{ “id”: long // id hóa đơn “code”: string // Mã hóa đơn “purchaseDate”: datetime// Ngày hóa đơn “branchId”: int, // Id chi nhánh “branchName”: string, // Tên chi nhánh “soldById”: long?, // Id thu ngân “soldByName”: string, // Tên thu ngân “customerId”: long?, // Id khách hàng “customerName”: string, // Tên khách hàng “code”: string, // Mã khách hàng “total”: decimal, // Khách cần trả “totalPayment”: decimal, // Khách đã trả “status”: int, // Trạng thái hóa đơn “statusValue”: string, // Trạng thái hóa đơn bằng chữ “createdDate”: datetime, // Ngày tạo “modifiedDate”: datetime, // Ngày cập nhật “payments” :[{ “id”: long, “code”: string, “amount”: decimal, “status”: byte?, “statusValue”: string, “transDate”: datetime, “bankAccount”: string, “accountId”: int?, }], // Thông tin thanh toán “invoiceOrderSurcharges” :[{ “id”: long, “invoiceId”: long?, “surchargeId”: int?, “name”: string, “value”: decimal, “price”: decimal, “createdDate”: datetime, }], // Thông tin thu khác }] “invoiceDetails” :[{ “productId”: long, “productCode”: string, “productName”: string, “quantity”: float?, “price”: decimal?, “discountRatio”: float?, “discount”: decimal?, “note”: string, }], // Chi tiết hóa đơn }] “saleChannels” :[{ “id”: int, “name”: string, “isNotDelete”: bool?, “retailerId”: int?, “position”: int?, “isActive”: bool?, “createdBy”: long?, “createdDate”: datetime?, }], // Thông tin kênh bán }] } |
- Mục đích sử dụng: Trả về danh sách khách hàng
- Phương thức và URL: GET https://api-integration-booking.kiotviet.vn/public/customer
- Request: Sử dụng hàm GET với tham số:
- “id”: long, optional // Id của khách hàng
- “code”: string, optional // Mã của khách hàng
- Response:
{ “total”: int, tổng “pageSize”: int, bao nhiêu dòng / 1 trang dữ liệu “data”: [{ “id”: long // id khách hàng “code”: string // Mã khách hàng “name”: datetime// Tên khách hàng “gender”: Boolean?// Giới tính “birthDate”: datetime?, // Ngày sinh “contactNumber”: string// Số điện thoại “address”: string// Địa chỉ “locationName”: string, // Khu vực “wardName”: string, // Phường xã “email”: string// Email khách hàng “organization”: string// Công ty “comments”: string// Ghi chú “taxCode”: string// Mã số thuế “debt”: decimal, // Nợ hiện tại “totalInvoceid”: decimal?// Tổng bán “totalPoint”: double?// Tổng điểm “retailerId”: long?, // Id cửa hàng “createdDate”: datetime, // Ngày tạo “modifiedDate”: datetime, // Ngày cập nhật “rewardPoint”: long?// Điểm hiện tại “customerGroups” :[{ “id”: long, “name”: string, “createdDate”: datetime, }], // Thông tin nhóm khách hàng } |
- Mục đích sử dụng: Trả về chi tiết khách hàng
- Phương thức và URL:
- GET https://api-integration-booking.kiotviet.vn/public/customer/{id}
- GET https://api-integration-booking.kiotviet.vn/public/customer/{id}/code/{code}
- Request: Sử dụng hàm GET với tham số:
- “code”: string, optional // Lấy theo mã khách hàng
- “name”: string, optional // Theo tên khách hàng
- “contactNumber”: string, optional // Theo số điện thoại của khách hàng
- “includeCustomerGroup”: boolean?, optional // Lấy thông tin nhóm khách hàng hay không
- “birthDate”: datetime?, optional // Theo ngày sinh
- “groupId”: long?, optional // Theo nhóm khách hàng
- “lastModifiedFrom”: datetime, optional // Thời gian cập nhật
- “currentItem”: int?,
- “pageSize”: int?, // số items trong 1 trang, mặc định 20 items, tối đa 100 items
- Response:
{ “total”: int, tổng “pageSize”: int, bao nhiêu dòng / 1 trang dữ liệu “data”: [{ “id”: long // id hóa đơn “code”: string // Mã hóa đơn “name”: datetime// Ngày hóa đơn “gender”: Boolean?// Giới tính “birthDate”: datetime?, // Ngày sinh “contactNumber”: string// Số điện thoại “address”: string// Địa chỉ “locationName”: string, // Khu vực “wardName”: string, // Phường xã “email”: string// Email khách hàng “organization”: string// Công ty “comments”: string// Ghi chú “taxCode”: string// Mã số thuế “debt”: decimal, // Nợ hiện tại “totalInvoceid”: decimal?// Tổng bán “totalPoint”: double?// Tổng điểm “retailerId”: long?, // Id cửa hàng “createdDate”: datetime, // Ngày tạo “modifiedDate”: datetime, // Ngày cập nhật “rewardPoint”: long?// Điểm hiện tại “customerGroups” :[{ “id”: long, “name”: string, “createdDate”: datetime, }], // Thông tin nhóm khách hàng } |
- URL: https://api-integration-booking.kiotviet.vn/public/customer
- Method: POST
- Mô tả: API này cho phép tạo khách hàng cho gian hàng
- Headers:
Key | Value | Mô tả |
Accept | application/json | Định dạng dữ liệu trả về là JSON. |
PublicApiKey | lấy từ gian hàng | Key public API dùng để xác thực. |
- Body:
{ "BranchId": 1971, "Code": "PL00001", "Name": "test test", "Gender": 0, "BirthDate": "26-02-1987", "ContactNumber": "0123456789", "Address": "Hanoi", "Email": "test@gmail.com", "Comments": "comment", "TaxCode": "C10221" } |
Field | Type | Required | Note |
BranchId | int | True | Id chi nhánh tạo khách |
Code | string | True | Mã khách hàng (không trùng với mã đã tạo của khách hàng khác) (< 50 ký tự) |
Name | string | True | Tên khách hàng (< 255 ký tự) |
Gender | bool? | False | Giới tính (0-Nữ, 1-Nam, null-không xác định) |
BirthDate | datetime | False | Ngày sinh |
ContactNumber | string | False | Số điện thoại |
Address | string | False | Địa chỉ (< 255 ký tự) |
string | False | Email (đúng định dạng mail) | |
Comments | string | False | Comment cho khách hàng (< 20000ký tự) |
- Response
- Thành công => Code 200 (OK) + Info khách vừa tạo
{ "result": { "id": 282286, "code": "PL00001", "name": "test test", "gender": false, "contactNumber": "", "address": "", "email": "", "comments": "", "retailerId": 200001005, "createdDate": "2025-03-31T10:32:46.2730000", "saleChannelId": 6490 }, "message": "Tạo khách hàng thành công" } |
- Lỗi => Error Code 400 (Bad Request)
{ "message": "Bad Request", "errors": [ { "message": "Mã khách hàng là trường bắt buộc!", "code": 0 } ] } |
- Mục đích sử dụng: sửa thông tin khách hàng
- URL: https://api-integration-booking.kiotviet.vn/public/customer/{Id}
- Method: PUT
- Headers
Key | Value | Mô tả |
Accept | application/json | Định dạng dữ liệu trả về là JSON. |
PublicApiKey | lấy từ gian hàng | Key public API dùng để xác thực. |
- Request
Id : Id của khách hàng cần sửa
Body
{
"Code": "PL00002",
"Name": "test test",
"Gender": 0,
"BirthDate": "26-02-1987",
"ContactNumber": "0123456789",
"Address": "Hanoi",
"Email": "test@gmail.com",
"Comments": "comment",
"TaxCode": "C10221"
}
Note: Đối với các giá trị string
Không gửi field: Giữ nguyên giá trị
Gửi trống: update với giá trị trống.
Field | Type | Required | Note |
Code | string | False | Mã khách hàng (không trùng với mã đã tạo của khách hàng khác) (< 50 ký tự) Không được để string trống |
Name | string | False | Tên khách hàng (< 255 ký tự) Không được để string trống |
Gender | bool? | False | Giới tính (0-Nữ, 1-Nam, null-không xác định) |
BirthDate | datetime | False | Ngày sinh |
ContactNumber | string | False | Số điện thoại |
Address | string | False | Địa chỉ (< 255 ký tự) |
string | False | Email (đúng định dạng mail) | |
Comments | string | False | Comment cho khách hàng (< 20000ký tự) |
TaxCode | string | False | Mã số thuế (< 50ký tự) |
- Response
- Thành công => Code 200 (OK) + Info khách vừa sửa
{ "result": { "id": 282286, "code": "PL00001", "name": "test test", "gender": false, "contactNumber": "", "address": "", "email": "", "comments": "", "retailerId": 200001005, "createdDate": "2025-03-31T10:32:46.2730000", "saleChannelId": 6490 }, "message": "Tạo khách hàng thành công" } |
Lỗi => Error Code 400 (Bad Request)
{ "message": "Bad Request", "errors": [ { "message": "Email không hợp lệ", "code": 0 } ] } |
7.5. Danh sách nhóm khách hàng
- Tổng quan: API lấy danh sách nhóm khách hàng cho phép truy xuất danh sách các nhóm khách hàng với khả năng phân trang, tìm kiếm và sắp xếp.
- Endpoint Information
Method: GET
URL: /public/customer-group
Content-Type: application/json
- Request Parameters
- HTTP Headers
Header | Type | Required | Mô tả |
Authorization | string | ✅ Yes | Bearer token để xác thực |
- Query Parameters
Field | Type | Required | Mô tả | Ràng buộc |
PageIndex | int | ❌ No | Số trang cần lấy | Mặc định: 1, tối thiểu: 1 |
PageSize | int | ❌ No | Số lượng bản ghi trên 1 trang | Mặc định: 20, tối đa: 100 |
searchTerm | string | ❌ No | Từ khóa tìm kiếm theo tên hoặc mô tả | Tìm kiếm không phân biệt hoa thường |
sortBy | string | ❌ No | Trường sắp xếp | Name, CreatedDate (mặc định: CreatedDate) |
sortDirection | string | ❌ No | Hướng sắp xếp | Asc, Desc (mặc định: Desc) |
- Business Rules
Quy tắc | Mô tả |
Phân trang | Hệ thống sử dụng phân trang để tối ưu hiệu suất |
Tìm kiếm | Tìm kiếm theo cả tên và mô tả nhóm khách hàng |
Sắp xếp | Hỗ trợ sắp xếp theo tên và ngày tạo |
Dữ liệu theo retailer | Chỉ trả về dữ liệu thuộc retailer được xác thực |
- Response Format
- Success Response (200 OK)
Field | Type | Mô tả |
data | array | Danh sách nhóm khách hàng |
data[].id | long | ID của nhóm khách hàng |
data[].name | string | Tên nhóm khách hàng |
data[].description | string | Mô tả nhóm khách hàng |
data[].discount | decimal | Số tiền chiết khấu (có thể null) |
data[].discountRatio | decimal | Phần trăm chiết khấu (có thể null) |
data[].createdDate | datetime | Thời gian tạo |
data[].modifiedDate | datetime | Thời gian cập nhật gần nhất |
total | int | Tổng số bản ghi |
pageSize | int | Số lượng bản ghi trên trang |
timestamp | datetime | Thời gian phản hồi |
- Error Response (400 Bad Request)
Error Code | Message | Mô tả |
INVALID_PAGE_INDEX | Số trang phải lớn hơn 0 | Khi PageIndex < 1 |
INVALID_PAGE_SIZE | Kích thước trang phải từ 1 đến 100 | Khi PageSize không hợp lệ |
INVALID_SORT_FIELD | Trường sắp xếp không hợp lệ | Khi sortBy không phải Name hoặc CreatedDate |
INVALID_SORT_DIRECTION | Hướng sắp xếp không hợp lệ | Khi sortDirection không phải Asc hoặc Desc |
- Error Response (401 Unauthorized)
Error Code | Message | Mô tả |
UNAUTHORIZED | Không có quyền truy cập | Khi token không hợp lệ hoặc thiếu header |
- Example Usage
- Request Example 1 - Lấy trang đầu tiên
GET /public/customer-group?PageIndex=1&PageSize=10
- Request Example 2 - Tìm kiếm và sắp xếp
GET /public/customer-group?searchTerm=VIP&sortBy=Name&sortDirection=Asc&PageIndex=1&PageSize=20
- Success Response Example
{
"data": [
{
"id": 12345,
"name": "Khách hàng VIP",
"description": "Nhóm khách hàng có giá trị cao với đặc quyền đặc biệt",
"discount": null,
"discountRatio": 15.5,
"createdDate": "2025-08-01T10:30:00Z",
"modifiedDate": "2025-08-01T11:45:00Z"
},
{
"id": 12346,
"name": "Khách hàng thường",
"description": "Nhóm khách hàng cơ bản",
"discount": 10000,
"discountRatio": null,
"createdDate": "2025-08-01T09:15:00Z",
"modifiedDate": null
}
],
"total": 25,
"pageSize": 10,
"timestamp": "2025-08-01T12:00:00Z"
}
- Empty Result Response Example
{
"data": [],
"total": 0,
"pageSize": 20,
"timestamp": "2025-08-01T12:00:00Z"
}
- Test Scenarios
- Valid Test Cases
Test Case | Input | Expected Result |
Lấy trang đầu tiên | PageIndex=1, PageSize=20 | 200 - Trả về danh sách trang 1 |
Tìm kiếm theo tên | searchTerm="VIP" | 200 - Trả về các nhóm có chứa "VIP" |
Sắp xếp theo tên | sortBy=Name, sortDirection=Asc | 200 - Danh sách sắp xếp theo tên A-Z |
Sắp xếp theo ngày tạo | sortBy=CreatedDate, sortDirection=Desc | 200 - Danh sách sắp xếp theo ngày tạo mới nhất |
Phân trang | PageIndex=2, PageSize=10 | 200 - Trả về trang 2 với 10 items |
Không có kết quả | searchTerm="xyz123" | 200 - Trả về mảng rỗng |
- Invalid Test Cases
Test Case | Input | Expected Result |
Số trang âm | PageIndex=-1 | 400 - INVALID_PAGE_INDEX |
Số trang bằng 0 | PageIndex=0 | 400 - INVALID_PAGE_INDEX |
Kích thước trang quá lớn | PageSize=200 | 400 - INVALID_PAGE_SIZE |
Kích thước trang âm | PageSize=-5 | 400 - INVALID_PAGE_SIZE |
Trường sắp xếp không hợp lệ | sortBy="InvalidField" | 400 - INVALID_SORT_FIELD |
Hướng sắp xếp không hợp lệ | sortDirection="Invalid" | 400 - INVALID_SORT_DIRECTION |
Thiếu token | Không có Authorization header | 401 - UNAUTHORIZED |
- Performance Notes
- Optimization Tips
Tip | Mô tả |
Sử dụng phân trang | Luôn sử dụng PageSize phù hợp để tối ưu hiệu suất |
Tìm kiếm hiệu quả | Sử dụng từ khóa tìm kiếm cụ thể để giảm số lượng kết quả |
Cache kết quả | Kết quả có thể được cache trong thời gian ngắn |
- Response Time Guidelines
Scenario | Expected Response Time |
< 100 records | < 200ms |
100-1000 records | < 500ms |
1000 records | < 1000ms |
7.6. Tạo nhóm khách hàng
- Tổng quan: API tạo mới nhóm khách hàng cho phép tạo các nhóm khách hàng với thông tin cơ bản và cài đặt chiết khấu.
- Endpoint Information
Method: POST
URL: /public/customer-group
Content-Type: application/json
- Request Parameters
- HTTP Headers
Header | Type | Required | Mô tả |
Content-Type | string | ✅ Yes | application/json |
- Request Body Fields
Field | Type | Required | Mô tả | Ràng buộc |
name | string | ✅ Yes | Tên nhóm khách hàng | 1-250 ký tự, không chứa ký tự đặc biệt |
description | string | ❌ No | Mô tả nhóm khách hàng | Tối đa 1000 ký tự |
discount | decimal | ❌ No | Số tiền chiết khấu cố định | 0 < giá trị < 9×10¹³ |
discountRatio | decimal | ❌ No | Phần trăm chiết khấu | 0.0 ≤ giá trị ≤ 100.0 |
- Business Rules
Quy tắc | Mô tả |
Ưu tiên chiết khấu | Khi cả discount và discountRatio được cung cấp, hệ thống sẽ ưu tiên discountRatio và tự động set discount = null |
Tên duy nhất | Tên nhóm khách hàng phải duy nhất trong cùng một retailer |
Validation | Tên không được chứa ký tự đặc biệt (@#$%^&* etc.) |
- Response Format
- Success Response (200 OK)
Field | Type | Mô tả |
id | long | ID của nhóm khách hàng vừa tạo |
name | string | Tên nhóm khách hàng |
description | string | Mô tả nhóm khách hàng |
discount | decimal | Số tiền chiết khấu (có thể null) |
discountRatio | decimal | Phần trăm chiết khấu (có thể null) |
createdDate | datetime | Thời gian tạo |
modifiedDate | datetime | Thời gian cập nhật (null khi mới tạo) |
- Error Response (400 Bad Request)
Error Code | Message | Mô tả |
GROUP_NAME_REQUIRED | Tên nhóm khách hàng là bắt buộc | Khi field name bị empty hoặc null |
GROUP_NAME_INVALID | Tên nhóm khách hàng không được chứa ký tự đặc biệt | Khi name chứa ký tự đặc biệt |
GROUP_NAME_TOO_LONG | Tên nhóm khách hàng không được vượt quá 250 ký tự | Khi name > 250 ký tự |
GROUP_NAME_EXISTS | Tên nhóm khách hàng đã tồn tại | Khi name đã được sử dụng trong retailer |
DISCOUNT_INVALID | Số tiền chiết khấu phải lớn hơn 0 và nhỏ hơn 900000000000000 | Khi discount không hợp lệ |
DISCOUNT_RATIO_INVALID | Mức chiết khấu phải nằm trong khoảng từ 0 đến 100 | Khi discountRatio không hợp lệ |
- Example Usage
- Request Example
{
"name": "Khách hàng VIP",
"description": "Nhóm khách hàng có giá trị cao với đặc quyền đặc biệt",
"discount": 50000,
"discountRatio": 15.5
}
- Success Response Example
{
"id": 12345,
"name": "Khách hàng VIP",
"description": "Nhóm khách hàng có giá trị cao với đặc quyền đặc biệt",
"discount": null,
"discountRatio": 15.5,
"createdDate": "2025-08-01T10:30:00Z",
"modifiedDate": null
}
- Test Scenarios
- Valid Test Cases
Test Case | Input | Expected Result |
Tạo với thông tin tối thiểu | name: "Khách VIP" | 200 - Tạo thành công |
Tạo với đầy đủ thông tin | name + description + discountRatio | 200 - Tạo thành công |
Tạo với tên 250 ký tự | name: 250 chars | 200 - Tạo thành công |
Ưu tiên discountRatio | discount + discountRatio | 200 - discount = null, discountRatio được áp dụng |
- Invalid Test Cases
Test Case | Input | Expected Result |
Tên rỗng | name: "" | 400 - GROUP_NAME_REQUIRED |
Tên chỉ có khoảng trắng | name: " " | 400 - GROUP_NAME_REQUIRED |
Tên quá dài | name: >250 chars | 400 - GROUP_NAME_TOO_LONG |
Tên có ký tự đặc biệt | name: "@#$%" | 400 - GROUP_NAME_INVALID |
Discount âm | discount: -100 | 400 - DISCOUNT_INVALID |
DiscountRatio > 100 | discountRatio: 150 | 400 - DISCOUNT_RATIO_INVALID |
7.7. Pubic API Lấy danh gói dịch vụ của khách
- Mục đích: APIs này được sử dụng để truy xuất danh sách toàn bộ gói dịch vụ đã bán thuộc cửa hàng đã được xác thực (authenticated retailer), bao gồm cả khả năng lọc, phân trang.
7.7.1. Lấy danh sách gói dịch vụ đã bán
- Phương thức: GET
- Endpoint: https://api-integration-booking.kiotviet.vn/public/get-customer-combos
- Tham số yêu cầu (Request Parameters)
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
PageSize | int | Số lượng GDV mỗi trang(MAX = 100). | |
CurrentItem | int | Vị trí bản ghi bắt đầu truy xuất dữ liệu. | |
CustomerId | long | Lọc theo Id khách hàng | |
CustomerCode | string | Lọc theo mã khách hàng | |
ComboCode | string | Lọc theo mã GDV | |
ComboName | string | Tìm kiếm theo tên GDV. | |
PurchaseDateFrom | dateTime | Lọc theo ngày bán GDV(>= startOfDate yyyy-mm-dd 00:00:00) | |
PurchaseDateTo | dateTime | Lọc theo ngày bán GDV(<= endOfDate yyyy-mm-dd 23:59:59) | |
SortBy | string | Hỗ trợ sorting với các fields: | |
SortOrder | string | Sort theo chiều: |
- Phản hồi (Response)
Dữ liệu phản hồi là một đối tượng JSON có cấu trúc như sau:
{
"result": {
"total": 523, // Tổng số bản ghi
"pageSize": 2, // Số lượng records mỗi page
"data": [
{
"id": 52948,
"productId": 2152948,
"productCode": "P000021",
"productName": "Cobo chăm sóc da",
"customerId": 40244,
"expireDate": "2028-11-24T23:59:59.9970000",
"customerProductStatus": 1,
"retailerId": 607371,
"code": "C000596",
"currentValue": 3,
"usedValue": 0
},
{
"id": 52945,
"productId": 2141211,
"productCode": "P000022",
"productName": "Combo salon trọn gói",
"customerId": 41228,
"expireDate": "2028-11-24T23:59:59.9970000",
"customerProductStatus": 1,
"retailerId": 607371,
"code": "C000594",
"currentValue": 3,
"usedValue": 0
}
],
"timestamp": "2026-01-08T10:40:26.0060374+07:00"
},
"message": ""
}
- Mô tả các trường trong data
Trường | Kiểu dữ liệu | Mô tả |
id | long | Id GDV |
code | string | Mã GDV |
productCode | string | Mã sản phẩm |
productId | long | Id sản phẩm |
productName | string | Tên GDV |
expireDate | dateTime? | Thời hạn GDV (null là vô thời hạn) |
customerProductStatus | int | Trạng thái GDV: |
retailerId | long | Id gian hàng |
currentValue | int | Số lượng còn lại của GDV |
usedValue | int | Số lượng đã dùng |
7.7.2. Lấy chi tiết gói dịch vụ
- Phương thức: GET
- Endpoint: https://api-integration-booking.kiotviet.vn/public/get-customer-combo-details
- Tham số yêu cầu (Request Parameters)
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
CustomerId | long | Id khách hàng | |
CustomerComboId | long | Id GDV |
- Phản hồi (Response)
Dữ liệu phản hồi là một đối tượng JSON có cấu trúc như sau:
{
"result": {
"total": 0, // ignore
"pageSize": 0, // ignore
"data": [
{
"customerComboId": 49134,
"customerComboProductName": "Combo chăm sóc da",
"expireDate": "2025-06-07T23:59:59.9970000",
"purchaseDate": "2024-12-02T10:22:25.0000000",
"customerProductStatus": 1,
"customerComboQuantity": 0,
"customerComboItems": [
{
"customerComboItemId": 57563,
"customerComboItemProductId": 1123431,
"customerComboItemProductCode": "P000021",
"customerComboItemProductName": "Nặn mụn",
"customerComboItemRemainQuantity": 0,
"customerComboDetailQuantity": 2,
"returnedQuantity": 1,
"bookedAndInvoicedQuantity": 1
},
{
"customerComboItemId": 57564,
"customerComboItemProductId": 1123432,
"customerComboItemProductCode": "P000022",
"customerComboItemProductName": "Rửa mặt",
"customerComboItemRemainQuantity": 0,
"customerComboDetailQuantity": 15,
"returnedQuantity": 1,
"bookedAndInvoicedQuantity": 14
}
]
}
],
"timestamp": "2026-01-08T10:40:11.2444696+07:00"
},
"message": ""
}
- Mô tả các trường trong data
Trường | Kiểu dữ liệu | Mô tả |
result.data.customerComboId | long | Id GDV |
result.data.customerComboProductName | string | Tên GDV |
result.data.expireDate | string | Thời hạn GDV (null là vô thời hạn) |
result.data.purchaseDate | dateTime? | Ngày mua gói(NULL là gói import) |
result.data.customerProductStatus | int | Trạng thái GDV: |
result.data.customerComboItems | array | Items trong GDV |
result.data.customerComboItems[i].customerComboItemId | long | Item Id |
result.data.customerComboItems[i].customerComboItemProductId | long | Id sản phẩm |
result.data.customerComboItems[i].customerComboItemProductCode | string | Mã sản phẩm |
result.data.customerComboItems[i].customerComboItemProductName | string | Tên dịch vụ |
result.data.customerComboItems[i].customerComboItemRemainQuantity | int | Số lượng còn lại của dịch vụ |
result.data.customerComboItems[i].customerComboDetailQuantity | int | Số lượng gốc |
result.data.customerComboItems[i].returnedQuantity | int | Số lượng đã trả |
result.data.customerComboItems[i].bookedAndInvoicedQuantity | int | Số lượng đã dùng |
- Mục đích sử dụng API này cho phép lấy danh sách các booking từ hệ thống, có hỗ trợ phân trang và lọc theo một số tiêu chí.
- URL: https://api-integration-booking.kiotviet.vn/public/booking
- Method: GET
- Headers:
- Parameters
- Response
| { "result": { "total": 2, "pageSize": 2, "data": [ { "bookingId": 1024621, "bookingUuid": "7738aaca-769f-4041-9e0e-034eb391e80b", "bookingCode": "B000372", "bookingStatus": "Chưa tới", "bookingCreatedDate": "2024-10-01T15:38:43.1730000", "bookingTimeNearest": "2024-10-01T15:38:43.1830000", "branchId": 3897, "bookingDetails": [ { "productName": "Dịch vụ 60 phút", "productCode": "SP999325783" }, { "productName": "Dịch vụ không có nguyên liệu tiêu hao", "productCode": "SP999325777" } ] }, { "bookingId": 1024971, "bookingUuid": "7738aaca-769f-4041-9e0e-034eb391e80b", "bookingCode": "B000373", "bookingStatus": "Chưa tới", "bookingCreatedDate": "2024-10-01T18:02:17.3130000", "bookingTimeNearest": "2024-10-01T18:02:17.3370000", "branchId": 3897, "bookingDetails": [ { "productName": "Dịch vụ 60 phút", "productCode": "SP999325783", "employees": "thaimeo1" }, { "productName": "Dịch vụ massage", "productCode": "SP999325780", "employees": "thaimeo2" } ] } ], "timestamp": "2024-10-02T08:47:27.1939334+07:00" }, "message": "" } |
- Mô tả Response
- URL: https://api-integration-booking.kiotviet.vn/public/bookingdetail
- Method: GET
- Mục đích: API này cho phép lấy danh sách các BookingDetail từ hệ thống theo BookingId
- Headers
- Parameters
- Response
| { "result": { "total": 2, "pageSize": 1, "data": [ { "bookingId": 1024971, "bookingUuid": "7738aaca-769f-4041-9e0e-034eb391e80b", "bookingCode": "B000373", "bookingStatus": "Chưa tới", "bookingCreatedDate": "2024-10-01T18:02:17.3130000", "bookingTimeNearest": "2024-10-01T18:02:17.3370000", "branchId": 3897, "bookingDetails": [ { "productName": "Dịch vụ 60 phút", "productCode": "SP999325783", "employees": "thaimeo1" }, { "productName": "Dịch vụ massage", "productCode": "SP999325780", "employees": "thaimeo2" } ] } ], "timestamp": "2024-10-02T08:47:27.1939334+07:00" }, "message": "" } |
- Mô tả Response
- URL: https://api-integration-booking.kiotviet.vn/public/booking/busy
- Method: GET
- Mô tả: API này cho phép lấy danh sách các lịch bận trong khoảng thời gian filter
- Headers:
- Parameters:
- URL: https://api-integration-booking.kiotviet.vn/public/booking
- Method: POST
- Mô tả: API này cho phép tạo lịch hẹn cho gian hàng
- Headers:
- Body:
| { "BookingInfo": { "BranchId": 12345, -- Bắt buộc "CustomerId": 123, -- Bỏ trống nếu là khách lẻ "BookingDetails": [ { "StartTime": "2025-03-01T14:00:00", -- Bắt buộc "Duration": 60, -- Thời gian sử dụng lịch hẹn / Bắt buộc "Quantity": 1, -- Số lượng lịch hẹn / Bắt buộc "ProductId": 575755, -- Id dịch vụ của lịch hẹn / Bắt buộc "BookingDetailStaffs": [ { "StaffId": 12345 // Id của nhân viên thực hiện dịch vụ }, { "StaffId": 23456 } ] } ] } } |
- Respons
- Thành công => Code 200 (OK)
- Lỗi => Error Code 400 (Bad Request)
- URL: https://api-integration-booking.kiotviet.vn/public/employee
- Method: GET
- Mô tả: API này cho phép lấy danh sách các nhân viên của cửa hàng
- Headers:
- Parameters:
- Response
| { "result": { "total": 36, "total1": 0, "total2": 0, "pageSize": 1, "data": [ { "id": 40, "name": "nhanvien1", "mobilePhone": "0987563214", "address": "Hanoi", "locationName": "Hà Nội - Quận Hoàn Kiếm", "wardName": "Phường Trần Hưng Đạo", "retailerId": 200010000, "branchId": 123, -- chi nhánh tạo "createdDate": "2025-02-16T10:08:57.4780000", "isDeleted": false, "sourceId": 444555, "userId": 123, "employeeBranches": [ { "id": 45, "retailerId": 200010000, "branchId": 123, "employeeId": 444555, "bookingEmployeeId": 40 } ] } ], "timestamp": "2025-03-17T16:26:00.1184016+07:00", "pageIndex": 0 }, "message": "" } |
Như vậy, KiotViet đã thực hiện xong phần hướng dẫn sử dụng Public API.
Mọi thắc mắc xin liên hệ tổng đài tư vấn bán hàng 1800 6162, tổng đài hỗ trợ phần mềm 1900 6522 hoặc email cho chúng tôi tại địa chỉ: hotro@kiotviet.com để được hỗ trợ và giải đáp.
Chúc Quý khách thành công!
Tài liệu được cập nhật mới nhất ngày 16/07/2025
Mục lục
- I. Thiết lập kết nối API
- II. Chức năng
- 1. Authenticate
- 2. Nhóm hàng
- 3. Hàng hóa
- 4. Lấy danh sách chi nhánh
- 5. Bảng giá
- 5.1. Lấy danh sách bảng giá
- 5.2. Lấy chi tiết bảng giá
- 6. Hóa đơn
- 6.1. Lấy danh sách hóa đơn
- 6.2. Lấy chi tiết hóa đơn
- 7. Khách hàng
- 7.1. Lấy danh sách khách hàng
- 7.2. Lấy chi tiết khách hàng
- 7.3. Tạo khách hàng
- 7.4. Sửa khách hàng
- 7.5. Danh sách nhóm khách hàng
- 7.6. Tạo nhóm khách hàng
- 7.7. Pubic API Lấy danh gói dịch vụ của khách
- 8. Lịch hẹn
- 8.1. Danh sách lịch hẹn
- 8.2. Danh sách chi tiết lịch hẹn theo BookingID
- 8.3. Danh sách lịch bận
- 8.4. Tạo lịch hẹn
- 9. Danh sách nhân viên
