AGENT SKILL

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

03 SKILL.md 正文

Битрикс24: CRM через REST

Граница задачи

Навык читает CRM клиента и сверяет её с рекламой. Запись (создание, изменение, удаление лидов, сделок, полей, стадий, вебхуков) — только по отдельному плану, с точным списком полей, «да» владельца и чтением после записи. Реклама, цели, ставки и кампании меняются только навыком yandex-direct-unified.

Доступ

  1. Берёт адрес из переменной BITRIX24_WEBHOOK_URL (вид https://<портал>/rest/<id_пользователя>/<код>/) или из закрытого JSON с правами 0600. Адрес и код никогда не печатай, не передавай аргументом командной строки и не клади в журнал, отчёт и репозиторий.
  2. Вебхук действует от имени сотрудника, который его создал, и в рамках выбранных скоупов. Создаёт администратор или сотрудник с разрешением администратора. Для чтения достаточно скоупа crm; имена сотрудников требуют user; статистика звонков (voximplant.statistic.get) требует telephony и право «Статистика звонков — Просмотр». Если на ответе insufficient_scope, не повторяй запрос: попроси отдельный вебхук с нужным скоупом (переменная BITRIX24_TELEPHONY_WEBHOOK_URL) или используй локальное приложение.
  3. Часть методов (например, привязка виджетов, часть телефонии) недоступна из вебхука и требует контекста приложения. Для нескольких порталов, событий и методов с контекстом создай локальное приложение (OAuth 2.0: access_token живёт 1 час, refresh_token 180 дней; код авторизации 30 секунд) и храни токены в файле 0600.
  4. Новый вебхук или приложение создаёт только владелец или по его явному «да». Перед этим проверь, нет ли уже подходящего. Срок действия вебхука может быть ограничен: при ошибке авторизации сначала проверь его.
  5. Файлы доступа и выгрузки (в них телефоны и имена) держи в закрытой папке, добавь её в .gitignore, в отчётах и чатах телефоны маскируй.

Режим чтения

  1. Скрипт 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 (только с чтением внутри). Любой другой метод — отказ.
  2. Основной путь — crm.item.list (entityTypeId: лид 1, сделка 2, контакт 3, компания 4). crm.lead.list и crm.deal.list помечены в документации как устаревшие; используй их только когда поле недоступно в crm.item.list.
  3. Страница списка всегда 50 записей. Малые выборки — через start/next. Большие выгрузки — обход по ID: сортировка ID по возрастанию, в фильтре >ID последнего полученного, start=-1, повтор пока вернулось 50. Для этого режима total не приходит: объём считай отдельным запросом.
  4. Множественные поля (PHONE, EMAIL) перечисляй в select явно; маска * их и пользовательские поля не включает, добавляй UF_*. Поля UTM (UTM_SOURCE, UTM_MEDIUM, UTM_CAMPAIGN, UTM_CONTENT, UTM_TERM) называй в select явно; в crm.item.list сверь их имена через crm.item.fields.
  5. В фильтре ENTITY_ID и STATUS_ID справочников передавай строкой. Префиксы: >=, >, <=, <, @ (IN, массив), !@, %, =, !=.
  6. Лимиты (облако): для тарифа «Энтерпрайз» 5 запросов в секунду при пороге 250, для остальных 2 в секунду при пороге 50; превышение — HTTP 503 QUERY_LIMIT_EXCEEDED; ресурсоёмкость — HTTP 429 OPERATION_TIME_LIMIT (ориентир operating_reset_at в блоке time). Держи не больше одного потока, паузу между запросами не меньше 0,5 с, при 503/429 повторяй с растущей паузой, не запускай параллельные серии с того же IP. batch — до 50 команд, вложенный batch запрещён, ошибки команд лежат в result_error при ответе 200.
  7. Каждая выгрузка сохраняет манифест: метод, фильтр, период, число строк, число уникальных ID, число страниц, признак complete, время начала и конца. Повтор или отсутствие ID в выгрузке — ошибка; ID скрипт добавляет в поля сам. В файл попадают только объявленные поля (--fields или набор по умолчанию), даже если метод вернул больше. Телефоны, почта и имена сохраняются только с --include-personal-data и только если названы в --fields. Неполную выгрузку (complete=false) не превращай в отчёт.
  8. Время: даты REST приходят в часовом поясе портала. Переводи всё в UTC и записывай границу периода с поясом; Метрика считает в поясе счётчика, копия данных BI отстаёт.

Что прочитать перед вопросами клиенту

  1. Все воронки сделок (crm.category.list с entityTypeId=2; основная воронка имеет id=0) и стадии каждой через crm.status.list; семантика стадии: S успех, F провал, пусто или P в работе.
  2. Статусы лидов, справочник источников, пользовательские поля лидов и сделок, историю стадий (crm.stagehistory.list, TYPE_ID: 1 создание, 2 промежуточная, 3 финальная, 5 смена воронки).
  3. Какие формы и интеграции уже заводят лиды: штатные веб-формы CRM и установленные приложения интеграции форм. Пока не прочитано, не пиши «форма не подключена» и не включай второй отправитель.
  4. Только после этого спрашивай клиента о том, чего в CRM нет.

Атрибуция обращений

Порядок источников для лида, строго в таком порядке:

  1. Точная метка: UTM_SOURCE (yandex; вариант ya принимай только при UTM_MEDIUM=cpc и числовой кампании, существующей в выгрузке Директа), UTM_MEDIUM=cpc, UTM_CAMPAIGN равен идентификатору кампании Директа; UTM_CONTENT равен идентификатору объявления, yclid — подтверждение клика. Совпадение только точное, без подбора по похожести.
  2. Номер коллтрекинга: ближайший к созданию лида входящий звонок (CALL_TYPE 2 или 3), связанный с лидом прямо (CRM_ENTITY_TYPE=LEAD) или через дело звонка с владельцем-лидом, разница не больше 300 секунд, совпадение номеров с картой источников, единственный кандидат. Окно не расширяй: большие окна переносят исходящие лиды во входящие.
  3. Иначе источник из подписи CRM с префиксом «CRM:».

Дополнительные правила:

  • Общий (основной) номер организации не является рекламной связью.
  • Если оператор набрал номер без открытой карточки, телефония сама заводит лид (CALL_TYPE=1 в пределах нескольких секунд от создания): выдели такие лиды в отдельный источник «Исходящий звонок оператора», не называй их «не реклама» (первичный источник пациента не записан) и не считай в стоимости обращения.
  • Заявка без метки — unknown, не органика. Источник доказывает только ClientID Метрики из карточки (визит в Метрике до заявки). Сопоставление «по времени цели» годится для разовой оценки и помечается как оценка.
  • ClientID со значением 0 не связь с Метрикой. Отсутствие согласия на аналитику даёт пустое значение.
  • Тестовые и служебные записи отфильтровывай одним и тем же условием во всех выборках (пользовательские поля «тест», «служебная форма», имя «Тест»). Новые тестовые лиды без разрешения владельца не создавай.
  • Единица счёта — карточка лида. Повторные карточки одного телефона показывай отдельной строкой («уникальных телефонов»), первичный источник клиента — отдельным столбцом.
  • Удалённые лиды в выгрузке не видны; звонки на рекламные номера бери из статистики звонков отдельным показателем и не складывай с лидами.

Сверка с Директом и Метрикой

  1. Расход, показы, клики и кампании читай навыком yandex-direct-unified (или yd_* MCP), цели и визиты — ym_*. Не вызывай их API из этого навыка.
  2. Сопоставляй по числовым идентификаторам кампаний и объявлений. Таблица должна показывать три числа по каждой кампании: конверсии цели в Метрике/Директе, лиды CRM с точной меткой, лиды CRM по номеру коллтрекинга.
  3. Расхождение между конверсиями рекламы и лидами CRM ожидаемо (заявка без метки, звонок без согласия, окно атрибуции). Назови причину по доказательствам: ClientID, метка, звонок, время. Нулевой результат в отчёте не доказывает отсутствие обращений.
  4. Воронка: стадия «записан» не равна явке; успешная сделка не равна оплате; выручка привязана к дате создания лида или к дате закрытия, укажи, к какой. Проверь двойные сделки на одну сумму.
  5. НДС: перед любой арифметикой с расходом проверь признак НДС источника (расход, полученный штатным коннектором рекламной аналитики Битрикс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

hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k