bitrix24-crm-api
Безопасное подключение к Битрикс24 через входящий вебхук или локальное приложение: чтение лидов, сделок, воронок, стадий, источников, UTM, звонков и истории стадий, сверка с Яндекс Директом и Метрикой, атрибуция обращений, запись только по плану и разрешению владельца. Использовать вместо amoCRM/Roistat, когда CRM клиента — Битрикс24.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- bitrix24-crm-api
- description
- Безопасное подключение к Битрикс24 через входящий вебхук или локальное приложение: чтение лидов, сделок, воронок, стадий, источников, UTM, звонков и истории стадий, сверка с Яндекс Директом и Метрикой, атрибуция обращений, запись только по плану и разрешению владельца. Использовать вместо amoCRM/Roistat, когда CRM клиента — Битрикс24.
02 资源文件 3
- 参考文档agents/openai.yaml454 B
- 脚本scripts/bitrix24_read.py14.0 KB
- 脚本tests/test_bitrix24_read.py9.0 KB
03 SKILL.md 正文
Битрикс24: CRM через REST
Граница задачи
Навык читает CRM клиента и сверяет её с рекламой. Запись (создание, изменение, удаление лидов, сделок, полей, стадий, вебхуков) — только по отдельному плану, с точным списком полей, «да» владельца и чтением после записи. Реклама, цели, ставки и кампании меняются только навыком yandex-direct-unified.
Доступ
- Берёт адрес из переменной
BITRIX24_WEBHOOK_URL(видhttps://<портал>/rest/<id_пользователя>/<код>/) или из закрытого JSON с правами0600. Адрес и код никогда не печатай, не передавай аргументом командной строки и не клади в журнал, отчёт и репозиторий. - Вебхук действует от имени сотрудника, который его создал, и в рамках выбранных скоупов. Создаёт администратор или сотрудник с разрешением администратора. Для чтения достаточно скоупа
crm; имена сотрудников требуютuser; статистика звонков (voximplant.statistic.get) требуетtelephonyи право «Статистика звонков — Просмотр». Если на ответеinsufficient_scope, не повторяй запрос: попроси отдельный вебхук с нужным скоупом (переменнаяBITRIX24_TELEPHONY_WEBHOOK_URL) или используй локальное приложение. - Часть методов (например, привязка виджетов, часть телефонии) недоступна из вебхука и требует контекста приложения. Для нескольких порталов, событий и методов с контекстом создай локальное приложение (OAuth 2.0:
access_tokenживёт 1 час,refresh_token180 дней; код авторизации 30 секунд) и храни токены в файле0600. - Новый вебхук или приложение создаёт только владелец или по его явному «да». Перед этим проверь, нет ли уже подходящего. Срок действия вебхука может быть ограничен: при ошибке авторизации сначала проверь его.
- Файлы доступа и выгрузки (в них телефоны и имена) держи в закрытой папке, добавь её в
.gitignore, в отчётах и чатах телефоны маскируй.
Режим чтения
- Скрипт
scripts/bitrix24_read.py(командыprobe,schema,export) вызывает только методы из белого списка:crm.item.list,crm.item.fields,crm.lead.list,crm.deal.list,crm.lead.fields,crm.lead.userfield.list,crm.status.list,crm.status.entity.types,crm.category.list,crm.dealcategory.list,crm.stagehistory.list,crm.activity.list,crm.contact.list,voximplant.statistic.get,user.get,scope,batch(только с чтением внутри). Любой другой метод — отказ. - Основной путь —
crm.item.list(entityTypeId: лид 1, сделка 2, контакт 3, компания 4).crm.lead.listиcrm.deal.listпомечены в документации как устаревшие; используй их только когда поле недоступно вcrm.item.list. - Страница списка всегда 50 записей. Малые выборки — через
start/next. Большие выгрузки — обход по ID: сортировкаIDпо возрастанию, в фильтре>IDпоследнего полученного,start=-1, повтор пока вернулось 50. Для этого режимаtotalне приходит: объём считай отдельным запросом. - Множественные поля (
PHONE,EMAIL) перечисляй вselectявно; маска*их и пользовательские поля не включает, добавляйUF_*. Поля UTM (UTM_SOURCE,UTM_MEDIUM,UTM_CAMPAIGN,UTM_CONTENT,UTM_TERM) называй вselectявно; вcrm.item.listсверь их имена черезcrm.item.fields. - В фильтре
ENTITY_IDиSTATUS_IDсправочников передавай строкой. Префиксы:>=,>,<=,<,@(IN, массив),!@,%,=,!=. - Лимиты (облако): для тарифа «Энтерпрайз» 5 запросов в секунду при пороге 250, для остальных 2 в секунду при пороге 50; превышение — HTTP 503
QUERY_LIMIT_EXCEEDED; ресурсоёмкость — HTTP 429OPERATION_TIME_LIMIT(ориентирoperating_reset_atв блокеtime). Держи не больше одного потока, паузу между запросами не меньше 0,5 с, при 503/429 повторяй с растущей паузой, не запускай параллельные серии с того же IP.batch— до 50 команд, вложенныйbatchзапрещён, ошибки команд лежат вresult_errorпри ответе 200. - Каждая выгрузка сохраняет манифест: метод, фильтр, период, число строк, число уникальных ID, число страниц, признак
complete, время начала и конца. Повтор или отсутствие ID в выгрузке — ошибка;IDскрипт добавляет в поля сам. В файл попадают только объявленные поля (--fieldsили набор по умолчанию), даже если метод вернул больше. Телефоны, почта и имена сохраняются только с--include-personal-dataи только если названы в--fields. Неполную выгрузку (complete=false) не превращай в отчёт. - Время: даты REST приходят в часовом поясе портала. Переводи всё в UTC и записывай границу периода с поясом; Метрика считает в поясе счётчика, копия данных BI отстаёт.
Что прочитать перед вопросами клиенту
- Все воронки сделок (
crm.category.listсentityTypeId=2; основная воронка имеетid=0) и стадии каждой черезcrm.status.list; семантика стадии:Sуспех,Fпровал, пусто илиPв работе. - Статусы лидов, справочник источников, пользовательские поля лидов и сделок, историю стадий (
crm.stagehistory.list,TYPE_ID: 1 создание, 2 промежуточная, 3 финальная, 5 смена воронки). - Какие формы и интеграции уже заводят лиды: штатные веб-формы CRM и установленные приложения интеграции форм. Пока не прочитано, не пиши «форма не подключена» и не включай второй отправитель.
- Только после этого спрашивай клиента о том, чего в CRM нет.
Атрибуция обращений
Порядок источников для лида, строго в таком порядке:
- Точная метка:
UTM_SOURCE(yandex; вариантyaпринимай только приUTM_MEDIUM=cpcи числовой кампании, существующей в выгрузке Директа),UTM_MEDIUM=cpc,UTM_CAMPAIGNравен идентификатору кампании Директа;UTM_CONTENTравен идентификатору объявления,yclid— подтверждение клика. Совпадение только точное, без подбора по похожести. - Номер коллтрекинга: ближайший к созданию лида входящий звонок (
CALL_TYPE2 или 3), связанный с лидом прямо (CRM_ENTITY_TYPE=LEAD) или через дело звонка с владельцем-лидом, разница не больше 300 секунд, совпадение номеров с картой источников, единственный кандидат. Окно не расширяй: большие окна переносят исходящие лиды во входящие. - Иначе источник из подписи CRM с префиксом «CRM:».
Дополнительные правила:
- Общий (основной) номер организации не является рекламной связью.
- Если оператор набрал номер без открытой карточки, телефония сама заводит лид (
CALL_TYPE=1в пределах нескольких секунд от создания): выдели такие лиды в отдельный источник «Исходящий звонок оператора», не называй их «не реклама» (первичный источник пациента не записан) и не считай в стоимости обращения. - Заявка без метки —
unknown, не органика. Источник доказывает только ClientID Метрики из карточки (визит в Метрике до заявки). Сопоставление «по времени цели» годится для разовой оценки и помечается как оценка. - ClientID со значением
0не связь с Метрикой. Отсутствие согласия на аналитику даёт пустое значение. - Тестовые и служебные записи отфильтровывай одним и тем же условием во всех выборках (пользовательские поля «тест», «служебная форма», имя «Тест»). Новые тестовые лиды без разрешения владельца не создавай.
- Единица счёта — карточка лида. Повторные карточки одного телефона показывай отдельной строкой («уникальных телефонов»), первичный источник клиента — отдельным столбцом.
- Удалённые лиды в выгрузке не видны; звонки на рекламные номера бери из статистики звонков отдельным показателем и не складывай с лидами.
Сверка с Директом и Метрикой
- Расход, показы, клики и кампании читай навыком
yandex-direct-unified(илиyd_*MCP), цели и визиты —ym_*. Не вызывай их API из этого навыка. - Сопоставляй по числовым идентификаторам кампаний и объявлений. Таблица должна показывать три числа по каждой кампании: конверсии цели в Метрике/Директе, лиды CRM с точной меткой, лиды CRM по номеру коллтрекинга.
- Расхождение между конверсиями рекламы и лидами CRM ожидаемо (заявка без метки, звонок без согласия, окно атрибуции). Назови причину по доказательствам: ClientID, метка, звонок, время. Нулевой результат в отчёте не доказывает отсутствие обращений.
- Воронка: стадия «записан» не равна явке; успешная сделка не равна оплате; выручка привязана к дате создания лида или к дате закрытия, укажи, к какой. Проверь двойные сделки на одну сумму.
- НДС: перед любой арифметикой с расходом проверь признак НДС источника (расход, полученный штатным коннектором рекламной аналитики Битрикс24, приходит с НДС). Неподтверждённый коэффициент не добавляй.
Запись
Любая запись требует: плана с точным списком сущностей и полей, «да» владельца на этот план, снимка полей «до» в закрытой папке, записи только перечисленных полей, чтения после записи с сопоставлением, журнала с откатом. Запрещено без отдельного «да»: создание и удаление лидов и сделок, смена стадий, изменение пользовательских полей, создание вебхуков и приложений, массовые изменения. Ответ HTTP 500 или таймаут на записи означает «исход неизвестен»: перечитай запись, а не повторяй вызов вслепую. Создание пользовательских полей — только отдельным скриптом с режимом без --apply (печатает план); в наборе записывающих скриптов нет.
Ловушки
- Лид может сразу конвертироваться в сделку: ищите обращение и по сделке (
crm.deal.listс фильтром@LEAD_ID), а не только по лиду. - Повторное сообщение существующего контакта новый лид не создаёт: повторные обращения ищите по контакту; дубли по телефону —
crm.duplicate.findbycommсtype: PHONE. - Общая форма сайта может присылать лиды вебхуком без меток: смотрите поля формы, а не только
UTM_*. - Чаты открытых линий:
imopenlines.crm.chat.getLastId(CRM_ENTITY_TYPE:LEAD,DEAL,CONTACT) отдаёт только последний чат сущности — для периода перебирайте все сущности; сообщения —im.dialog.messages.getсDIALOG_IDвидаchat<id>. Метка запуска бота (/start <метка>) видна в сообщениях чата; ссылка мессенджера без метки к рекламе не привязывается. - Поля, которые дописывает фоновая интеграция аналитики, появляются через несколько минут после создания лида.
- «Группа номеров» в описании источника — группа номеров АТС, а не коллтрекинг.
- Роботы и бизнес-процессы лидов не трогайте.
- Цепочку коллтрекинга (пул подменных номеров → скрипт сайта → приёмник звонков → карта номеров в BI) включайте с конца: пул номеров — последним, после всех потребителей.
- Без вебхука в браузере, где пользователь уже вошёл в портал, те же методы доступны из вкладки через
BX.rest.callMethod(права — этого пользователя). Значения форм, вебхуков и токенов из вкладки целиком не выгружайте.
Сбои
insufficient_scope: нужен другой скоуп, не повторяй запрос.INVALID_CREDENTIALS,NO_AUTH_FOUND: проверь ID пользователя и код вебхука в адресе; у вебхука мог истечь срок.ACCESS_DENIED«REST is available only on commercial plans»: REST недоступен на текущем тарифе.expired_token: продли токены приложения и повтори вызов.ERROR_METHOD_NOT_FOUND: опечатка в методе или нет скоупа.
Граница публикации
Не публикуй адреса порталов, коды вебхуков, ID пользователей, телефоны, имена, названия кампаний клиента и выгрузки. Публичные примеры и тесты — только синтетические.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.