#Partner Connect

Подключение внешних сервисов к Битрикс24: ваше приложение запрашивает у пользователя разрешение на доступ к его порталу и получает API-ключ Вайбкод для дальнейших вызовов. Поток построен по схеме Authorization Code — той же, что у OAuth-провайдеров Google или GitHub.

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: client_id + client_secret партнёра | Скоупы ключа: запрашиваются на странице согласия

#Содержание

• Когда применять
• Как это работает
• Справочник эндпоинтов
• Полный сценарий — Express-обработчик от и до
• `GET /v1/connect/authorize` — старт потока, редирект на согласие
• `POST /v1/connect/token` — обмен кода на API-ключ
• Использование API-ключа
• Доступные скоупы
• Время жизни и отзыв ключа
• Безопасность
• Регистрация партнёра
• Смотрите также

#Когда применять

Сценарий — внешний SaaS-продукт, который интегрируется с порталами Битрикс24 ваших клиентов: CRM-аналитика, синхронизация с 1С, чат-ассистент, конструктор лендингов. Кнопка «Подключить Битрикс24» на вашем сайте запускает поток: пользователь выбирает портал и подтверждает скоупы, ваш сервер получает постоянный API-ключ и работает с порталом от имени пользователя.

Если вы пишете приложение, которое ставится внутри портала Битрикс24 и работает только с ним, — используйте обычный API-ключ, см. Авторизация и ключи.

#Как это работает

Ваше приложение → [1. Redirect] → Вайбкод Consent Page → [2. Согласие]
    ↑                                                          ↓
    └──── [4. API-ключ] ←── [3. Code → redirect_uri] ──────────┘

1. Redirect — отправляете пользователя на /v1/connect/authorize с client_id, redirect_uri, state и списком скоупов.
2. Согласие — пользователь видит страницу Вайбкод, выбирает портал и подтверждает или отклоняет запрошенные скоупы.
3. Код — после одобрения пользователь возвращается на redirect_uri с параметрами code и state. При отказе — redirect_uri?error=access_denied&state=....
4. Обмен — сервер партнёра отправляет POST /v1/connect/token и получает API-ключ.

#Справочник эндпоинтов

#Полный сценарий

Пример Express-обработчика, который проводит пользователя через оба эндпоинта от и до. Перед запуском поместите client_id и client_secret, выданные командой Битрикс24 Вайбкод, в переменные окружения, а redirect_uri зарегистрируйте у партнёра.

import express from 'express'
import crypto from 'node:crypto'

const app = express()
const sessions = new Map() // в продакшене — Redis или БД

const CLIENT_ID = process.env.PARTNER_CLIENT_ID
const CLIENT_SECRET = process.env.PARTNER_CLIENT_SECRET
const REDIRECT_URI = 'https://yourapp.com/callback'

// 1. Кнопка «Подключить Битрикс24» ведёт сюда
app.get('/connect', (req, res) => {
  const state = crypto.randomBytes(16).toString('hex')
  sessions.set(state, { userId: req.user.id, createdAt: Date.now() })

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scopes: 'crm,task',
    state,
  })
  res.redirect(`https://vibecode.bitrix24.tech/v1/connect/authorize?${params}`)
})

// 2. Вайбкод возвращает пользователя сюда после согласия или отказа
app.get('/callback', async (req, res) => {
  const { code, state, error } = req.query

  const session = sessions.get(state)
  if (!session) return res.status(400).send('Неизвестный state')
  sessions.delete(state)

  if (error === 'access_denied') {
    return res.redirect('/dashboard?connect=denied')
  }

  // 3. Обмениваем код на API-ключ — серверный запрос с client_secret
  const tokenRes = await fetch('https://vibecode.bitrix24.tech/v1/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      redirect_uri: REDIRECT_URI,
    }),
  })
  const data = await tokenRes.json()

  if (!data.success) {
    return res.status(400).send(`Ошибка обмена: ${data.error.code}`)
  }

  // 4. Сохраняем привязку: пользователь нашего сервиса ↔ портал Битрикс24
  await db.connections.upsert({
    userId: session.userId,
    portalDomain: data.portal.domain,
    portalName: data.portal.name,
    apiKey: encrypt(data.api_key), // секрет, шифруем перед хранением
    scopes: data.scopes,
  })

  res.redirect('/dashboard?connect=ok')
})

// 5. Дальше используем сохранённый ключ для вызовов от имени пользователя
async function listDeals(userId) {
  const connection = await db.connections.findByUserId(userId)
  const apiKey = decrypt(connection.apiKey)

  const res = await fetch('https://vibecode.bitrix24.tech/v1/deals?limit=10', {
    headers: { 'X-Api-Key': apiKey },
  })
  return res.json()
}

Ключевые моменты сценария:

• state генерируется на сервере и проверяется при возврате — без этой проверки злоумышленник может подсунуть пользователю чужой код.
• client_secret хранится только на сервере и в браузер не попадает.
• API-ключ шифруется перед записью в БД и расшифровывается только в момент вызова.
• При error=access_denied пользователь видит понятное сообщение, а не страницу с ошибкой обмена.

