> 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/english/b2b2c-partner/api-method/hotel-1/overview-and-environments.md).

# Overview and Environments

## Overview

A booking goes through four stages: **search price → lock price → create booking → confirm after the partner collects payment**. Gotadi holds the room and confirms with the hotel; the partner owns the UI and the payment collection.

```mermaid
flowchart TD
    subgraph SYNC["Catalogue sync - periodic"]
        direction LR
        P1["content/properties"] --> P2["content/property"]
    end

    subgraph BOOK["Booking flow"]
        direction TB
        A["availability<br/><i>lowest price</i>"] --> B["offers<br/><i>rooms, rate plans</i>"]
        B --> C["price-check<br/><i>lock price, bookingToken</i>"]
        C --> D["bookings/create<br/><i>room hold, paymentDeadline</i>"]
        D --> E{{"Partner collects payment"}}
        E --> F["bookings/commit<br/><i>Gotadi debits balance, issues booking</i>"]
        F --> G["bookings/get<br/><i>check status</i>"]
    end

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

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

| Step | API                                         | Purpose                                          | What to keep                                      |
| ---- | ------------------------------------------- | ------------------------------------------------ | ------------------------------------------------- |
| 1    | `content/properties` → `content/property`   | Sync the hotel catalogue, periodically           | `masterId`, content                               |
| 2    | `availability`                              | Search lowest prices across hotels               | available `masterId`s                             |
| 3    | `offers`                                    | List every room and rate plan of one hotel       | `offerId` (30 min)                                |
| 4    | `price-check`                               | Lock the price                                   | `bookingToken` (15 min)                           |
| 5    | `bookings/create`                           | Hold the room, create a booking awaiting payment | `bookingNumber`, `paymentDeadline`, `totalAmount` |
| —    | —                                           | **Partner collects payment from the guest**      | `partnerTransId`                                  |
| 6    | `bookings/commit`                           | Gotadi debits the balance and issues the booking | `status`, `hotelConfirmationCode`                 |
| 7    | `bookings/get`                              | Check status                                     | `status`                                          |
| 8    | `bookings/cancel-check` → `bookings/cancel` | Check the penalty, then cancel                   | `refundAmount`                                    |

`bookings/get` can be called at any time after `bookings/create`, especially when `create` or `commit` times out.

### Environments

| Environment | Base URL                         | Notes                                         |
| ----------- | -------------------------------- | --------------------------------------------- |
| UAT         | `https://uat-api.gotadi.com/bsv` | Test data; bookings do not produce real rooms |
| Production  | Issued after certification       | Production keys differ from UAT keys          |

Every API is `POST {baseUrl}/api/partner/v1/<api name>`, e.g. `POST https://uat-api.gotadi.com/bsv/api/partner/v1/availability`. **The body is always encrypted, including read-only APIs.**

| Convention       | Value                                                   |
| ---------------- | ------------------------------------------------------- |
| Required headers | `apikey: <apikey>`, `Content-Type: application/json`    |
| Date             | `yyyy-MM-dd`                                            |
| Datetime         | ISO-8601, offset `+07:00` — `2026-11-18T12:00:00+07:00` |
| Currency         | `VND`, amounts are integers                             |
| Language         | `vi` (default) or `en`                                  |

{% hint style="warning" %}
**Every business code, errors included, is returned over HTTP 200.** The real status is the `code` field inside the response envelope.
{% endhint %}
