При работе с внешними API разработчики часто сталкиваются с ситуацией, когда стандартный запрос возвращает лишь краткую информацию (например, только список заказов без состава товаров). В современных системах, таких как CloudShop и аналогичные, для получения расширенных данных используется механизм включений (include). В этой статье мы разберем, как правильно сформировать запрос в 1С, чтобы сервер вернул полную информацию, включая товары, остатки и оплаты.
Рассмотрим стандартную ситуацию: при отправке обычного GET-запроса на эндпоинт selling/orders/index мы получаем массив данных, в котором есть ID заказа, дата и имя покупателя, но отсутствуют вложенные сущности, такие как позиции товаров (goods_items). В инструментах тестирования API (например, Postman) расширение ответа достигается добавлением структуры include в тело запроса. Однако в 1С начинающие разработчики часто пытаются добавить эти параметры в строку запроса, что не всегда работает корректно.
Важно понимать разницу между типами запросов. Несмотря на то что получение данных традиционно ассоциируется с GET, многие современные API требуют использования POST-запроса, если в него необходимо передать сложную структуру параметров в формате JSON. Проанализируем, как реализовать это в коде 1С.
Если структура параметров статична и не требует сложной логики формирования, мы можем передать JSON-строку напрямую в тело запроса. Разберем этот пример:
// Сначала создаем запрос, указывая путь к методу
Запрос = Новый HTTPЗапрос("selling/orders/index", Заголовки);
// Формируем строку JSON в точном соответствии с требованиями API
ТелоЗапроса = "{""include"": [""goods_items.reserves"", ""goods_outlet_items"", ""payment"", ""receipts""]}";
// Устанавливаем тело запроса
Запрос.УстановитьТелоИзСтроки(ТелоЗапроса);
// Отправляем запрос методом POST (для 1С это ОтправитьДляОбработки)
РезультатЗапроса = Соединение.ОтправитьДляОбработки(Запрос);
В данном случае мы используем метод ОтправитьДляОбработки объекта HTTPСоединение, который соответствует HTTP-методу POST. Это критически важный момент: метод Получить (GET) в 1С не поддерживает передачу тела запроса в явном виде.
Для более гибкой разработки рекомендуется использовать встроенные средства работы с JSON. Это позволит динамически добавлять или удалять поля в зависимости от условий задачи, а также гарантирует отсутствие ошибок в синтаксисе кавычек. Разберем процесс по шагам:
include.
// 1. Формируем массив необходимых расширений
МассивДопПолей = Новый Массив;
МассивДопПолей.Добавить("goods_outlet_items");
МассивДопПолей.Добавить("goods_items.reserves");
МассивДопПолей.Добавить("payment");
МассивДопПолей.Добавить("receipts");
// 2. Помещаем его в структуру
СтруктураЗапроса = Новый Структура;
СтруктураЗапроса.Вставить("include", МассивДопПолей);
// 3. Сериализация в JSON
ЗаписьJSON = Новый ЗаписьJSON;
НастройкиСериализации = Новый НастройкиСериализацииJSON;
НастройкиСериализации.ФорматСериализацииДаты = ФорматДатыJSON.ISO;
ЗаписьJSON.УстановитьСтроку();
ЗаписатьJSON(ЗаписьJSON, СтруктураЗапроса, НастройкиСериализации);
ТелоЗапроса = ЗаписьJSON.Закрыть();
// 4. Установка тела и отправка
Запрос.УстановитьТелоИзСтроки(ТелоЗапроса, КодировкаТекста.UTF8);
РезультатЗапроса = Соединение.ОтправитьДляОбработки(Запрос);
Использование объектов ЗаписьJSON и НастройкиСериализацииJSON позволяет нам контролировать формат дат и кодировку, что крайне важно для стабильной интеграции.
После получения ответа сервер возвращает JSON, содержащий полную информацию. Одной из проблем при чтении JSON в 1С является формат дат. В строке ответа они часто приходят в виде 2024-08-13 15:18:26. Проанализируем функцию для правильного преобразования такой строки в тип Дата 1С:
Функция ПреобразоватьДатуAPI(Значение) Экспорт
Результат = Дата(1, 1, 1);
Если Значимо(Значение) Тогда
// Очищаем строку от лишних символов для приведения к формату ГГГГММДДЧЧММСС
СтрДаты = СтрЗаменить(Значение, "-", "");
СтрДаты = СтрЗаменить(СтрДаты, "T", "");
СтрДаты = СтрЗаменить(СтрДаты, ":", "");
СтрДаты = СтрЗаменить(СтрДаты, " ", "");
Результат = Дата(Лев(СтрДаты, 14));
КонецЕсли;
Возврат Результат;
КонецФункции
При использовании функции ПрочитатьJSON мы можем указать массив имен свойств, которые должны быть автоматически распознаны как даты. Это упрощает код и делает его более читаемым.
При интеграции с реальными базами заказов их количество может исчисляться тысячами. Важно помнить, что API не вернет все заказы сразу. Разберем дополнительные параметры, которые стоит добавить в наш JSON-запрос:
"page": 1 для перехода по страницам данных.updated_at_from, чтобы забирать из системы только те заказы, которые изменились с момента последней синхронизации. Это значительно снизит нагрузку на сеть и 1С.per_page поможет регулировать количество заказов в одном пакете (обычно от 15 до 100).Для успешной отправки запросов не забудьте правильно инициализировать HTTPСоединение. Если сайт работает по протоколу HTTPS (порт 443), необходимо использовать защищенное соединение. Проанализируем пример настройки:
ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
Соединение = Новый HTTPСоединение(
"адрес.сервера.api", // Адрес хоста без https://
443, // Порт
, , , , // Логин/пароль (если не используются в заголовках)
ЗащищенноеСоединение
);
// Не забывайте устанавливать Content-Type, иначе сервер может не понять JSON
Заголовки = Новый Соответствие;
Заголовки.Вставить("Content-Type", "application/json");
Заголовки.Вставить("Authorization", "Bearer " + ТокенДоступа);
Подведем итог: для получения полной информации о заказах через внешнее API в 1С необходимо использовать метод POST (функция ОтправитьДляОбработки), передавать параметры в формате JSON через тело запроса (УстановитьТелоИзСтроки) и обязательно указывать расширяемые поля в ключе include. Такой подход обеспечит получение всех вложенных данных (товаров, платежей) за один запрос, что существенно оптимизирует работу алгоритмов обмена данными.