JSON в 1С: ЗаписьJSON, ПрочитатьJSON, структура и соответствие

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

Что такое JSON в 1С и когда он лучше XDTO?

JSON это текстовый формат обмена: объекты в фигурных скобках, массивы в квадратных, строки, числа, true, false и null. В 1С он ложится на три коллекции: объект JSON становится структурой или соответствием, массив JSON становится массивом. Больше платформе ничего не нужно, схему данных описывать не надо.

В 1С есть и второй путь обмена, XDTO: пакет со схемой, фабрика, сериализатор. Он нужен, когда с обеих сторон 1С или когда формат задан XSD-схемой. Для всего остального я беру JSON:

Подробно про XDTO, фабрику и пакеты я писал в статье XDTO в 1С: XML и JSON. Здесь речь только о JSON.

Как записать JSON в 1С: ЗаписьJSON и ЗаписатьJSON

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

Функция ЗаписатьСтрокуJSON(Данные, ФормироватьСПереносами = Ложь) Экспорт

    ЗаписьJSON = Новый ЗаписьJSON;
    Если ФормироватьСПереносами Тогда
        // Читаемый JSON с отступами табуляцией: для отладки и логов
        ЗаписьJSON.УстановитьСтроку(Новый ПараметрыЗаписиJSON(, Символы.Таб));
    Иначе
        // Одна строка без переносов: для передачи по сети
        ЗаписьJSON.УстановитьСтроку(Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Нет, Символы.Таб));
    КонецЕсли;

    НастройкиСериализацииJSON = Новый НастройкиСериализацииJSON;
    НастройкиСериализацииJSON.ВариантЗаписиДаты = ВариантЗаписиДатыJSON.ЛокальнаяДатаСоСмещением;
    НастройкиСериализацииJSON.ФорматСериализацииДаты = ФорматДатыJSON.ISO;

    ЗаписатьJSON(ЗаписьJSON, Данные, НастройкиСериализацииJSON);

    // Закрыть() для записи в строку возвращает готовый текст JSON
    Возврат ЗаписьJSON.Закрыть();
КонецФункции

Обратите внимание на последнюю строку: при записи в строку Закрыть() возвращает результат. Отдельного метода «получить строку» нет.

Чтобы собрать структуру в JSON, данные готовят обычными коллекциями. Вот так в учебном HTTP-сервисе формируется список товаров:

МассивТоваров = Новый Массив;

СтруктураТовара = Новый Структура;
СтруктураТовара.Вставить("UUID", "86fabe85-8300-11ea-847a-3085a93c8c97");
СтруктураТовара.Вставить("Name", "Товар 1");
МассивТоваров.Добавить(СтруктураТовара);

ДанныеJSON = ЗаписатьСтрокуJSON(МассивТоваров, Истина);

На выходе получается массив объектов:

[
    {
        "UUID": "86fabe85-8300-11ea-847a-3085a93c8c97",
        "Name": "Товар 1"
    }
]

Какие типы 1С можно записать в JSON?

ЗаписатьJSON принимает не всё подряд. Без дополнительной обработки записываются:

Ссылку на справочник, таблицу значений или объект документа напрямую передать нельзя, платформа остановится на ошибке о недопустимом типе. Их сначала перекладывают в структуру или соответствие.

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

Таблицу значений проще всего превратить в массив соответствий: строка таблицы становится объектом JSON, колонки становятся его свойствами. Ссылку записывают как строку с уникальным идентификатором через XMLСтрока. Фрагмент из учебной конфигурации, где я сравниваю JSON и XDTO на выгрузке справочника:

Выгрузка = РезультатЗапроса.Выгрузить();
Данные = Новый Массив;

Для каждого ТекущийЭлемент Из Выгрузка Цикл
    СтруктураДанных = Новый Соответствие;
    СтруктураДанных.Вставить("Ссылка",          XMLСтрока(ТекущийЭлемент.Ссылка));
    СтруктураДанных.Вставить("ПометкаУдаления", ТекущийЭлемент.ПометкаУдаления);
    СтруктураДанных.Вставить("Код",             ТекущийЭлемент.Код);
    СтруктураДанных.Вставить("Наименование",    ТекущийЭлемент.Наименование);
    Данные.Добавить(СтруктураДанных);
КонецЦикла;

Так же решается запрос «массив структур в JSON»: массив, в каждом элементе структура или соответствие, и одним вызовом ЗаписатьJSON всё уходит в строку.

Как записать JSON в файл?

