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

Внешний API приложения

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

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key | Ключ: ключ внешнего API приложения

Когда это нужно | Что включить | Ключ | Адрес и методы | Что получает приложение | Что возвращается вызывающему | Примеры | Приложение, которое зовут автоматизации | Результат долгой операции | Ограничения | Ошибки

Когда это нужно

Канал решает две задачи.

Внешняя система вызывает приложение. Интегратор или сервис заказчика получает ключ внешнего API и обращается к маршрутам приложения напрямую: платформа доставляет запрос приложению и возвращает ответ вызывающему как есть.

Приложение вызывает другое приложение. Двум приложениям одного портала не нужно договариваться о сетевом доступе и придумывать собственную аутентификацию: вызывающее приложение отправляет запрос по адресу платформы с ключом вызываемого.

Во внутренний контур портала канал не ходит: это ровно проброс до вашего кода. Запросы к данным Битрикс24 по-прежнему идут через Entity API.

Что включить на стороне приложения

Канал работает при трёх условиях.

  1. Переключатель «Внешний API» включён в карточке приложения. Он стоит в карточке приложения на платформе и принимает значения «Включён» и «Выключен». Управлять им может тот, кто управляет приложением.

  2. У приложения есть сервер. Без сервера включить переключатель нельзя, а вызов возвращает 409 APP_API_NO_SERVER.

  3. Сервер не засыпает — или работает по расписанию (см. ниже). Автоматический сон отключён, тариф сервера не вытесняемый, окна пробуждения не заданы. Иначе переключатель не включится, а вызов вернёт 409 APP_API_NOT_ALWAYS_ON. Как отключить авто-сон — Настроить авто-сон. У galaxy-приложения этот метод отвечает 400 GALAXY_APP_USE_GALAXY_ROUTE — таймер сна ему через API не задаётся, отключите авто-сон в кабинете, в карточке сервера приложения.

    Сервер в режиме «по расписанию» тоже подходит, если его тариф не вытесняемый. В окнах своего расписания работы он отвечает как обычно. Вне окон сервер спит, и вызов возвращает 409 APP_API_OUTSIDE_SCHEDULE с заголовком Retry-After — числом секунд до начала ближайшего окна; если срок вычислить нельзя (например, расписание сервера удалено), заголовка нет, и повтор по времени не поможет — проверьте расписание сервера. Запущенный сервер принимает вызов и вне окна. 503 APP_API_UNAVAILABLE получают сервер, пробуждение которого запрещено (например, приостановлено по оплате), и сервер, который не запущен и не спит вне окна: ещё просыпается к началу окна, остановлен, в ошибке или ещё создаётся. Переключатель у сервера по расписанию включается, пока сервер запущен и его пробуждение не запрещено.

    После конца окна сервер засыпает не сразу, а по простою. Пока он не уснул, вызовы проходят к приложению, и каждый такой вызов считается активностью: сервер работает дольше, и это время оплачивает владелец приложения.

Важно: включённый переключатель публикует весь HTTP-контур приложения держателям ключа. Отбора маршрутов на стороне платформы нет — держатель ключа может обратиться к любому пути приложения. Аутентификацию и разграничение доступа своих маршрутов приложение делает само: платформа оставляет для этого свободным заголовок Authorization и передаёт его приложению без изменений.

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

Ключ

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

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

Кто может выпустить. Владелец приложения либо администратор портала. Владельцем выпущенного ключа в обоих случаях становится владелец приложения — он же платит за вызовы.

Сколько ключей. До 10 действующих ключей на приложение. Одиннадцатый выпуск возвращает 409 APP_API_KEY_LIMIT с полями limit и used. Отзыв ключа освобождает место сразу. Срока жизни у ключа нет — он действует до отзыва, до выключения переключателя или до смены владельца приложения.

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

Ключ передаётся одним из двух заголовков, оба равноправны:

