> 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/encryption-and-signing.md).

# Encryption and signing

Requests and responses share one shape: a `{key, data}` body. The only difference from the B2B2C webview is that the content inside `data` is **JSON** instead of a `|`-joined string.

| Component      | Algorithm                                              | String encoding             |
| -------------- | ------------------------------------------------------ | --------------------------- |
| Session key    | 3DES (`DESede`), random 24 bytes, one key per request  | —                           |
| `key`          | `RSA/ECB/PKCS1Padding` of the session key              | Base64 URL-safe, no padding |
| `data`         | `DESede/ECB/PKCS5Padding` of the envelope JSON (UTF-8) | Base64 URL-safe, no padding |
| `signature`    | `SHA256withRSA` (PKCS#1 v1.5)                          | Standard Base64             |
| `payload` hash | SHA-256 of the `payload` string (UTF-8)                | lowercase hex               |

### 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 before being encrypted into `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        | Type        | Description                                                        |
| ------------ | ----------- | ------------------------------------------------------------------ |
| `accessCode` | string      | Partner accessCode                                                 |
| `timestamp`  | int64       | Epoch **seconds**. More than 300 seconds off is rejected (`26`)    |
| `requestId`  | string ≤ 64 | Not reused within 10 minutes; UUID recommended                     |
| `payload`    | string      | A **string** holding the API JSON, not an object                   |
| `signature`  | string      | Signed over `accessCode\|timestamp\|requestId\|sha256hex(payload)` |

{% hint style="info" %}
`payload` is a **string**. Both sides hash exactly that string, so field order and whitespace do not matter.
{% endhint %}

Steps to build a request:

1. Build `payload` = the API JSON, as a string.
2. Compute `sha256hex(payload)`, assemble the signing string, sign it with the partner private key to get `signature`.
3. Assemble the envelope JSON, generate a random 3DES key, encrypt the envelope to get `data`.
4. Encrypt the 3DES key with the Gotadi public key to get `key`.
5. Send `{key, data}` with the `apikey` header.

### Response

HTTP 200, body `{key, data}`. `key` is decrypted with the partner private key to recover the 3DES key; `data` decrypts to the envelope:

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

Verify `signature` with the Gotadi public key over `accessCode|timestamp|requestId|code|sha256hex(payload)`, check `accessCode` matches `gotadiAccessCode` and `requestId` matches the request sent — **only then** trust `code` and `payload`. On error, `payload` is `"{}"`, except code `20 PRICE_CHANGED`, which carries the new price and `bookingToken`.

{% hint style="danger" %}
Errors raised **before** Gotadi can decrypt the request (wrong `apikey`, corrupt `key`/`data`, Partner API not enabled) return HTTP 400 or 401 with plain, **unencrypted** JSON: `{"code": "07", "message": "..."}`. Your client must handle both body shapes.
{% endhint %}

### requestId and idempotency

* One new `requestId` per request.
* **Only the 4 write APIs** — `price-check`, `bookings/create`, `bookings/commit`, `bookings/cancel` — remember `requestId` for 10 minutes:
  * same `requestId` + same `payload` → the original response is returned, nothing is processed twice;
  * same `requestId` + different `payload` → `27 DUPLICATED_REQUEST_ID`;
  * first call still running → `01 ON_PROCESS`.
* When retrying after a timeout, **keep the same `requestId`**, change only `timestamp` and re-sign.
* Read APIs do not store `requestId`; `availability` polling uses a **new** one each round.
