Публичный API Vector Trading

Эта страница описывает REST API для владельцев бандлов. Точный контракт схем доступен в Swagger.

API позволяет:

• получать список ваших пакетов ботов
• искать пользователей по имени
• получать историю неотозванных доступов к бандлу
• создавать и отзывать доступы
• читать короткоживущие checkout-сессии

API ключи доступны пользователям с premium или elite подпиской в Профиль -> API ключи.

API ключи предназначены для server-side интеграций. Не храните и не используйте их в браузерном JavaScript: публичные REST API запросы не опираются на web session Vector Trading, cookies или credentialed browser CORS.

Scopes:

• bundles: список ваших пакетов ботов
• users: поиск пользователей по имени
• grants: просмотр, создание и отзыв доступов

Используйте grants: write, если внешняя платёжная система должна выдавать или отзывать доступ к бандлу.

Каждый запрос должен содержать:

Authorization: Bearer vt_<apiKeyId>_<secret>

Base URL:

https://www.vector-trading.app/api/rest/v1

Запросы ограничены 240 запросами в минуту с одного IP-адреса и 240 запросами в минуту с одного API-ключа. Каждый запрос должен укладываться в оба лимита. При превышении API возвращает 429 Too Many Requests; повторите запрос, снизив частоту.

Все endpoints, возвращающие списки, принимают опциональные limit и cursor. Ответ содержит фактически применённый limit и nextCursor, если доступна следующая страница. Передавайте nextCursor без изменений в следующий запрос и сохраняйте остальные фильтры и сортировку. В первом запросе cursor не указывается; отсутствие nextCursor означает конец списка. Неполная или даже пустая страница не означает конец списка, пока в ответе есть nextCursor: продолжайте запросы до его отсутствия.

1. Получите бандлы через GET /bundles.
2. Найдите пользователя через GET /users?displayName=....
3. Создайте доступ через POST /bundles/<bundleId>/grants.
4. Отслеживайте историю неотозванных доступов через GET /bundles/<bundleId>/grants.

curl -G "https://www.vector-trading.app/api/rest/v1/bundles" \  -H "Authorization: Bearer $VECTOR_API_KEY" \  --data-urlencode "limit=50" \  --data-urlencode "cursor=<nextCursor>"

Архивные бандлы не возвращаются. Поскольку каждое source-чтение ограничено, длинная архивная история может дать неполную или пустую страницу с nextCursor; продолжайте запросы до отсутствия cursor.

curl -G "https://www.vector-trading.app/api/rest/v1/users" \  -H "Authorization: Bearer $VECTOR_API_KEY" \  --data-urlencode "displayName=alex" \  --data-urlencode "limit=10" \  --data-urlencode "cursor=<nextCursor>"

displayName — case-insensitive prefix-поиск длиной 2–30 символов. Используйте возвращённый userId для операций с доступами.

curl -G "https://www.vector-trading.app/api/rest/v1/bundles/<bundleId>/users" \  -H "Authorization: Bearer $VECTOR_API_KEY" \  --data-urlencode "limit=50" \  --data-urlencode "cursor=<nextCursor>"

Возвращает публичную информацию о пользователях, текущий тип доступа, период текущего grant-а и конец непрерывного доступа (accessEndsAt или accessIsPermanent).

curl -G "https://www.vector-trading.app/api/rest/v1/bundles/<bundleId>/grants" \  -H "Authorization: Bearer $VECTOR_API_KEY" \  --data-urlencode "limit=50" \  --data-urlencode "cursor=<nextCursor>"

Возвращает все неотозванные grants, включая истёкшие: id, grantType, optional userId, sourceId, startsAt, endsAt, createdAt. Grant отсутствующего или окончательно удалённого Account остаётся в истории без userId. Внешняя интеграция сама решает, учитывать ли такие записи. Vector Trading не публикует Account status через этот API. При селективных фильтрах API ограничивает объём одного чтения, поэтому страница grants может быть пустой или содержать меньше limit записей вместе с nextCursor. Продолжайте с теми же фильтрами и сортировкой до ответа без cursor.

curl -X POST "https://www.vector-trading.app/api/rest/v1/bundles/<bundleId>/grants" \  -H "Authorization: Bearer $VECTOR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "userId": "<userId>",    "grantType": "paid_external",    "endsAt": "2026-07-19T12:00:00.000Z",    "sourceId": "stripe:invoice:in_123"  }'

Допустимые grantType: owner_grant, paid_external, referral_reward, gift.

Используйте endsAt для временного доступа. Vector Trading сам выбирает startsAt grant-а: доступ начинается сразу или после текущей непрерывной цепочки доступа. Если endsAt уже покрыт активной или запланированной цепочкой, API вернёт покрывающий grant и не создаст дубликат. Если endsAt не указан, доступ бессрочный.

Для paid_external поле sourceId обязательно и должно указывать на оплаченный invoice, платёж или webhook-событие. Оно должно быть visible ASCII token по грамматике [A-Za-z0-9][A-Za-z0-9._:-]{0,255}. Если sourceId повторяется для того же бандла, пользователя и типа доступа, API вернёт существующий grant.

Vector Trading не обрабатывает платежи и не хранит состояние рекуррентной подписки вашего checkout-а. Используйте Vector Trading как ledger доступа:

1. Когда первый invoice оплачен, создайте paid_external grant с endsAt, равным окончанию оплаченного периода.
2. Когда оплачен рекуррентный renewal invoice, снова вызовите этот endpoint с новым sourceId и endsAt следующего периода.
3. Для разовой lifetime-покупки создайте paid_external grant с уникальным sourceId и не указывайте endsAt.
4. Если renewal-платёж не прошёл, не создавайте новый grant. Текущий доступ истечёт естественно.
5. Если клиент отменил подписку в конце периода, не отзывайте текущий grant. Просто перестаньте создавать будущие grants.
6. При немедленной отмене, refund или chargeback отзовите текущие или будущие grants через revoke endpoint.

curl -X DELETE "https://www.vector-trading.app/api/rest/v1/bundles/<bundleId>/grants/<grantId>" \  -H "Authorization: Bearer $VECTOR_API_KEY"

Внимание: отзыв выставляет revokedAt выбранному grant-у и всем текущим или будущим grant-ам этого пользователя в этом бандле, которые начинаются после него. Физического удаления grant-ов нет.

Владелец бандла может указать strict HTTPS paymentUrl в платных условиях бандла. paymentUrl доступен только вместе с информационной ценой и валютой бандла. Когда пользователь подтверждает дисклеймер платформы, Vector Trading создаёт checkout-сессию на 15 минут и открывает URL владельца, добавив checkoutId в query string. Перед списанием оплаты checkout владельца должен прочитать эту сессию через API.

curl -X GET "https://www.vector-trading.app/api/rest/v1/checkout/<checkoutId>" \  -H "Authorization: Bearer $VECTOR_API_KEY"

API ключ должен принадлежать владельцу бандла и иметь grants: read.

Ответ содержит checkoutId, bundleId, userId, displayName, текущие display-условия бандла (price, currency, discount) и не содержит trialPeriodDays. Перед списанием оплаты покажите пользователю displayName и сумму платежа.

Частые случаи:

• 401: API ключ отсутствует или некорректен
• 403: у ключа нет нужного scope
• 404: бандл, пользователь, grant или checkout-сессия не найдены
• 400: некорректный параметр или тело запроса
• 413: JSON body слишком большой
• 415: body отправлен не как application/json
• 429: превышен лимит запросов
• 500/503: server error с generic public message и requestId