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

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

Есть ошибки, которые невозможно предотвратить внимательностью.

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

Виноватых нет. Все старались. Просто задача «безошибочно переписать двадцать цифр с фото» не решается старанием — она решается тем, что её не должно существовать.

Меня зовут Михаил Аймаутов, я отвечаю за ИТ и автоматизацию в Wollmer — компании, которая занимается бытовой техникой. Расскажу, как мы перестроили самый ручной процесс в компании, и почему бо́льшая часть работы оказалась не про код.