Как передать параметры в POST-запросе в 1С

POST-запросы в 1С выполняются через объекты HTTPСоединение и HTTPЗапрос. Параметры при этом могут передаваться тремя способами: в адресной строке (query-параметры), в теле запроса (строка, JSON, двоичные данные) и в заголовках. Какой способ выбрать — определяется документацией конкретного API, с которым вы интегрируетесь.

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

Базовая схема POST-запроса в 1С

Минимальный каркас любого POST-запроса состоит из трёх объектов: соединения, запроса и ответа. Соединение создаётся с указанием сервера и порта, запрос — с указанием ресурса (пути на сервере), затем вызывается метод ОтправитьДляОбработки(), который и выполняет POST.

SSL = Новый ЗащищенноеСоединениеOpenSSL();
Соединение = Новый HTTPСоединение("api.example.com", 443, , , , , SSL);

Запрос = Новый HTTPЗапрос("/v1/orders");
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.УстановитьТелоИзСтроки("{""name"":""Тест""}", КодировкаТекста.UTF8);

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

Обратите внимание: метод ОтправитьДляОбработки() — это и есть POST. Метод Получить() выполняет GET, Записать() — PUT. Путать их нельзя: многие API принимают параметры только через POST и вернут ошибку 405 при другом методе.

Передача параметров в адресной строке

Query-параметры дописываются к ресурсу после знака вопроса и работают в том числе в POST-запросах. Так часто передают ключи доступа, номера страниц, идентификаторы операций. Пример: /v1/orders?api_key=abc123&limit=50.

Ресурс = "/v1/orders?api_key=" + КлючAPI + "&limit=50";
Запрос = Новый HTTPЗапрос(Ресурс);

Значения параметров нужно кодировать функцией КодироватьСтроку() с способом СпособКодированияСтроки.КодировкаURL, иначе пробелы, кириллица и спецсимволы сломают запрос. Это одна из самых частых причин ошибки 400 от сервера.

Значение = КодироватьСтроку(НазваниеТовара, СпособКодированияСтроки.КодировкаURL);
Ресурс = "/v1/search?query=" + Значение;

Передача параметров в теле запроса

Строка и JSON

Основной способ — метод УстановитьТелоИзСтроки(). Для JSON-API тело формируется либо конкатенацией строк, либо правильнее — через ЗаписьJSON, которая сама экранирует кавычки и спецсимволы.

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписьJSON.ЗаписатьНачалоОбъекта();
ЗаписьJSON.ЗаписатьИмяСвойства("number");
ЗаписьJSON.ЗаписатьЗначение("00123");
ЗаписьJSON.ЗаписатьИмяСвойства("date");
ЗаписьJSON.ЗаписатьЗначение(Формат(ТекущаяДатаСеанса(), "ДФ=yyyy-MM-dd"));
ЗаписьJSON.ЗаписатьКонецОбъекта();

ТелоJSON = ЗаписьJSON.Закрыть();

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

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

Двоичные данные и файлы

Если нужно передать файл (например, отправить PDF или картинку в API), используется УстановитьТелоИзДвоичныхДанных() или УстановитьИмяФайлаТела(). Второй вариант удобен для больших файлов — 1С не загружает их целиком в память.

Запрос = Новый HTTPЗапрос("/v1/upload");
Запрос.Заголовки.Вставить("Content-Type", "application/octet-stream");
Запрос.УстановитьИмяФайлаТела("C:\Temp\invoice.pdf");

Форма application/x-www-form-urlencoded

Некоторые API (например, сервисы авторизации OAuth) требуют параметры в теле в формате формы: login=user&password=123&grant_type=password. Тело собирается строкой, а в заголовке указывается соответствующий тип.

Тело = "grant_type=client_credentials&client_id=" + ИдКлиента + "&client_secret=" + Секрет;
Запрос = Новый HTTPЗапрос("/oauth/token");
Запрос.Заголовки.Вставить("Content-Type", "application/x-www-form-urlencoded");
Запрос.УстановитьТелоИзСтроки(Тело, КодировкаТекста.UTF8);

