При интеграции 1С с Битрикс24 одной из самых частых задач является передача файлов: счетов, актов, договоров в формате PDF или обычных текстовых логов. Однако разработчики часто сталкиваются с ситуацией, когда небольшие текстовые файлы передаются корректно, а тяжелые бинарные данные (например, PDF объемом 10–20 МБ) приходят на сторону Битрикса "битыми" и не открываются. Разберем подробно, почему это происходит и как правильно реализовать передачу данных.
Проанализируем стандартный процесс: мы берем ДвоичныеДанные файла, преобразуем их в Base64Строка и вставляем в тело POST-запроса. Если мы используем тип контента application/x-www-form-urlencoded (передаем данные как строку с параметрами через &), то символы, из которых состоит Base64, могут быть интерпретированы сервером неверно.
Выясним причину: в кодировке Base64 используются символы +, / и =. В стандарте URL-кодирования символ "+" зарезервирован и интерпретируется как пробел. Когда 1С отправляет "сырую" Base64-строку внутри параметров запроса, Битрикс24 получает пробелы вместо плюсов. Для текстового файла это может быть некритично, но для структуры PDF-файла замена даже одного байта приводит к невозможности его прочитать.
Рассмотрим самый простой и быстрый способ исправления ошибки. Нам необходимо принудительно закодировать строку Base64 перед тем, как добавлять ее в тело запроса. Посмотрим на пример кода, который решает эту проблему:
// Получаем двоичные данные файла
ВремФайл = Новый ДвоичныеДанные(ПутьКФайлу);
// Преобразуем в Base64
СтрокаФорматBase64 = Base64Строка(ВремФайл);
// КРИТИЧЕСКИ ВАЖНЫЙ ШАГ: кодируем строку для URL
// Это преобразует "+" в "%2B", "/" в "%2F" и т.д.
СтрокаФорматBase64 = КодироватьСтроку(СтрокаФорматBase64, СпособКодированияСтроки.КодировкаURL);
// Формируем тело запроса
ТелоЗапроса = "fields[UF_CRM_FILE][fileData][0]=document.pdf"
+ "&fields[UF_CRM_FILE][fileData][1]=" + СтрокаФорматBase64;
Запрос = Новый HTTPЗапрос(АдресРесурса);
Запрос.УстановитьТелоИзСтроки(ТелоЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
В этом примере функция КодироватьСтроку с параметром СпособКодированияСтроки.КодировкаURL гарантирует, что все служебные символы Base64 дойдут до Битрикс24 в неизменном виде. После получения Битрикс выполнит обратное преобразование, и файл восстановится корректно.
Современный REST API Битрикс24 лучше всего работает с форматом JSON. Использование JSON избавляет нас от необходимости вручную вызывать КодироватьСтроку, так как данные передаются не в виде параметров URL, а в структурированном объекте. Рассмотрим, как переписать наш запрос более профессионально:
// Подготовим структуру данных для JSON
ДанныеФайла = Новый Массив;
ДанныеФайла.Добавить("document.pdf");
ДанныеФайла.Добавить(Base64Строка(ВремФайл)); // Здесь КодироватьСтроку НЕ НУЖНА
Поля = Новый Структура;
Поля.Вставить("UF_CRM_FILE", ДанныеФайла);
СтруктураЗапроса = Новый Структура;
СтруктураЗапроса.Вставить("fields", Поля);
// Преобразуем структуру в JSON-строку
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, СтруктураЗапроса);
СтрокаТелоJSON = ЗаписьJSON.Закрыть();
// Формируем HTTP-запрос
Запрос = Новый HTTPЗапрос(АдресРесурса);
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.УстановитьТелоИзСтроки(СтрокаТелоJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Преимущества этого метода: мы избегаем двойного кодирования и потенциальных ошибок с лишними символами. Кроме того, JSON-запросы легче отлаживать, так как их структура прозрачна. Для форматирования и проверки корректности таких структур подойдёт инструмент для валидации и генерации JSON.
Когда мы передаем файлы значительного объема, нужно учитывать несколько технических ограничений, о которых часто забывают:
HTTPСоединение имеет небольшое время ожидания. Для передачи больших файлов обязательно увеличивайте таймаут.
Соединение = Новый HTTPСоединение(Сервер, , , , , 120, Новый ЗащищенноеСоединениеOpenSSL());
client_max_body_size в Nginx и post_max_size в PHP. Если файл (с учетом Base64) превышает эти значения, сервер просто сбросит соединение или вернет ошибку 413.Если прямая отправка в поле CRM все же вызывает сложности из-за объемов, проанализируем двухэтапную схему загрузки, которая считается более надежной:
Шаг 1: Используем метод disk.storage.uploadfile. Мы загружаем файл непосредственно в хранилище Битрикса. Это позволяет работать с потоками данных и более эффективно использовать память.
Шаг 2: Получаем идентификатор загруженного файла (ID). При создании сделки или лида в поле типа "Файл" передаем не Base64-строку, а массив вида ["n12345"], где 12345 — это ID файла на диске. Префикс "n" сообщает системе, что нужно взять уже существующий на сервере файл.
Такой подход значительно снижает риск прерывания транзакции при создании сложного объекта в CRM, так как самая тяжелая часть работы (загрузка байтов) выполняется отдельно. Для интерактивной отладки и проверки выполнения подобных методов можно использовать обработку для работы с REST API Битрикс24.
Подведем итог нашему исследованию. Если ваши PDF-файлы портятся при отправке:
КодироватьСтроку при формировании тела запроса в формате x-www-form-urlencoded.УстановитьТелоИзСтроки вы указали ИспользованиеByteOrderMark.НеИспользовать. Наличие BOM-символов в начале запроса может сбить парсер на стороне Битрикса.HTTPСоединение до 60-120 секунд.Соблюдение этих правил позволит вам настроить стабильный обмен данными между 1С и Битрикс24 без потерь и повреждений файлов.