Xem mục lục
Public API
Hướng dẫn sử dụng tính năng Kết nối API
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 (1), bạn kích chọn Thiết lập cửa hàng (2).
- Bạn chọn Thiết lập kết nối API (3). Trên thông tin thiết lập kết nối bạn thao tác như sau:
Kích Tạo mã (4) để tạo ra Mã bảo mật
Kích Hoạt động (5)
- Kích Lưu (6).
- Để ngừng hoạt động kết nối API, bạn kích Ngừng hoạt động -> kích 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 Thiết lập 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 http://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,
“productType”: int? (optional) //Loại hàng hóa
Nếu có "productType", 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 http://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 http://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 http://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 http://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 http://api-integration-booking.kiotviet.vn/public/invoice/{id}
- GET http://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 http://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 http://api-integration-booking.kiotviet.vn/public/customer/{id}
- GET http://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 }
|
8.1. Danh sách lịch hẹn
- 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
- Mô tả Response
8.2. Danh sách chi tiết lịch hẹn theo BookingID
- 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
- Mô tả Response
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/10/2024
KiotViet - Phần mềm quản lý bán hàng phổ biến nhất
- Với 300.000 nhà kinh doanh sử dụng
- Chỉ từ: 6.000đ/ ngày
