Вайб-кодинг для Битрикс24: приложения и обработчики с агентом

Вайб кодинг для Битрикс24 звучит заманчиво: описали задачу словами, агент написал обработчик, а менеджеры получают задачу по каждой новой сделке. На деле такой код ломается в трёх местах: агент придумывает несуществующие методы REST, пишет запись в боевой портал без проверки и не учитывает лимиты. Ниже способ работать с агентом так, чтобы этих проблем не было: от выбора типа интеграции до тестов и расчёта стоимости сессии.

Факты о REST API Битрикс24 ниже сверены с официальной документацией (apidocs.bitrix24.com) на 18 октября 2026. Названия пунктов интерфейса там английские, в русской версии портала сверьтесь с реальными. Что такое вайб-кодинг вообще и сколько стоит час работы агента, мы писали в статье Вайб-кодинг: что это и сколько стоит↗.

Сначала выберите тип интеграции

Агенту нужно сказать, что именно строить. В документации Битрикс24 есть сравнение инструментов для локальных решений, вот его суть:

Большинство «хочу, чтобы по новой сделке создавалась задача» решается связкой исходящего вебхука и входящего: событие приходит в ваш обработчик, обработчик вызывает REST. Приложение нужно, когда у решения есть интерфейс или оно работает для разных пользователей. В документации есть и отдельная оговорка: часть методов через вебхуки недоступна (встраивание в интерфейс, события телефонии, часть событий чат-ботов), для них нужно локальное приложение.

Вайб кодинг Битрикс24: подготовьте агента

