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

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

Для большинства прикладных задач достаточно связки «Структура → ЗаписьJSON»: вы собираете данные в структуру или соответствие, затем одним вызовом преобразуете их в строку JSON. Потоковый вариант с ЗаписатьНачалоОбъекта нужен, когда документ большой, формируется по частям или требует точного контроля над порядком полей. СериализаторXDTO подходит только для обмена между базами 1С, где нужно передать ссылки и сложные объекты.

Какие средства формирования JSON есть в 1С и когда их применять

Платформа 1С:Предприятие предлагает три основных подхода. Первый — сериализация коллекций: вы заполняете Структуру, Соответствие или Массив и передаёте их методу ЗаписатьJSON. Это самый короткий и читаемый код, подходящий для 90% задач интеграции.

Второй подход — потоковая запись через объект ЗаписьJSON с явными вызовами методов. Он даёт полный контроль: можно формировать документ частями в цикле, записывать «сырые» фрагменты, управлять экранированием. Третий подход — СериализаторXDTO с методом ЗаписатьJSON, который умеет превращать в JSON ссылки на объекты базы, табличные части и перечисления. Его стоит использовать только для обмена между базами 1С, потому что внешняя система не поймёт внутренние типы платформы.

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

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

Подходит для большинства API-интеграций. Код короткий, структура данных видна сразу. Ограничение: весь документ сначала собирается в памяти.

Потоковая ЗаписьJSON

Подходит для больших документов и выгрузок в цикле. Даёт контроль над порядком полей, но код длиннее и легче допустить ошибку в парности начала и конца объектов.

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

Подходит для обмена между базами 1С: сериализует ссылки и объекты конфигурации. Не подходит для внешних API — формат полей специфичен для платформы.

Как сформировать JSON из структуры или соответствия

Базовый сценарий выглядит так: создаёте структуру, добавляете в неё поля, вложенные структуры и массивы, затем сериализуете. Ключи структуры станут именами свойств JSON, поэтому используйте имена, которые ожидает принимающая система, — обычно латиницей в camelCase.

Данные = Новый Структура;
Данные.Вставить("orderNumber", "ЗК-001245");
Данные.Вставить("customer", "ООО Ромашка");
Данные.Вставить("total", 15480.50);
Данные.Вставить("isPaid", Истина);

Товары = Новый Массив;
Строка = Новый Структура;
Строка.Вставить("sku", "ART-101");
Строка.Вставить("qty", 3);
Строка.Вставить("price", 5160.17);
Товары.Добавить(Строка);
Данные.Вставить("items", Товары);

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

Результатом будет строка вида {"orderNumber":"ЗК-001245","customer":"ООО Ромашка","total":15480.5,"isPaid":true,"items":[{"sku":"ART-101","qty":3,"price":5160.17}]}. Обратите внимание: булево значение преобразуется в true/false, числа пишутся без кавычек, а Неопределено и NULL превращаются в null.

Как правильно выгрузить даты, ссылки и специальные типы

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

ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(, Символы.Таб, , , , , , Истина);
Запись = Новый ЗаписьJSON;
Запись.УстановитьСтроку(ПараметрыЗаписи);

Данные = Новый Структура;
Данные.Вставить("date", ТекущаяДатаСеанса());

ЗаписатьJSON(Запись, Данные, , , "ПреобразованиеДаты", ЭтотОбъект);

Более простой путь — заранее преобразовать дату в строку ISO 8601 с помощью функции ЗаписатьДатуJSON(Дата, ФорматДатыJSON.ISO, ВариантЗаписиДатыJSON.ЛокальнаяДатаСоСмещением) и вставить её в структуру как строку. Для ссылок на объекты базы передавайте уникальный идентификатор: Строка(Ссылка.УникальныйИдентификатор()) — это стандартный способ связать записи 1С с внешними системами.

Как сформировать JSON потоковым способом для больших выгрузок

Когда нужно выгрузить, например, каталог из десятков тысяч товаров, собирать всё в один массив в памяти нерационально. Потоковая запись позволяет формировать документ по частям и писать сразу в файл:

Запись = Новый ЗаписьJSON;
Запись.ОткрытьФайл("C:\Export\catalog.json");
Запись.ЗаписатьНачалоОбъекта();
Запись.ЗаписатьИмяСвойства("products");
Запись.ЗаписатьНачалоМассива();

