Для 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.
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-приложение
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 неизвестен либо клиент отключён:
{
"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 — Ошибки.