Значения в таком теле тоже нужно URL-кодировать, особенно пароли со спецсимволами &, =, %. Без кодирования сервер неверно разберёт пары «ключ=значение».

Передача параметров через заголовки

Заголовки задаются через коллекцию Запрос.Заголовки методом Вставить(). Через них передают токены авторизации, тип содержимого, идентификаторы клиентов. Типовой набор для работы с защищённым API:

Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Запрос.Заголовки.Вставить("Accept", "application/json");
Запрос.Заголовки.Вставить("X-Request-Id", Строка(Новый УникальныйИдентификатор));

Имена заголовков нечувствительны к регистру, но значения — чувствительны. Токен с лишним пробелом или в неверном регистре приведёт к ошибке 401, хотя сам запрос сформирован правильно.

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

После отправки обязательно анализируйте Ответ.КодСостояния. Успешные коды — 200, 201, 204. Коды 400 и 422 означают ошибку в параметрах, 401 и 403 — проблему с авторизацией, 500 — сбой на стороне сервера. Тело ответа с JSON разбирается через ЧтениеJSON.

Если Ответ.КодСостояния = 200 Тогда
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
Данные = ПрочитатьJSON(Чтение); // структура или соответствие
Чтение.Закрыть();
Иначе
ВызватьИсключение "Ошибка API: " + Ответ.КодСостояния + " " + Ответ.ПолучитьТелоКакСтроку();
КонецЕсли;

Сохраняйте текст ошибки из тела ответа в журнал регистрации — большинство API возвращают там человекочитаемое описание, какой именно параметр не прошёл проверку. Это сокращает отладку с часов до минут.

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

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

Код состояния ответа

Норма

200, 201 или 204

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

400/422 — ошибка в параметрах, 401 — авторизация, 500 — сбой сервера

Тело ответа

Норма

Валидный JSON или ожидаемые данные

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

HTML-страница ошибки или пустое тело при коде 200

Поведение API

Норма

Созданный объект виден в системе-получателе

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

Запрос прошёл, но данных на той стороне нет

Ограничения и безопасность

Вызов HTTP-запроса из серверного кода выполняется под правами пользователя сеанса; для фоновых интеграций используйте регламентные задания с отдельным служебным пользователем. Не храните пароли и токены в коде или в открытых реквизитах — используйте безопасное хранилище или константы с ограниченным доступом.

Устанавливайте таймаут соединения (пятый параметр конструктора HTTPСоединение, в секундах). Без таймаута зависший сервер заблокирует сеанс 1С на неопределённое время, а при вызове из проведения документа — остановит работу пользователей.

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

Как передать структуру 1С как JSON в POST-запросе?

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

Чем ОтправитьДляОбработки() отличается от Получить()?

Первый метод выполняет POST-запрос, второй — GET. Для передачи параметров в теле нужен именно POST; при использовании Получить() тело игнорируется, а сервер обычно возвращает ошибку 405 Method Not Allowed.

Сервер возвращает ошибку 400, хотя параметры верные. Что проверить?

Проверьте заголовок Content-Type, кодировку тела (UTF-8), URL-кодирование значений в адресной строке и экранирование кавычек в JSON. Также посмотрите текст ошибки в теле ответа — там обычно указано, какой параметр отклонён.

Как передать файл через POST из 1С?

Используйте УстановитьИмяФайлаТела() с путём к файлу или УстановитьТелоИзДвоичныхДанных() для данных из хранилища. Укажите корректный Content-Type, а если API требует multipart/form-data — сформируйте границы частей тела вручную строкой.

Можно ли отправить POST-запрос с клиента тонкого или веб-клиента?

HTTPСоединение доступен и на клиенте, но правильнее выполнять запросы на сервере: там нет ограничений браузера, доступны защищённые соединения и не раскрываются токены в клиентском коде.

Как задать таймаут, чтобы запрос не зависал?

Передайте таймаут в секундах пятым параметром конструктора HTTPСоединение, например: Новый HTTPСоединение("api.example.com", 443, , , 30, SSL). Дополнительно оберните вызов в Попытка/Исключение для обработки сетевых сбоев.