X-Api-Key: YOUR_APP_EXTERNAL_API_KEY
Authorization: Bearer YOUR_APP_EXTERNAL_API_KEY

Вторая форма нужна клиентам, которые умеют только Authorization. Если приложению нужен собственный Authorization, передавайте ключ платформы через X-Api-Key — тогда заголовок Authorization доедет до приложения нетронутым.

Адрес и методы

METHOD https://vibecode.bitrix24.tech/v1/applications/:applicationId/api/<путь в приложении>

Принимаются GET, POST, PUT, PATCH, DELETE и HEAD. Метод доезжает до приложения тем же, каким пришёл.

Параметр Тип Обяз. Описание
ПараметрapplicationId (path) Типstring Обяз.да ОписаниеИдентификатор приложения. Список: GET /v1/applications
Параметр<путь в приложении> (path) Типstring Обяз.нет ОписаниеВсё, что идёт после /api/, приложение получает как свой путь запроса. Пустой путь означает корень приложения. Предел длины — 2048 символов
Параметрстрока запроса Типstring Обяз.нет ОписаниеПередаётся приложению дословно, платформа её не разбирает

Что отбивается в пути. Путь проверяется и в исходном виде, и в однократно раскодированном, поэтому обход через процентное кодирование не проходит. Ответ 400 APP_API_BAD_PATH дают:

  • сегмент . или .. в любом месте, в том числе с параметром сегмента после точки с запятой
  • путь, начинающийся с // или с /@
  • обратный слэш
  • абсолютный адрес вместо пути
  • управляющие символы
  • битое процентное кодирование
  • символы вне набора, пригодного для пути, — их надо кодировать

Точки внутри сегмента законны: /files/report..v2 проезжает.

Что отбивается в строке запроса. Действует один набор допустимых символов по RFC 3986. Внутри значения параметра законны .., // и ;, а обратный слэш, пробел и всё за пределами набора обязаны приезжать в процентном кодировании. Иначе — тот же 400 APP_API_BAD_PATH.

Что получает приложение

Приложение получает исходный метод, путь после /api/, строку запроса и тело запроса без изменений.

К ним платформа добавляет заголовки, которые приложение не может получить ни от кого другого — входящие заголовки с префиксом X-Vibe- срезаются, поэтому подделать их вызывающий не может.

Заголовок Что несёт
ЗаголовокX-Vibe-Request-Id Что несётИдентификатор вызова. Тот же идентификатор платформа пишет в свой журнал — называйте его в обращении в поддержку
ЗаголовокX-Vibe-Caller-Kind Что несётВид вызывающего: external-api — вызов через этот канал, contract — вызов метода по контракту решения, у долгого метода он описан на странице Отправить результат долгого метода. Это и есть признак, по которому приложение отличает внешний вызов от открытия в интерфейсе Битрикс24
ЗаголовокX-Vibe-Caller-Portal-Id Что несётПортал, которому принадлежит ключ
ЗаголовокX-Vibe-Caller-Key-Id Что несётИдентификатор ключа, которым сделан вызов. Годится для журналирования и для разграничения доступа внутри приложения

Важно: заголовков X-Vibe-User-Id, X-Vibe-User-Name, X-Vibe-User-Role и X-Vibe-Authorization на этом пути нет. Они появляются только тогда, когда приложение открывает человек через интерфейс Битрикс24 и у него есть сессия — Что приходит в приложение. Внешний вызов сессии не несёт, поэтому пользовательская личность приложению недоступна: известен портал и ключ, но не сотрудник. Код, написанный по странице «Что приходит в приложение», на внешнем вызове увидит анонимного посетителя — читайте X-Vibe-Caller-Kind и расходитесь по ветвям.

