Kết nối API
(Ngành Khách sạn, Nhà nghỉ)

Nội dung hướng dẫn trong bài viết này được thực hiện trên giao diện mới. Để tham khảo hướng dẫn trên giao diện cũ, vui lòng truy cập tại đây
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:
Danh sách chi nhánh
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
Bảng giá
Hóa đơn: lấy danh sách hóa đơn và chi tiết hóa đơn.
Khách hàng: lấy danh sách khách hàng và các thông tin chi tiết của khách hàng
Hạng phòng: lấy về danh sách hạng phòng, chi tiết hạng phòng và số phòng trống của hạng phòng
Đặt phòng: tạo đặt phòng mới và lấy về chi tiết của đặt phòng
Kênh bán: lấy danh sách và chi tiết kênh bán
- 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ý, bạn nhấn vào biểu tượng bánh răng Thiết lập góc phải màn hình → chọn Khách sạn → Kết nối API.

- Nhấn Chỉnh sửa
- Nhập Tên kết nối.
- Chọn Trạng thái hoạt động: Hoạt động.
- Nhấn Tạo mã.

- Tích chọn Tôi đã đọc và đồng ý với điều khoản trên → chọn Đồng ý.

- Nhấn Lưu để ghi nhận thông tin.

- Để ngừng hoạt động kết nối API, sau khi nhấn Chỉnh sửa → bạn chọn 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. Tài khoản admin của chủ khách sạn truy cập màn hình Quản lý → nhấn vào biểu tượng bánh răng Thiết lập góc phải màn hình → chọn Khách sạ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ụ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-hotel.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
“pageIndex”: int, // thứ tự trang lấy dữ liệu
- Response:
{ "total": int, “pageSize”: int, "data": [ { "id": long, // Id chi nhánh "name": string, "address": string, "retailer Id": long, // Id cửa hàng "modifiedDate": datetime, "createdDate": "datetime, "isActive": bool, "contactNumber": string, "locationName": string, "wardName": string, "province": string, "district": string, } ], "timestamp": datetime } |
Mô tả chi tiết cho các liên quan đến thông tin nhóm hàng hóa như sau:
- 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-hotel.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
“pageIndex”: int, // thứ tự trang lấy dữ liệu
“hierachicalData”: boolean?, // nếu HierachicalData=true thì mình sẽ lấy cả nhóm hàng con
- Response:
“total”: int, “pageSize”: int, “pageIndex”: int, “data”: [ { “id”: int, // ID nhóm hàng hóa "parentId”: int?, // Id của danh mục cha "name": string, // Tên nhóm hàng hóa “hasChild”: boolean?, // nhóm hàng có con hay không “modifiedDate”: datetime? // thời gian cập nhật “createdDate”: datetime “children”: [] }], "timestamp": datetime } |
Mô tả chi tiết cho các liên quan đến thông tin hàng hóa như sau:
- 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-hotel.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
“pageIndex”: int, // thứ tự trang lấy dữ liệu
“categoryId”: int, optional //Id nhóm hàng cần filter
"productTypes": int [] ,optional , //loại hàng hóa
"IsActive": bool? //Hàng đang kinh doanh,
"Name": string //search hàng hóa theo tên,code
Nếu có "productType", giá trị thuộc :
- 2: hàng hóa thường
- 3: hàng hóa dịch vụ
- Response:
“total”: int, // Tổng số hàng hóa “pageSize”: int, “data”: [{ “id”: long, // ID hàng hóa “code”: string, // Code hàng hóa "allowsSale": Boolean, // Sản phẩm được bán trực tiếp hay không "name": string, // Tên sản phẩm "categoryId": long, // Id của nhóm hàng hóa "categoryName": string, // Tên của nhóm hàng hóa “description”: string, // Mô tả sản phẩm "productAttributes": [ { "id": long, // id của bảng "attributeId": long, // id của attributeId "productId": long, // id của productid "value": string, // giá trị thuộc tính "createdDate": "2022-03-15T11:04:27.2770000" }], // danh sách thuộc tính “unit”: string, // đơn vị tính của 1 sản phẩm, “productImages”: [{“Image”: string, // ảnh sản phẩm}], “basePrice”: decimal?, // giá sản phẩm }], |
- Mục đích sử dụng: Trả về danh sách bảng giá
- Phương thức và URL: GET https://api-integration-hotel.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á
“pageIndex”: int, // thứ tự trang lấy dữ liệu
“pageSize”: int?, // số items trong 1 trang, mặc định 50 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 bảng giá “name”: string // tên bảng giá “isActive”: boolean // trạng thái hoạt động hay không “isGlobal”: boolean, // áp dụng cho tất cả chi nhánh “startDate”: datetime, // ngày bắt đầu áp dụng “endDate”: datetime, // ngày hết hạn “forAllCusGroup”: boolean // áp dụng cho tất cả nhóm khách hàng “forAllUser”: boolean, // áp dụng cho tất cả user “priceBookBranches” :// [{ “id”: long, //Id quan hệ bảng giá – chi nhánh “priceBookId”: long,//ID bảng giá “branchId”: long, //ID chi nhánh áp dụng }], “priceBookCustomerGroups” :// [{ “customerGroupName”: string, “id”: long, //Id quan hệ bảng giá – nhóm khách hàng “priceBookId”: long,//ID bảng giá “customerGroupId”: long,//ID nhóm khách hàng }], “priceBookUsers” :[{ “userName”: string,//Tên người dùng “id”: long, //Id quan hệ “priceBookId”: long, //ID bảng giá “userId”: long,//ID người dùng }], }] } |
- 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-hotel.kiotviet.vn/public/pricebook/{id}
Request: Sử dụng hàm GET với tham số:
“id”: long // ID của bảng giá
- Response:
{ “total”: int, “pageSize”: int, // số items trong 1 trang, mặc định 20 items, tối đa 100 items “data”: [{ “id”: long // id bảng giá “name”: string // tên bảng giá “isActive”: boolean // trạng thái hoạt động hay không “isGlobal”: boolean, // có phải là bảng giá chung không “startDate”: datetime, // ngày bắt đầu áp dụng “endDate”: datetime, // ngày hết hạn “forAllCusGroup”: boolean // áp dụng cho tất cả nhóm khách hàng “forAllUser”: boolean, // áp dụng cho tất cả user “priceBookBranches” :// [{ “id”: long, //Id quan hệ bảng giá – chi nhánh “priceBookId”: long,//ID bảng giá “branchId”: long, //ID chi nhánh áp dụng }], “priceBookCustomerGroups” :// [{ “customerGroupName”: string, “id”: long, //Id quan hệ bảng giá – nhóm khách hàng “priceBookId”: long,//ID bảng giá “customerGroupId”: long,//ID nhóm khách hàng }], “priceBookUsers” :[{ “userName”: string,//Tên người dùng “id”: long, //Id quan hệ “priceBookId”: long, //ID bảng giá “userId”: long,//ID người dùng }], “priceBookDetails” :[{ “id”: long, //Id chi tiết bảng giá “priceBookId”: long, //ID bảng giá “productId”: long,//ID sản phẩm “price”: decimal,// đơn giá “priceBookVersion”: int?,// version bảng giá “applyCondition” : { // điều kiện áp dụng “Priority”: int // thứ tự ưu tiên “DayOfWeeks”: int [] // Ngày của tuần “Dates”: DateTime [] // Danh sách ngày áp dụng } “priceSteps”:[{ // bước giá “fromThHour”: int // từ giờ thứ mấy “price”: decimal, // đơn giá “type”: int, // kiểu bước giá }] }], }]} |
- Mục đích sử dụng: Trả về danh sách hóa đơn
- Phương thức và URL: GET https://api-integration-hotel.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
“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
“pageIndex”: int, // thứ tự trang lấy dữ liệu
“pageSize”: int?, // số items trong 1 trang, mặc định 50 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 “customerCode”: 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 “createdBy”: long, // Id tài khoản tạo “payments” :[{ “id”: long, “code”: string, “amount”: decimal, “status”: byte?, “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-hotel.kiotviet.vn/public/invoice/{id}
- Request: Sử dụng hàm GET với tham số:
“id”: long, optional // Id 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 “createdBy”: long, // Id tài khoản tạo “createdByName”: string, // tài khoản tạo “discount”: decimal, // giảm giá “discountRatio”: double?, // % giảm giá “saleChannelId”: int?, // Id kênh bán “surcharge”: decimal, // thu khác “desception”: string, // ghi chú “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-hotel.kiotviet.vn/public/customer
- 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
“includeCustomerGroup”: boolean?, optional // Lấy thông tin nhóm khách hàng hay không
“IncludeCustomerTotal”: boolean?, optional // Lấy tổng số tiền hóa đơn, tổng điểm hay không
“contactNumber”: string, optional // Theo số điện thoại của khách hàng
“birthDate”: datetime, optional // Lấy theo sinh nhật khách hàng
“lastModifiedFrom”: string, optional // Thời gian cập nhật
“groupId”: long, optional // Theo id nhóm khách hàng
“pageSize”: int?, // số items trong 1 trang, mặc định 50 items, tối đa 100 items
“pageIndex”: int, // thứ tự trang lấy dữ liệu
- 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 “totalInvoiced”: 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-hotel.kiotviet.vn/public/customer/{id}
- Request: Sử dụng hàm GET với tham số:
“id”: long, optional // Lấy theo mã khách hàng
“includeCustomerGroup”: boolean?, optional // Lấy thông tin nhóm khách hàng hay không
“includeCustomerTotalInvoiced”: boolean?, optional // Lấy tổng số tiền invoice hay không
- Response:
{ “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 “totalInvoiced”: 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: Lấy về danh sách hạng phòng và số phòng trống của hạng phòng
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/room-class
- Request: Sử dụng hàm GET với tham số:
“branchIds”: int[] , optional // Lấy theo chi nhánh
“startDate”: datetime, required // Thời gian nhận phòng
“endDate”: datetime, required // Thời gian trả phòng
“totalRoom”: int?, optional // Số lượng phòng trống
“pageSize”: int?, // số items trong 1 trang, mặc định 50 items, tối đa 100 items
“pageIndex”: int, // thứ tự trang lấy dữ liệu
- Response:
{ "total": 1, "pageIndex": 1, "pageSize": 50, "data": [ { "id": 120841, "retailerId": 602482, "branchId": 2560, // Id chi nhánh "code": "HP000138", // mã hạng phòng "name": "Hạng phòng Luxury", // tên hạng phòng "description": "Mô tả", // Mô tả hạng phòng "createdDate": "2024-04-15T11:15:24.1200000", // ngày tạo "basePrice": 100000.0000, giá niêm yết "pricePerHour": 100000.0000, giá giờ "pricePerDay": 100000.0000, giá ngày "pricePerNight": 700000.0000, giá đêm "pricePerMonth": 0, giá tháng "roomClassAttribute": { "id": 12944, "standardChildren": 1, // số lượng trẻ em tiêu chuẩn "standardAdult": 2, // số lượng người lớn tiêu chuẩn "maxChildren": 1, // số lượng trẻ em tối đa "maxAdult": 2 // số lượng người lớn tối đa }, "productImages": [ // ảnh hạng phòng { "id": 12939, "image": "https://d1k20gtjgkmqcd.cloudfront.net/mthu3/9eca86912b0748c1887cb25e17f393e5" } ], "totalAvailableRoom": 15, // số lượng phòng trống “version”: // version thay đổi của hạng phòng } ] } |
- Mục đích sử dụng: Lấy về chi tiết hạng phòng và số lượng phòng trống
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/room-class/{id}
- Request: Sử dụng hàm GET với tham số:
“Id”: long, required // Id hạng phòng
“StartDate”: datetime, required // Thời gian nhận phòng
“EndDate”: datetime, required // Thời gian trả phòng
“TotalRoom”: int?, optional // Số lượng phòng trống
- Response:
{ "id": 120841, "retailerId": 602482, "branchId": 2560, // Id chi nhánh "code": "HP000138", // mã hạng phòng "name": "Hạng phòng Luxury", // tên hạng phòng "description": "Mô tả", // Mô tả hạng phòng "isActive": true, // đang kinh doanh "createdDate": "2024-04-15T11:15:24.1200000", // ngày tạo "basePrice": 100000.0000, giá niêm yết "pricePerHour": 100000.0000, giá giờ "pricePerDay": 100000.0000, giá ngày "pricePerNight": 700000.0000, giá đêm "pricePerMonth": 0, giá tháng "roomClassAttribute": { "id": 12944, "standardChildren": 1, // số lượng trẻ em tiêu chuẩn "standardAdult": 2, // số lượng người lớn tiêu chuẩn "maxChildren": 1, // số lượng trẻ em tối đa "maxAdult": 2 // số lượng người lớn tối đa }, "productImages": [ // ảnh hạng phòng { "id": 12939, "image": "https://d1k20gtjgkmqcd.cloudfront.net/mthu3/9eca86912b0748c1887cb25e17f393e5" } ], "totalAvailableRoom": 15, // số lượng phòng trống, “version”: // version thay đổi của hạng phòng } |
- Mục đích sử dụng: Tạo đặt phòng mới
- Phương thức và URL:
Post https://api-integration-hotel.kiotviet.vn/public/order
- Request: Sử dụng hàm Post với body:
{ "phone":"0349202944", // string(255) / required / sdt khách hàng "customerName": "Xuân Hùng", // string(255) / optional/ tên khách hàng "email":"xuanhung@gmail.com", // string(255) / optional/ email khách hàng "checkInTime":"2024-04-20 00:00:00", // datetime / required / Thời gian nhận phòng ( không có giây và nhỏ hơn thời gian trả) // nếu đặt phòng theo ngày và đêm thì không truyển giờ phút giây hệ thống sẽ lấy theo giờ cài đặt "checkOutTime":"2024-04-22 15:47:53" , // datetime / required / Thời gian nhận phòng ( không có giây và lớn hơn thời gian nhận) / nếu đặt phòng theo ngày và đêm thì không chuyển giờ phút giây hệ thống sẽ lấy theo giờ cài đặt "counterType":1, // int / required / hình thức lưu trú (1: Giờ, 2: Ngày, 3: Đêm ) "branchId":3498, // int / required / Id chi nhánh "adultQuantity":1, //int / optional/ số lượng người lớn "childQuantity":1, //int / optional/ số lượng trẻ em "note":"Ghi chú đặt phòng", // string(1000) / optional/ ghi chú đặt phòng "roomClasses":[ // required / danh sách đặt phòng { "id":120841, // long / required / Id hạng phòng "quantity":2, // int/ required/ số lượng phòng "price":"20000", // long/ required / giá hạng phòng "note":"Ghi chú chi tiết", // string(1000) / optional / ghi chú hạng phòng "version":3 // int/ required / version hạng phòng } ], "payment": // optional / tiền khách thanh toán { "method":”transfer”, // string/ required (cash : Tiền mặt , card: Thẻ, transfer: “Chuyển khoản”) "amount":"20000", // long/ required / số tiền khách trả } } |
- Response:
{ "uuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "customerId": 63182, "purchaseDate": "2024-04-20T10:08:32.0000000", // thời gian thanh toán "code": "DP000805", // mã đặt phòng "branchId": 3498, // id chi nhánh "status": 1, // trạng thái đặt phòng (1: đã đặt,2: hoàn thành, 3: đã hủy, 4: Chưa xác nhận) "modifiedDate": "2024-04-20T10:09:21.1000000", // ngày cập nhật "retailerId": 602482, "discount": 71100.0000, // tổng giảm giá "soldById": 24587, // nhân viên thanh toán "createdDate": "2024-04-20T10:09:15.0530000", ngày tạo đặt phòng “createdBy”: long, // Id tài khoản tạo "modifiedBy": 11889, // người chỉnh sửa đặt phòng "discountRatio": 10, // phần tram giảm giá "total": 710289.0000, // tổng tiền hóa đơn "totalPayment": 200000.0000, // số tiền khách đã thanh toán "surcharge": 70389.0000, // thu khác "saleChannelId": 602482, // kênh bán "originVersion": 15, "orderDetails": [ { "uuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", // uuid chi tiết đặt phòng "productId": 120843, // id sản phẩm "quantity": 1, // số lượng "price": 700000.0000, // đơn giá "discount": 0.0000, // giảm giá "createdDate": "2024-04-20T10:09:17.8630000", // ngày tạo "discountRatio": 0, // phần tram giảm giá "modifiedDate": "2024-04-20T10:09:20.7870000", // ngày cập nhật "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, // id phòng "checkInTime": "2024-04-20T10:09:00.0000000", // ngày nhận phòng "checkOutTime": "2024-04-20T11:00:00.0000000", // ngày trả phòng "status": 2, trạng thái chi tiết đặt phòng (1: Đã đặt, 2: Đã nhận phòng, 3: Đã trả phòng, 4: Đã hủy,5: Chưa xác nhận) "productType": 6 // loại sản phẩm (2: Hàng hóa, 3: Dịch vụ, 6: Hạng phòng, 7: Phu phí), "counterType": 3, // hình thức lưu trú (1: Giờ, 2: Ngày, 3: Đêm ,4: Tháng) "retailerId": 602482, "branchId": 3498, // Id Chi nhánh "basePrice": 700000.0000, // Giá niêm yết "subTotal": 700000 // Tổng thành tiền }, { "productId": 120841, "quantity": 0, "price": 0.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.6230000", "discountRatio": 0, "uuid": "86d77aeb-95b6-4090-bdc7-af27ae026ed6", "modifiedDate": "2024-04-20T10:09:20.5400000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 7, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 0.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", "extraFeeId": 8226 }, { "productId": 120841, "quantity": 0, "price": 0.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.6230000", "discountRatio": 0, "uuid": "6bb035ce-8748-4a30-b68c-50dbc7056616", "modifiedDate": "2024-04-20T10:09:20.5430000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 7, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 0.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", "extraFeeId": 8225 }, { "productId": 120842, "quantity": 0, "price": 1000000.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.8500000", "discountRatio": 0, "uuid": "51d5aa32-ad3c-4577-97a0-91ba872dccad", "modifiedDate": "2024-04-20T10:09:20.7870000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "checkInTime": "2024-04-20T10:09:00.0000000", "checkOutTime": "2024-04-20T10:09:00.0000000", "status": 2, "productType": 6, "counterType": 2, "retailerId": 602482, "branchId": 3498, "basePrice": 1000000.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418" }, { "productId": 120938, "quantity": 1, "price": 11000.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:19.0600000", "discountRatio": 0, "uuid": "b79a0b5e-6841-488a-999a-09e73836aa4a", "modifiedDate": "2024-04-20T10:09:20.5430000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 3, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 11000.0000, "subTotal": 11000, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418" } ], "orderAttachments": [ // danh sách file đính kèm { "id": 254, "attachmentUrl": "https://d1k20gtjgkmqcd.cloudfront.net/mthu3/OrderAttachments/1e91d0dc4c5d4fd6bed480a368fcd7a0_0e3a7188146b46d6a79e3d62bb38ced2", "fileName": "hi.xlsx", "createdDate": "2024-04-20T10:09:19.2630000" } ], “historyNote”: “Ghi chú”, // Ghi chú đặt phòng "isCompletedPayment": false, // đã hoàn thành thanh toán hay chưa? "adultQuantity": 1, // số lượng người lớn "childQuantity": 0, // số lượng trẻ em "subTotal": 711000.0000, // tổng thành tiền đặt phòng "discountValue": 71100.0000 // tổng tiền giảm giá } |
- Mục đích sử dụng: Lấy về chi tiết đặt phòng
- Phương thức và URL: GET https://api-integration-hotel.kiotviet.vn/public/order
- Request: Sử dụng hàm GET với tham số:
“uuid”: guid ?, optional // Lấy theo uuid
“code”: string, optional // Lấy theo mã đặt phòng
- Response:
{ "uuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid đặt phòng "customerId": 63182, "purchaseDate": "2024-04-20T10:08:32.0000000", // thời gian thanh toán "code": "DP000805", // mã đặt phòng "branchId": 3498, // id chi nhánh "status": 1, // trạng thái đặt phòng (1: đã đặt,2: hoàn thành, 3: đã hủy, 4: Chưa xác nhận) "modifiedDate": "2024-04-20T10:09:21.1000000", // ngày cập nhật "retailerId": 602482, "discount": 71100.0000, // tổng giảm giá "soldById": 24587, // nhân viên thanh toán "createdDate": "2024-04-20T10:09:15.0530000", ngày tạo đặt phòng “createdBy”: long, // Id tài khoản tạo "modifiedBy": 11889, // người chỉnh sửa đặt phòng "discountRatio": 10, // phần tram giảm giá "total": 710289.0000, // tổng tiền hóa đơn "totalPayment": 200000.0000, // số tiền khách đã thanh toán "surcharge": 70389.0000, // thu khác "saleChannelId": 602482, // kênh bán "originVersion": 15, "orderDetails": [ { "uuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", // uuid chi tiết đặt phòng "productId": 120843, // id sản phẩm "quantity": 1, // số lượng "price": 700000.0000, // đơn giá "discount": 0.0000, // giảm giá "createdDate": "2024-04-20T10:09:17.8630000", // ngày tạo "discountRatio": 0, // phần tram giảm giá "modifiedDate": "2024-04-20T10:09:20.7870000", // ngày cập nhật "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, // id phòng "roomName": "101", // tên phòng "checkInTime": "2024-04-20T10:09:00.0000000", // ngày nhận phòng "checkOutTime": "2024-04-20T11:00:00.0000000", // ngày trả phòng "status": 2, trạng thái chi tiết đặt phòng (1: Đã đặt, 2: Đã nhận phòng, 3: Đã trả phòng, 4: Đã hủy,5: Chưa xác nhận) "productType": 6 // loại sản phẩm (2: Hàng hóa, 3: Dịch vụ, 6: Hạng phòng, 7: Phu phí), "counterType": 3, // hình thức lưu trú (1: Giờ, 2: Ngày, 3: Đêm ,4: Tháng) "retailerId": 602482, "branchId": 3498, // Id Chi nhánh "basePrice": 700000.0000, // Giá niêm yết "subTotal": 700000 // Tổng thành tiền }, { "productId": 120841, "quantity": 0, "price": 0.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.6230000", "discountRatio": 0, "uuid": "86d77aeb-95b6-4090-bdc7-af27ae026ed6", "modifiedDate": "2024-04-20T10:09:20.5400000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 7, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 0.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", "extraFeeId": 8226 }, { "productId": 120841, "quantity": 0, "price": 0.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.6230000", "discountRatio": 0, "uuid": "6bb035ce-8748-4a30-b68c-50dbc7056616", "modifiedDate": "2024-04-20T10:09:20.5430000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 7, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 0.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418", "extraFeeId": 8225 }, { "id": 219177, "orderId": 108633, "productId": 120842, "quantity": 0, "price": 1000000.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:18.8500000", "discountRatio": 0, "uuid": "51d5aa32-ad3c-4577-97a0-91ba872dccad", "modifiedDate": "2024-04-20T10:09:20.7870000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "checkInTime": "2024-04-20T10:09:00.0000000", "checkOutTime": "2024-04-20T10:09:00.0000000", "status": 2, "productType": 6, "counterType": 2, "retailerId": 602482, "branchId": 3498, "basePrice": 1000000.0000, "subTotal": 0, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418" }, { "productId": 120938, "quantity": 1, "price": 11000.0000, "discount": 0.0000, "createdDate": "2024-04-20T10:09:19.0600000", "discountRatio": 0, "uuid": "b79a0b5e-6841-488a-999a-09e73836aa4a", "modifiedDate": "2024-04-20T10:09:20.5430000", "orderUuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", "isDeleted": false, "roomId": 52926, "status": 0, "productType": 3, "counterType": 0, "retailerId": 602482, "branchId": 3498, "basePrice": 11000.0000, "subTotal": 11000, "parentUuid": "7c37cd98-da15-4408-ab57-bca6b73d9418" } ], "orderAttachments": [ // danh sách file đính kèm { "id": 254, "attachmentUrl": "https://d1k20gtjgkmqcd.cloudfront.net/mthu3/OrderAttachments/1e91d0dc4c5d4fd6bed480a368fcd7a0_0e3a7188146b46d6a79e3d62bb38ced2", "fileName": "hi.xlsx", "createdDate": "2024-04-20T10:09:19.2630000" } ], “historyNote”: “Ghi chú”, // Ghi chú đặt phòng "isCompletedPayment": false, // đã hoàn thành thanh toán hay chưa? "adultQuantity": 1, // số lượng người lớn "childQuantity": 0, // số lượng trẻ em "subTotal": 711000.0000, // tổng thành tiền đặt phòng "discountValue": 71100.0000 // tổng tiền giảm giá } |
9.3. Lấy danh sách đặt phòng
- Mục đích sử dụng: Lấy danh sách đặt phòng
- Phương thức và URL: GET https://api-integration-hotel.kiotviet.vn/public/order/list
- Request: Sử dụng hàm GET với tham số:
- “createdDateFrom”: Datetime, required //Thời gian tạo từ
- “createdDateTo”: Datetime, required //Thời gian tạo đến
- “statuses”: int[], optional //Trạng thái (1: đã đặt,2: hoàn thành, 3: đã hủy, 4: Chưa xác nhận)
- “pageIndex”: int, optional // Số thứ tự trang
- “pageSize”: int, optional // Kích thước trang (tối đa 50)
- Response:
{ "result": { "total": 1, "pageIndex": 0, "pageSize": 50, "data": [ { "uuid": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid đặt phòng "customerId": 63182, "purchaseDate": "2024-04-20T10:08:32.0000000", // thời gian thanh toán "code": "DP000805", // mã đặt phòng "branchId": 3498, // id chi nhánh "status": 1, // trạng thái đặt phòng (1: đã đặt,2: hoàn thành, 3: đã hủy, 4: Chưa xác nhận) "modifiedDate": "2024-04-20T10:09:21.1000000", // ngày cập nhật "retailerId": 602482, "discount": 71100.0000, // tổng giảm giá "soldById": 24587, // nhân viên thanh toán "createdDate": "2024-04-20T10:09:15.0530000", ngày tạo đặt phòng "createdByName": string, // tài khoản tạo "modifiedBy": 11889, // người chỉnh sửa đặt phòng "discountRatio": 10, // phần tram giảm giá "total": 710289.0000, // tổng tiền hóa đơn "totalPayment": 200000.0000, // số tiền khách đã thanh toán "surcharge": 70389.0000, // thu khác "saleChannelId": 602482, // kênh bán "originVersion": 15, "roomNames": [ “Deluxe Room” ], “historyNote”: “Ghi chú”, // Ghi chú đặt phòng "isCompletedPayment": false, // đã hoàn thành thanh toán hay chưa? "adultQuantity": 1, // số lượng người lớn "childQuantity": 0, // số lượng trẻ em "subTotal": 711000.0000, // tổng thành tiền đặt phòng "discountValue": 71100.0000 // tổng tiền giảm giá } ], "timestamp": "2025-12-31T08:30:59.6906756+07:00" } |
9.4. Tạo mã QR thanh toán đặt phòng
- Mục đích sử dụng: Tạo mã QR thanh toán (VietQR qua cổng DigiInvoice) cho một đặt phòng để khách quét và chuyển khoản. Khi ngân hàng báo có, hệ thống tự ghi nhận tiền vào đặt phòng và gửi webhook ORDER_QR_PAID.
- Phương thức và URL:
POST https://api-integration-hotel.kiotviet.vn/public/order/qr-payment
- Request: Sử dụng hàm Post với body:
{ "orderUuid": "3f2c9b7e-8d41-4c2a-9f6e-1a2b3c4d5e6f", // string / required / uuid đặt phòng "amount": 500000, // long / required / số tiền cần thu, lớn hơn 0 "description": "Thanh toan don DP000012", // string(80) / optional / nội dung chuyển khoản "bankAccountType": "Bank" // string / optional / loại tài khoản nhận tiền: Bank (Tài khoản ngân hàng) hoặc Wallet (Tài khoản ví điện tử) } |
- Mô tả các trường trong body:
Trường | Kiểu dữ liệu | Bắt buộc | Mô tả |
|
| BẮT BUỘC | Uuid đặt phòng |
|
| BẮT BUỘC | Số tiền cần thu, phải lớn hơn 0. Hệ thống không so sánh với số tiền còn phải thu của đặt phòng |
|
| TÙY CHỌN | Nội dung chuyển khoản. Hệ thống tự bỏ dấu tiếng Việt, bỏ ký tự đặc biệt (chỉ giữ chữ cái, chữ số và khoảng trắng) và cắt còn tối đa 80 ký tự. Không truyền thì dùng |
|
| TÙY CHỌN | Loại tài khoản nhận tiền trong Thiết lập Đặt lịch online: |
- Lưu ý:
- Tài khoản nhận tiền lấy từ mục thanh toán trong Thiết lập Đặt lịch online của gian hàng:
Bank→ Tài khoản ngân hàng,Wallet→ Tài khoản ví điện tử; chỉ xét hình thức đang bật và đã chọn tài khoản. Chưa thiết lập thì API trả lỗi 400. - Hệ thống không kiểm tra
amountso với số tiền còn phải thu của đặt phòng; đối tác tự quyết định số tiền cần thu. - Mỗi lần gọi tạo ra một mã QR mới với
transactionIdmới. Chỉ nên hiển thị mã QR mới nhất cho khách để tránh thanh toán trùng. transactionIdtrả về chính làtransactionIdtrong webhookORDER_QR_PAID, dùng để đối chiếu mã QR nào đã được thanh toán.- Không tạo được mã QR cho đặt phòng đã hủy hoặc đã hoàn thành.
- Response:
{ "result": { "orderUuid": "3f2c9b7e-8d41-4c2a-9f6e-1a2b3c4d5e6f", "orderCode": "DP000012", // mã đặt phòng "amount": 500000, // số tiền của mã QR "qrCode": "data:image/png;base64,iVBORw0KGgo...", // ảnh mã QR dạng base64 (data URI) "transactionId": "3f2c9b7e-8d41-4c2a-9f6e-1a2b3c4d5e6f", // mã yêu cầu thanh toán QR, trùng transactionId trong webhook ORDER_QR_PAID "content": "Thanh toan don DP000012" // nội dung chuyển khoản thực tế (sau chuẩn hoá) } } |
- Lỗi thường gặp:
HTTP |
| Nguyên nhân |
| Id đặt phòng là bắt buộc | Thiếu |
| Số tiền thanh toán phải lớn hơn 0 | Thiếu |
| Loại tài khoản nhận tiền không hợp lệ, chỉ nhận Bank (tài khoản ngân hàng) hoặc Wallet (tài khoản ví điện tử) |
|
| Đặt phòng DP000012 không tồn tại |
|
| Đặt phòng đã hủy hoặc đã hoàn thành, không thể tạo mã QR thanh toán | Trạng thái đặt phòng là 2 (hoàn thành) hoặc 3 (đã hủy) |
| Gian hàng chưa thiết lập tài khoản nhận thanh toán QR trong Đặt lịch online | Không truyền |
| Gian hàng chưa thiết lập tài khoản ngân hàng nhận thanh toán QR trong Đặt lịch online | Truyền |
| Không tạo được mã QR thanh toán, vui lòng thử lại | Cổng thanh toán lỗi hoặc quá thời gian xử lý |
- Mục đích sử dụng: Trả về danh sách kênh bán
- Phương thức và URL: GET https://api-integration-hotel.kiotviet.vn/public/sale-channels
- Request: Sử dụng hàm GET với tham số:
“name”: string?, optional // lọc theo tên kênh bán
“isActive”: Boolean?, optional // lọc theo trạng thái hoạt động của kênh bán
“saleChannelIds”: int[]?, optional // lọc theo id kênh bán
“pageIndex”: int, // thứ tự trang lấy dữ liệu
“pageSize”: int?, // số items trong 1 trang, mặc định 50 items, tối đa 100 items
- Response:
{ |
- Mục đích sử dụng: Trả về thông tin chi tiết của kênh bán theo id
- Phương thức và URL: GET https://api-integration-hotel.kiotviet.vn/public/sale-channels/{id}
- Request: Sử dụng hàm GET với tham số:
“id”: long // ID của kênh bán
- Response:
{ |
11. Phiếu bàn giao ca
Mô tả chi tiết cho các API liên quan đến thông tin phiếu bàn giao ca (ca làm việc) như sau:
11.1. Lấy danh sách phiếu bàn giao ca
- Mục đích sử dụng: Lấy danh sách phiếu bàn giao ca của một chi nhánh theo khoảng ngày mở ca, ca mở gần nhất đứng đầu.
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/workingshifts
- Request: Sử dụng hàm GET với tham số:
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
|
| BẮT BUỘC | Id chi nhánh (xem 2. Lấy danh sách chi nhánh) |
|
| BẮT BUỘC | Ngày mở ca từ, định dạng |
|
| BẮT BUỘC | Ngày mở ca đến, định dạng |
|
| TÙY CHỌN | Id nhân viên mở ca, phân cách bằng dấu phẩy, ví dụ |
|
| TÙY CHỌN | Số thứ tự trang, bắt đầu từ 1 |
|
| TÙY CHỌN | Kích thước trang, mặc định 50, tối đa 100 |
- Response:
{ "result": { "total": 2, // tổng số phiếu bàn giao ca thỏa điều kiện "pageIndex": 1, "pageSize": 50, "data": [ { "id": 21137, // id ca, dùng để lấy chi tiết (11.2) "code": "CA000137", // mã phiếu bàn giao ca "branchId": 310, // id chi nhánh "userId": 24587, // id nhân viên mở ca "userName": "Nguyễn Văn A", // tên nhân viên mở ca "status": 1, // trạng thái ca (1: đang mở, 2: đã đóng) "openDate": "2026-09-30T07:58:12.0000000", // thời điểm mở ca "openShiftMoney": 500000.0000, // tiền mặt đầu ca "openShiftNote": "Ca sáng", // ghi chú mở ca "createdDate": "2026-09-30T07:58:12.0000000", // ngày tạo "modifiedDate": "2026-09-30T07:58:12.0000000" // ngày cập nhật }, { "id": 21120, "code": "CA000136", "branchId": 310, "userId": 24590, "userName": "Trần Thị B", "status": 2, "openDate": "2026-09-29T14:00:05.0000000", "closeDate": "2026-09-29T22:03:41.0000000", // thời điểm đóng ca, không có khi ca đang mở "openShiftMoney": 500000.0000, "closeShiftMoney": 1500000.0000, // tiền mặt bàn giao thực tế do nhân viên nhập khi đóng ca "totalCloseShiftCash": 1550000.0000, // tiền mặt cuối ca theo hệ thống = tiền mặt đầu ca + tiền mặt thu chi trong ca "closeShiftNote": "Thiếu 50.000", // ghi chú đóng ca "createdDate": "2026-09-29T14:00:05.0000000", "modifiedDate": "2026-09-29T22:03:41.0000000" } ], "timestamp": "2026-10-05T08:30:59.6906756+07:00" } } |
- Lưu ý:
- Chênh lệch tiền mặt của ca đã đóng =
closeShiftMoney−totalCloseShiftCash. - Trường không có giá trị (ví dụ
closeDatecủa ca đang mở) không xuất hiện trong response. branchIdkhông thuộc gian hàng thì trả về danh sách rỗng.
- Lỗi thường gặp:
HTTP |
| Nguyên nhân |
| Tham số BranchId không đúng | Thiếu |
| StartDate, EndDate không được để trống | Thiếu |
| StartDate không được lớn hơn EndDate |
|
| Khoảng cách thời gian không được lớn hơn 90 ngày |
|
11.2. Lấy chi tiết phiếu bàn giao ca
- Mục đích sử dụng: Lấy thông tin một phiếu bàn giao ca, tổng hợp thu chi theo từng loại chứng từ và (tùy chọn) hàng hóa, phòng đã bán trong ca.
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/workingshift/summary
- Request: Sử dụng hàm GET với tham số:
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
|
| BẮT BUỘC | Id ca, lấy từ trường |
|
| TÙY CHỌN |
|
- Response:
{ "result": { "workingShift": { // thông tin ca, cùng cấu trúc một phần tử data của 11.1 "id": 21137, "code": "CA000137", "branchId": 310, "userId": 24587, "userName": "Nguyễn Văn A", "status": 1, "openDate": "2026-09-30T07:58:12.0000000", "openShiftMoney": 500000.0000, "openShiftNote": "Ca sáng", "createdDate": "2026-09-30T07:58:12.0000000", "modifiedDate": "2026-09-30T07:58:12.0000000" }, "details": [ // tổng hợp theo loại chứng từ, loại không phát sinh trong ca sẽ không có dòng { "documentType": 1, // loại chứng từ (1: bán hàng, 2: phiếu thu, 3: phiếu chi, 4: trả hàng) "quantity": 2.0000, // số chứng từ "cash": 0.0000, // tiền mặt "transfer": 369000.0000, // chuyển khoản "card": 0.0000, // thẻ "point": 0.0000, // thanh toán bằng điểm "wallet": 299780.0000, // ví điện tử "voucher": 0.0000, // voucher "debt": 0.0000, // khách nợ, chỉ có giá trị với documentType = 1 "total": 668780.0000 // tổng = cash + transfer + card + point + wallet + voucher + debt }, { "documentType": 3, // phiếu chi mang giá trị âm "quantity": 6.0000, "cash": 0.0000, "transfer": -1022150.0000, "card": -50666.0000, "point": 0.0000, "wallet": -4644444.0000, "voucher": 0.0000, "debt": 0.0000, "total": -5717260.0000 } ], "productDetails": [ // mảng rỗng khi includeInvoiceProduct = false { "productId": 2326, // id hàng hóa, phòng "name": "Standard (Ngày)", // tên đầy đủ "quantity": 1.0000 // tổng số lượng đã bán trong ca } ] } } |
- Lưu ý:
- Ca đang mở (
status= 1): số liệu tính tại thời điểm gọi, thay đổi khi có giao dịch mới hoặc hóa đơn bị hủy. - Ca đã đóng (
status= 2): số liệu đã chốt lúc đóng ca, không thay đổi về sau. - Số tiền được làm tròn theo tiền tệ của gian hàng (VND: số nguyên).
- Lỗi thường gặp:
HTTP |
| Nguyên nhân |
| Ca làm việc không tồn tại |
|
12. Khóa phòng
Mô tả chi tiết cho các API liên quan đến khóa phòng (phòng tạm ngừng cho thuê để sửa chữa, dùng nội bộ…, mã dạng KP000001) như sau:
12.1. Lấy danh sách khóa phòng
- Mục đích sử dụng: Lấy danh sách khóa phòng của gian hàng, sắp xếp theo thời gian bắt đầu khóa tăng dần.
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/room-locks
- Request: Sử dụng hàm GET với tham số:
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
|
| TÙY CHỌN | Id chi nhánh, phân cách bằng dấu phẩy, ví dụ |
|
| TÙY CHỌN | Id phòng, phân cách bằng dấu phẩy. Lấy khóa phòng có ít nhất một phòng trong danh sách |
|
| TÙY CHỌN | Loại khóa (1: sửa chữa, 2: dùng nội bộ, 3: khác), phân cách bằng dấu phẩy |
|
| TÙY CHỌN | Trạng thái (1: đang khóa, 2: đã hủy), phân cách bằng dấu phẩy. Không truyền thì lấy cả hai |
|
| TÙY CHỌN | Lọc khóa phòng có thời gian khóa giao với khoảng |
|
| TÙY CHỌN | Lấy khóa phòng có |
|
| TÙY CHỌN | Lấy khóa phòng được tạo hoặc cập nhật từ thời điểm này, dùng để đồng bộ phần dữ liệu thay đổi |
|
| TÙY CHỌN | Số thứ tự trang, bắt đầu từ 1 |
|
| TÙY CHỌN | Kích thước trang, mặc định 20, tối đa 100 |
- Response:
{ "result": { "total": 2, // tổng số khóa phòng thỏa điều kiện "pageIndex": 1, "pageSize": 20, "data": [ { "uuid": "7c1e5b0a-3f2d-4e8b-9a61-2d4c8f0e7b35", // uuid khóa phòng, dùng để lấy chi tiết (2.13.2) "code": "KP000015", // mã khóa phòng "retailerId": 602482, // id gian hàng "branchId": 3498, // id chi nhánh "branchName": "Chi nhánh trung tâm", // tên chi nhánh "lockType": 1, // loại khóa (1: sửa chữa, 2: dùng nội bộ, 3: khác) "status": 1, // trạng thái (1: đang khóa, 2: đã hủy) "startTime": "2026-10-20T14:00:00.0000000", // thời gian bắt đầu khóa = giờ nhận phòng sớm nhất của các phòng "endTime": "2026-10-22T12:00:00.0000000", // thời gian kết thúc khóa = giờ trả phòng muộn nhất của các phòng "rooms": [ // danh sách phòng bị khóa { "roomId": 53121, // id phòng "roomName": "P101", // tên phòng "roomClassId": 121236, // id hạng phòng (xem 2.8. Hạng phòng) "roomClassName": "Phòng 01 giường đôi" // tên hạng phòng }, { "roomId": 53122, "roomName": "P102", "roomClassId": 121236, "roomClassName": "Phòng 01 giường đôi" } ], "note": "Bảo trì điều hòa", // lý do khóa "createdBy": 24587, // id tài khoản tạo "createdByName": "admin", // tên tài khoản tạo "createdDate": "2026-10-15T09:12:31.4570000", // ngày tạo "modifiedBy": 24587, // id tài khoản cập nhật gần nhất "modifiedDate": "2026-10-15T09:12:31.9800000" // ngày cập nhật gần nhất }, { "uuid": "1f0e7c3b-2a9d-4e85-b6c4-7d3a9e0f5b21", "code": "KP000012", "retailerId": 602482, "branchId": 3498, "branchName": "Chi nhánh trung tâm", "lockType": 2, "status": 2, "startTime": "2026-10-25T14:00:00.0000000", "endTime": "2026-10-26T12:00:00.0000000", "rooms": [ { "roomId": 53130, "roomName": "P201", "roomClassId": 121240, "roomClassName": "Phòng gia đình" } ], "createdBy": 24587, "createdByName": "admin", "createdDate": "2026-10-12T08:05:10.1270000", "modifiedBy": 24590, "modifiedDate": "2026-10-14T16:45:02.3300000", "cancelledDate": "2026-10-14T16:45:02.1230000" // thời điểm hủy, chỉ có khi status = 2 } ], "timestamp": "2026-10-15T09:30:59.6906756+07:00" } } |
- Lưu ý:
- Kết quả sắp xếp theo
startTimetăng dần, trùngstartTimethì theo thứ tự tạo. startDate,endDatelọc theo khoảng thời gian khóa giao nhau, không tính chạm biên: khóa phòng kết thúc đúng lúcstartDatehoặc bắt đầu đúng lúcendDatekhông được trả về.statuseschỉ gồm giá trị khác 1, 2 thì trả về danh sách rỗng.- Trường không có giá trị (ví dụ
notekhi không nhập lý do,cancelledDatecủa khóa phòng đang khóa) không xuất hiện trong response. - Khóa phòng đã hủy vẫn trả đủ danh sách phòng đã khóa trước khi hủy.
- Khóa phòng không xuất hiện trong 9.3. Lấy danh sách đặt phòng.
- Lỗi thường gặp:
HTTP |
| Nguyên nhân |
| PageSize không được lớn hơn 100 |
|
| StartDate phải nhỏ hơn EndDate |
|
12.2. Lấy chi tiết khóa phòng
- Mục đích sử dụng: Lấy thông tin một khóa phòng theo uuid.
- Phương thức và URL:
GET https://api-integration-hotel.kiotviet.vn/public/room-locks/{uuid}
- Request: Sử dụng hàm GET với tham số:
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
|
| BẮT BUỘC | Uuid khóa phòng, lấy từ trường |
- Response:
{ "result": { // cùng cấu trúc một phần tử data của 2.13.1 "uuid": "7c1e5b0a-3f2d-4e8b-9a61-2d4c8f0e7b35", "code": "KP000015", "retailerId": 602482, "branchId": 3498, "branchName": "Chi nhánh trung tâm", "lockType": 1, "status": 1, "startTime": "2026-10-20T14:00:00.0000000", "endTime": "2026-10-22T12:00:00.0000000", "rooms": [ { "roomId": 53121, "roomName": "P101", "roomClassId": 121236, "roomClassName": "Phòng 01 giường đôi" }, { "roomId": 53122, "roomName": "P102", "roomClassId": 121236, "roomClassName": "Phòng 01 giường đôi" } ], "note": "Bảo trì điều hòa", "createdBy": 24587, "createdByName": "admin", "createdDate": "2026-10-15T09:12:31.4570000", "modifiedBy": 24587, "modifiedDate": "2026-10-15T09:12:31.9800000" } } |
- Lỗi thường gặp:
HTTP |
| Nguyên nhân |
| Khóa phòng không tồn tại |
|
| Unable to bind to request 'PublicRoomLockDetail' |
|
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 27/10/2026
Mục lục
- I. Thiết lập kết nối API
- II. Chức năng
- 1. Authenticate
- 2. Lấy danh sách chi nhánh
- 3. Lấy danh sách nhóm hàng
- 4. Lấy danh sách hàng hóa
- 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
- 8. Hạng phòng
- 8.1. Lấy danh sách hạng phòng
- 8.2. Lấy chi tiết hạng phòng
- 9. Đặt phòng
- 9.1. Tạo đặt phòng
- 9.2. Lấy chi tiết đặt phòng
- 9.3. Lấy danh sách đặt phòng
- 9.4. Tạo mã QR thanh toán đặt phòng
- 10. Kênh bán
- 10.1. Danh sách kênh bán
- 10.2. Chi tiết kênh bán
- 11. Phiếu bàn giao ca
- 11.1. Lấy danh sách phiếu bàn giao ca
- 11.2. Lấy chi tiết phiếu bàn giao ca
- 12. Khóa phòng
- 12.1. Lấy danh sách khóa phòng
- 12.2. Lấy chi tiết khóa phòng