Привет! Меня зовут Максим Месилов, я один из мейнтейнеров 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, и часть из них не работает — пришлось делать скоринг вариантов по эвристике.

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