Что срезается из запроса. Ключ платформы (X-Api-Key), Cookie, служебные заголовки соединения, Host, Content-Length и семейства заголовков доверия к прокси целиком: X-Forwarded, X-Original, X-Rewrite, CF, Fastly. Точечно срезаются имена, из которых стандартные библиотеки читают адрес клиента: Forwarded, X-Real-Ip, Client-Ip, X-Client-Ip, True-Client-Ip, X-Cluster-Client-Ip, Forwarded-For, Appengine-User-Ip, X-Appengine-User-Ip. Значение любого из них у внешнего вызова задаёт сам вызывающий, поэтому приложение его не получает и доверять адресу клиента на этом пути не может.

Authorization срезается по значению, а не по имени: платформа убирает его только тогда, когда там лежит её собственный ключ. Собственная схема приложения — Authorization: Bearer eyJ…, Basic, любая другая — доезжает без изменений.

Что возвращается вызывающему

Статус и тело ответа приложения передаются вызывающему как есть. Заголовки ответа тоже, кроме Set-Cookie, Content-Length, служебных заголовков соединения и заголовков с префиксом X-Vibe- — этот префикс на обоих направлениях принадлежит платформе.

Ответы 3xx передаются как есть — платформа по ним не переходит, решение принимает вызывающий.

Отказ платформы отличается от ответа приложения по заголовку X-Vibecode-Proxy-Error. Он стоит на каждом ответе, который построила платформа, и снимается ровно тогда, когда ответ пришёл от приложения. Приложение выставить его не может — из ответа приложения этот заголовок срезается.

Тело отказа платформы — конверт V1:

JSON
{
  "success": false,
  "error": {
    "code": "APP_API_NOT_ALWAYS_ON",
    "message": "Application API is not reachable"
  }
}

Поэтому разбирать ответ надо в таком порядке: сначала X-Vibecode-Proxy-Error, потом статус. Статус 503 с этим заголовком — отказ платформы, статус 503 без него — ответ самого приложения.

Ответ без этого заголовка и без конверта V1 — например HTML-страница с кодом 400 на запрос с двумя заголовками Content-Length — пришёл от промежуточного узла на пути к платформе, а не от неё и не от приложения.

Заголовок X-Vibe-Request-Id на ответе вызывающему стоит, когда вызов дошёл до туннеля приложения: на ответе приложения и на отказах, которые вернул сам туннель. На отказах до туннеля — ключ, переключатель, сервер, путь, размер тела, — на 503 APP_API_TIMEOUT и при насыщении канала идентификатора нет: в обращении в поддержку называйте applicationId и время вызова.

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда false — конверт приходит только на отказе платформы
Полеerror.code Типstring ОписаниеКод отказа из таблицы Ошибки
Полеerror.message Типstring ОписаниеАнглийское пояснение. Разбирайте error.code, не текст

Примеры

Оба примера показывают ключ внешнего API. Второй оси авторизации у этого адреса нет: личный ключ и ключ авторизации приложения возвращают 403 APP_API_NOT_GRANTED, потому что не привязаны к приложению.

curl — ключ внешнего API

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/applications/7f3a1c40-0a2e-4b5d-9c11-2f8e6d3b0a55/api/score" \
  -H "X-Api-Key: YOUR_APP_EXTERNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dealId": 741, "amount": 125000}'

JavaScript — ключ внешнего API

javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/applications/7f3a1c40-0a2e-4b5d-9c11-2f8e6d3b0a55/api/score',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_EXTERNAL_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ dealId: 741, amount: 125000 }),
  },
);

if (res.headers.get('x-vibecode-proxy-error') === '1') {
  const { error } = await res.json();
  throw new Error(`платформа отказала: ${error.code}`);
}

const data = await res.json();

Приложение, которое зовут автоматизации

Автоматизации — частый вызывающий, и у них свои привычки. Приложение, рассчитанное на автоматизации, придерживается трёх правил.

