> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Формат взаимодействия

Почти все методы API Oblodai — это HTTP‑запросы **`POST`** с телом в формате **JSON**. Так работают
даже операции чтения: тело для них — либо пустой объект `{}`, либо объект с фильтрами.

**`GET`‑эндпоинтов всего три**, и все они публичные (без подписи):

| Метод                                         | Назначение                                                    |
| --------------------------------------------- | ------------------------------------------------------------- |
| [`GET /v1/currencies`](/reference/currencies) | Каталог валют и сетей.                                        |
| [`GET /v1/link/{id}`](/reference/link-public) | Публичные данные [платёжной ссылки](/reference/payment-link). |
| [`GET /v1/pay/{id}`](/reference/pay-get)      | Публичные данные счёта для hosted‑страницы оплаты.            |

Всё остальное — `POST`.

**Базовый URL:** `https://api.oblodai.com`

***

## Запрос

| Что                      | Значение                                                             |
| ------------------------ | -------------------------------------------------------------------- |
| HTTP‑метод               | `POST` (кроме трёх публичных `GET` выше)                             |
| Заголовок `Content-Type` | `application/json`                                                   |
| Тело                     | JSON‑объект (для чтения — `{}` или фильтры)                          |
| Аутентификация           | Три заголовка подписи — см. [Аутентификация](/reference/basics-auth) |
| Ограничение размера тела | 1 МиБ                                                                |

### Заголовки запроса

| Заголовок         | Обяз.   | Значение                                                                                                                                                                                                                               |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`    | да      | `application/json`                                                                                                                                                                                                                     |
| `X-Public-Id`     | да\*    | Несекретный идентификатор API‑ключа.                                                                                                                                                                                                   |
| `X-Timestamp`     | да\*    | Unix‑секунды на момент подписи.                                                                                                                                                                                                        |
| `X-Signature`     | да\*    | HMAC‑SHA256 канонической строки.                                                                                                                                                                                                       |
| `Idempotency-Key` | **нет** | Уникальное значение (≤255 символов) для безопасного повтора создающих операций: платежа, выплаты, возврата, кошелька, перевода, батча. Одинаковое во всех попытках одного действия. → [Идемпотентность](/reference/basics-idempotency) |

\* Кроме публичных методов.

### Заголовки ответа

| Заголовок                   | Когда приходит                                    | Значение                                                                               |
| --------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `Idempotent-Replayed: true` | На повторе с уже использованным `Idempotency-Key` | Ответ **воспроизведён**: новый объект не создан, вернулся ранее сохранённый результат. |
| `Retry-After`               | При `429`                                         | Через сколько секунд повторять. → [Ограничение частоты](/reference/basics-ratelimit)   |

Пример «пустого» запроса на чтение (баланс):

```bash theme={null}
curl -s https://api.oblodai.com/v1/balance \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "X-Public-Id: $PUBLIC_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d '{}'
```

***

## Успешный ответ

При успешной обработке (HTTP `200 OK`) API всегда возвращает **конверт** с полем `state: 0` и
полезной нагрузкой в `result`:

```json theme={null}
{
  "state": 0,
  "result": { "...": "полезные данные операции" }
}
```

`result` может быть объектом, массивом или примитивом — зависит от метода. Конкретную форму смотрите
на странице соответствующего эндпоинта.

<Note>
  **Единственное исключение** — [`POST /v1/webhooks`](/reference/webhooks-register): он возвращает
  `201 Created` и «голый» объект без конверта `state`/`result`. Это оговорено на его странице.
</Note>

***

## Ответ с ошибкой

При ошибке возвращается конверт с объектом `error`, а HTTP‑статус отражает класс ошибки:

```json theme={null}
{
  "error": {
    "code": "payout.insufficient_funds",
    "message": "insufficient available balance"
  }
}
```

* `code` — машиночитаемый код вида `<домен>.<причина>`. **Ветвитесь в коде по нему.**
* `message` — человекочитаемое пояснение. Безопасно логировать, но не полагайтесь на его точный текст.

Полный разбор классов и кодов — [Формат ответа и коды ошибок](/reference/basics-errors).

***

## Связанные страницы

<CardGroup cols={2}>
  <Card title="Аутентификация и подпись запросов" href="/reference/basics-auth" icon="arrow-right" horizontal />

  <Card title="Формат ответа и коды ошибок" href="/reference/basics-errors" icon="arrow-right" horizontal />

  <Card title="Идемпотентность" href="/reference/basics-idempotency" icon="arrow-right" horizontal />
</CardGroup>