Вместо УстановитьСтроку вызывается ОткрытьФайл. Четвёртым параметром передаются те же ПараметрыЗаписиJSON:

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

ЗаписьJSON.ОткрытьФайл(КаталогВременныхФайлов() + "ВыгрузкаJSON.txt",,, ПараметрыЗаписиJSON);
ЗаписатьJSON(ЗаписьJSON, Данные);
ЗаписьJSON.Закрыть();

Второй и третий параметры ОткрытьФайл задают кодировку и запись BOM. Если файл будет читать не 1С, а скрипт на Python или PHP, кодировку лучше задать явно: UTF-8.

Экранирование: кириллица, слеши и кавычки

По умолчанию 1С пишет кириллицу как есть. Некоторым API нужно иначе. Подпись запроса к Amazon S3, например, считается от строки, где всё вне ASCII заменено на \uXXXX. Для таких случаев у ПараметрыЗаписиJSON есть параметры экранирования:

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

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

Как прочитать JSON в 1С: в структуру или в соответствие?

Чтение зеркально записи: ЧтениеJSON, источник (строка или файл) и глобальная функция ПрочитатьJSON. Её второй параметр решает, во что превратятся объекты JSON: Ложь даёт структуру, Истина даёт соответствие. Рабочий вариант из конфигурации с JWT-авторизацией:

Функция ПрочитатьСтрокуJSON(Знач СтрокаJSON, Знач ИменаСвойствСоЗначениямиДата = Неопределено,
    ПрочитатьВСоответствие = Истина) Экспорт

    Результат = Неопределено;

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

    Возврат Результат;
КонецФункции

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

Почему соответствие безопаснее структуры?

Строку JSON в структуру прочитать можно, и часто так и делают. Я по умолчанию читаю в соответствие, и у этого три причины.

1. Имена свойств. Ключ структуры обязан быть правильным идентификатором 1С. Свойства order-id, 1c_code или @type в структуру не лягут, ПрочитатьJSON упадёт на первом же таком ключе. В соответствии ключом может быть любая строка.
2. Регистр. В JSON Name и name это разные свойства, а в структуре 1С это один ключ. Соответствие хранит ключи как есть.
3. Отсутствующие поля. Данные.order при отсутствии свойства даёт исключение. Данные.Получить("order") или Данные["order"] вернёт Неопределено, и это спокойно проверяется в Если.

Как это выглядит в обработчике, который принимает заказ с сайта:

Данные = ns_Обмен.ПрочитатьСтрокуJSON(ДанныеJSON, ИменаСвойствСоЗначениямиДата);

ДанныеЗаказа = Данные.Получить("order");
Если ДанныеЗаказа <> Неопределено Тогда
    Результат = ns_Документы.ДобавитьОбновитьЗаказ(ДанныеЗаказа);
    Если Результат = Неопределено Тогда
        КодОтвета = 400;
    КонецЕсли;
Иначе
    КодОтвета = 400;
КонецЕсли;

Структура удобна, когда формат ваш и стабилен: обращение через точку короче и подсказывается в конфигураторе. Для ответа чужого API выбирайте соответствие.

Чтение JSON из файла

Файл открывается методом ОткрытьФайл, дальше всё так же:

ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.ОткрытьФайл(КаталогВременныхФайлов() + "ВыгрузкаJSON.txt");

Результат = ПрочитатьJSON(ЧтениеJSON, Истина);
ЧтениеJSON.Закрыть();

После чтения из массива соответствий можно восстановить элементы справочника с теми же ссылками. Идентификатор, который при записи ушёл через XMLСтрока, превращается обратно в ссылку:

Для каждого ТекущийОбъект Из СписокОбъектов Цикл
    НоваяСсылка = Справочники.Номенклатура.ПолучитьСсылку(
        Новый УникальныйИдентификатор(ТекущийОбъект["Ссылка"]));

    НовыйОбъект = Справочники.Номенклатура.СоздатьЭлемент();
    НовыйОбъект.УстановитьСсылкуНового(НоваяСсылка);
    НовыйОбъект.Наименование = ТекущийОбъект["Наименование"];
    НовыйОбъект.Код = ТекущийОбъект["Код"];
    НовыйОбъект.Записать();
КонецЦикла;

Даты, числа и null: что происходит при преобразовании

Типов в JSON меньше, чем в 1С, поэтому на границе часть информации теряется. Где именно, проще показать таблицей:

Как передать дату в JSON 1С?

