Как сохранить JSON в файл в 1С

Сохранение данных в формате JSON — типовая задача при интеграции 1С с веб-сервисами, сайтами и внешними системами. Встроенный язык платформы предоставляет для этого объект ЗаписьJSON, который формирует корректный JSON-документ и записывает его в файл или строку. Ручная сборка JSON через конкатенацию строк — частая ошибка: она ломается на спецсимволах, кавычках и переносах строк.

В этой статье разобраны два подхода: универсальная запись через ЗаписьJSON с явным контролем структуры и быстрая сериализация объектов через СериализаторXDTO. Также рассмотрены запись на сервере и на клиенте, выбор кодировки, проверка результата и типичные ошибки, из-за которых файл оказывается пустым или битым.

Примеры кода приведены для управляемых форм и современных версий платформы 1С:Предприятие 8.3. Код работает как на сервере, так и на клиенте, если не указано иное.

Базовый способ: объект ЗаписьJSON

Объект ЗаписьJSON — штатный механизм платформы для формирования JSON. Он сам экранирует спецсимволы, корректно обрабатывает типы данных (строки, числа, булево, даты) и гарантирует валидность итогового документа. Это главный аргумент против «ручной» сборки JSON через строки.

Минимальный рабочий пример записи простого объекта в файл:

ЗаписьJSON = Новый ЗаписьJSON;
ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(, Символы.Таб);
ЗаписьJSON.ОткрытьФайл("C:\Temp\data.json", "UTF-8", , ПараметрыЗаписи);

ЗаписьJSON.ЗаписатьНачалоОбъекта();
ЗаписьJSON.ЗаписатьИмяСвойства("Номенклатура");
ЗаписьJSON.ЗаписатьЗначение("Кабель ВВГ 3х2.5");
ЗаписьJSON.ЗаписатьИмяСвойства("Цена");
ЗаписьJSON.ЗаписатьЗначение(125.50);
ЗаписьJSON.ЗаписатьИмяСвойства("Активна");
ЗаписьJSON.ЗаписатьЗначение(Истина);
ЗаписьJSON.ЗаписатьКонецОбъекта();

ЗаписьJSON.Закрыть();

Второй параметр ОткрытьФайл() задаёт кодировку. Для обмена с внешними системами почти всегда нужен UTF-8. Параметр ПараметрыЗаписиJSON со вторым аргументом Символы.Таб включает форматирование отступами — файл становится читаемым для человека. Если файл читает только машина, форматирование можно опустить.

Запись массивов и вложенных структур

Реальные выгрузки редко ограничиваются плоским объектом. Для массива используются методы ЗаписатьНачалоМассива() и ЗаписатьКонецМассива(), вложенные объекты открываются внутри свойства повторным вызовом ЗаписатьНачалоОбъекта().

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.ОткрытьФайл("C:\Temp\orders.json", "UTF-8");

ЗаписьJSON.ЗаписатьНачалоОбъекта();
ЗаписьJSON.ЗаписатьИмяСвойства("Заказы");
ЗаписьJSON.ЗаписатьНачалоМассива();

Для Каждого СтрокаЗаказа Из ТаблицаЗаказов Цикл
ЗаписьJSON.ЗаписатьНачалоОбъекта();
ЗаписьJSON.ЗаписатьИмяСвойства("Номер");
ЗаписьJSON.ЗаписатьЗначение(СтрокаЗаказа.Номер);
ЗаписьJSON.ЗаписатьИмяСвойства("Сумма");
ЗаписьJSON.ЗаписатьЗначение(СтрокаЗаказа.Сумма);
ЗаписьJSON.ЗаписатьКонецОбъекта();
КонецЦикла;

ЗаписьJSON.ЗаписатьКонецМассива();
ЗаписьJSON.ЗаписатьКонецОбъекта();
ЗаписьJSON.Закрыть();

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

Сериализация структур и соответствий

