Hotelia Hub Raw API Documentation

📖 Giới thiệu

Hotelia Hub Raw API là một hệ thống PHP thuần (không framework) được thiết kế để xử lý việc tìm kiếm thông tin khách sạn và giá phòng từ Agoda. Hệ thống được convert từ Laravel sang PHP thuần để tối ưu hiệu suất và giảm dependency.

Cache thông minh: Lưu cache kết quả trong 5 phút để giảm API calls
Validation mạnh mẽ: Kiểm tra tính hợp lệ của tất cả parameters
Logging chi tiết: Ghi log đầy đủ để debug và monitoring
Error handling: Xử lý lỗi toàn diện với response codes chuẩn
CORS support: Hỗ trợ cross-origin requests cho frontend
Multiple request methods: Hỗ trợ cả GET và POST requests

🚀 API Endpoint

POST GET apimghubraw.helistudio.vn//api/agoda/v1.37/hotelSearch

📋 Parameters

Parameter	Type	Required	Description
`hotels`	array	Required	Danh sách mã khách sạn (ví dụ: ["HOTEL001", "HOTEL002"])
`checkIn`	string	Required	Ngày nhận phòng (định dạng: YYYY-MM-DD)
`checkOut`	string	Required	Ngày trả phòng (định dạng: YYYY-MM-DD)
`occupancy.rooms`	integer	Required	Số phòng (tối thiểu: 1)
`occupancy.adults`	integer	Required	Số người lớn (tối thiểu: 1)
`occupancy.childrenAges`	array	Optional	Danh sách tuổi trẻ em (ví dụ: [8, 12])
`log`	boolean	Optional	Bật/tắt logging (true/false)

📝 Ví dụ Request

POST với JSON:

{
    "hotels": ["HOTEL001", "HOTEL002"],
    "checkIn": "2025-01-15",
    "checkOut": "2025-01-17",
    "occupancy": {
        "rooms": 1,
        "adults": 2,
        "childrenAges": [8, 12]
    },
    "log": true
}

GET với URL Parameters:

GET /api/agoda/v1.37/hotelSearch?hotels[]=HOTEL001&hotels[]=HOTEL002&checkIn=2025-01-15&checkOut=2025-01-17&occupancy[rooms]=1&occupancy[adults]=2&occupancy[childrenAges][]=8&occupancy[childrenAges][]=12&log=true

📤 Response Examples

✅ 200 - SUCCESS

Request thành công

⚠️ 400 - INVALID_REQUEST

Lỗi validation parameters

❌ 500 - SERVER_ERROR

Lỗi hệ thống

Success Response (200):

{
    "responseStatus": "SUCCESS",
    "version": "v1.37",
    "checkIn": "2025-01-15",
    "checkOut": "2025-01-17",
    "currency": "USD",
    "hotels": [
        {
            "hotelCode": "HOTEL001",
            "hotelName": "Example Hotel",
            "rooms": [
                {
                    "roomType": "Deluxe Room",
                    "price": 120.50,
                    "availability": "Available"
                }
            ]
        }
    ],
    "cache": false
}

Error Response (400):

{
    "responseStatus": "INVALID_REQUEST",
    "version": "v1.37",
    "remark": {
        "hotels": ["The hotels field is required."],
        "checkIn": ["The checkIn field is required."]
    }
}

⚙️ Thông tin kỹ thuật

🏗️ Kiến trúc hệ thống:

PHP thuần: Không sử dụng framework, tối ưu hiệu suất
MVC Pattern: Tách biệt logic xử lý và presentation
Dependency Injection: Quản lý dependencies hiệu quả
File-based Cache: Cache nhanh không cần database
PSR Standards: Tuân thủ coding standards PHP

📊 Performance:

Cache Timeout: 5 phút (300 giây)
API Timeout: 30 giây cho external calls
Memory Usage: Tối ưu cho môi trường shared hosting
Response Time: < 100ms cho cached requests

📋 Yêu cầu hệ thống

PHP Version	7.4 hoặc cao hơn
Extensions	curl, json, mbstring
Web Server	Apache với mod_rewrite
Permissions	Write access cho thư mục cache/ và logs/

🏨 Hotelia Hub Raw API