Пока Выборка.Следующий() Цикл
Запись.ЗаписатьНачалоОбъекта();
Запись.ЗаписатьИмяСвойства("sku");
Запись.ЗаписатьЗначение(Выборка.Артикул);
Запись.ЗаписатьИмяСвойства("name");
Запись.ЗаписатьЗначение(Выборка.Наименование);
Запись.ЗаписатьКонецОбъекта();
КонецЦикла;

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

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

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

Как отправить JSON во внешний HTTP-сервис

Сформированная строка обычно передаётся телом POST-запроса. Используйте HTTPСоединение и HTTPЗапрос, обязательно указывая заголовок Content-Type: application/json — без него многие серверы не распознают тело запроса.

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

Ответ = Соединение.ОтправитьДляОбработки(Запрос);

Ответ сервера разбирается обратным методом — ЧтениеJSON. Обязательно проверяйте код ответа: 200 или 201 означают успех, коды 4xx указывают на ошибку в вашем запросе (невалидный JSON, отсутствующие поля, неверный токен), коды 5xx — на проблему на стороне сервера, где имеет смысл повторная отправка с задержкой.

Как проверить, что JSON сформирован корректно

Простейшая проверка — разобрать сформированную строку обратно через ЧтениеJSON. Если разбор прошёл без исключения и все поля на месте, синтаксис корректен. Дополнительно вставьте строку в любой онлайн-валидатор JSON, чтобы увидеть структуру в читаемом виде.

Проверяйте не только синтаксис, но и соответствие контракту внешнего API: имена полей, типы значений, обязательность полей. Типичная ситуация — JSON валиден, но сервер отвечает ошибкой 400, потому что поле названо customer вместо client или число передано строкой. Сверяйтесь с документацией API и смотрите текст ошибки в ответе.

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

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

Синтаксис JSON

Норма

ЧтениеJSON разбирает строку без исключения, структура данных совпадает с ожидаемой

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

Ошибка разбора — ищите непарные скобки, лишние запятые, неэкранированные кавычки

Имена и типы полей

Норма

Имена совпадают с документацией API, числа — числами, булево — true/false

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

Сервер отвечает 400 с указанием на неизвестное или неверное поле

Даты

Норма

Строка в формате ISO 8601, внешняя система корректно её парсит

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

Дата смещена на часовой пояс или не распознаётся

Кодировка

Норма

UTF-8, кириллица передаётся без искажений

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

Кракозябры вместо русских букв — проверьте КодировкаТекста.UTF8 при установке тела

Ограничения и нюансы, о которых стоит знать

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

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

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

Чем отличается Структура от Соответствия при формировании JSON?

Структура требует, чтобы ключи были допустимыми идентификаторами встроенного языка — без пробелов, дефисов и цифры в начале. Соответствие принимает любые строковые ключи, поэтому используйте его, когда API требует поля вида "order-id" или "1c_code". В JSON оба варианта сериализуются одинаково — как объект.

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

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

Почему в JSON попадают кракозябры вместо русских букв?

Проблема почти всегда в кодировке при передаче или записи в файл. При отправке по HTTP указывайте УстановитьТелоИзСтроки с КодировкаТекста.UTF8, при записи в файл через ЗаписьТекста выбирайте кодировку UTF-8. Сам ЗаписьJSON корректно работает с Unicode.

Как передать в JSON файл или картинку?

JSON не хранит двоичные данные напрямую. Стандартное решение — прочитать файл в двоичные данные и закодировать в Base64 через Base64Строка(), затем вставить результат как строковое поле. Учтите, что размер данных при этом вырастает примерно на треть, поэтому большие файлы лучше передавать отдельным multipart-запросом.

Можно ли сформировать JSON без программирования, типовой обработкой?

В типовых конфигурациях есть механизмы обмена (например, обмен с сайтом, ЭДО), которые формируют данные автоматически, но произвольный JSON по своему шаблону без кода не создать. Для разовой выгрузки можно написать небольшую внешнюю обработку — это 20–30 строк кода по образцам из статьи.

Что делать, если внешняя система требует массив в корне JSON, а не объект?

Передайте в ЗаписатьJSON массив напрямую: ЗаписатьJSON(Запись, МассивДанных). Платформа корректно сериализует корневой массив. При потоковой записи начните с ЗаписатьНачалоМассива вместо ЗаписатьНачалоОбъекта.