> For the complete documentation index, see [llms.txt](https://developer.gotadi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gotadi.com/vietnamese/doi-tac-b2b2c/phuong-thuc-api/hotel/tong-quan-va-moi-truong.md).

# Tổng quan và môi trường

{% hint style="info" %}
Hợp đồng **v1.1.0** (14/10/2026). Đăng ký, khoá và cách mã hoá giống hệt kết nối B2B2C hiện tại — nếu đã là đối tác B2B2C (webview), Gotadi chỉ bật thêm quyền Partner API trên cùng bộ thông tin.
{% endhint %}

Một booking đi qua bốn bước: **tìm giá → chốt giá → tạo booking → xác nhận sau khi đối tác thu tiền của khách**. Gotadi giữ phòng và xác nhận với khách sạn; đối tác giữ giao diện và việc thu tiền.

```mermaid
flowchart TD
    subgraph SYNC["Đồng bộ danh mục - định kỳ"]
        direction LR
        P1["content/properties"] --> P2["content/property"]
    end

    subgraph BOOK["Luồng đặt phòng"]
        direction TB
        A["availability<br/><i>giá thấp nhất</i>"] --> B["offers<br/><i>phòng, gói giá</i>"]
        B --> C["price-check<br/><i>chốt giá, bookingToken</i>"]
        C --> D["bookings/create<br/><i>giữ phòng, paymentDeadline</i>"]
        D --> E{{"Đối tác thu tiền của khách"}}
        E --> F["bookings/commit<br/><i>Gotadi trừ số dư, xuất booking</i>"]
        F --> G["bookings/get<br/><i>tra cứu trạng thái</i>"]
    end

    subgraph CXL["Huỷ booking"]
        direction LR
        H["bookings/cancel-check"] --> I["bookings/cancel"]
    end

    SYNC -.-> BOOK
    G -.-> CXL
```

| Bước | API                                         | Việc                                         | Kết quả giữ lại                                   |
| ---- | ------------------------------------------- | -------------------------------------------- | ------------------------------------------------- |
| 1    | `content/properties` → `content/property`   | Đồng bộ danh mục khách sạn, định kỳ          | `masterId`, content                               |
| 2    | `availability`                              | Tìm giá thấp nhất nhiều khách sạn            | `masterId` còn phòng                              |
| 3    | `offers`                                    | Lấy mọi phòng và gói giá của 1 khách sạn     | `offerId` (30 phút)                               |
| 4    | `price-check`                               | Chốt giá                                     | `bookingToken` (15 phút)                          |
| 5    | `bookings/create`                           | Giữ phòng, tạo booking chờ thanh toán        | `bookingNumber`, `paymentDeadline`, `totalAmount` |
| —    | —                                           | **Đối tác thu tiền của khách**               | `partnerTransId`                                  |
| 6    | `bookings/commit`                           | Gotadi trừ số dư, xuất booking với khách sạn | `status`, `hotelConfirmationCode`                 |
| 7    | `bookings/get`                              | Tra cứu trạng thái                           | `status`                                          |
| 8    | `bookings/cancel-check` → `bookings/cancel` | Xem phí huỷ rồi huỷ                          | `refundAmount`                                    |

`bookings/get` gọi được bất kỳ lúc nào sau `bookings/create`, nhất là khi `create` hoặc `commit` bị timeout.

### Môi trường

| Môi trường | Base URL                         | Ghi chú                                          |
| ---------- | -------------------------------- | ------------------------------------------------ |
| UAT        | `https://uat-api.gotadi.com/bsv` | Dữ liệu test, booking không phát sinh phòng thật |
| Production | Cấp sau khi chứng nhận           | Khoá production khác khoá UAT                    |

Mọi API có dạng `POST {baseUrl}/api/partner/v1/<tên API>`, ví dụ `POST https://uat-api.gotadi.com/bsv/api/partner/v1/availability`. **Body luôn mã hoá, kể cả API chỉ đọc.**

| Quy ước         | Giá trị                                              |
| --------------- | ---------------------------------------------------- |
| Header bắt buộc | `apikey: <apikey>`, `Content-Type: application/json` |
| Ngày            | `yyyy-MM-dd`                                         |
| Thời điểm       | ISO-8601 múi `+07:00` — `2026-11-18T12:00:00+07:00`  |
| Tiền tệ         | `VND`, số tiền là số nguyên                          |
| Ngôn ngữ        | `vi` (mặc định) hoặc `en`                            |

{% hint style="warning" %}
**Mọi mã nghiệp vụ, kể cả lỗi, đều trả HTTP 200.** Trạng thái thật nằm ở `code` trong envelope response.
{% endhint %}

## Danh sách API

Ví dụ dưới đây là `payload` **đã giải mã**, viết dạng object cho dễ đọc. Khi gửi, `payload` là chuỗi JSON nằm trong envelope.

| # | API                                         | Mục đích                                       |
| - | ------------------------------------------- | ---------------------------------------------- |
| 1 | `content/properties`                        | Danh mục khách sạn của một quốc gia (cursor)   |
| 2 | `content/property`                          | Content đầy đủ của một khách sạn               |
| 3 | `availability`                              | Giá thấp nhất của tối đa 50 khách sạn          |
| 4 | `offers`                                    | Mọi phòng và gói giá của một khách sạn         |
| 5 | `price-check`                               | Chốt giá một gói, nhận `bookingToken`          |
| 6 | `bookings/create`                           | Tạo booking chờ thanh toán                     |
| 7 | `bookings/commit`                           | Báo đã thu tiền, Gotadi xác nhận với khách sạn |
| 8 | `bookings/get`                              | Tra cứu booking                                |
| 9 | `bookings/cancel-check` → `bookings/cancel` | Xem phí huỷ, huỷ booking                       |
