Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/endpoints.md индекс документации — /llms.txt

Эндпоинты Partner Connect

Переключатель методов Partner Connect. Каждая вкладка открывает страницу эндпоинта с параметрами, примерами кода и ответами.

Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: client_id и client_secret приложения в теле запроса, у статуса Компании — секрет подключения в X-Api-Key

Начать авторизацию пользователя

GET /v1/connect/authorize

Перенаправляет пользователя на страницу согласия Битрикс24 Вайбкод.

Параметры

Параметр Тип Обяз. Описание
Параметрclient_id Типstring Обяз.да ОписаниеИдентификатор партнёра, полученный при регистрации клиента
Параметрredirect_uri Типstring Обяз.да ОписаниеURL обратного вызова. Должен совпадать с одним из зарегистрированных у клиента
Параметрstate Типstring Обяз.да ОписаниеПроизвольная строка, которая вернётся вместе с кодом. Защита от CSRF
Параметрscope Типstring Обяз.нет ОписаниеЗапрашиваемые права через пробел или запятую: crm task im. Если не передать — применяются права, зарегистрированные для клиента. Запрос права за пределами зарегистрированного набора отклоняется
Параметрcode_challenge Типstring Обяз.условно ОписаниеХеш SHA-256 от code_verifier в base64url без =. Обязателен для публичного клиента или при обязательном PKCE, иначе необязателен
Параметрcode_challenge_method Типstring Обяз.условно ОписаниеS256, обязателен вместе с code_challenge. Другие методы, пустые значения и метод без хеша отклоняются
Параметрportal Типstring Обяз.нет ОписаниеДомен портала Битрикс24, который выбрать заранее на странице согласия: mycompany.bitrix24.ru. Подсказка, а не выбор портала — см. Подсказка портала
Параметрoperation Типstring Обяз.нет ОписаниеТолько для клиента в режиме COMPANY: CREATE — новое подключение, RECONNECT — новое согласие администратора без смены секрета, ROTATE_SECRET — замена секрета без расширения прав. По умолчанию CREATE. Назначение сохраняется на весь поток и при согласии и обмене кода не меняется — см. Переподключение и ротация секрета
Параметрcredential_version Типinteger Обяз.условно ОписаниеТекущая версия секрета подключения, от 1. Обязателен для клиента в режиме COMPANY при operation=ROTATE_SECRET. Значение берите из поля data.credential_version ответа GET /v1/connect/company/status

Для клиента с секретом PKCE необязателен, если не включён в настройках клиента. Если передать code_challenge, платформа сохранит его и потребует соответствующий code_verifier при обмене кода. PKCE дополняет client_secret, а не заменяет его. Для публичного клиента и при обязательном PKCE хеш нужен всегда.

Подсказка портала

Если приложение знает, из какого портала Битрикс24 пришёл пользователь, передайте домен этого портала в параметре portal. Схему и путь можно не отрезать, регистр не важен.

https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=crm%20task&state=abc123random&portal=mycompany.bitrix24.ru
  • Если пользователь — активный участник указанного портала, этот портал выбран на странице согласия заранее. Иначе портал на странице выбирается так же, как без параметра.
  • Пользователь может выбрать другой портал. Ключ выдаётся на тот портал, который пользователь подтвердил, поэтому портал ключа берите из поля portal.domain ответа POST /v1/connect/token, а не из своей подсказки.
  • Ответ authorize от параметра не зависит: приложение не узнаёт, состоит ли пользователь в указанном портале.
  • Некорректное значение не вызывает ошибку и не возвращается на redirect_uri — вход идёт как без параметра.
  • Подсказку учитывает только поток с кодом авторизации для клиентов в режиме PERSONAL. Клиенты в режиме COMPANY параметр игнорируют, у входа с устройства подсказки портала нет.

Примеры

Эндпоинт открывается переходом браузера пользователя по ссылке, которую собирает приложение. Ключ API и заголовки X-Api-Key и Authorization не нужны: приложение называет себя параметром client_id.

curl — OAuth-приложение

Запрос показывает ответ, который получит браузер пользователя: 302 с адресом страницы согласия в заголовке Location.

Terminal
curl -i "https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=crm%20task&state=abc123random"

JavaScript — OAuth-приложение

javascript
const state = crypto.randomUUID()
// сохраните state в сессии пользователя, чтобы сверить его на redirect_uri

const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://yourapp.com/callback',
  scope: 'crm task',
  state,
})