При записи формат даты задают два свойства настроек. ФорматСериализацииДаты = ФорматДатыJSON.ISO даёт строку вида 2026-10-21T15:30:00. ВариантЗаписиДаты = ВариантЗаписиДатыJSON.ЛокальнаяДатаСоСмещением добавляет часовой пояс: +03:00. Смещение я пишу всегда: сервер сайта часто живёт в UTC, и без смещения заказ из 23:30 по Москве попадёт не в тот день.

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

ИменаСвойствСоЗначениямиДата = Новый Массив;
ИменаСвойствСоЗначениямиДата.Добавить("updated_at");
ИменаСвойствСоЗначениямиДата.Добавить("date");

Данные = ПрочитатьСтрокуJSON(Результат.Тело, ИменаСвойствСоЗначениямиДата);

Это рабочий фрагмент из обмена 1С с сайтом на Django. Если в JSON дата в другом формате, например 21.10.2026, такой список не поможет: строку придётся разбирать самостоятельно.

Числа и пустые значения

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

Функция ДобавитьЗначение(ТекущееЗначение, ПреобразоватьЧислоВСтроку = Ложь) Экспорт

    Если НЕ ЗначениеЗаполнено(ТекущееЗначение) Тогда
        Возврат Неопределено; // в JSON уйдёт null
    КонецЕсли;

    Если ТипЗнч(ТекущееЗначение) = Тип("Строка") Тогда
        Возврат СокрЛП(ТекущееЗначение);
    КонецЕсли;

    Если ТипЗнч(ТекущееЗначение) = Тип("Число") Тогда
        Если ПреобразоватьЧислоВСтроку Тогда
            Возврат Формат(ТекущееЗначение, "ЧДЦ=2; ЧРГ=''; ЧГ=0");
        Иначе
            Возврат ТекущееЗначение;
        КонецЕсли;
    КонецЕсли;

    Если ТипЗнч(ТекущееЗначение) = Тип("Дата") Тогда
        Возврат Формат(ТекущееЗначение, "ДФ=yyyy-MM-dd");
    КонецЕсли;

    // Ссылку на справочник отдаём идентификатором
    МетаданныеПолноеИмя = ТекущееЗначение.Метаданные().ПолноеИмя();
    Если СтрНайти(МетаданныеПолноеИмя, "Справочник") > 0 Тогда
        Возврат XMLСтрока(ТекущееЗначение);
    КонецЕсли;

    Возврат Неопределено;
КонецФункции

Здесь же решено, что пустое значение уходит как null, а не как 0 или "". О таком правиле лучше договориться с другой стороной заранее: для сайта «цена 0» и «цены нет» совсем не одно и то же.

Большой JSON: потоковая запись и чтение

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

На больших объёмах ЗаписьJSON пишут по элементам. В учебных конфигурациях такого кода нет, поэтому пример короткий и строго по синтаксис-помощнику:

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.ОткрытьФайл(ИмяФайла);

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

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

Выборка запроса читается по одной строке, и в памяти не копится ничего. Чтение тоже можно вести по токенам: ЧтениеJSON.Прочитать() сдвигается на следующий элемент, ТипТекущегоЗначения говорит, что под курсором, ТекущееЗначение отдаёт значение. Удобнее всего комбинировать: дойти до начала очередного объекта в массиве и прочитать только его через ПрочитатьJSON:

ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.ОткрытьФайл(ИмяФайла);

Пока ЧтениеJSON.Прочитать() Цикл
    Если ЧтениеJSON.ТипТекущегоЗначения = ТипЗначенияJSON.НачалоОбъекта Тогда
        Элемент = ПрочитатьJSON(ЧтениеJSON, Истина); // один объект из массива
        // обработать Элемент и забыть о нём
    КонецЕсли;
КонецЦикла;

ЧтениеJSON.Закрыть();

Для HTTP-обмена объём лучше резать ещё раньше, страницами: клиент просит ?page=3, сервис отдаёт сто записей и ссылку на следующую страницу. Как это сделано в бэкенде для мобильного приложения, показано в статье про JSON и пагинацию в HTTP-сервисе 1С.

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

JSON в HTTP-запросе и HTTP-сервисе

Чаще всего JSON в 1С ходит по HTTP. Тут есть две стороны: 1С вызывает чужой API или сама отвечает как HTTP-сервис.

1С отправляет POST-запрос с JSON

Функция из обмена с сайтом на Django. Тело ставится через УстановитьТелоИзСтроки с кодировкой UTF-8 и без BOM, заголовок Content-Type объявлен явно:

