Балансы и организации

Что такое Business API

Business API — программный доступ к балансу бизнес-организации. Раздел нужен партнёрам, которые закупают объём у GPTunneL и раздают его своим клиентам: агентствам, дистрибьюторам, white-label-площадкам.

Через API можно:

• переводить деньги с баланса своей организации на личный счёт пользователя или на счёт другой организации — Перевод баланса;
• создавать организации-клиенты и назначать им владельца — Создание организации.

Партнёрам, у которых клиенты регистрируются на собственной площадке, дополнительно подключаются методы работы с клиентами — см. Клиенты партнёра:

• смотреть баланс клиента — Баланс клиента;
• получать его траты за период — Траты клиента за период;
• возвращать переведённые средства на свой баланс — Возврат средств;
• получать список организаций клиента — Организации клиента.

Клиент о переводе ничего не делает: деньги появляются на его счёте сразу, историю он видит в личном кабинете как операцию «Перевод».

Авторизация

Все запросы выполняются по API-ключу организации (заголовок Authorization). Ключ создаётся во вкладке API бизнес-профиля владельцем или администратором организации. Ключ личного аккаунта для раздела не подходит: перевод ответит 403 с кодом 22, остальные методы — 403 с кодом 13. См. раздел С чего начать?.

Подключение

Раздел включается для организации индивидуально. Порядок такой:

1. Менеджер GPTunneL включает организации переводы и, если нужно, создание организаций. Пока создание не включено, orgs/create отвечает 403 с кодом 32.
2. Владелец или администратор организации включает на API-ключе тумблер «Переводы» — при создании ключа или позже, в его настройках. Пересоздавать ключ не нужно. Тумблер появляется только после того, как организации включены переводы (шаг 1). Ключ без тумблера получает на перевод 403 с кодом 22.
3. Организация пополняет свой баланс. Переводы списываются с него с учётом кредитного лимита, если он назначен.

Если перевод отвечает 22 или 16

Сначала проверяется ключ, потом организация. Код 22 значит, что на ключе выключен тумблер «Переводы». Если тумблера в настройках ключа нет, переводы для организации ещё не включены — напишите менеджеру. Код 16 приходит, когда тумблер на ключе включён, но организация переводить не может: переводы для неё выключили, организация удалена или обслуживается через дистрибьютора.

Общие правила

• Базовый адрес: https://gptunnel.ru/api/v1/. Все методы — POST с JSON-телом, только HTTPS.
• Денежные методы требуют заголовок Idempotency-Key: 8–64 символа из A-Za-z0-9_- (у возврата — 8–60), уникальный на каждую операцию. Повтор запроса с тем же ключом и тем же телом вернёт тот же результат с replayed: true и не спишет деньги второй раз. Тот же ключ с другим телом — 409, код 20.
• Пользователи и организации адресуются по id: 24 шестнадцатеричных символа, буквы только строчные (a-f). Пользователь видит свой id в личном кабинете по кнопке «Скопировать ID», организация — в карточке клиента.
• Ответ всегда JSON с полем code: 0 — успех, иначе код ошибки из справочника. HTTP-статус дублирует класс ошибки. Исключение — 401 на непринятый ключ: у него свой формат, см. справочник.

{ "code": 0, "transaction_id": "order-2026-10-20-000153", "amount": 500 }

{ "code": 19, "message": "Insufficient funds on the organization balance." }

Лимиты

Ограничение	Значение
Максимальная сумма перевода и возврата с явной amount	100 000 ₽
Точность суммы	2 знака после запятой
Длина Idempotency-Key	8–64 символа A-Za-z0-9_-
Длина Idempotency-Key у возврата	8–60 символов A-Za-z0-9_-
Период отчёта о тратах	92 дня по дням, 366 по месяцам
Длина названия организации	1–255 символов

Клиенты партнёра

Методы balance/get, balance/spending, balance/refund и orgs/list подключаются отдельно, под конкретного партнёра с собственной площадкой — доменом, на котором регистрируются его пользователи. Подключает менеджер GPTunneL; тумблера в кабинете для них нет. Ключ организации, которой методы не подключены, получает 403 с кодом метода: 34, 40, 35 или 36. У возврата раньше проверяется тумблер «Переводы» на ключе: без него придёт 403 с кодом 22.

Эти методы работают только с клиентами партнёра:

• пользователь — аккаунт, зарегистрированный на площадке партнёра. Адресуется по user_id, операции идут с его личным счётом;
• организация — организация, действующий владелец которой — такой пользователь. Адресуется по org_id. Организация с владельцем, который не является вашим клиентом, этим методам не видна, даже если вы создали её или переводили ей деньги.

На чужого клиента ответ тот же, что на несуществующего: 404 с кодом 17 для пользователя и 24 для организации. Узнать по ответу, есть ли такой аккаунт у другого партнёра, нельзя.

user_id клиент видит в личном кабинете по кнопке «Скопировать ID»; организации пользователя с их org_id отдаёт orgs/list.

Поиск по телефону

Поле user_data: { "phone": "+79XXXXXXXXX" } вместо user_id доступно только партнёрам, у которых аккаунты клиентов заводятся по номеру телефона. Остальным оно отвечает 403 с кодом 27 — используйте user_id.

Чтение баланса, трат и списка организаций ничего не меняет и Idempotency-Key не требует. Возврат — денежная операция: ему нужны заголовок Idempotency-Key и ключ с тумблером «Переводы».