Справочник API Oblodai

Точное описание каждого метода и объекта API Oblodai.

В справочнике описаны все методы API Oblodai и все объекты, которыми он оперирует. Для каждого метода указаны параметры, их типы и обязательность, примеры запроса (cURL / Python / Node.js), пример ответа, коды ошибок и важные нюансы поведения.

API‑версия: v1 · Базовый URL: https://api.oblodai.com

Почти все методы — POST с телом в формате JSON. GET‑эндпоинтов три, и все публичные: GET /v1/currencies, GET /v1/link/{id} и GET /v1/pay/{id}. Все запросы, кроме явно помеченных «публичный», подписываются вашим API‑ключом. См. Аутентификация и подпись запросов.

Про call(...) в примерах. В примерах на Python/Node встречается хелпер call("/v1/...", {...}) — это ваша функция‑обёртка, которая добавляет подпись запроса. Её готовое определение (на 4 языках) — в Как подписать запрос. Проще не писать её вручную, а взять SDK — он подписывает за вас.

Если вам нужна не отдельная справка по методу, а пошаговое руководство под задачу — откройте Инструкции.

​

Разделы справочника

Основы

Формат, подпись, ошибки, деньги, сети, лимиты.

Платежи

Объект платежа и все методы приёма — от создания счёта до автовозврата.

Ссылки и сплиты

Платёжные ссылки и распределение платежей между партнёрами.

Массовые операции

Батчи: до 5000 платежей, возвратов или выплат одним запросом.

Кошельки и баланс

Статические кошельки, баланс мерчанта, рефералы.

Выплаты и возвраты

Объект выплаты, создание, подтверждение, комиссии, возвраты.

Вебхуки

Формат вебхука, регистрация, журнал доставок, тестовые события.

Публичные методы

Каталог валют и курсы — без API‑ключа.

Материалы

Каталог ошибок, глоссарий, диаграммы потоков.

---

​

Как проходит платёж (за 20 секунд)

Покупатель создаёт счёт и получает депозит‑адрес. Он платит в крипте на этот адрес, а сеть блокчейна подтверждает транзакцию. После достаточного числа подтверждений Oblodai присылает вам вебхук, и вы отмечаете заказ оплаченным. Наглядно — диаграммы.

---

​

Основы работы с API

• Формат взаимодействия — POST + JSON, конверт state/result.
• Аутентификация и подпись запросов — HMAC‑SHA256, три заголовка, примеры на 4 языках.
• Формат ответа и коды ошибок — HTTP‑классы и коды вида <домен>.<причина>.
• Идемпотентность — безопасные повторы: заголовок Idempotency-Key и order_id.
• Форматы сумм и денег — суммы строками, без float.
• Поддерживаемые сети и валюты — пары currency + network.
• Ограничение частоты и IP‑allowlist — rate limit, доверенные IP.

​

Справочные материалы

• Справочник кодов ошибок — все коды одной таблицей, сгруппированы по домену.
• Глоссарий — все термины документации.
• Диаграммы: жизненные циклы и потоки — схемы платежей, выплат, вебхуков.

---

​

Публичные методы (без ключа)

• GET /v1/currencies — каталог: два списка — в чём можно получать (currencies) и в чём можно назначать цену (pricing_currencies: 23 фиата + монеты).
• POST /v1/exchange-rate/list — текущие курсы валют к USDT.

---

​

Приём платежей

• Объект платежа (Payment) — структура и статусы payment_status.

Метод	Назначение
POST /v1/payment	Создание платёжного счёта (инвойса)
POST /v1/payment/batch	Массовое создание счетов (до 5000, асинхронно)
POST /v1/payment/info	Информация о счёте (включая refunds[])
POST /v1/payment/history	Список платежей мерчанта
POST /v1/payment/send-email	Отправить счёт письмом покупателю
POST /v1/payment/services	Доступные методы приёма
POST /v1/payment/qr	QR‑код депозит‑адреса счёта
POST /v1/wallet/qr	QR‑код произвольного адреса
POST /v1/payment/accepted/list · /set	Принимаемые валюты для агностичных счетов
POST /v1/payment/discount/list · /set	Скидки/наценки плательщику
POST /v1/payment/accuracy/get · /set	Допуск недоплаты
POST /v1/payment/autorefund/get · /set	Автовозврат при недо/переплате
POST /v1/vrcs	Авто‑конвертация волатильных депозитов в USDT

