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

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

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

Метод	Назначение
GET /v1/currencies	Каталог валют и сетей.
GET /v1/link/{id}	Публичные данные платёжной ссылки.
GET /v1/pay/{id}	Публичные данные счёта для hosted‑страницы оплаты.

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

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

---

​

Запрос

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

​

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

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

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

​

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

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

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

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:

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

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

Единственное исключение — POST /v1/webhooks: он возвращает 201 Created и «голый» объект без конверта state/result. Это оговорено на его странице.

---

​

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

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

{
  "error": {
    "code": "payout.insufficient_funds",
    "message": "insufficient available balance"
  }
}

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

Полный разбор классов и кодов — Формат ответа и коды ошибок.

---

​

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

Аутентификация и подпись запросов

Формат ответа и коды ошибок

Идемпотентность