Песочница
Тестовый ключ cbal_test_5f2a… работает на отдельном эндпоинте sandbox.cobalflow.ru. Деньги не списываются, но весь поток — от валидации до вебхуков — идентичен продакшену.
Открыть кабинет
Быстрый старт · 01
Введение в API
Первый шаг в документации. Здесь вы получите ключи, настроите заголовки авторизации и отправите первый реальный запрос — без лишнего контекста и без лишнего жаргона.
Этот раздел рассчитан на разработчика, который уже зарегистрировался в кабинете Cobalflow и хочет довести интеграцию до первой успешной транзакции. Мы идём по шагам: аутентификация, первый GET-запрос к каталогу валют и разбор того, что делать, когда API отвечает ошибкой.
Шаг 0 · Ключи
Получите ключи за минуту
В кабинете разработчика у каждого проекта есть два ключа: публичный (для песочницы) и секретный (для продакшена). Копируйте секретный ключ сразу — второй раз мы его не показываем.
Продакшен
Секретный ключ выдаётся после верификации реквизитов. Базовый адрес — api.cobalflow.ru/v2. Ключ действует до первого ротирования, лимит по умолчанию — 120 запросов в минуту.
Проверить статусБезопасность
Никогда не храните секретный ключ в клиентском коде и не отправляйте его в лог. Для подписи вебхуков мы используем отдельный HMAC-ключ — он генерируется автоматически при создании подписки.
Политика ключей
Шаг 1 · Authentication
Как настроить заголовки Authorization
Каждый запрос к Cobalflow API несёт в заголовке Authorization токен вида Bearer. Без него любой метод вернёт 401 — даже чтение каталога.
Формат заголовка
Схема проста: Authorization: Bearer cbal_live_…. Между словом Bearer и токеном — ровно один пробел. Заголовок чувствителен к регистру, ключ передаётся целиком, без кавычек.
Справка по методамОбязательные заголовки
Помимо авторизации мы ожидаем Content-Type: application/json на всех POST/PUT. Для идемпотентных выгрузок добавьте Idempotency-Key — тогда повторный запрос вернёт тот же результат, а не дубль.
Список заголовковПример на cURL
Минимальный рабочий запрос: curl -H "Authorization: Bearer $COBAL_KEY" https://api.cobalflow.ru/v2/accounts. Переменную ключа держите в окружении, а не в команде — так её не зацепит .gitignore.
Клиенты и SDK
Шаг 2 · First Request
Первый GET-запрос к каталогу валют
Каталог валют — лучший способ проверить, что ключ работает и соединение стабильно. Метод GET /v2/currencies не требует тела и возвращает список из 24 валют, доступных вашему аккаунту.
Запрос
GET /v2/currencies?status=active — без тела, только заголовок авторизации. Параметр status принимает значения active, archived или all (по умолчанию — active).
Полный список методовОтвет
Код 200 и JSON-массив. Каждая запись содержит code (ISO 4217), name, decimals и флаг payout_enabled. Для рубля: {"code":"RUB","decimals":2,"payout_enabled":true}.
Схема ответаЧто проверить
Если в ответе есть RUB и USD — ключ активен и аккаунт верифицирован. Замерьте заголовок X-Request-Id: он понадобится команде поддержки, если что-то пойдёт не так дальше по цепочке.
Диагностика
Шаг 3 · Error Handling
Как интерпретировать коды ошибок
Каждый не-2xx ответ приходит в едином формате: {"error":{"code":"…","message":"…","request_id":"…"}}. Поле code — стабильный идентификатор, по нему вы строите логику, а не по тексту сообщения.
400 · Валидация
Коды validation_failed, invalid_parameter. Значит, тело запроса не прошло проверку: пропущенное поле, неверный формат ISO-валюты или сумма в копейках вместо рублей. Исправьте и повторите — это не требует ротации ключа.
Каталог кодов 4xx401 / 403 · Доступ
unauthorized — ключ не найден или просрочен; forbidden — ключ валиден, но аккаунт не имеет права на этот метод (например, выгрузка до верификации). В обоих случаях проверьте, какой именно ключ вы используете: песочный или продакшен.
Политика доступа429 / 5xx · Повтор
rate_limited приходит при превышении 120 запросов в минуту — заголовки Retry-After и X-Ratelimit-Reset подскажут, когда возвращаться. Для 5xx используйте экспоненциальный бэкофф и идемпотентные ключи, чтобы не создать дубль.
Лимиты и ретраиКлюч в руках — отправляйте первый запрос
Песочница готова принять ваш GET /v2/currencies прямо сейчас. Если ответ придёт за < 400 мс — вы уже внутри Cobalflow, дальше только интеграция.
Вопросы
Что спрашивают на первом шаге
Нет. Ключи раздельные и работают на разных хостах: sandbox.cobalflow.ru и api.cobalflow.ru. Передача песочного ключа на продакшенный эндпоинт вернёт 401 unauthorized.
Обычно это означает, что запрос не дошёл до нашего API — проверьте прокси, DNS и что адрес указан как https://api.cobalflow.ru без лишнего пути. Если проблема повторяется, напишите в поддержку с телом запроса и таймстампом.
Медианное время ответа API — 38 мс, p99 — 620 мс. Рекомендуемый таймаут на клиенте — 5 секунд для GET-методов и 15 секунд для выгрузок. По превышению не повторяйте запрос без идемпотентного ключа.
24 валюты: RUB, USD, EUR, GBP, KZT, BYN, UAH, AZN, GEL, TRY, CNY, JPY, CHF, SEK, NOK, DKK, PLN, CZK, HUF, RON, AED, SAR, KRW и SGD. Расширенный список открывается через отдельную заявку в кабинете.