const authorizeUrl = `https://vibecode.bitrix24.tech/v1/connect/authorize?${params}`
// отправьте пользователя по authorizeUrl: ссылкой или редиректом со своего сервера

Серверный код, который собирает такую ссылку и проверяет state при возврате, — в полном примере. Ссылку для своего приложения можно собрать и без кода: помощник «Собрать ссылку» в карточке приложения, см. Регистрация приложения и права.

Поля ответа

Ответ — редирект на redirect_uri с параметрами в строке запроса:

Параметр Тип Описание
Параметрcode Типstring ОписаниеОдноразовый код авторизации. Приходит после одобрения. Обменивается на ключ через POST /v1/connect/token
Параметрstate Типstring ОписаниеЗначение state из запроса без изменений
Параметрerror Типstring ОписаниеКод отказа. Приходит вместо code
Параметрerror_description Типstring ОписаниеМашинный код причины отказа. Приходит при отказе после экрана согласия и при отказе клиенту в режиме COMPANY — см. Подключение Компании

Пример ответа

Успешный редирект после одобрения:

https://yourapp.com/callback?code=AUTH_CODE_HERE&state=abc123random

Редирект при отказе пользователя на странице согласия:

https://yourapp.com/callback?error=access_denied&state=abc123random

Пример ответа при ошибке

400 — client_id неизвестен либо клиент отключён:

JSON
{
  "error": "invalid_client",
  "error_description": "Unknown or inactive client"
}

Ошибки

Ошибки этого эндпоинта приходят тремя разными путями, и обработать нужно все три.

До того как redirect_uri проверен — обычный ответ 400 с телом RFC 6749. Возвращать пользователя некуда: адрес ещё не подтверждён, редирект на непроверенный URL был бы уязвимостью.

HTTP error Условие
HTTP400 errorinvalid_request УсловиеНе передан один из client_id, redirect_uri, state
HTTP400 errorinvalid_client Условиеclient_id неизвестен либо клиент отключён
HTTP400 errorinvalid_request Условиеredirect_uri искажён: не разбирается как URL, содержит фрагмент #, логин или пароль. error_description — Redirect URI is malformed
HTTP400 errorinvalid_request УсловиеСхема redirect_uri не разрешена для его адреса: не https у адреса не на localhost, не http и не https у localhost. error_description — Redirect URI scheme is not allowed for this host
HTTP400 errorinvalid_request Условиеredirect_uri не совпадает ни с одним зарегистрированным. error_description — Redirect URI not registered

После того как redirect_uri проверен — редирект обратно на него с параметрами error и state (RFC 6749 §4.1.2.1). Ваш обработчик redirect_uri обязан это разбирать.

error в редиректе Условие
error в редиректеinvalid_scope УсловиеЗапрошено неизвестное право или право за пределами зарегистрированного набора клиента
error в редиректеinvalid_scope УсловиеКлиент в режиме COMPANY запросил платформенное право vibe:*, кроме vibe:ai и vibe:storage: подключению Компании доступны только эти два платформенных права
error в редиректеinvalid_request УсловиеОбязательный PKCE не передан, либо переданы некорректный code_challenge или code_challenge_method. Поддерживается только S256
error в редиректеinvalid_request УсловиеКлиент в режиме COMPANY передал operation не из CREATE, RECONNECT, ROTATE_SECRET
error в редиректеaccess_denied с error_description=CONNECT_COMPANY_NOT_READY УсловиеКлиенту в режиме COMPANY отказано до страницы согласия: технические условия подключения не выполнены — клиент отключён либо его настройка для режима COMPANY некорректна, запрошенная operation ему недоступна, партнёр не подтвердил режим Компании, режим клиента в этот момент меняется либо выдача подключений Компании не готова на платформе. Отказ держится, пока не устранена его причина, поэтому сам по себе повтор его не снимает
error в редиректеaccess_denied с error_description=CONNECT_COMPANY_DISABLED УсловиеКлиенту в режиме COMPANY отказано до страницы согласия: подключение Компании недоступно для выбранного пользователя или портала — см. Подключение Компании
error в редиректеaccess_denied УсловиеПользователь нажал «Отклонить» на странице согласия
error в редиректеaccess_denied УсловиеПользователь подтвердил доступ, но ключ выдать не удалось: у портала нет подписки или тарифа, открывающего доступ к Вайбкод, регион не поддерживается либо исчерпан лимит ключей. Машинный код причины приходит в error_description
error в редиректеtemporarily_unavailable УсловиеПользователь подтвердил доступ, но выписка ключа не завершилась из-за временной недоступности Битрикс24. Машинный код причины, например BITRIX_UNAVAILABLE, приходит в error_description. Попытку можно повторить
https://yourapp.com/callback?error=invalid_scope&state=abc123random

