Как записать JSON в 1С: способы, код и проверка результата

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

Ключевая сложность — соответствие типов. В JSON нет дат, ссылок на объекты базы и типа «Неопределено» в том виде, в каком их понимает 1С. Дату придётся форматировать строкой, ссылку заменять на GUID или представление, а «Неопределено» — на null или пропуск поля. Если заранее не определить правила преобразования, приёмная сторона получит данные, которые не сможет разобрать.

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

Какой способ записи JSON выбрать

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

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

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

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

Подходит для любых документов, вложенных объектов, массивов и потоковой записи в файл. Требует больше кода и аккуратности с открытием/закрытием структур.

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

Подходит для структур, соответствий и массивов с простыми типами. Один вызов вместо десятков строк, но не поддерживает ссылки, даты сериализует в свой формат.

ЗаписьJSON + ЗаписатьJSON()

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

Потоковая запись через объект ЗаписьJSON

Объект ЗаписьJSON — основной инструмент. Он последовательно формирует документ: вы открываете объект, пишете свойства, открываете вложенные объекты и массивы, закрываете их в обратном порядке. Минимальный пример записи в строку:

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

Запись.ЗаписатьНачалоОбъекта();

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

Запись.ЗаписатьИмяСвойства("Количество");
Запись.ЗаписатьЗначение(12.5);

Запись.ЗаписатьИмяСвойства("Активен");
Запись.ЗаписатьЗначение(Истина);

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

Результат = Запись.Закрыть();

Метод Закрыть() возвращает сформированную строку JSON. Альтернативный вариант — ЗаписатьСвойство(Имя, Значение), который объединяет запись имени и значения в один вызов. Для записи в файл вместо УстановитьСтроку() используйте конструктор с параметрами: Новый ЗаписьJSON(ИмяФайла, "UTF-8") — тогда документ пишется на диск порциями.

Проверьте, что каждому ЗаписатьНачалоОбъекта() и ЗаписатьНачалоМассива() соответствует закрывающий вызов. Незакрытая структура — самая частая причина ошибки «Нарушена последовательность вызовов» при закрытии записи.

1. 1
   Создайте объект: Новый ЗаписьJSON и вызовите УстановитьСтроку()
2. 2
   Откройте корневой объект: ЗаписатьНачалоОбъекта()
3. 3
   Запишите свойства парами ЗаписатьИмяСвойство() + ЗаписатьЗначение()
4. 4
   Закройте объект: ЗаписатьКонецОбъекта()
5. 5
   Получите результат: СтрокаJSON = Запись.Закрыть()
6. 6
   Проверьте строку чтением обратно через ЧтениеJSON

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

Реальные документы редко плоские: заказ содержит массив строк товаров, контрагент — вложенный объект адреса. Вложенность формируется теми же методами, просто внутри открытого объекта открывается следующий:

Запись.ЗаписатьИмяСвойства("Товары");
Запись.ЗаписатьНачалоМассива();

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

Запись.ЗаписатьКонецМассива();

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

Если поле может отсутствовать, решите заранее: не писать его вообще или писать со значением null. Многие API различают «поле отсутствует» и «поле равно null». Для записи null используйте Запись.ЗаписатьЗначение(Неопределено) — платформа преобразует его в null, либо явно ЗаписатьNull() в новых версиях платформы.

Автоматическая сериализация структур

Когда документ уже собран в виде структуры или соответствия, проще использовать сериализатор. Он обходит коллекцию и формирует JSON без ручного управления:

Данные = Новый Структура;
Данные.Вставить("Номер", "0001-000123");
Данные.Вставить("Сумма", 15400.50);
Данные.Вставить("Проведен", Истина);

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

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

Ограничение способа — типы. Ссылки на объекты базы, ХранилищеЗначения, уникальные идентификаторы в произвольном виде сериализатор не обработает как ожидает внешняя система. Даты он запишет в формате ISO, но если API ждёт Unix-время или другой шаблон, придётся преобразовывать дату в строку до сериализации.

