Привет! Меня зовут Максим Месилов, я один из мейнтейнеров BITRIX24 PHP SDK.
У Битрикс24 большой REST API: через него разработчики подключают внешние сервисы, работают с CRM и создают приложения для Marketplace.
С API можно работать напрямую, но тогда появляется повторяющаяся техническая работа: авторизация, вызовы методов и обработка ответов. Каждый раз писать это заново неудобно, поэтому вокруг API постепенно появился PHP SDK — библиотека, которая берёт на себя базовую работу с платформой и даёт разработчику привычный интерфейс на PHP.
Сегодня рассказываю, как PHP SDK для Битрикс24 вырос из pet-проекта в официальный инструмент, зачем он нужен в эпоху AI-кодинга и почему SDK становится нижним слоем для разработки приложений и интеграций вокруг Битрикс24.
Официальный репозиторий PHP SDK здесь: github.com/bitrix24/b24phpsdk
Как и зачем начали создавать SDK
PHP SDK для Битрикс24 начинался как pet-проект. У разработчиков уже был базовый набор инструментов для работы с API: REST API Битрикс24 и CRest. Этого хватало, чтобы отправлять запросы и получать ответы, но для разработки больших интеграций хотелось более удобного уровня абстракции.
В каждом проекте разработчику приходилось заново решать одни и те же технические задачи транспортного слоя: авторизоваться, вызывать методы API, обрабатывать ответы и ошибки, приводить данные к нужным типам, работать с batch-запросами. Эти повторяющиеся операции и стали тем слоем, который хотелось вынести в общую библиотеку. Чтобы упростить себе работу, разработчику нужно вынести повторяющийся транспортный слой в общую библиотеку.
Выглядит это так: подключение к порталу занимает одну строку.
<?php declare(strict_types=1); use Bitrix24\SDK\Services\ServiceBuilderFactory; require_once 'vendor/autoload.php'; $b24 = ServiceBuilderFactory::createServiceBuilderFromWebhook('INSERT_HERE_YOUR_WEBHOOK_URL'); $deal = $b24->getCRMScope()->deal()->get(134)->deal(); echo $deal->TITLE; // string echo $deal->DATE_CREATE->format('d.m.Y'); // CarbonImmutable, а не строка из JSON
В статье примеры упрощены, но мы рекомендуем вам придерживаться базовых принципов:
ставьте PHP через docker;
секретные ключи передавайте через переменные окружения, не надо коммитить их в репозиторий с кодовой базой приложения
Цикл обучающих видео с пошаговыми инструкциями можно посмотреть в учебном курсе «REST API Битрикс24».
Хотя работать с библиотекой удобнее, чем с API напрямую, но такой транспортный слой редко даёт по-настоящему серьёзные преимущества. Получается, что разработчик просто работает с большим набором отдельных HTTP-ручек. Вместо этого важнее прикладная логика: автоматизация продаж, связь CRM с внешним сервисом, отчёты. А транспортный слой, в котором хранятся HTTP-запросы к API — это фундамент, на котором строится полезная бизнес-функциональность.
API-методы немного отличались от подсистемы к подсистеме по сигнатурам и полям, поэтому разработчик вынужден был каждый раз сверяться с документацией.
Так появилась идея SDK: закрыть этот технический транспортный слой готовой библиотекой. Разработчику не нужно каждый раз вручную собирать HTTP-запросы, разбирать JSON-ответы и повторно писать обработку ошибок. Вместо этого он работает с понятными PHP-классами и методами, которые отражают структуру API Битрикс24.
В чём была сложность: у Битрикс24 больше тысячи REST-методов, и их нужно аккуратно разложить по библиотеке.
Почему SDK пришлось писать вручную
В разработке SDK есть два основных подхода.
Первый подход: построить библиотеку на основе машиночитаемой спецификации API. Обычно для этого используют OpenAPI. Если вендор описывает методы, параметры и ответы в специальном формате, часть рутинной работы можно поручить кодогенерации: один и тот же API превращается в библиотеки для PHP, JavaScript, Python или других языков.
Но это возможно, если у API уже есть такая спецификация. В случае Битрикс24 на тот момент не существовало готовой OpenAPI-спецификации, поэтому автоматическая генерация SDK была невозможна.
Второй подход: создавать PHP SDK вручную. Это был более трудоёмкий подход, но он позволял двигаться вперёд без OpenAPI-спецификации. Я и ряд разработчиков это понимали, поэтому мы скооперировались вокруг того, чтобы сделать библиотеку, которая давала бы нам тот тулинг, который нам хотелось для языка PHP версии 7.4.
Как библиотека выросла из pet-проекта
Поначалу SDK развивался как обычный pet-проект: я периодически делал паузы в разработке, другие разработчики помогали с поддержкой, библиотека постепенно набирала пользователей.
Со временем проект стал заметен: репозиторий собрал 400 звёзд на GitHub, а на Packagist в пиковые периоды набиралось 120 установок в день. Некоторые старые проекты продолжают использовать эту зависимость.
В какой-то момент библиотека переросла уровень pet-проекта. Битрикс24 начал больше внимания уделять Developer Experience и DevRel, и SDK перенесли в namespace вендора и стали развивать уже как официальный инструмент для разработчиков.
Новая API 3.0, OpenAPI и системный релизный цикл
Позже PHP SDK вошёл в число участников Яндекс Open Source Code Jam — программы поддержки open-source-проектов. Для библиотеки это стало ещё одним шагом от личного pet-проекта к инструменту, которым пользуется сообщество.
Сейчас SDK развивается уже как часть более системной экосистемы. У Битрикс24 появилась новая версия REST API 3.0 с поддержкой OpenAPI-спецификации, а вместе с ней — третья версия PHP SDK. Мы стараемся развиваться регулярно и делать релизы раз в месяц.
Что вообще за версии?
REST-API развивался с момента публичного запуска Битрикс24 и накопился большой пласт легаси, в том числе по структурам данных которое отдает API. Вендор принял решение существенно обновить дизайн REST-API и поэтому сделали новую версию которая не совместима с текущей.
Ключевые улучшения:
единый формат ответа для всех методов,
получение связанных данных одним запросом,
повторный вызов без дублей по заголовку Idempotency-Key,
встроенная OpenAPI-документация.
Вот, как выглядят адреса эндпоинтов:— {portal}/rest/{user_id}/{token}/{method} для v1
— {portal}/rest/api/{user_id}/{token}/{method} для v3
Детальную информацию о методах v3 можно посмотреть в разделе «Обзор REST 3.0»
Ветка SDK v3 содержит новые методы и все старые, а ветка v1 только старые, поэтому, «по умолчанию» разработку имеет смысл вести на версии SDK 3.*
Покрытие API постепенно расширяется и сейчас дошло до 70%:
100%: imopenlines, booking, note, mail, documentgenerator, lists, biconnector, entity, imconnector
im -- 99%
sale 89%,
landing 85%,
catalog 72%,
humanresources 71%
crm 61% (102 непокрытых метода)
tasks 26%,
disk 42%,
timeman 44%,
rpa и vote -- 0%
Дополнительно в разработку SDK включились разработчики из сообщества, а мой фокус сместился с добавления методов на тулинг.
Главное, что сейчас у нас есть комьюнити PHP-разработчиков и понимание, что библиотека — это просто нижний слой. Поверх него появляются инструменты для жизненного цикла приложения, а ещё выше — стартеры, которые можно использовать как готовые шаблоны проектов. Задача всей этой конструкции — стандартизировать базовые уровни разработки, чтобы разработчик быстрее переходил к прикладной бизнес-логике.
Зачем SDK, когда есть AI-кодинг
С появлением AI-кодинга может показаться, что отдельный SDK уже не важен, потому что можно закинуть промпт в любую LLM, она сама напишет код для работы с REST-API и всё заработает с первого раза.
Для небольших нишевых сценариев это может сработать. Допустим, у вас есть 100 методов в REST API, а вы работаете только с тремя. С ИИ вам не нужно тащить зависимость в виде отдельной библиотеки на 100 методов. Вы просите агента сгенерировать код, который будет работать с 3 методами.
В более сложных проектах появляются проблемы. При работе нужно опираться на качественный уровень абстракции. То есть нельзя перепрыгнуть несколько уровней абстракции, если они недостаточно качественные и надежные. Ошибки всё равно будут, даже с развитыми ИИ-агентами. И если вы не используете качественные абстракции, все ваши наработки будут работать нестабильно.
Можно отлаживать код и исправлять ошибки. Но если у вас уже есть что-то отлаженное, то даже если это делали не вы, стоит это использовать. Просто потому, что это позволяет фокусироваться только на той части, которая вам нужна.
При этом все подходы имеют право на жизнь, одного правильного подхода нет. Хорошо, когда есть выбор, и каждый разработчик сам может принять решение: «я это использую» или «я это не использую».
Как именно будет в итоге и куда мы придём, пока неизвестно. Но надеемся, что это будет более хороший мир.
LLM и OpenSource
Кажется, что сейчас наступила золотая эра опенсорса: LLM ускорили доставку фич, массовые изменения, черновики PR, коммиты и рутинные проверки. Кодогенерация позволяет сделать 100500 фич или PR. Все счастливы? К сожалению, не совсем.
Агентная разработка позволяет прямо внутри процесса выполнения задачи сказать: «пойди оформи ишью и предложи PR», если у вас настроен MCP для Github, то агент все это сделает и мейнтейнер проекта получит волну slop-багрепортов\фиксов и будет вынужден начать их разбирать. Естественно, со своей стороны, он тоже может попросить LLM ему помочь. Ah Shit, Here We Go Again moment.
Мы приходим к тому, что приходится пересматривать весь пайплайн разработки и давать агентам возможность получить максимум обратной связи: линтеры, гайды, юнит и интеграционные тесты. Ответственность разработчика никуда не девается и вы как и прежде должны подумать перед мерджем предложенных изменений или добавлении функционала.
Работа maintainer не исчезает, но меняется фокус поддержки: документация, skills, инструкции, контекст для агентов, политики PR и прочие вещи которые раньше частенько выпадали из скоупа активностей разработчиков.
Главная польза SDK: типизация и предсказуемость
Один из главных плюсов SDK — типизация.
REST API возвращает данные в JSON: даты, цены и другие поля приходят как строки или числа, а разработчику дальше нужно самому приводить их к нужным типам.
В большом приложении такая ручная обработка быстро превращается в рутину. Если библиотека предоставляет удобный типизированный интерфейс, разработчику проще работать с такими вещами. Он может уже опираться на библиотеку и решать прикладные задачи не отвлекаясь на рутину.
Вариант 1 — ничего не делаем, возвращаем массив «как есть»
Интересные статьи
Интересные статьи
