Xác thực & API key

Mọi request gửi header Authorization: Bearer {api_key}:{api_secret}. API key do GoHost cấp — chủ cơ sở hoặc đối tác liên hệ hỗ trợ GoHost để xin; hiện chưa có màn hình tự tạo key trong PMS.

Xin API key

Khi xin key, gửi cho GoHost:

• Tổ chức (chủ chuỗi / chủ cơ sở) cho phép đối tác truy cập.
• Tên đối tác và mục đích kết nối.
• Các scope cần dùng (bảng dưới) và ngày hết hạn nếu muốn.

GoHost trả về hai giá trị:

Giá trị	Dạng	Ghi chú
api_key	pub_live_…	Định danh key
api_secret	sec_live_…	Chỉ hiện một lần khi tạo. GoHost không lưu bản rõ, không xem lại được

Lưu api_secret ở kho bí mật phía máy chủ của bạn — không đưa vào mã nguồn, ứng dụng di động hay trình duyệt. Lộ secret: báo GoHost cấp secret mới; secret cũ mất hiệu lực ngay lập tức.

Gửi kèm request

curl -s https://platform.gohost.vn/pms/api/public/v1/properties \
  -H "Authorization: Bearer pub_live_xxx:sec_live_yyy"

Thiếu header hoặc sai định dạng → 401 AUTH_001. Sai key, key đã bị tắt hoặc đã hết hạn → 401 AUTH_002.

Phạm vi (scope)

Mỗi key có một danh sách scope. Gọi endpoint ngoài phạm vi → 403 AUTH_006, phản hồi kèm required_scope và your_scopes để biết thiếu gì.

Scope	Cho phép
properties:read	Cơ sở, loại phòng, tìm phòng trống, danh mục tham chiếu, nguồn đặt, phương thức thanh toán, dịch vụ
bookings:read	Xem danh sách và chi tiết đặt phòng
bookings:write	Tạo, xác nhận, thêm thanh toán, huỷ, cập nhật đặt phòng; trả phòng / huỷ / đổi giá từng phòng
webhooks:read	Xem endpoint webhook và lịch sử gửi
webhooks:write	Tạo, sửa, xoá endpoint webhook, đổi secret, gửi thử

Khi xin key, ghi rõ các scope cần dùng — GoHost chỉ bật đúng những scope đó.

Một key, nhiều cơ sở: tenant_id

Một key gắn với một tổ chức và dùng được cho mọi cơ sở trong tổ chức đó. Mỗi cơ sở có tenant_id (UUID) nằm trong đường dẫn: /properties/{tenant_id}/…. Lấy danh sách bằng Get Properties List.

GoHost kiểm tenant_id ở mọi request:

Mã	Nghĩa
TENANT_001	tenant_id không phải UUID hợp lệ
TENANT_002	Không có cơ sở này
TENANT_003	Cơ sở không thuộc tổ chức của key
TENANT_004	Cơ sở đang bị tạm ngưng

Bảng mã lỗi đầy đủ: Giới hạn, phản hồi & mã lỗi.