HTTPСоединение = Новый HTTPСоединение(АдресСервера, Порт,,,, 30, SSL);

Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", СтрШаблон("Token %1", Токен));
Заголовки.Вставить("Content-Type", "application/json");

HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, Заголовки);
HTTPЗапрос.УстановитьТелоИзСтроки(СформироватьJSON(ДанныеДляЗапроса),
    КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);

Результат = HTTPСоединение.ВызватьHTTPМетод("POST", HTTPЗапрос);

ДанныеВозврата = Новый Структура("Код, Тело", Результат.КодСостояния, Результат.ПолучитьТелоКакСтроку());

Ответ разбирается только после проверки кода состояния. Если сервер вернул 500 или 502, в теле HTML-страница ошибки, и ПрочитатьJSON на ней споткнётся о первый же символ <.

1С принимает и отдаёт JSON в HTTP-сервисе

Обработчик POST из учебного REST API, к которому обращается Python-клиент:

Функция ProductsV1POST(Запрос)
    ДанныеJSON = Запрос.ПолучитьТелоКакСтроку();
    Данные = ПрочитатьСтрокуJSON(ДанныеJSON);

    ДанныеОтвета = СформироватьДанныеОтвета();
    Попытка
        Возврат ВернутьДанные(ДанныеОтвета,
            Новый Структура("message, data", "Товары добавлены в базу", Данные), 200);
    Исключение
        Возврат ВернутьОшибку(ДанныеОтвета, ОписаниеОшибки(), 501);
    КонецПопытки;
КонецФункции

Функция СформироватьОтвет(Данные, Код)
    Ответ = Новый HTTPСервисОтвет(Код);
    Ответ.Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");

    ДанныеJSON = ЗаписатьСтрокуJSON(Данные, Истина);

    Ответ.УстановитьТелоИзСтроки(ДанныеJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
    Возврат Ответ;
КонецФункции

У ответа единый конверт: соответствие с ключами response и error. Клиенту не нужно гадать, где данные, а где описание ошибки. Как создать сам сервис, настроить шаблоны URL и опубликовать его, разобрано в статье HTTP-сервисы 1С. Если доступ к сервису закрыт токеном, полезная нагрузка JWT тоже JSON, и функции записи и чтения там те же; пример в разборе JWT-авторизации в 1С.

Сериализация объектов: когда нужен СериализаторXDTO

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

Процедура СериализоватьXDTO_JSON(ОбъектСериализации) Экспорт
    ЗаписьJSON = Новый ЗаписьJSON;
    ПараметрыЗаписиJSON = Новый ПараметрыЗаписиJSON(, Символы.Таб);
    ЗаписьJSON.ОткрытьФайл(КаталогВременныхФайлов() + "ВыгрузкаXDTO_JSON.txt",,, ПараметрыЗаписиJSON);

    СериализаторXDTO.ЗаписатьJSON(ЗаписьJSON, ОбъектСериализации, НазначениеТипаXML.Явное);

    ЗаписьJSON.Закрыть();
КонецПроцедуры

Функция ДесериализоватьXDTO_JSON() Экспорт
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.ОткрытьФайл(КаталогВременныхФайлов() + "ВыгрузкаXDTO_JSON.txt");

    ДесериализованныйОбъект = СериализаторXDTO.ПрочитатьJSON(ЧтениеJSON);

    ЧтениеJSON.Закрыть();
    Возврат ДесериализованныйОбъект;
КонецФункции

Формально это JSON, но со служебными полями 1С о типах. Сайт на Laravel такую выгрузку без отдельного разбора не поймёт, другая база 1С с той же конфигурацией прочитает её одной строкой. Отсюда правило: сериализатор нужен для обмена 1С ↔ 1С, а для внешних систем данные собирают в структуры и соответствия вручную. Как работают фабрика XDTO и пакеты и чем отличается выгрузка в XML, разобрано в статье XDTO в 1С.

Почему 1С пишет «Непредвиденный символ при чтении JSON» и что делать с другими ошибками

Сразу скажу, ошибки JSON в 1С почти всегда сводятся к пяти ситуациям:

Есть ещё одна частая и при этом тихая ошибка: дата строкой там, где ждали Дата. Код не падает, но сравнение Данные["date"] > НачалоДня(ТекущаяДата()) сравнивает строку с датой. Если поле хранит дату, внесите его в ИменаСвойствСоЗначениямиДата.

Где отработать JSON-обмен на практике

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