Принимайте и application/x-www-form-urlencoded, и JSON. Автоматизация, отправляющая HTTP-запрос, складывает значения полями формы и JSON не собирает. Приложение, которое читает только JSON, на таком вызове получит пустое тело. Разбирайте оба типа содержимого и сводите их к одной структуре.

Отвечайте плоским JSON. Автоматизация кладёт в переменные бизнес-процесса значения верхнего уровня, вложенные объекты и массивы ей недоступны. Ответ вида {"score": 82, "verdict": "approve"} разбирается автоматизацией целиком, а {"result": {"score": 82}} — нет.

Отдавайте GET /openapi.json со схемой своих маршрутов. Схема, выложенная приложением, доступна снаружи тем же каналом — по адресу …/api/openapi.json. Так вызывающая сторона — человек, другое приложение или AI-агент — узнаёт набор маршрутов и формы тел, не читая ваш код.

Результат долгой операции

Действие бизнес-процесса Битрикс24 «Выполнить решение Вайбкод» вызывает решение через этот канал. Операция контракта решения с x-vibe-async: true в окно вызова не укладывается, поэтому её результат приходит в процесс не ответом на вызов, а отдельным событием:

  1. Действие передаёт в запросе заголовок X-Bitrix24-Event-Token — токен своего шага. Платформа доставляет его приложению без изменений: в число срезаемых заголовков он не входит.
  2. Решение сохраняет токен вместе с задачей и отвечает 202 в пределах окна ответа приложения — 25 секунд. Шаг процесса после этого ждёт события.
  3. Закончив работу, решение вызывает POST /v1/workflows/event: в поле eventToken — токен из заголовка, в поле returnValues — результат, объект по схеме callbacks.result этой операции. Процесс продолжает работу.
  4. Пока события нет, шаг ждёт до своего таймаута. Значение по умолчанию действие берёт из x-vibe-timeout-seconds операции — целое число секунд от 60 до 86 400.

Событие отправляется ключом платформы, а не ключом вызова. Ключ внешнего API на POST /v1/workflows/event получает 403 APP_API_KEY_OUT_OF_SCOPE. Отвечает решение своим ключом vibe_api_… со скоупом bizproc: человек создаёт его и передаёт приложению переменной окружения при развёртывании, по соглашению VIBE_API_KEY. Требования к этому ключу и готовый обработчик — Долгий метод в бизнес-процессе.

Заголовков X-Vibe-Reply-Url и X-Vibe-Reply-Token на этом пути нет. Платформа ставит их только при вызове метода по контракту решения, и результат там уходит на маршрут Отправить результат долгого метода. Решение, которое в этом канале ждёт адрес ответа из заголовка, результат не отправит, и шаг процесса закончится по таймауту.

javascript
// Обработчик операции invoice.generate: принять задачу и ответить сразу.
app.post('/invoices', (req, res) => {
  const eventToken = req.headers['x-bitrix24-event-token'];
  queue.push({ eventToken, order: req.body }); // работа идёт после ответа
  res.status(202).json({ accepted: true });
});

// Работа закончена — результат уходит в процесс событием.
await fetch('https://vibecode.bitrix24.tech/v1/workflows/event', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.VIBE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    eventToken,
    returnValues: { invoiceNumber: 'A-17', url: 'https://example.com/invoices/A-17.pdf' },
  }),
});

Вызов из другого приложения

Вызывающему приложению нужен ключ вызываемого. Положите его в переменные окружения при развёртывании — POST /v1/infra/servers/:id/deploy — и читайте оттуда:

javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/applications/${process.env.PARTNER_APP_ID}/api/score`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.PARTNER_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ dealId: 741 }),
  },
);

На стороне вызываемого приложения такой запрос отличается от робота значением X-Vibe-Caller-Key-Id — заведите отдельный ключ под каждого вызывающего, и приложение сможет их различать.

Ограничения

Ограничение Значение
ОграничениеТело запроса Значение4 МиБ. Больше — 413 APP_API_PAYLOAD_TOO_LARGE
ОграничениеТело ответа приложения Значение4 МиБ. Больше — 502 APP_API_RESPONSE_TOO_LARGE без Retry-After: повтор такой ответ не исправит
ОграничениеВремя ответа приложения Значение25 секунд на ответ приложения. Дольше — 503 APP_API_UNAVAILABLE с Retry-After. Общий предел вызова — 30 секунд, за ним 503 APP_API_TIMEOUT
ОграничениеЧастота вызовов Значение120 запросов в минуту на ключ. Действующее значение — в заголовке x-ratelimit-limit. Больше — 429 APP_API_RATE_LIMITED
ОграничениеОдновременные вызовы ЗначениеКанал ограничивает число вызовов, идущих разом. При насыщении — 503 APP_API_UNAVAILABLE с Retry-After
ОграничениеДлина пути Значение2048 символов
ОграничениеДействующих ключей на приложение Значение10

Долгую работу выносите за пределы вызова: принимайте задачу, отвечайте 202 сразу и отправляйте результат событием процесса — Результат долгой операции. Двадцать пять секунд — это предел канала, а не рекомендация.

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

Ответ приложения передаётся как есть, поэтому его форму задаёт само приложение. Ответ приложения, написанного по конвенции для роботов:

JSON
{
  "score": 82,
  "verdict": "approve",
  "checkedAt": "2026-09-12T08:41:03Z"
}

Признак успеха — статус ответа и отсутствие заголовка X-Vibecode-Proxy-Error, а не поле success: обёртки платформы на успешном ответе нет.

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

409 — переключатель внешнего API выключен:

JSON
{
  "success": false,
  "error": {
    "code": "APP_API_NOT_ENABLED",
    "message": "Application API is not reachable"
  }
}

Текст message у отказов допуска один и тот же — Application API is not reachable — для APP_API_NOT_GRANTED, APP_API_NOT_ENABLED, APP_API_NO_SERVER, APP_API_NOT_ALWAYS_ON, APP_API_OUTSIDE_SCHEDULE и APP_API_UNAVAILABLE по серверу. Различайте их по error.code.

Ошибки

Каждый ответ из этой таблицы несёт заголовок X-Vibecode-Proxy-Error: 1.

HTTP Код Описание
HTTP400 КодAPP_API_BAD_PATH ОписаниеПуть или строка запроса не прошли проверку
HTTP401 КодMISSING_API_KEY ОписаниеЗаголовок с ключом не передан
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не существует или отозван
HTTP402 КодACCOUNT_FROZEN ОписаниеСчёт владельца приложения заморожен
HTTP403 КодAPP_API_NOT_GRANTED ОписаниеКлюч выпущен для другого приложения или не является ключом внешнего API
HTTP403 КодAPP_API_KEY_OUT_OF_SCOPE ОписаниеКлючом внешнего API вызван другой адрес платформы
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч переведён в режим чтения, а вызов изменяет данные
HTTP404 КодAPP_API_APP_NOT_FOUND ОписаниеПриложения с таким applicationId нет или оно удалено
HTTP409 КодAPP_API_NOT_ENABLED ОписаниеВнешний API приложения выключен
HTTP409 КодAPP_API_NO_SERVER ОписаниеУ приложения нет сервера
HTTP409 КодAPP_API_NOT_ALWAYS_ON ОписаниеСервер приложения засыпает — автосон, вытесняемый тариф или заданные окна пробуждения; у сервера по расписанию — только вытесняемый тариф
HTTP409 КодAPP_API_OUTSIDE_SCHEDULE ОписаниеСервер работает по расписанию и сейчас спит вне окна. Обычно приходит с Retry-After — числом секунд до начала ближайшего окна; если срок вычислить нельзя (например, расписание сервера удалено), заголовка нет, и повтор по времени не поможет — проверьте расписание сервера
HTTP413 КодAPP_API_PAYLOAD_TOO_LARGE ОписаниеТело запроса больше 4 МиБ
HTTP429 КодAPP_API_RATE_LIMITED ОписаниеПревышена частота вызовов на ключ
HTTP429 КодQUOTA_EXCEEDED ОписаниеИсчерпана квота вызовов владельца приложения
HTTP502 КодAPP_API_BAD_ENVELOPE ОписаниеПриложение ответило вне контракта — например статусом из диапазона 1xx
HTTP502 КодAPP_API_RESPONSE_TOO_LARGE ОписаниеОтвет приложения больше 4 МиБ. Retry-After не приходит
HTTP503 КодAPP_API_UNAVAILABLE ОписаниеСервер приложения не запущен или его пробуждение запрещено, приложение не отвечает, или канал насыщен. Приходит с Retry-After в секундах
HTTP503 КодAPP_API_TIMEOUT ОписаниеОтвет не пришёл за 30 секунд — общий предел вызова. Приходит с Retry-After в секундах

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

Ошибки выдачи ключа приходят на карточке приложения, а не на этом адресе: 409 APP_API_KEY_LIMIT — достигнут предел действующих ключей, 409 APP_API_KEY_ISSUE_CONFLICT — владелец приложения сменился, пока ключ выпускался.

Известные особенности

  • Без оговорок повторяются только 429 APP_API_RATE_LIMITED и 409 APP_API_OUTSIDE_SCHEDULE с заголовком Retry-After. Оба отказа приходят до передачи запроса приложению. Заголовок несёт срок в секундах. У APP_API_OUTSIDE_SCHEDULE это срок до начала рабочего окна сервера, и повтор раньше него получит тот же отказ. APP_API_OUTSIDE_SCHEDULE без заголовка повтором не лечится: срок вычислить нельзя (например, расписание сервера удалено) — проверьте расписание сервера. 502 повтором не лечится: он означает, что ответ приложения не укладывается в контракт канала.
  • 503 повторяйте только для идемпотентной операции. APP_API_UNAVAILABLE и APP_API_TIMEOUT приходят и тогда, когда запрос уже передан приложению: платформа перестала ждать ответ или соединение с приложением оборвалось. Приложение могло довести работу до конца, поэтому слепой повтор неидемпотентного вызова задваивает её. Статуса 504 этот адрес не отдаёт вовсе: медленное приложение приходит вызывающему как 503 — и когда платформа перестаёт ждать ответ на двадцать пятой секунде (APP_API_UNAVAILABLE), и когда вызов упирается в общий предел в тридцать секунд (APP_API_TIMEOUT). Увидели 504 на этом адресе — он пришёл не от канала, а от промежуточного узла на пути к платформе.
  • Причину 503 различает код, а не статус. APP_API_TIMEOUT означает ровно одно — приложение не ответило за общий предел вызова, и лечится это выносом долгой работы за пределы вызова. APP_API_UNAVAILABLE собирает под собой молчащий туннель, недоступный сервер и насыщенный канал: их вызывающему не различить, и для идемпотентной операции остаётся повтор через Retry-After. Разобрать причину можно по обращению в поддержку: с идентификатором из X-Vibe-Request-Id, если он на ответе есть, иначе — по applicationId и времени вызова.
  • Один шумный вызывающий отбирает канал у остальных. Доля одного портала ограничена, но эта доля — предел, а не резерв. Когда канал занят соседями, отказ 503 получает и тот, кто своей доли не выбрал.
  • Платит владелец вызываемого приложения. Вызовы расходуют его квоту, а всегда включённый сервер стоит денег независимо от числа вызовов. Вызывающая сторона за канал не платит.
  • Путь приложения в журнал платформы не попадает. Платформа пишет его длину, но не значение — секрет в пути не станет достоянием журнала. Это не разрешение класть туда секреты: путь видят и вызывающий, и промежуточные узлы.

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