Привет! Меня зовут Максим Месилов, я один из мейнтейнеров BITRIX24 PHP SDK.

У Битрикс24 большой REST API: через него разработчики подключают внешние сервисы, работают с CRM и создают приложения для Marketplace.

С API можно работать напрямую, но тогда появляется повторяющаяся техническая работа: авторизация, вызовы методов и обработка ответов. Каждый раз писать это заново неудобно, поэтому вокруг API постепенно появился PHP SDK — библиотека, которая берёт на себя базовую работу с платформой и даёт разработчику привычный интерфейс на PHP.

Сегодня рассказываю, как PHP SDK для Битрикс24 вырос из pet-проекта в официальный инструмент, зачем он нужен в эпоху AI-кодинга и почему SDK становится нижним слоем для разработки приложений и интеграций вокруг Битрикс24.

Работа с файлами в REST API Битрикс24 — та задача, где документация заканчивается ровно там, где начинаются проблемы. Официальные примеры показывают, как загрузить один файл в одно поле. А дальше выясняется, что у crm.item.update и crm.deal.update разные несовместимые форматы, что вложенный base64 через http_build_query уходит в никуда, а сервер при этом честно отвечает «result».

За год я делал файловую логику в шести проектах: перелив сделок между порталами, загрузка фотоописей с мобильного, парсинг PDF из карточек, сборка архивов, синхронизация аватаров. Везде подход получился разный.

Собрал всё в один разбор — шесть подходов с кодом и восемь граблей:

два формата файлового значения, которые нельзя смешивать, и почему при смешении затираются уже прикреплённые файлы;

тихий провал: HTTP 200, в ответе result, поле не обновилось;

useOriginalUfNames=Y, без которого UF_CRM_* молча игнорируются;

downloadUrl приходит с пустым auth= и без подстановки токена не скачивается, а при протухшем токене вместо файла отдаётся HTML-страница с кодом 200;

у одного изображения бывает несколько URL, и часть из них не работает — пришлось делать скоринг вариантов по эвристике.

В конце — таблица «что брать под какую задачу» и чеклист граблей. Двадцать блоков кода, всё из боевых проектов.

Каждый день мы натыкаемся на одни и те же грабли в связке фронта и бэка. Каждые такие грабли — это деньги и время. А если ещё и договариваться не умеем, процессов нет и решать никто не берётся, то дальше начинаются конфликты, атмосфера в команде проседает и проблемы копятся ещё быстрее.

Статья не про саму автогенерацию — с ней всё понятно, про неё и без меня написано достаточно. Мы внедрили генерацию типов из OpenAPI, и она вытащила наружу то, что с генерацией напрямую не связано: кто не хочет писать комментарии, почему у одной сущности два имени и почему у нас падал dev. По сути — про команду, эго и умение договариваться.

Сразу оговорюсь: это не единственно верный путь. Команды и компании разные, у всех свои нюансы, я рассказываю, как было у нас. Но если автогенерации у вас ещё нет и вы соберётесь её внедрять — будете хотя бы знать, что вас ждёт.

У моего генератора QR-кодов листами появился публичный API: POST с JSON, в ответ сразу готовый PDF, до 1500 кодов за запрос, без регистрации и ключей. Внутри рассказ, почему я не завел ни ключи, ни Redis, как работает лимитер на файлах с flock и fail-open, и на какой грабле Apache POST молча превращался в GET.