Остальные отказы клиенту в режиме COMPANY приходят так же: error=access_denied и машинный код причины в error_description. Список этих кодов открыт — см. Подключение Компании.

Превышение частоты — 429 до всякой проверки параметров, поэтому ни редиректа, ни state не будет. Лимит: 30 запросов в минуту, считается по паре client_id и адрес вызывающего. Действующее значение — в заголовке x-ratelimit-limit. Тело приходит в общем конверте API — { "success": false, "error": { "code": "RATE_LIMITED", "message": "..." } }, а не в форме RFC 6749, и заголовки X-RateLimit-* присутствуют.

Обработать этот путь нужно отдельно, потому что authorize открывается переходом браузера: пользователь увидит страницу с JSON вместо экрана согласия, на redirect_uri не придёт ничего, и приложение не получит обратно свой state. Приложение обязано считать такую авторизацию незавершённой по своему таймауту, а не ждать обратного вызова. Значение Retry-After называет минимальную паузу.

Отказ после экрана согласия

Отказ в выдаче ключа наступает уже после того, как пользователь подтвердил доступ. Причину он видит на странице согласия Вайбкод, а в приложение возвращается по кнопке — тогда на redirect_uri приходит error, error_description и исходный state:

https://yourapp.com/callback?error=access_denied&error_description=MARKETPLACE_REQUIRED&state=abc123random

error_description несёт машинный код причины, по которому приложение может показать свой экран:

Код в error_description Что произошло
Код в error_descriptionMARKETPLACE_REQUIRED Что произошлоНа портале нет активной подписки BitrixGPT + Маркетплейс. Там, где доступ открывает тариф Битрикс24, вместо него приходят BY_PAID_ONLY, KZ_PAID_ONLY и UZ_PAID_ONLY
Код в error_descriptionKEY_LIMIT_REACHED Что произошлоКлюч выдать нельзя: исчерпан лимит ключей пользователя или портальный потолок платформы — см. Лимит ключей
Код в error_descriptionBITRIX_UNAVAILABLE Что произошлоБитрикс24 не ответил во время выписки ключа. Приходит с error=temporarily_unavailable, а не access_denied
Код в error_descriptionSTATE_EXPIRED Что произошлоСсылка согласия истекла до подтверждения — авторизацию начинают заново с /v1/connect/authorize
Код в error_descriptionadmin_approval_requested Что произошлоПользователь не администратор портала и попросил администраторов разрешить приложению AI — запрос пришёл им в чат бота. Приходит, когда на платформе включено разрешение AI администратором портала. Когда администратор разрешит AI, авторизацию начинают заново с /v1/connect/authorize

Список кодов открыт: приложение должно понимать любой error_description как причину отказа и не полагаться на то, что перечень выше исчерпывающий.

При отказе в доступе по денежной причине пользователь видит встроенную карточку оплаты на странице согласия. Действия относятся к выбранному порталу Битрикс24. Для MARKETPLACE_REQUIRED карточка предлагает «Узнать подробнее» — открыть описание подписки в новой вкладке, а также активировать пробный период, если он доступен этому порталу. Для BY_PAID_ONLY, KZ_PAID_ONLY, UZ_PAID_ONLY и INT_TARIFF_REQUIRED предлагается выбрать тариф Битрикс24. Для INT_VIBE_PLUS_REQUIRED — тариф Vibe+. При INT_TARIFF_REQUIRED на .com в зависимости от выбранного портала также может предлагаться Vibe+. В модели Vibe+ карточка предлагает активацию пробного периода, если он доступен. Демо-тариф Битрикс24 подключают в самом Битрикс24, если он там доступен.

Пока пользователь не нажмёт кнопку возврата в приложение, на redirect_uri ничего не приходит. Возврат после такого отказа передаёт error=access_denied, машинный код причины в error_description и исходный state. code и API-ключ не выдаются. После покупки или активации пробного периода вернитесь в приложение и начните авторизацию заново с /v1/connect/authorize: одноразовое состояние прежней ссылки уже использовано.

Полный справочник общих ошибок API — Ошибки.

Смотрите также