> 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/ma-hoa-va-ky.md).

# Mã hóa và ký

Request và response dùng cùng một dạng: body `{key, data}`. Khác B2B2C webview duy nhất ở chỗ nội dung bên trong `data` là **JSON** thay cho chuỗi nối `|`.

| Thành phần     | Thuật toán                                                     | Mã hoá chuỗi                   |
| -------------- | -------------------------------------------------------------- | ------------------------------ |
| Khoá phiên     | 3DES (`DESede`), khoá ngẫu nhiên 24 byte, mỗi request một khoá | —                              |
| `key`          | `RSA/ECB/PKCS1Padding` của khoá phiên                          | Base64 URL-safe, không padding |
| `data`         | `DESede/ECB/PKCS5Padding` của envelope JSON (UTF-8)            | Base64 URL-safe, không padding |
| `signature`    | `SHA256withRSA` (PKCS#1 v1.5)                                  | Base64 chuẩn                   |
| Hash `payload` | SHA-256 của chuỗi `payload` (UTF-8)                            | hex chữ thường                 |

### Request

{% code title="POST /bsv/api/partner/v1/availability" %}

```http
POST /bsv/api/partner/v1/availability
apikey: <apikey>
Content-Type: application/json

{"key": "<key>", "data": "<data>"}
```

{% endcode %}

Envelope trước khi mã hoá vào `data`:

```json
{
  "accessCode": "PARTNER_ACCESS_CODE",
  "timestamp": 1791700000,
  "requestId": "6f1c2a7e-0b9d-4b3e-9a51-2f0c3d4e5f60",
  "payload": "{\"masterIds\":[\"1001\",\"1002\"],\"checkin\":\"2026-11-20\",\"checkout\":\"2026-11-22\",\"rooms\":[{\"adults\":2,\"childAges\":[]}]}",
  "signature": "<signature>"
}
```

| Field        | Kiểu        | Mô tả                                                          |
| ------------ | ----------- | -------------------------------------------------------------- |
| `accessCode` | string      | accessCode của đối tác                                         |
| `timestamp`  | int64       | Epoch **giây**. Lệch quá 300 giây bị từ chối (`26`)            |
| `requestId`  | string ≤ 64 | Không dùng lại trong 10 phút; khuyên dùng UUID                 |
| `payload`    | string      | **Chuỗi** chứa JSON của API, không phải object                 |
| `signature`  | string      | Ký trên `accessCode\|timestamp\|requestId\|sha256hex(payload)` |

{% hint style="info" %}
`payload` là một **chuỗi**. Hai bên băm đúng chuỗi này nên không phụ thuộc thứ tự field hay khoảng trắng.
{% endhint %}

Các bước tạo request:

1. Tạo `payload` = JSON của API, dạng chuỗi.
2. Tính `sha256hex(payload)`, ghép chuỗi ký, ký bằng private key đối tác được `signature`.
3. Ghép envelope JSON, sinh khoá 3DES ngẫu nhiên, mã envelope được `data`.
4. Mã khoá 3DES bằng public key Gotadi được `key`.
5. Gửi `{key, data}` kèm header `apikey`.

### Response

HTTP 200, body `{key, data}`. `key` giải bằng private key đối tác ra khoá 3DES; `data` giải ra envelope:

```json
{
  "accessCode": "GOTADI_ACCESS_CODE",
  "timestamp": 1791700001,
  "requestId": "6f1c2a7e-0b9d-4b3e-9a51-2f0c3d4e5f60",
  "code": "00",
  "message": "Succeeded",
  "payload": "{...}",
  "signature": "<signature>"
}
```

Đối tác kiểm `signature` bằng public key Gotadi trên chuỗi `accessCode|timestamp|requestId|code|sha256hex(payload)`, kiểm `accessCode` khớp `gotadiAccessCode` và `requestId` khớp request đã gửi, **rồi mới tin** `code` và `payload`. Khi lỗi, `payload` là `"{}"`, trừ mã `20 PRICE_CHANGED` (kèm giá và `bookingToken` mới).

{% hint style="danger" %}
Lỗi xảy ra **trước** khi Gotadi giải mã được request (sai `apikey`, `key`/`data` hỏng, đối tác chưa bật Partner API) trả HTTP 400 hoặc 401 với JSON thường, **không mã hoá**: `{"code": "07", "message": "..."}`. Client phải xử lý được cả hai dạng body.
{% endhint %}

### requestId và chống trùng

* Mỗi request một `requestId` mới.
* **Chỉ 4 API ghi** — `price-check`, `bookings/create`, `bookings/commit`, `bookings/cancel` — nhớ `requestId` trong 10 phút:
  * cùng `requestId` + cùng `payload` → nhận lại đúng response cũ, không xử lý lần hai;
  * cùng `requestId` + khác `payload` → `27 DUPLICATED_REQUEST_ID`;
  * lần đầu chưa xong → `01 ON_PROCESS`.
* Khi retry vì timeout, **giữ nguyên `requestId`**, chỉ đổi `timestamp` và ký lại.
* Các API đọc không lưu `requestId`; polling `availability` dùng `requestId` **mới** mỗi lần.
