Yêu cầu và phản hồi
Trang này trình bày các định dạng nội dung yêu cầu, lớp bọc phản hồi, phân trang, định dạng ngày và số tiền, cũng như cách diễn giải mã trạng thái HTTP.
Nội dung yêu cầu#
Các endpoint dùng một trong hai định dạng nội dung. Trang tham chiếu của từng endpoint cho biết định dạng nào được áp dụng.
| Định dạng | Content-Type | Dùng cho |
|---|---|---|
| Trường form | application/x-www-form-urlencoded hoặc multipart/form-data | Đăng nhập, danh sách phòng, kiểm tra mã giảm giá, quốc gia |
| JSON | application/json | Gửi đặt phòng (BookingPushRQ), bắt đầu thanh toán |
| Chuỗi truy vấn | — | Mọi endpoint GET |
Trường dạng mảng trong nội dung form được lặp lại với dấu ngoặc vuông: childAges[]=7&childAges[]=12. Nội dung JSON phải dùng mã hóa UTF-8.
Lớp bọc phản hồi#
Phản hồi ở dạng JSON. Phần lớn phản hồi có cờ success; danh sách được trả về kèm count và items:
{
"success": true,
"count": 3,
"items": [
{
"id": 1,
"titleCode": "TRY",
"symbol": "₺",
"price": 1
},
{
"id": 2,
"titleCode": "EUR",
"symbol": "€",
"price": 47.85000000000000142108547152020037174224853515625
}
]
}Khi kiểm tra quy tắc nghiệp vụ thất bại, API trả về success: false kèm mô tả lỗi, theo một trong hai dạng:
{
"success": false,
"message": "online_cupon_is_not_found"
}{
"success": false,
"errorMessage": "Invalid parameters.",
"errorCode": 10022
}Ngoại lệ: endpoint thông tin liên hệ trả về một đối tượng trần không có lớp bọc, còn gửi đặt phòng trả về đối tượng BookingPushRS. Cả hai đều được trình bày trong phần tham chiếu.
Mã trạng thái HTTP#
| Mã | Khi nào | Cần làm gì |
|---|---|---|
| 200 | Yêu cầu đã được xử lý (thành công hoặc lỗi quy tắc nghiệp vụ) | Kiểm tra success, message / errorCode. |
| 401 | Token bị thiếu, sai định dạng hoặc không xác định | Đăng nhập lại; xem Xác thực. |
| 404 | Tham số đường dẫn không khớp với bản ghi nào (ví dụ /hotel/{hotelID}/…, /payment/type/{paymentType}) | Kiểm tra ID. |
| 405 | Sai phương thức HTTP | Dùng phương thức nêu trong phần tham chiếu (quốc gia và danh sách phòng dùng POST). |
| 500 | Lỗi máy chủ không mong muốn | Thử lại sau một khoảng ngắn; nếu lỗi vẫn tiếp diễn, hãy gửi yêu cầu hỗ trợ kèm theo yêu cầu API đã gửi. |
Phân trang#
Các endpoint danh sách (/external/currencies, /external/languages, /external/online/social/media, /external/stock/packages) được phân trang theo số trang:
| Tham số | Mô tả | Mặc định |
|---|---|---|
limit | Số bản ghi mỗi trang. | 20 |
page | Số trang, bắt đầu từ 1. | 1 |
offset | Số bản ghi cần bỏ qua. Nếu có tham số này, page bị bỏ qua. | — |
order | Trường sắp xếp; thêm tiền tố - để sắp xếp giảm dần (-id). Các trường được phép được liệt kê theo từng endpoint. | — |
count là tổng số bản ghi; danh sách đã hết khi page × limit ≥ count.
Ngày, giờ và số tiền#
| Loại | Định dạng | Ví dụ |
|---|---|---|
| Ngày trong yêu cầu | YYYY-MM-DD | 2026-08-18 |
| Ngày của phòng trống | YYYY-MM-DD hoặc YYYY-MM-DDTHH:MM:SS | 2026-08-18T12:00:00 |
| Ngày của giá theo đêm (phản hồi) | DD.MM.YYYY (trường tarih) | 18.08.2026 |
| Khoảng ngày của phòng trống (phản hồi) | YYYY-MM-DD HH:MM:SS, từ 12:00 đến 12:00 ngày hôm sau | 2026-08-18 12:00:00 |
| Số tiền | Chuỗi có hai chữ số thập phân, dấu chấm làm dấu phân cách | "965.00" |
| Tiền tệ | ISO 4217; lấy từ cài đặt kênh trực tuyến của khách sạn | TRY |
| Múi giờ | Múi giờ của khách sạn | Europe/Istanbul |
Ngày trả phòng không tính vào thời gian lưu trú: từ 18 đến 20 tháng 8 là hai đêm. Không cộng số tiền bằng float; hãy dùng thư viện số thập phân hoặc số nguyên theo đơn vị tiền nhỏ nhất.
Ngôn ngữ#
Danh sách phòng nhận trường language (ISO 639-1: tr, en, de…) và trả về tên phòng, tên tiện nghi và thông báo lỗi bằng ngôn ngữ đó. Danh sách gói dịch vụ yêu cầu languageID; các ID lấy từ endpoint Ngôn ngữ.