#GET /v1/connect/authorize

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

Query-параметры:

Пример URL:

https://vibecode.bitrix24.tech/v1/connect/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scopes=crm,task&state=abc123random

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

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

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

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

#Ошибки

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

#POST /v1/connect/token

Обменивает одноразовый код авторизации на постоянный API-ключ. Принимает application/json и application/x-www-form-urlencoded.

Поля запроса (body):

#Примеры

#curl

curl -X POST https://vibecode.bitrix24.tech/v1/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=RECEIVED_CODE \
  -d redirect_uri=https://yourapp.com/callback

#JavaScript

const res = await fetch('https://vibecode.bitrix24.tech/v1/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code: receivedCode,
    redirect_uri: 'https://yourapp.com/callback',
  }),
})

const data = await res.json()
// data.api_key — постоянный API-ключ Вайбкод
// data.portal — выбранный пользователем портал
// data.scopes — подтверждённые скоупы
// data.user — пользователь, выдавший доступ

#Поля ответа

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

{
  "success": true,
  "api_key": "vibe_app_...",
  "portal": {
    "domain": "example.bitrix24.ru",
    "name": "Моя компания"
  },
  "scopes": ["crm", "task"],
  "user": {
    "name": "Иван Иванов",
    "email": "ivan@example.com"
  }
}

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

400 — отсутствует обязательный параметр:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameters"
  }
}

#Ошибки

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

#Использование API-ключа

Полученный ключ имеет тип APP и работает как стандартный API-ключ Вайбкод. Передавайте его в заголовке X-Api-Key:

curl -H "X-Api-Key: vibe_app_..." \
  https://vibecode.bitrix24.tech/v1/deals

Один и тот же ключ можно использовать с любым эндпоинтом Вайбкод API в пределах подтверждённых скоупов: список сделок, batch-запросы, поиск, агрегация и т. д.

Партнёрский ключ работает с одним заголовком X-Api-Key и не требует Authorization: Bearer <session_token>. Это отличает его от ключей OAuth-приложений из каталога Вайбкод с тем же префиксом vibe_app_... — там сессия пользователя обязательна.

#Доступные скоупы

При вызове /v1/connect/authorize передавайте те же скоупы, что и при создании стандартного API-ключа в портале Битрикс24. На странице согласия пользователь видит список и может снять отдельные пункты — итоговый набор приходит в поле scopes ответа /v1/connect/token.

Полный список поддерживаемых значений (32 скоупа: crm, task, tasks, im, imbot, imopenlines, call, telephony, bizproc, calendar, timeman, catalog, sale, lists, disk, entity, user, user_basic, user_brief, user.userfield, department, landing, documentgenerator, sign.b2e, sonet_group, log, vote, ai_admin, biconnector, booking, delivery, pay_system, main, placement, userfieldtype) описан в разделе Авторизация и ключи.

#Время жизни и отзыв ключа

• Код авторизации (code) действует 5 минут и одноразовый. После обмена через /v1/connect/token повторный вызов с тем же кодом вернёт INVALID_CODE.
• Стейт согласия (внутреннее состояние страницы согласия) живёт 10 минут — если пользователь не подтвердит за это время, ссылку придётся выдавать заново.
• API-ключ не имеет срока истечения. Действует, пока:
  • пользователь не отзовёт доступ в портале (на странице управления выданными правами в личном кабинете),
  • либо команда Битрикс24 Вайбкод не приостановит партнёрское приложение.

При отзыве ключа все запросы с ним возвращают 401 KEY_INACTIVE. Если ключ удалён или неизвестен — 401 INVALID_API_KEY. Партнёр должен корректно обработать оба кода и предложить пользователю повторно авторизоваться.

#Безопасность

• State-параметр — генерируйте криптостойкую случайную строку на каждый запрос и сверяйте при возврате на redirect_uri. Защищает от CSRF.
• client_secret — только на сервере. Никогда не передавайте секрет в браузер, мобильное приложение или клиентский код. Обмен кода на ключ выполняется только серверным запросом.
• Хранение ключа. API-ключ — секрет, который даёт доступ к данным пользователя. Храните в зашифрованном виде, ограничивайте доступ к строке подключения, не логируйте.
• Привязка redirect_uri. Значение в /v1/connect/authorize и /v1/connect/token должно совпадать символ в символ — несоответствие приведёт к INVALID_CODE.

#Регистрация партнёра

Самостоятельная регистрация пока не предусмотрена — client_id и client_secret выдаёт команда Битрикс24 Вайбкод после ревью заявки. Чтобы оставить заявку, напишите на lev@bitrix.ru.

В заявке укажите:

• название и краткое описание приложения,
• сценарий использования,
• список запрашиваемых скоупов,
• один или несколько redirect_uri, которые будете использовать.

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

• Авторизация и ключи — общие правила работы с API-ключами Вайбкод, типы ключей (включая OAuth-приложения), список скоупов
• Управляющие ключи — программное создание ключей для собственного портала
• Ошибки API — общий справочник кодов ошибок