Если данные уже собраны в Структуру или Соответствие, вручную перебирать свойства не нужно — платформа умеет сериализовать их автоматически через ЗаписатьJSON() из глобального контекста. Это самый короткий путь для типовых выгрузок.

Данные = Новый Структура;
Данные.Вставить("Организация", "ООО Ромашка");
Данные.Вставить("ИНН", "7701234567");
Данные.Вставить("СуммаДолга", 15400.75);

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.ОткрытьФайл("C:\Temp\company.json", "UTF-8");
ЗаписатьJSON(ЗаписьJSON, Данные);
ЗаписьJSON.Закрыть();

У этого способа есть ограничение: имена свойств должны быть корректными идентификаторами (структура не позволит вставить ключ с пробелом или дефисом). Если внешняя система требует ключи вида "order-number", используйте Соответствие — оно допускает произвольные строковые ключи и тоже сериализуется через ЗаписатьJSON().

Сравнение вариантов

ЗаписьJSON вручную

Полный контроль над структурой и именами ключей. Подходит для сложных и неоднородных документов, но требует больше кода.

ЗаписатьJSON + Структура

Быстро и лаконично. Ограничение: ключи должны быть валидными идентификаторами.

ЗаписатьJSON + Соответствие

Произвольные имена ключей, включая дефисы и пробелы. Порядок ключей не гарантирован.

СериализаторXDTO

Для ссылочных объектов 1С (документы, справочники). Требует аккуратной настройки и даёт специфичный формат ссылок.

Запись на сервере и на клиенте

Путь к файлу интерпретируется относительно того процесса, где выполняется код. Если процедура помечена директивой &НаСервере, путь C:\Temp\data.json указывает на диск сервера 1С, а не компьютера пользователя. Это самая частая причина «файл записался, но я его не вижу».

Для записи на компьютер пользователя в тонком или веб-клиенте прямой доступ к файловой системе ограничен. Рабочий подход — сформировать JSON в строку на сервере, передать её на клиент и там сохранить через диалог выбора файла или поместить во временное хранилище с последующим получением:

// На сервере: формируем JSON в строку
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Данные);
СтрокаJSON = ЗаписьJSON.Закрыть();

// На клиенте: сохраняем через поток или диалог
Документ = Новый ТекстовыйДокумент;
Документ.УстановитьТекст(СтрокаJSON);
Документ.Записать("C:\Users\User\Documents\data.json", "UTF-8");

В веб-клиенте ТекстовыйДокумент.Записать() работает только с расширением для работы с файлами и после получения разрешения у пользователя. Альтернатива без расширения — поместить строку во временное хранилище и вызвать ПолучитьФайл(), тогда браузер сам предложит сохранить файл.

1. 1
   Определите, где выполняется код: на сервере или на клиенте — от этого зависит доступный путь
2. 2
   Создайте объект ЗаписьJSON и откройте файл с кодировкой UTF-8
3. 3
   Запишите структуру данных методами ЗаписатьНачалоОбъекта/ЗаписатьСвойство или через ЗаписатьJSON()
4. 4
   Вызовите Закрыть() и убедитесь, что исключений не возникло
5. 5
   Откройте файл в текстовом редакторе и проверьте валидность JSON и корректность кириллицы

Кодировка, BOM и кириллица

По умолчанию при записи текстовых файлов платформа может добавить BOM (byte order mark) и использовать системную кодировку, если кодировка не указана явно. Для JSON стандартом де-факто является UTF-8. Большинство веб-сервисов корректно обрабатывают UTF-8 с BOM и без него, но встречаются парсеры, которые ломаются на BOM и возвращают ошибку вида «unexpected character».

Чтобы получить файл строго в UTF-8 без BOM, используйте объект ЗаписьТекста в связке со строковым вариантом ЗаписьJSON:

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, Данные);
СтрокаJSON = ЗаписьJSON.Закрыть();

ЗаписьТекста = Новый ЗаписьТекста("C:\Temp\data.json", "UTF-8", , Ложь);
ЗаписьТекста.Записать(СтрокаJSON);
ЗаписьТекста.Закрыть();

