Привет! Меня зовут Роман Льдоков. Я занимаюсь разработкой интеграций и решений на базе Битрикс24 с использованием Python и ИИ-технологий в компании IT-Solution.
В этой статье я расскажу о том, как мы разрабатывали Python SDK для работы с REST API Битрикс24, поделюсь подходом к его проектированию и автоматизации с использованием ИИ и MCP-сервера, а также покажу, какие задачи решает эта библиотека и как она упрощает разработку интеграций.
Создание собственных приложений и интеграций для Битрикс24 остаётся востребованной задачей. Однако на практике разработчики сталкиваются с рядом системных сложностей, которые замедляют разработку и повышают порог входа.
Ключевая из них — работа с обширным REST API, насчитывающим более 1200 методов. Каждый из них имеет собственный набор параметров, форматов передачи данных и особенностей поведения. Для разработчиков на PHP и JavaScript существуют официальные SDK: они берут на себя рутинную работу с API, снижают вероятность ошибок и позволяют сосредоточиться на бизнес-логике, а не на технических деталях взаимодействия с платформой.
Тем, кто использует другие языки, до недавнего времени везло меньше. Им приходилось практически постоянно обращаться к документации, чтобы уточнить параметры, формат запросов и допустимые значения. Даже при работе с уже знакомыми методами это замедляет разработку и увеличивает вероятность ошибок.
Мы в своей практике активно используем Python, и эта проблема напрямую касалась нас. В какой-то момент мы решили закрыть её системно — и разработали собственный SDK для работы с Битрикс24, который стал официальной библиотекой.
В этой статье мы расскажем, какие задачи решает эта библиотека и как мы создавали её с использованием ИИ и MCP-сервера Битрикс24 для разработчиков. Материал получился объемным, поэтому мы добавили оглавление:
Часть 1. Как SDK решает ключевые проблемы разработки
Основные возможности использования SDK
Главная идея SDK — предоставить разработчику удобный Python-интерфейс поверх REST API. Вместо последовательности действий вида «собрать URL → сформировать параметры → отправить POST-запрос → распарсить ответ» остается простой и понятный вызов метода:
from b24pysdk import Client, BitrixWebhook
client = Client(
BitrixWebhook(
domain="example.bitrix24.ru",
webhook_token="user_id/webhook_key",
)
)
deal = client.crm.deal.get(bitrix_id=2).result
print(deal)При таком подходе разработчику не нужно вручную формировать HTTP-запросы, следить за базовым URL и запоминать названия методов REST API. Это делает код более читаемым и снижает вероятность ошибок.
SDK предоставляет предсказуемую структуру и поддерживает подсказки IDE. Разработчик может сразу видеть список доступных методов для конкретной сущности и использовать автодополнение.
Работа с параметрами также упрощается за счёт встроенных проверок — как на этапе написания кода, так и во время выполнения. SDK проверяет наличие обязательных параметров, типы данных (на базовом уровне), а также предлагает допустимые значения, если они ограничены. Кроме того, методы снабжены docstring’ами и комментариями, которые помогают понять их назначение и способ использования. В случае ошибки валидации выбрасывается исключение с понятным описанием причины.
Вызов методов и передача параметров унифицированы для всех используемых скоупов. Это позволяет не учитывать различия между методами REST API и не задумываться о способах передачи параметров.
Работа с большим объемом данных
При работе со списочными методами необходимо учитывать ограничения API: REST API Битрикс24 возвращает не более 50 записей за один запрос. Разработчику приходится помнить об этом лимите, писать циклы для обхода страниц и аккуратно агрегировать результаты. Это усложняет код и увеличивает вероятность ошибок.
В SDK работа с пагинацией реализована “под капотом”, полностью снимая эту задачу с разработчика. В результате типовой сценарий работы со списочными методами выглядит так:
request = client.crm.lead.list(
select=["ID","TITLE"],
filter={
"<=OPPORTUNITY":20000,
"IS_MANUAL_OPPORTUNITY":"Y",
},
order={
"TITLE":"ASC",
},
).as_list(limit=50)
for deal in request.result:
print(deal["TITLE"])Также доступен “ленивый” вариант с генератором — когда нет необходимости загружать все данные в память сразу (например, при больших выгрузках):
request = client.crm.deal.list().as_list_fast(descending=True)
for deal in request.result:
print(deal["TITLE"])Под капотом SDK использует стандартный механизм постраничного обхода, описанный в документации Битрикс24.
Batch-запросы и производительность
При работе с большим количеством операций выполнение отдельных REST-запросов для каждой операции приводит к проблемам с производительностью и превышением лимитов REST API.
SDK решает эту задачу за счет встроенной поддержки batch-запросов на двух уровнях:
-
call_batch()— для выполнения до 50 подзапросов за один вызов; -
call batches()— для больших объёмов; SDK автоматически разбивает запросы на группы и выполняет их последовательно.
Оба метода поддерживают передачу запросов:
-
по ключам (в виде словаря);
-
в виде последовательности.
Пример: формирование batch-запроса на создание компаний:
requests_data = {
"company1": client.crm.company.add(
fields={...},
),
"company2": client.crm.company.add(
fields={...},
),
# еще записи
}
batch_request = client.call_batch(methods=requests_data, ignore_size_limit=True)
for key, company in batch_request.result.result.items():
print(f"{key}: {company['ID']}")Если количество запросов превышает лимит:
requests = [
client.crm.activity.update(bitrix_id=1, fields={"RESPONSIBLE_ID":1}),
client.crm.activity.update(bitrix_id=2, fields={"RESPONSIBLE_ID":1}),
# другие запросы
]
batches_request = client.call_batches(methods=requests, halt=True)
for activity in batches_request.result.result:
print(activity["TITLE"])Работа с OAuth
Если приложение взаимодействует с Битрикс24 по OAuth, появляется обязательная рутина: токены имеют ограниченный срок жизни, и необходимо корректно реализовать их обновление, обрабатывать ошибки и сохранять новые значения.
В SDK эта логика инкапсулирована внутри токена и механизма выполнения запросов.Перед каждым вызовом проверяется, не истек ли токен, и при необходимости выполняется обновление. Если во время запроса API возвращает ошибку, связанную с истекшим токеном, SDK также автоматически пытается его обновить и повторить запрос.
Ключевые особенности:
-
обновление токена происходит автоматически при необходимости;
-
повторный запрос выполняется без участия разработчика;
-
логика refresh не размазывается по коду приложения;
-
обновленный токен устанавливается централизованно.
Дополнительно SDK предоставляет точку расширения: после успешного обновления токена генерируется событие (OAuthTokenRenewedEvent), которое можно перехватить и, например, сохранить новые значения в базе или другом хранилище.
В результате:
-
интеграция становится устойчивее к истечению токена;
-
уменьшается количество ошибок, связанных с авторизацией;
-
код приложения не содержит дублирующей логики обновления.
Использование SDK ИИ-агентами
Благодаря предсказуемому дереву вызовов методов и единообразной структуре параметров, SDK существенно снижает неоднозначность при работе с API. ИИ не требуется:
-
формировать URL-строки;
-
искать названия REST-методов;
-
определять структуру параметров.
В результате вызовы проще генерируются, а ответы — корректнее интерпретируются и валидируются.
SDK в этом сценарии выступает как надежный исполнитель, обеспечивающий стабильный и предсказуемый интерфейс взаимодействия с API.
Благодаря предсказуемому дереву вызовов методов и единообразной структуре параметров, SDK существенно снижает неоднозначность при работе с API. ИИ не требуется:
-
формировать URL-строки;
-
искать названия REST-методов;
-
определять структуру параметров.
В результате вызовы проще генерируются, а ответы — корректнее интерпретируются и валидируются.
SDK в этом сценарии выступает как надежный исполнитель, обеспечивающий стабильный и предсказуемый интерфейс взаимодействия с API.
Итог
Если собрать всё в одну картину, B24PySDK снимает основные сложности, на которых обычно теряется время при интеграциях с Битрикс24:
В результате разработка интеграций становится быстрее, надёжнее и более масштабируемой.
Часть 2. Как мы разрабатывали SDK B24PySDK
Масштаб задачи
С самого начала было понятно, что речь идет не о нескольких удобных обертках над REST API, а о полноценном SDK, который должен масштабироваться на большой объём методов в API Битрикс24, которых более 1200. Проблема быстро перестает быть только «кодовой»: недостаточно просто написать несколько хороших функций, нужен воспроизводимый способ расширять библиотеку дальше.
Для каждого метода нужно определить сигнатуру, корректно собрать параметры, сохранить соответствие REST API, оформить документацию и затем проверить, что всё это не выбивается из общей архитектуры SDK. Поэтому к SDK с самого начала предъявлялись два базовых требования: он должен давать единообразный интерфейс и при этом развиваться предсказуемым способом.
С чего начали: интерфейс и архитектура
Первым этапом стало проектирование интерфейса SDK — того, как именно разработчик будет с ним взаимодействовать. Здесь сразу выбрали простой и понятный принцип: вызов метода в SDK должен повторять REST-метод и его структуру.
Если в API есть crm.deal.list, то в SDK это должно выглядеть так:
client.crm.deal.list(...)
Если есть user.get, то так:
client.user.get(...)То есть библиотека не должна вводить дополнительный слой терминологии или предлагать собственные названия методов. Разработчик должен видеть в SDK ту же структуру, что и в REST API, только в более удобной форме.
Следующим важным решением стало единообразие сигнатур. Все публичные методы должны были выглядеть предсказуемо: параметры передаются в одном стиле, служебные аргументы оформляются одинаково, а различия между методами не должны превращаться в различия интерфейса без необходимости.
Например, если метод принимает данные сущности, сигнатура должна быть устроена одинаково:
client.crm.lead.add(fields={...}, timeout=10)
client.crm.deal.update(bitrix_id=1, fields={...}, timeout=10)Важно здесь не только наличие параметров, но и сам подход: именованные аргументы, единый timeout, единый стиль передачи данных. Такой контракт был важен и для разработчиков, и для IDE-подсказок, и для последующей автоматизации.
Первые ручные обёртки: почему начали с CRM
В качестве первого раздела выбрали CRM. Причина была не в популярности этого раздела, а в его разнообразии. В CRM есть методы с fields, списочные методы с filter, select и order, вложенные сущности и разные варианты структуры ответа. Это делало CRM удобной площадкой для проверки архитектурных решений на реальных сценариях.
Первые обёртки для CRM писались вручную. Этот этап был принципиально важен, потому что до автоматизации нужно было получить эталонные реализации. Они позволяли увидеть, какие сигнатуры действительно удобны, как лучше называть параметры, какие элементы должны быть обязательными для всех методов, а какие решения, наоборот, ведут к разнородности и должны быть исключены.
Упрощенно такой эталонный метод выглядел так:
@type_checker
def add(
self,
fields: JSONDict,
*,
timeout: Timeout = None,
) -> BitrixAPIRequest:
return self._add(fields, timeout=timeout)
А метод обновления — так:
@type_checker
def update(
self,
bitrix_id: int,
fields: JSONDict,
*,
timeout: Timeout = None,
) -> BitrixAPIRequest:
return self._update(bitrix_id=bitrix_id, fields=fields, timeout=timeout)Даже на таких простых примерах было видно, какие решения стоит закреплять как стандарт: использование bitrix_id, единый timeout, обязательная валидация типов и отсутствие “особых случаев” в публичном интерфейсе.
Формирование правил
После появления первых ручных оберток стало понятно, что следующий шаг — превратить накопленные решения в формальные правила. Без этого даже хорошо спроектированная библиотека быстро начинает терять единый стиль: одни методы пишутся по одному принципу, другие по другому, а локальные упрощения постепенно ломают общую структуру.
Поэтому мы сформировали набор правил, который описывал, как должны быть устроены методы, как должны называться параметры, как сохраняется соответствие REST-иерархии, как оформляется документация и как строятся примеры использования.
Например, правило “вызов метода повторяет REST-метод” означало, что допустимо:
client.crm.template.add(...)и недопустимо:
client.crm.template_add(...)А правило для сигнатур означало, что метод должен выглядеть предсказуемо и не превращаться в набор исключений от случая к случаю.
В результате появился не просто код, а документированный способ расширять SDK дальше.
Подготовка к автоматизации
Для человека многие вещи могут оставаться “по умолчанию понятными”, но для автоматической генерации этого недостаточно: любое двусмысленное правило рано или поздно будет понято неправильно. Поэтому мы сделали зафиксированные правила максимально однозначными: команда не просто собрала внутренние договоренности, а довела их до состояния, в котором по ним можно было воспроизводимо генерировать новые методы, документацию и тесты.
Параллельно настроили инфраструктуру разработки: локальную работу через Docker, типовые команды через Makefile, разделение тестов на unit и integration. Типовой локальный сценарий выглядел как запуск линтера, unit-тестов и integration-тестов через стандартные команды проекта, а integration-часть при этом оставалась opt-in и требовала реальных credentials.
Именно на этом этапе стало ясно, что автоматизация без формализованных правил и без инфраструктуры проверки не дает нужного эффекта: она лишь ускоряет появление ошибок.
Как MCP-сервер Битрикс24 усилил возможности ИИ
Ключевой качественный скачок произошел после появления MCP-сервера Битрикс24 для разработчиков. ИИ можно было использовать и раньше, но без надежного источника истины он неизбежно оставался ограничен: мог хорошо продолжать паттерн, но не всегда точно воспроизводил структуру API.
MCP изменил ситуацию, потому что дал агенту доступ к структурированной и актуальной информации о методах: их названиям, параметрам, допустимым значениям и другим важным деталям. Это резко снизило вероятность того, что модель начнёт “додумывать” отсутствующие части API или путать похожие методы.
Как работал ИИ-агент
На первом этапе мы подготовили документацию по разработке модулей SDK. В ней зафиксировали архитектурные требования, стиль кода, правила типизации, структуру методов, требования к параметрам и порядок подготовки тестов. Документация изначально учитывала широкий набор технических сценариев и граничных случаев.
На втором этапе разработали отдельную инструкцию для ИИ-агента. Она требовала строгого следования утвержденной документации, использования данных из b24mcp как основного источника по методам и проверки решений на соответствие существующим реализациям в проекте. Агенту передавались правила генерации, примеры вручную написанных оберток и данные из MCP. На основе этого он генерировал код методов, документацию, примеры использования и тесты.
На третьем этапе мы перевели процесс в итерационный режим: генерация, проверка результата, анализ несоответствий, уточнение документации и повторный запуск. По итогам каждой итерации правила становились точнее. В результате был сформирован устойчивый процесс, при котором ИИ-агент, опираясь на данные b24-dev-mcp и внутренние правила проекта, формирует корректный и согласованный результат для SDK и сопутствующих материалов.
Пример результата на уровне использования:
client.crm.lead.add(fields={"TITLE": "New lead"})
client.crm.lead.list(select=["ID", "TITLE"], filter={"ASSIGNED_BY_ID": 1})
client.crm.lead.delete(bitrix_id=10)То есть ИИ не создавал новый интерфейс, а воспроизводил уже зафиксированный.
Кроме самих методов, агент генерировал и примеры использования. Например, для списочного метода:
request = client.crm.lead.list(
select=["ID", "TITLE"],
filter={"ASSIGNED_BY_ID": 1},
)
for lead in request.as_list(limit=50).result:
print(lead["TITLE"])В результате на выходе получался не только код SDK, но и сопутствующие материалы, которые также оставались консистентными.
Проверка результатов
Несмотря на использование MCP, ручная проверка оставалась обязательной частью конвейера. Она не ограничивалась общим просмотром кода и была ориентирована на конкретные классы ошибок, которые могли возникать даже при наличии детальных инструкций.
В ходе проверки мы анализировали следующие отклонения: неверную иерархию классов, лишние параметры, отсутствие обязательных параметров, ошибки типизации, отклонения от принятого нейминга параметров (например, использование id вместо bitrix_id), а также нарушения принятого стиля кода.
Дополнительно проверяли docstrings, ссылки на документацию и соблюдение единого формата оформления. Все результаты проходили проверку на соответствие внутренней документации по написанию оберток и официальной документации Битрикс24.
Генерация тестов
Для SDK такого масштаба ручная подготовка полного набора интеграционных проверок была бы сопоставима по трудозатратам с написанием самих оберток, а то и больше. Поэтому тестирование изначально включили в общий автоматизированный конвейер и стандартизировали на том же уровне, что и генерацию методов.
Ключевой принцип был таким же, как при генерации оберток: агент не писал тесты в произвольной форме, а ориентировался на уже принятые в проекте стандарты. Он анализировал существующие тесты в репозитории, воспроизводил их структуру, стиль кода, порядок шагов, формат зависимостей между тестами, подход к именованию и единый формат проверок. Это позволяло поддерживать единообразие и исключать ситуации, когда тест формально проходит, но написан в стиле, отличающемся от остального проекта.
Проверка результата строилась не только на факте успешного HTTP-вызова. Тесты формировались как проверка контракта метода и включали содержательную валидацию:
1. Проверка типа результата (dict, list, bool, int и т.д.) в соответствии с ожидаемым контрактом.
2. Проверка структуры ответа по полям: наличие обязательных полей и корректность их формата.
3. Проверка бизнес-связности сценария:
– если создается объект, тест проверяет, что возвращен идентификатор;
– затем объект извлекается методом get/list и сверяется по ключевым полям;
– после update повторно проверяется, что изменения действительно применялись;
– после delete проверяется корректный результат удаления.
4. Для списочных методов — отдельные проверки as_list() и as_list_fast(), включая поведение пагинации и формат коллекций.
5. Для зависимых сценариев — контроль правильного порядка выполнения через depends, чтобы каждый тест проверял конкретный этап жизненного цикла сущности.
Для того чтобы тесты соответствовали фактическому поведению API, агент дополнительно обращался к b24mcp и получал оттуда описание формата ответа, полей и типовых структур результата. На основе этих данных строились проверки полей и типов, а также уточнялись ожидания по различным методам (например, когда метод возвращает объект, а не список, или вложенную структуру вместо плоской).
Эффект от подхода
В итоге удалось получить не просто библиотеку, а масштабируемый способ ее развития. Добавление новых методов перестало быть ручной работой “с нуля” и стало частью воспроизводимого процесса. Код стал заметно более консистентным, потому что методы, написанные в разное время и для разных разделов API, подчинялись одним и тем же правилам. Кроме того, стало проще подключать новых разработчиков: вместо неявных договоренностей внутри команды появился документированный и понятный подход.
Отдельно важен эффект по времени. Даже без точного подсчёта человеко-часов очевидно, что разница между полностью ручной реализацией и генерацией по правилам с использованием MCP становится принципиальной уже на масштабе десятков методов, а при работе с сотнями и тысячами — тем более.
Главный результат этого подхода заключается не просто в том, что в разработке использовался ИИ. Важнее то, что удалось построить инженерную систему, в которой ИИ стал частью контролируемого процесса, а не источником случайного кода.
Часть 3. Планы по развитию
Следующим этапом развития B24PySDK мы видим движение от удобной обёртки над REST API к более полноценной прикладной платформе для разработки интеграций и приложений на Python. В ближайших планах — несколько направлений, которые должны сделать SDK полезнее как для обычной разработки, так и для сценариев с участием ИИ-агентов.
-
Планируем добавить модуль интеграции с популярными Python-фреймворками: Django, FastAPI и Flask. Это не только упростит подключение SDK к уже существующему приложению, но и закроет типовые платформенные сценарии валидацию входящих запросов из встраиваемых приложений, обработку онлайн-событий, а также поддержку действий активити и роботов бизнес-процессов. Отдельной планируем внедрить SDK в стартер b24-ai-starter, где можно будет показать готовые примеры использования на реальном шаблоне проекта, а также подготовить отдельные инструкции для AI-агентов, работающих с таким стеком. Это сократит время старта и сделает сценарии использования SDK более прикладными и воспроизводимыми.
-
Будем развивать объектную модели поверх REST API — добавим Bitrix-объекты, с которыми можно будет работать как с полноценным ORM-слоем: через менеджеры объектов, ленивые запросы, операции чтения и изменения в привычной объектной форме. При этом сами объекты будут предоставлять не только доступ к данным, но и высокоуровневые методы для обращения к API, позволяя выполнять типовые действия напрямую через объектную модель, без необходимости каждый раз вручную вызывать соответствующие обертки REST-методов. Особое внимание планируем уделить валидации и преобразованию данных: значения, приходящие из Bitrix24 в JSON-формате, должны автоматически и предсказуемо превращаться в нативные типы Python, а при отправке обратно — корректно сериализоваться в ожидаемый формат API. Такой слой должен еще сильнее сократить объем технического кода и приблизить работу с Bitrix24 к более естественной для Python-разработчика модели.
-
Отдельным направлением развития станет добавление асинхронности. Количество интеграционных сценариев растет, и все чаще требуется эффективно выполнять большое число сетевых операций без блокирующего режима работы. Поддержка асинхронного взаимодействия особенно важна для высоконагруженных интеграций, фоновых обработчиков, сервисов с большим количеством параллельных обращений к API и приложений, построенных на современном async-стеке. Появление асинхронного слоя расширит область применения SDK и сделает его более удобным для новых архитектурных сценариев.
-
Ещё одно постоянное направление — увеличение покрытия тестов. По мере расширения SDK особенно важно усиливать не только количество проверок, но и глубину покрытия: контрактов методов, типизации, пагинации, batch-сценариев, OAuth-логики и интеграционных цепочек. Это необходимо не только для стабильности текущих возможностей, но и для безопасного развития библиотеки дальше, когда новые модули, объектные abstractions и асинхронные механизмы начнут добавляться поверх уже существующей базы. Чем шире и точнее тестовое покрытие, тем проще сохранять консистентность SDK и тем надёжнее становится сам процесс его масштабирования.
Автор: IT-Solution