Первое: подключите агенту документацию. У Битрикс24 есть официальный MCP-сервер документации (https://mcp-dev.bitrix24.com/mcp, без авторизации), он нужен, чтобы модель находила настоящие методы и поля. Он только отдаёт документацию и не видит данных портала. В Claude Code подключение такое:

claude mcp add --transport http b24-dev-mcp https://mcp-dev.bitrix24.com/mcp

Второе: положите в корень проекта файл правил (CLAUDE.md для Claude Code, AGENTS.md для opencode и Codex). Не больше десятка строк, но каждая заменяет ошибку:

Правила проекта: интеграция с Битрикс24
- Прежде чем вызывать метод REST, найди его описание через MCP b24-dev-mcp. Не придумывай методы и поля.
- Адрес вебхука читай только из переменной B24_WEBHOOK. В код, логи и коммиты его не записывать.
- Методы записи (add, update, delete) запускать только против тестового портала (B24_ENV=test).
- Списки читать постранично, между запросами пауза 0,5 с. Не больше 50 записей за вызов.
- К каждой функции, которая ходит в REST, писать тест с подменой HTTP.

Третье: заведите тестовый портал или хотя бы отдельную воронку, а вебхук создайте от пользователя с ограниченной ролью. Запросы вебхука выполняются с правами создавшего его сотрудника, поэтому вебхук администратора даёт агенту права администратора. Как создать вебхук и подключить к порталу нейросеть, мы разбирали в статье интеграция нейросети в Bitrix24↗; здесь важно одно: секрет вебхука нельзя показывать и встраивать в публичный код.

Пример: обработчик события «новая сделка»

Исходящий вебхук отправляет событие на ваш URL. В документации по событиям есть два ограничения, которые обязательно нужно знать агенту. Нагрузка не регулируется: если за раз изменить тысячу сделок, обработчик получит тысячу вызовов. Повторов нет: если сервер не ответил или вернул ошибку, Битрикс24 запишет сбой и не отправит событие повторно. Для критичных случаев предусмотрены офлайн-события, которые забираются из очереди вручную, но, по документации, они доступны только приложению (подписка через event.bind), а не исходящему вебхуку. Кроме того, токены авторизации передаются не всегда, поэтому содержимое ключа auth проверяют в коде.

Обработчик на FastAPI (нужен пакет python-multipart для разбора формы):

import os
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks

app = FastAPI()
APP_TOKEN = os.environ["B24_APP_TOKEN"]


def make_task(deal_id: str) -> None:
    ...  # здесь вызов tasks.task.add через входящий вебхук


@app.post("/b24/events")
async def events(request: Request, background: BackgroundTasks):
    form = await request.form()
    token = form.get("auth[application_token]") or form.get("application_token")
    if token != APP_TOKEN:
        raise HTTPException(status_code=403)
    if form.get("event") == "ONCRMDEALADD":
        background.add_task(make_task, form.get("data[FIELDS][ID]"))
    return {"ok": True}

Имена полей формы и вид токена проверьте по первому реальному запросу: логируйте ключи формы (без значений токена) и сверьте с разделом событий документации. Принцип такой: быстро отвечать 200 и обрабатывать в фоне, чтобы очередь не копилась и события не терялись.

Для серверного приложения обработчик должен быть доступен по HTTPS, поэтому при локальной разработке нужен туннель до вашей машины или тестовый сервер. Конкретный инструмент подберите сами, это уже вне Битрикс24.

Чтение больших списков и лимиты

Методы *.list отдают по 50 записей и указывают в ответе next. Для агента, который пишет выгрузку, это основной шаблон:

import time
import requests


def iter_deals(webhook: str, pause: float = 0.5):
    start = 0
    while start is not None:
        r = requests.post(
            f"{webhook}/crm.deal.list.json",
            json={"select": ["ID", "TITLE", "STAGE_ID"], "start": start},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        yield from data["result"]
        start = data.get("next")
        if start is not None:
            time.sleep(pause)

Пауза не случайна. В облачной версии действует ограничение частоты по принципу «дырявого ведра»: по документации, на тарифах кроме Enterprise 2 запроса в секунду и порог 50, при превышении приходит 503 с кодом QUERY_LIMIT_EXCEEDED. Один запрос должен завершиться за 60 секунд. Чтобы сократить число HTTP-запросов, документация предлагает метод batch, в котором можно передать до 50 вызовов.

Проверка: тест с подменой HTTP

Попросите агента писать тесты вместе с кодом. Для функции выше:

import b24


class FakeResponse:
    def __init__(self, data):
        self.data = data

    def raise_for_status(self):
        pass

    def json(self):
        return self.data


def test_pagination(monkeypatch):
    pages = [{"result": [{"ID": "1"}], "next": 50}, {"result": [{"ID": "2"}]}]
    monkeypatch.setattr(b24.requests, "post", lambda url, json, timeout: FakeResponse(pages.pop(0)))
    ids = [d["ID"] for d in b24.iter_deals("https://x/rest/1/code", pause=0)]
    assert ids == ["1", "2"]

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

Если хочется обойтись вообще без собственного кода и хостинга, Битрикс24 в документации упоминает сервис Alaio Vibecode, который сам разворачивает приложение. Условия и возможности смотрите у него, мы их не проверяли.

Модель и стоимость сессии

Допустим, на приложение уходит сессия в 1,5 млн токенов входа и 150 тыс. выхода. Цены Zukko на 18 октября 2026, $ за 1M токенов.

• claude-sonnet-5-5 (0.4 / 2), без кэша: 1.5 × 0.4 + 0.15 × 2 = 0.6 + 0.3 = $0.90.
• Он же в Claude Code с кэшем (Anthropic-формат): 0.2 млн свежего входа, 1.2 млн чтения кэша, 0.1 млн записи, 0.15 млн выхода. 0.2 × 0.4 + 1.2 × 0.05 + 0.1 × 0.5 + 0.15 × 2 = 0.08 + 0.06 + 0.05 + 0.3 = $0.49.
• gpt-6.1-sol (0.27 / 1.32), без кэша: 1.5 × 0.27 + 0.15 × 1.32 = 0.405 + 0.198 ≈ $0.60.
• deepseek-v4.1-flash (0.013 / 0.038), без кэша: 1.5 × 0.013 + 0.15 × 0.038 = 0.0195 + 0.0057 ≈ $0.03.

Разбивка по кэшу условная, у вас она будет другой. Какая модель аккуратнее с REST, проверьте на небольшой задаче. Claude Code подключается переменными ANTHROPIC_BASE_URL=https://api.zukko.pro и ANTHROPIC_AUTH_TOKEN=fetch_..., см. документацию↗. Ключ создайте на странице API-ключей↗ и поставьте дневной лимит.

Частые вопросы

Можно ли доверить агенту писать в боевой портал?

Только после прогона на тестовом портале и с пользователем ограниченной роли. Методы удаления лучше вообще не генерировать.

Чем вебхук отличается от приложения?

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

Почему агент придумывает методы Битрикс24?

Без документации под рукой модель опирается на память. Подключите MCP-сервер документации и потребуйте в правилах проекта сверяться с ним.

Что делать, если обработчик не получил событие?

Повторов Битрикс24 не делает. Для критичных данных используйте офлайн-события (для этого нужно приложение, а не исходящий вебхук) или периодическую сверку через *.list.