Преобразование типов 1С в типы JSON

JSON поддерживает только строки, числа, булево, null, объекты и массивы. Всё остальное нужно привести к этим типам до записи. Основные правила:

• Дата — форматируйте строкой: Формат(Дата, "ДФ=yyyy-MM-ddTHH:mm:ss") для ISO-подобного формата. Согласуйте шаблон с приёмной стороной.
• Ссылка на объект — передавайте GUID: Строка(Ссылка.УникальныйИдентификатор()), либо человекочитаемый код или номер, если обмен идёт по ним.
• Неопределено — записывается как null либо поле пропускается.
• Булево — сериализуется напрямую как true/false, преобразование не требуется.
• Число — проверьте разделитель: в JSON дробная часть всегда через точку, платформа при записи значения типа Число делает это корректно сама.

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

Запись JSON в файл и отправка по HTTP

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

При отправке в HTTP-сервис строку JSON передают в теле запроса. Типовой фрагмент:

Соединение = Новый HTTPСоединение("api.example.com", 443,,,,, Новый ЗащищенноеСоединениеOpenSSL);
Запрос = Новый HTTPЗапрос("/v1/orders");
Запрос.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Запрос.УстановитьТелоИзСтроки(СтрокаJSON, КодировкаТекста.UTF8);

Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Если Ответ.КодСостояния <> 200 Тогда
ВызватьИсключение "Ошибка API: " + Ответ.КодСостояния;
КонецЕсли;

Заголовок Content-Type: application/json обязателен — без него многие серверы не распарсят тело. Кодировку указывайте явно и в заголовке, и в УстановитьТелоИзСтроки().

Проверка корректности результата

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

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

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

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

Обратное чтение через ЧтениеJSON

Норма

Документ разбирается без исключения, поля на месте

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

Исключение с указанием позиции — нарушена структура

Кодировка файла

Норма

Кириллица отображается корректно в редакторе

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

Крякозябры — файл записан не в UTF-8

Типы значений

Норма

Числа и булево без кавычек, даты в согласованном формате

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

Числа строками, дата в формате ДД.ММ.ГГГГ

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

Как записать в JSON значение null?

Передайте Неопределено в ЗаписатьЗначение() — платформа запишет null. При сериализации структуры через ЗаписатьJSON() значение Неопределено также преобразуется в null. Если нужно, чтобы поле с null вообще отсутствовало, не добавляйте его в структуру или оберните запись свойства в условие.

Можно ли сериализовать ссылку на документ напрямую?

Нет, сериализатор не преобразует ссылку в осмысленный JSON. Перед записью извлеките нужные реквизиты (номер, дату, GUID) и сформируйте из них структуру. Для идентификации объекта на приёмной стороне чаще всего используют Строка(Ссылка.УникальныйИдентификатор()).

Чем ЗаписатьJSON отличается от ЗаписьJSON?

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

Почему в файле вместо кириллицы нечитаемые символы?

Файл записан не в той кодировке, в которой его открывают. Укажите кодировку явно при создании записи: Новый ЗаписьJSON(ИмяФайла, КодировкаТекста.UTF8). Если файл читает внешняя система, уточните, нужен ли BOM — некоторые парсеры требуют его наличия, другие, наоборот, отвергают.

Как выгрузить таблицу значений в JSON?

Функция ЗаписатьJSON() поддерживает таблицы значений и запишет их как массив объектов, где имена полей совпадают с именами колонок. Либо обойдите таблицу в цикле и пишите каждую строку через ЗаписьJSON вручную — так можно контролировать имена полей и преобразование отдельных значений.

Как записать JSON в файл на сервере 1С?

Код выполняйте в серверной процедуре (директива &НаСервере или фоновое задание), путь указывайте относительно файловой системы сервера, а не клиента. Учётная запись агента сервера 1С должна иметь права на запись в целевой каталог. После записи файл можно передать клиенту через временное хранилище, если он нужен пользователю локально.