bitrix24-crm-api

Битрикс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 отстаёт.