Bắt đầu nhanh với GoHost Public API

API cho đối tácAdd-on

Tính năng này thuộc gói Add-on

Bạn vẫn đọc được đầy đủ hướng dẫn bên dưới. Khi cần bật, nhắn Zalo OA GoHost — CS sẽ giúp trong 1 ngày làm việc.

Có API key rồi thì đặt được phòng qua năm lời gọi: lấy tenant_id → tìm loại phòng còn trống → lấy nguồn đặt → tạo đặt phòng → thêm thanh toán hoặc xác nhận. Ví dụ dùng curl; thay $GOHOST_KEY bằng {api_key}:{api_secret} của bạn.

export GOHOST_API=https://platform.gohost.vn/pms/api/public/v1
export GOHOST_KEY='pub_live_…:sec_live_…'   # không commit giá trị này vào mã nguồn

1. Lấy danh sách cơ sở và `tenant_id`

Một key dùng được cho mọi cơ sở trong tổ chức. Mỗi cơ sở có tenant_id (UUID) — dùng nó trong đường dẫn của các bước sau.

curl -s "$GOHOST_API/properties" -H "Authorization: Bearer $GOHOST_KEY"

Cần scope properties:read. Kết quả được cache 5 phút. Chi tiết: Get Properties List.

2. Tìm loại phòng còn trống và giá

curl -s "$GOHOST_API/properties/<tenant_id>/room_types/search?checkin_date=2026-11-20&checkout_date=2026-11-22" \
  -H "Authorization: Bearer $GOHOST_KEY"

Ghi lại mã loại phòng cần đặt. Tham số đầy đủ: Search Room Type. Tìm trên mọi cơ sở của tổ chức cùng lúc: Search Properties.

3. Lấy nguồn đặt (`source_name`)

Mỗi đơn phải ghi nguồn đặt là tên một nguồn đang bật, không phải kênh OTA, của chính cơ sở đó — giá trị tự đặt như “Website ABC” bị từ chối (422). Lấy danh sách và dùng trường name:

curl -s "$GOHOST_API/properties/<tenant_id>/booking-sources" -H "Authorization: Bearer $GOHOST_KEY"

Chi tiết: Get Booking Sources. Muốn một nguồn riêng cho đối tác (vd “Website ABC”): nhờ cơ sở tạo nguồn đặt đó trên GoHost trước.

4. Tạo đặt phòng

curl -s -X POST "$GOHOST_API/properties/<tenant_id>/bookings" \
  -H "Authorization: Bearer $GOHOST_KEY" -H "Content-Type: application/json" \
  -d '{
    "checkin_date": "2026-11-20",
    "checkout_date": "2026-11-22",
    "source_name": "<name lấy ở bước 3>",
    "customer": { "name": "Nguyễn Văn A", "phone": "0900000000" },
    "booking_rooms": [{ "room_type_id": "<mã loại phòng>" }]
  }'

Cần scope bookings:write. Phản hồi có mã đặt phòng (id) — dùng cho các bước sau. Body đầy đủ (khách, nhiều phòng, giá theo ngày, thanh toán kèm theo): Create Booking.

5. Thêm thanh toán hoặc xác nhận đơn

Khách đã trả tiền: Add Payment — ghi khoản thu, không đổi trạng thái đơn.
Chốt đơn: Confirm Booking — chuyển đơn sang “Đã xác nhận”, có thể gửi kèm payments[].

6. Theo dõi thay đổi của đơn

Đơn còn có thể bị lễ tân sửa, huỷ, nhận phòng trên GoHost. Đăng ký webhook để nhận sự kiện thay vì gọi lại Get Booking Detail liên tục.

Lưu ý trước khi chạy thật

API chưa hỗ trợ idempotency key: lỗi mạng khi POST /bookings thì gọi Get Bookings kiểm đơn đã tạo chưa trước khi gửi lại, tránh tạo trùng.
Đơn tạo qua API là đơn thật: nó trừ tồn phòng và được đồng bộ lên các kênh OTA của cơ sở.
Ngày trả phòng phải sau ngày nhận phòng; API chưa nhận đơn trong ngày (đặt theo giờ).
Một số danh sách được cache vài phút (xem Giới hạn, phản hồi & mã lỗi).