​

Платёжные ссылки

Многоразовый URL оплаты: фиксированная сумма, донат (сумму вводит покупатель) или диапазон. Единственный способ принимать платежи без своего бэкенда (Tilda, Wix и т. п.).

Метод	Назначение
POST /v1/payment/link · /list · /info · /toggle	Создание и управление ссылками

​

Hosted‑страница оплаты и страница ссылки (публичные)

Метод	Назначение
GET /v1/pay/{id}	Публичные данные счёта
POST /v1/pay/{id}/select	Выбор валюты и сети покупателем
GET /v1/link/{id}	Публичные данные платёжной ссылки
POST /v1/link/{id}/checkout	Создать счёт по ссылке (без ключа)

---

​

Массовые операции (батчи)

До 5000 элементов в одном подписанном запросе, обработка асинхронная. Штатный способ не упираться в лимит частоты — один запрос вместо тысяч.

Метод	Назначение
POST /v1/payment/batch	Массовое создание счетов
POST /v1/refund/batch	Массовые возвраты
POST /v1/payout/batch	Массовые выплаты
POST /v1/batch/info	Статус батча и результат по каждому элементу

---

​

Сплиты

Доля каждого входящего платежа автоматически уходит партнёру — для партнёрских программ, маркетплейсов, разделения выручки.

Метод	Назначение
POST /v1/split/rule · /rule/list · /rule/delete	Правила распределения (внешний адрес или мерчант платформы)
POST /v1/split/config/get · /set	Окно удержания refund_hold_hours (и почему расчёт откладывается)

---

​

Кошельки, баланс, рефералы

• Объект кошелька (Wallet) — статический адрес и чем он отличается от инвойса.

Метод	Назначение
POST /v1/wallet	Создать статический кошелёк
POST /v1/wallet/block	Заблокировать/разблокировать кошелёк
POST /v1/wallet/blocked-address-refund	Возврат средств с кошелька
POST /v1/balance	Балансы мерчанта
POST /v1/referral/info	Реферальная статистика

---

​

Выплаты и возвраты

• Объект выплаты (Payout) — структура и статусы.

Метод	Назначение
POST /v1/payout	Создать выплату
POST /v1/payout/batch	Массовая выплата (до 5000, асинхронно) — основной путь
POST /v1/payout/mass	Массовая выплата (до 100, синхронно) — легаси
POST /v1/payout/info	Информация о выплате
POST /v1/payout/history	История выплат
POST /v1/payout/services	Доступные методы выплат
POST /v1/payout/calculate	Предрасчёт комиссии и сумм
POST /v1/payout/approve	Подтверждение выплаты (maker‑checker)
POST /v1/payment/refund	Возврат платежа (адрес необязателен)
POST /v1/refund/batch	Массовые возвраты (до 5000)
POST /v1/payout/fee-config/get · /set	Кто платит сетевую комиссию выплаты
POST /v1/payout/refund-fee-config/get · /set	Кто платит комиссию возврата
POST /v1/transfer/to-personal	Перевод на личный кошелёк владельца

---

​

Вебхуки

• Объект вебхука и проверка подписи — заголовки, формат тела, HMAC вебхука.

Метод	Назначение
POST /v1/webhooks	Регистрация URL для вебхуков
POST /v1/webhooks/deliveries	Журнал доставок
POST /v1/payment/resend	Переотправка вебхука платежа
POST /v1/testing-webhook, /v1/test-webhook/*	Тестовые вебхуки

​

Настройки аккаунта

Метод	Назначение
POST /v1/auto-withdraw/*	Автовывод на внешний адрес
POST /v1/api-allowlist/*	IP‑allowlist для API