Четвёртый параметр ЗаписьТекста со значением Ложь отключает запись BOM. Если кириллица в файле отображается «кракозябрами» — почти всегда причина в несовпадении кодировки записи и кодировки, в которой файл открывают для просмотра.

Обработка ошибок и проверка результата

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

Попытка
ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.ОткрытьФайл(ПутьКФайлу, "UTF-8");
ЗаписатьJSON(ЗаписьJSON, Данные);
ЗаписьJSON.Закрыть();
Исключение
ЗаписьЖурналаРегистрации("ВыгрузкаJSON",
УровеньЖурналаРегистрации.Ошибка, , ,
ОписаниеОшибки());
ВызватьИсключение;
КонецПопытки;

После записи полезно программно проверить результат: файл существует, имеет ненулевой размер, а его содержимое читается обратно через ЧтениеJSON. Обратное чтение — самый надёжный способ убедиться, что JSON валиден.

Контрольные точки

Как проверить результат

Файл создан по указанному пути

Норма

Файл существует, размер больше нуля

Тревожный признак

Файла нет или размер 0 байт — запись не выполнилась или не вызван Закрыть()

Валидность JSON

Норма

Файл открывается ЧтениеJSON без исключений

Тревожный признак

Ошибка парсинга — нарушена структура или обрезан файл

Кириллица в значениях

Норма

Текст читаем в редакторе с кодировкой UTF-8

Тревожный признак

Кракозябры — записана не та кодировка

Отсутствие BOM при строгих требованиях

Норма

Файл начинается сразу с { или [

Тревожный признак

Первые байты EF BB BF — присутствует BOM

Типичные ошибки при сохранении JSON

Большинство проблем при записи JSON в 1С повторяются из проекта в проект. Ниже — те, что встречаются чаще всего.

Отдельно стоит сказать о датах. В JSON нет типа «дата», и разные системы ожидают разный формат. Самый interoperable вариант — строка ISO 8601 вида 2026-05-17T14:30:00. Согласуйте формат с принимающей стороной до запуска обмена.

Частые вопросы

Чем ЗаписьJSON лучше сборки JSON через строки?

ЗаписьJSON автоматически экранирует кавычки, обратные слэши и управляющие символы, корректно выводит числа и булевы значения и гарантирует валидность документа. При ручной сборке любое значение с кавычкой внутри ломает весь файл, а найти такую ошибку в большом документе сложно.

Как сохранить JSON в файл на компьютере пользователя из серверного кода?

Напрямую — никак: сервер не имеет доступа к диску клиента. Сформируйте JSON в строку на сервере, передайте её на клиент и там сохраните через ТекстовыйДокумент.Записать() либо поместите данные во временное хранилище и вызовите ПолучитьФайл() — пользователь получит стандартный диалог сохранения.

Почему внешняя система не принимает мой JSON-файл?

Частые причины: BOM в начале файла, неверная кодировка, неожиданный формат дат или чисел (разделитель дробной части), а также обрезанный файл из-за отсутствия Закрыть(). Проверьте файл обратным чтением через ЧтениеJSON и сверьте формат с документацией принимающей системы.

Можно ли записать в JSON документ или элемент справочника целиком?

Да, через СериализаторXDTO: метод ЗаписатьJSON() в связке с сериализатором преобразует ссылочный объект в JSON-представление. Учтите, что ссылки при этом выгружаются в специфичном формате, понятном другой 1С, но не всегда удобном для сторонних систем — для произвольных интеграций лучше вручную формировать структуру с нужными полями.

Как записать большой массив данных, не загружая всё в память?

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

Нужно ли экранировать кириллицу в виде \uXXXX?

Нет, это необязательно. Формат \uXXXX — лишь один из способов представления символов в JSON. При записи в UTF-8 кириллица хранится в читаемом виде, и любой современный парсер её корректно обработает. Экранирование может потребоваться только если принимающая система явно этого требует или не поддерживает UTF-8.