Thiết lập Webhook
(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
- Bước 1: 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 Webhook.
- Bước 2: Bật tính năng.
- Nhập Wehook URL: Bắt đầu bằng https://
- Đặt lại Mã bảo mật (Secret key) nếu muốn.
- Bật xanh các sự kiện muốn ghi nhận.
- Chọn Lưu để hoàn tất thao tác thiết lập.
Lưu ý: Thời gian xử lý của server phải nhỏ hơn 3 giây và response status = 200.
II. Hướng dẫn validate webhook
1. Các thông tin chung
- Event được trả về theo method POST. Request body dạng application/json.
- Header bao gồm x-signature được mã hóa theo chuẩn SHA-HMAC256 (data + timestamp + retailerCode + secretKey) và x-timestamp là thời gian gửi thông tin theo giờ UTC
2. Hướng dẫn validate
Giải thích thuật ngữ:
- retailerCode: Mã gian hàng
- secretKey: Mã bí mật
- timeStamp: Là thời gian gửi được lấy bằng x-timestamp lấy từ header
- data: Request body
Code mẫu:
C#:
public static class WebhookHepler { public static bool Verify(string secretKey, string retailerCode, string timeStamp, string signature, object data) { try { var jsonSetting = new JsonSerializerSettings { Formatting = Formatting.Indented, ContractResolver = new CamelCasePropertyNamesContractResolver(), DateParseHandling = DateParseHandling.DateTimeOffset, DateFormatHandling = DateFormatHandling.IsoDateFormat, ReferenceLoopHandling = ReferenceLoopHandling.Ignore, NullValueHandling = NullValueHandling.Ignore }; var dataToStr = JsonConvert.SerializeObject(data, jsonSetting); byte[] secretBytes = Encoding.UTF8.GetBytes(secretKey); var verifyCombineStr = dataToStr + timeStamp + retailerCode + secretKey; byte[] dataBytes = Encoding.UTF8.GetBytes(verifyCombineStr); using (var hmac = new HMACSHA256(secretBytes)) { byte[] hmacBytes = hmac.ComputeHash(dataBytes); return System.Convert.ToBase64String(hmacBytes) == signature; } } catch (Exception ex) { return false; } } } |
Javascript :
function verify( secretKey, retailerCode, timeStamp, signature, dataStr ) { try { const secretBytes = CryptoJS.enc.Utf8.parse(secretKey); const verifyCombineStr = dataStr + timeHeader.toString() + retailerCode + secretKey; const dataBytes = CryptoJS.enc.Utf8.parse(verifyCombineStr); const hmac = CryptoJS.HmacSHA256(dataBytes, secretBytes); const hmacBase64 = CryptoJS.enc.Base64.stringify(hmac); return hmacBase64 === signature; } catch (ex) { return false; } } |
III. Sự kiện
Danh sách các sự kiện webhook mà hệ thống gửi đi:
Nhóm | eventName | Sự kiện |
ORDER_CREATED | Gian hàng có đặt phòng mới | |
ORDER_UPDATED | Gian hàng có thay đổi trên đặt phòng | |
ORDER_CANCELLED | Gian hàng hủy đặt phòng | |
CUSTOMER_CREATED | Gian hàng tạo khách hàng mới | |
CUSTOMER_UPDATED | Gian hàng cập nhật khách hàng | |
CUSTOMER_DELETED | Gian hàng xóa khách hàng | |
INVOICE_CREATED | Gian hàng tạo hóa đơn mới | |
INVOICE_UPDATED | Gian hàng cập nhật hóa đơn | |
INVOICE_CANCELLED | Gian hàng hủy hóa đơn | |
ORDER_QR_PAID | Gian hàng nhận thanh toán đặt phòng qua QR Code |
1. Đặt phòng
1.1. Gian hàng có đặt phòng mới ORDER_CREATED
Phát sinh khi gian hàng có đặt phòng mới được tạo.
Request body:
{ "eventName" : "ORDER_CREATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request 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 "createdBy": 11889, // người tạo đặt phòng "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 "productIName":"Hạng phòng vip", // tên 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, "productIName":"Phụ thu nhận sớm Hạng phòng vip", // tên sản phẩm "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, "productIName":"Hạng phòng royal", // tên sản phẩm "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á } } |
1.2. Gian có thay đổi trên đặt phòng ORDER_UPDATED
Phát sinh khi gian hàng có thay đổi thông tin của đặt phòng
Request body:
{ "eventName" : "ORDER_UPDATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request 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 "createdBy": 11889, // người tạo đặt phòng "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 }, { "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á } } |
1.3. Gian hàng hủy đặt phòng ORDER_CANCELLED
Phát sinh khi gian hàng hủy đặt phòng.
Request body:
{ "eventName" : "ORDER_CANCELLED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request 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 "createdBy": 11889, // người tạo đặt phòng "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 }, { "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á } } |
2. Khách hàng
2.1. Gian hàng tạo khách hàng mới CUSTOMER_CREATED
Phát sinh khi gian hàng có khách hàng mới được tạo
Request body:
{ "eventName" : "CUSTOMER_CREATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "data": { "id": long // id khách hàng "code": string // Mã khách hàng "name": string// 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 "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 "locationId":int?,// Id vị trí "nationId":int?,// Id quốc tịch "branchId":int?,// Id chi nhánh "avatar":string ,// avatar khách hàng, "type":string, // loại khách hàng (0: khách hàng cá nhân , 1: Khách hàng công ty) "isActive":bool ,// trạng thái hoạt động, "createdBy":long, // Id người tạo khách hàng, "customerAttachments":[ "id": long, "fileName": string, // tên file "type": short, // loại file (1: ảnh, 2: File đính kèm) "attachmentUrl": string, // url file ] } } |
2.2. Gian hàng cập nhật khách hàng CUSTOMER_UPDATED
Phát sinh khi gian hàng cập nhật thông tin khách hàng.
Request body:
{ "eventName" : "CUSTOMER_UPDATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "data": { "id": long // id khách hàng "code": string // Mã khách hàng "name": string// 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 "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 "locationId":int?,// Id vị trí "nationId":int?,// Id quốc tịch "branchId":int?,// Id chi nhánh "avatar":string ,// avatar khách hàng, "type":string, // loại khách hàng (0: khách hàng cá nhân , 1: Khách hàng công ty) "isActive":bool ,// trạng thái hoạt động, "createdBy":long, // Id người tạo khách hàng, "customerAttachments":[ "id": long, "fileName": string, // tên file "type": short, // loại file (1: ảnh, 2: File đính kèm) "attachmentUrl": string, // url file ] } } |
2.3. Gian hàng xóa khách hàng CUSTOMER_DELETED
Phát sinh khi gian hàng xóa khách hàng.
Request body:
{ "eventName" : "CUSTOMER_DELETED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "data": { "id": long // id khách hàng "code": string // Mã khách hàng "name": string// 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 "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 "locationId":int?,// Id vị trí "nationId":int?,// Id quốc tịch "branchId":int?,// Id chi nhánh "avatar":string ,// avatar khách hàng, "type":string, // loại khách hàng (0: khách hàng cá nhân , 1: Khách hàng công ty) "isActive":bool ,// trạng thái hoạt động, "createdBy":long, // Id người tạo khách hàng, "customerAttachments":[ "id": long, "fileName": string, // tên file "type": short, // loại file (1: ảnh, 2: File đính kèm) "attachmentUrl": string, // url file ] } } |
3. Hóa đơn
3.1. Gian hàng tạo hóa đơn mới INVOICE_CREATED
Phát sinh khi gian hàng có hóa đơn mới được tạo.
Request body:
{ "eventName" : "INVOICE_CREATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "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 người tạo hóa đơn "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?, "method": string, "voucherId": long?, }], // Thông tin thanh toán "invoiceOrderSurcharges" :[{ "id": long, "invoiceId": long?, "surchargeId": int?, "name": string, "value": decimal, "price": decimal, "surValueRatio": double, "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, "unit": string, "extraFreeId": int?, }], // 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 } } |
3.2. Gian hàng cập nhật hóa đơn INVOICE_UPDATED
Phát sinh khi gian hàng cập nhật hóa đơn.
Request body:
{ "eventName" : "INVOICE_UPDATED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "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 người tạo hóa đơn "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?, "method": string, "voucherId": long?, }], // Thông tin thanh toán "invoiceOrderSurcharges" :[{ "id": long, "invoiceId": long?, "surchargeId": int?, "name": string, "value": decimal, "price": decimal, "surValueRatio": double, "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, "unit": string, "extraFreeId": int?, }], // 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 } } |
3.3. Gian hàng hủy hóa đơn INVOICE_CANCELLED
Phát sinh khi gian hàng hủy hóa đơn.
Request body:
{ "eventName" : "INVOICE_CANCELLED", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "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 người tạo hóa đơn "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?, "method": string, "voucherId": long?, }], // Thông tin thanh toán "invoiceOrderSurcharges" :[{ "id": long, "invoiceId": long?, "surchargeId": int?, "name": string, "value": decimal, "price": decimal, "surValueRatio": double, "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, "unit": string, "extraFreeId": int?, }], // 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 } } |
4. Thanh toán đặt phòng online qua QR Code
4.1. Gian hàng nhận thanh toán đặt phòng online qua QR Code ORDER_QR_PAID
Phát sinh khi khách thanh toán đặt phòng online bằng mã QR và cổng thanh toán (DigiInvoice) báo mã QR đã thu đủ tiền.
Lưu ý: amount là số tiền của từng giao dịch QR vừa thu, không phải tổng tiền đặt phòng. Bên nhận nên dùng transactionId+subTransactionId để chống xử lý trùng khi nhận lại cùng một thông báo.
Các trường trong data:
Trường | Kiểu dữ liệu | Mô tả |
orderCode | string | Mã đặt phòng |
status | string | Trạng thái giao dịch QR do cổng thanh toán trả về: INPROCESS (Thanh toán nhưng chưa đủ), COMPLETED (thanh toán thành công), FAILED (thất bại) |
totalAmount | decimal | Số tiền thanh toán khi generate QR |
amount | decimal | Số tiền của giao dịch thanh toán vừa ghi nhận (không phải tổng tiền của đặt phòng) |
transactionId | string | Mã của yêu cầu thanh toán QR (mỗi mã QR sinh ra một transactionId) |
subTransactionId | string | Mã giao dịch con, tương ứng một thông báo chuyển khoản từ ngân hàng cho mã QR. |
paidAt | datetime | Thời điểm hệ thống ghi nhận thanh toán |
branchId | int | Id chi nhánh |
customerName | string | Tên khách hàng |
customerPhone | string | Số điện thoại khách hàng |
paymentMethod | string | Hình thức thanh toán: Transfer (chuyển khoản ngân hàng) hoặc Wallet (ví điện tử), xác định theo loại tài khoản nhận tiền của mã QR |
currency | string | Đơn vị tiền tệ, hiện tại là VND |
checkInDate | datetime? | Thời gian nhận phòng sớm nhất trong các phòng của đặt phòng |
checkOutDate | datetime? | Thời gian trả phòng muộn nhất trong các phòng của đặt phòng |
note | string | Ghi chú đặt phòng |
Request body:
{ "eventName": "ORDER_QR_PAID", // tên sự kiện "requestId": "1e91d0dc-4c5d-4fd6-bed4-80a368fcd7a0", // uuid request "data": { "orderCode": "DP000001", // mã đặt phòng "status": "COMPLETED", // trạng thái giao dịch QR "totalAmount": 550000, // số tiền thanh toán khi generate QR "amount": 550000, // số tiền của giao dịch vừa ghi nhận (không phải tổng tiền đơn) "transactionId": "3f2c9b7e-8d41-4c2a-9f6e-1a2b3c4d5e6f", // mã yêu cầu thanh toán QR "subTransactionId": "4653243", // mã giao dịch con, "paidAt": "2026-09-04T10:15:30.0000000", // thời điểm ghi nhận thanh toán "branchId": 3498, // id chi nhánh "customerName": "Trần Thị Hoa", // tên khách hàng "customerPhone": "0312931028", // số điện thoại khách hàng "paymentMethod": "Transfer", // hình thức thanh toán: Transfer | Wallet "currency": "VND", // đơn vị tiền tệ "checkInDate": "2026-09-05T14:00:00.0000000", // thời gian nhận phòng sớm nhất của các phòng trong đơn "checkOutDate": "2026-09-07T12:00:00.0000000", // thời gian trả phòng muộn nhất của các phòng trong đơn "note": "Khách yêu cầu phòng tầng cao" // ghi chú đặt phòng } } |
Như vậy, KiotViet đã thực hiện xong phần hướng dẫn sử dụng Webhook.
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 09/09/2026
Mục lục
- I. Cấu hình Webhook
- II. Hướng dẫn validate webhook
- 1. Các thông tin chung
- 2. Hướng dẫn validate
- III. Sự kiện
- 1. Đặt phòng
- 1.1. Gian hàng có đặt phòng mới ORDER_CREATED
- 1.2. Gian có thay đổi trên đặt phòng ORDER_UPDATED
- 1.3. Gian hàng hủy đặt phòng ORDER_CANCELLED
- 2. Khách hàng
- 2.1. Gian hàng tạo khách hàng mới CUSTOMER_CREATED
- 2.2. Gian hàng cập nhật khách hàng CUSTOMER_UPDATED
- 2.3. Gian hàng xóa khách hàng CUSTOMER_DELETED
- 3. Hóa đơn
- 3.1. Gian hàng tạo hóa đơn mới INVOICE_CREATED
- 3.2. Gian hàng cập nhật hóa đơn INVOICE_UPDATED
- 3.3. Gian hàng hủy hóa đơn INVOICE_CANCELLED
- 4. Thanh toán đặt phòng online qua QR Code
- 4.1. Gian hàng nhận thanh toán đặt phòng online qua QR Code ORDER_QR_PAID
