Partner API

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

Доступ

Базовый URL: https://clear-way.pro/api/v1
Авторизация: заголовок Authorization: Bearer <токен>

Токен выпускается в кабинете: API → Выпустить токен. Показывается один раз — мы храним только его хеш и восстановить не сможем. Там же перевыпуск: новый токен сразу отключает предыдущий.

Быстрый старт

TOKEN="ваш_токен"

# баланс и лимиты
curl -H "Authorization: Bearer $TOKEN" https://clear-way.pro/api/v1/account

# выдать хост клиенту с лимитом 500 ГБ
curl -X POST https://clear-way.pro/api/v1/hosts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"origin_addr":"1.2.3.4","origin_port":25454,"client_ref":"client-42","quota_gb":500}'

# кто сколько потребил
curl -H "Authorization: Bearer $TOKEN" https://clear-way.pro/api/v1/usage

Выдать хост клиенту

POST /hosts

Поле	Описание
origin_addr	публичный IP ноды клиента — обязательно (домены не принимаются)
origin_port	порт инбаунда — обязательно
client_ref	ваш идентификатор клиента, по нему группируется отчёт
quota_gb	лимит трафика на этот хост; без него — только ваш общий баланс
xhttp_extra	свои xhttpSettings, если нода клиента уже настроена по-своему

В ответе 201 приходит хост и блок config из трёх частей: config_profile (профиль для ноды клиента), host_config (Host для его панели) и inbound_json (отдельный инбаунд для 3x-ui).

Если хост на этот же origin_addr:origin_port уже создавался, вернётся существующий с полем "existing": true — повторный запрос не наплодит дублей.

Управление клиентами

Запрос	Что делает
GET /account	баланс, остаток, сколько хостов выдано из лимита
GET /hosts	список хостов, фильтр ?client_ref=
GET /hosts/{id}	один хост вместе с конфигом — если клиент потерял
PATCH /hosts/{id}	{"quota_gb": 1000} — изменить лимит {"enabled": false} — отключить неплательщика {"client_ref": "..."} — переназначить клиента
DELETE /hosts/{id}	удалить хост; история потребления сохраняется
GET /usage	потребление по клиентам, параметр ?period=2026-07

Отключение через enabled: false срабатывает за несколько секунд, хост при этом не удаляется — включить обратно так же просто.

Как работают лимиты

Уровня два, и они независимы:

• Ваш баланс — общий. Исчерпан → останавливаются все ваши хосты.
• Лимит на хост (quota_gb) — необязательный. Исчерпан → останавливается только этот клиент, остальные продолжают работать.

Второй уровень и позволяет продавать пакеты («500 ГБ клиенту») и защищает баланс от одного клиента, который выкачает всё.

Отчёт для биллинга

GET /usage отдаёт по каждому хосту bytes (это bytes_up + bytes_down — ровно та величина, по которой списывается ваш баланс) и requests.

Сумма по клиентам всегда сходится с тем, что списано у вас, поэтому расхождений в счетах не будет. В кабинете тот же отчёт есть с выгрузкой в CSV.

Тарификация запросов

CDN берёт плату не только за трафик, но и за количество HTTP-запросов, а у XHTTP «болтливый» уплинк. Включено 80 000 запросов на ГБ — обычный профиль VPN-трафика укладывается с запасом.

Сверх — 1 ₽ за 100 тысяч запросов по себестоимости, без наценки. Свой показатель считается как requests / (bytes / 1024³), либо смотрите готовую колонку «запросов на ГБ» в отчёте кабинета — там сразу видно, кто из клиентов «тяжёлый».

Ошибки

Формат: {"error": "описание"} с соответствующим кодом.

Код	Когда
401	токен отсутствует или не найден
403	API не включён, аккаунт заблокирован или достигнут лимит хостов
400	не публичный IP, некорректный порт или xhttp_extra
404	хост не найден или принадлежит другому аккаунту

Что делается только вручную

Пополнение баланса — в кабинете, раздел «Пополнить». Всё остальное доступно и через API, и мышкой.