Что такое JSON в 1С и как с ним работать

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

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

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

Что такое JSON и почему он стал стандартом для 1С

JSON (JavaScript Object Notation) — компактный текстовый формат, в котором данные описываются парами «ключ: значение». Поддерживаются строки, числа, булевы значения, null, массивы и вложенные объекты. Формат легко читается человеком и одинаково понимается практически всеми языками программирования.

В экосистеме 1С JSON вытеснил XML в задачах веб-интеграции: он короче, проще парсится и именно его ожидают REST API маркетплейсов, служб доставки, банков и CRM. XML остаётся актуальным для регламентированного обмена (ЭДО, отчётность, форматы ФНС), а JSON — для «живых» HTTP-запросов к внешним сервисам.

Какие объекты платформы отвечают за JSON

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

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

Как записать данные в JSON из 1С

Самый короткий путь — собрать данные в структуру и сериализовать её одной функцией. Это удобно для формирования тела HTTP-запроса к внешнему API.

Данные = Новый Структура;
Данные.Вставить("Номенклатура", "Кабель ВВГ 3х2.5");
Данные.Вставить("Количество", 10);
Данные.Вставить("Активен", Истина);

Запись = Новый ЗаписьJSON;
Запись.УстановитьСтроку();
ЗаписатьJSON(Запись, Данные);
СтрокаJSON = Запись.Закрыть();
// {"Номенклатура":"Кабель ВВГ 3х2.5","Количество":10,"Активен":true}

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

Как прочитать JSON в 1С

Обратная задача — разобрать ответ внешнего сервиса. Если структура ответа известна, достаточно одной функции ПрочитатьJSON(), которая вернёт структуру или соответствие.

Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(ТелоОтвета);
Результат = ПрочитатьJSON(Чтение, Истина); // Истина = читать в Соответствие
Чтение.Закрыть();

Статус = Результат["status"];
Для Каждого Элемент Из Результат["items"] Цикл
// обработка каждого элемента массива
КонецЦикла;

Чтение в соответствие (второй параметр Истина) безопаснее: внешний API может прислать ключи с дефисами или пробелами, которые недопустимы как имена свойств структуры. При чтении в структуру такой документ вызовет ошибку.

Потоковое чтение для сложных документов

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

Отправка JSON через HTTP-запрос

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

1. 1
   Сформируйте данные в Структуре или Соответствии и сериализуйте через ЗаписатьJSON
2. 2
   Создайте HTTPСоединение с указанием сервера, при необходимости — с SSL
3. 3
   Создайте HTTPЗапрос, установите заголовок Content-Type: application/json и тело запроса
4. 4
   Выполните метод (POST/GET) и проверьте код ответа: 2xx — успех, 4xx/5xx — ошибка
5. 5
   Разберите тело ответа через ПрочитатьJSON и проверьте обязательные поля перед использованием

Код ответа проверяют всегда: внешний сервис может вернуть ошибку в теле при статусе 200, а может вернуть HTML-страницу вместо JSON при сбое шлюза. Попытка разобрать такой ответ через ПрочитатьJSON() завершится исключением — его стоит обернуть в Попытка...Исключение с записью тела ответа в журнал регистрации.

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

Большинство проблем возникает не из-за самого формата, а из-за несоответствия типов и ожиданий. Дата в 1С и дата во внешнем API записываются по-разному, числа могут приходить строками, а отсутствующее поле — ломать логику обращения к структуре.

Отдельная группа ошибок — кодировка. Строку JSON для HTTP-запроса формируют в UTF-8; если внешний сервис отвечает в другой кодировке, кириллица в разобранных данных превратится в нечитаемые символы. Проверить это проще всего, выведя сырой ответ до разбора.

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

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

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

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

Синтаксис JSON

Норма

ПрочитатьJSON разбирает строку без исключения, все ключи на месте

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

Ошибка «Недопустимый символ» — лишняя запятая, незакрытая скобка или одинарные кавычки

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

Норма

Числа приходят числами, булево — булевом, массивы — массивами

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

Числа строками, null вместо значения, объект вместо массива

Кириллица

Норма

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

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

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

HTTP-обмен

Норма

Код ответа 2xx и тело разбирается как JSON

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

Код 4xx/5xx или HTML в теле ответа

Когда JSON не подходит и что использовать вместо

JSON — не универсальное решение. Для регламентированного электронного документооборота, обмена с госсистемами и типовых планов обмена в 1С применяется XML с жёсткими схемами. Для обмена между базами 1С часто удобнее штатные механизмы: планы обмена, EnterpriseData, веб-сервисы или прямое COM/OData-подключение.

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

JSON + HTTP

Интеграция с внешними API, сайтами, мобильными приложениями. Требует ручной обработки ошибок и контроля форматов

XML / EnterpriseData

Типовой обмен между конфигурациями 1С и регламентированный ЭДО. Избыточен для простых веб-запросов

OData

Доступ к данным базы 1С извне без программирования на стороне 1С. Требует публикации и настройки прав

Планы обмена

Регулярная синхронизация между базами 1С с контролем изменений. Не подходит для произвольных внешних систем

Часто задаваемые вопросы

Чем ПрочитатьJSON отличается от ЧтениеJSON?

ЧтениеJSON — это объект потокового разбора: вы вручную двигаетесь по документу методом Прочитать(). ПрочитатьJSON — глобальная функция, которая использует объект ЧтениеJSON внутри себя и сразу возвращает готовую Структуру или Соответствие целиком.

Почему при чтении JSON возникает ошибка «Недопустимое имя свойства»?

Потому что документ читается в Структуру, а ключ содержит символы, запрещённые для имён свойств, — дефис, пробел, цифру в начале. Решение — читать с параметром ПрочитатьВСоответствие = Истина и обращаться к данным через квадратные скобки.

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

Штатный сериализатор записывает дату в строковом виде. Формат нужно согласовать с принимающей стороной: чаще всего используют ISO 8601. При чтении строковую дату преобразуют обратно вручную или через параметры восстановления даты в ПрочитатьJSON.

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

Напрямую — нет, ссылки не являются JSON-совместимым типом. Обычно передают строковое представление уникального идентификатора (Строка(Ссылка.УникальныйИдентификатор())) или заранее подготовленную структуру с нужными полями объекта.

Что делать, если внешний сервис возвращает ответ не в UTF-8?

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

Есть ли в 1С проверка JSON по схеме, как XSD для XML?

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