Как правильно реализовать соединение 1С с API банка через HTTP и настроить подпись запросов?

← На главную

Интеграция 1С с банковскими сервисами — одна из самых ответственных задач программиста. Чаще всего сложности возникают не на этапе написания кода, а на этапе соблюдения строгих требований безопасности и протоколов обмена данными. В этой статье мы подробно разберем процесс создания HTTP-запроса к банковскому API, проанализируем типичные ошибки начинающих разработчиков и выясним, как правильно подписывать данные с помощью HMAC-SHA256.

Выбор правильного метода HTTP-запроса

Рассмотрим распространенную ситуацию: разработчик пытается передать данные в формате JSON, используя метод Получить() (GET). Это критическая ошибка. В архитектуре REST API метод GET предназначен исключительно для получения данных, и он не предполагает наличия тела запроса (body). Если вам необходимо передать параметры в формате JSON, практически всегда следует использовать метод POST или его аналоги.

В языке 1С для отправки данных на сервер используются методы ОтправитьДляОбработки() или ВызватьHTTPМетод(). Проанализируем пример корректного вызова:


// Создаем соединение
Соединение = Новый HTTPСоединение("u2-demo-ext.mono.st4g3.com", 443, , , , , Новый ЗащищенноеСоединениеOpenSSL());

// Подготавливаем запрос
Запрос = Новый HTTPRequest("/api/order/confirm");
// ... установка заголовков и тела ...

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

Использование ЗащищенноеСоединениеOpenSSL обязательно для банковских API, так как они работают исключительно по протоколу HTTPS. Если не указать этот объект в конструкторе HTTPСоединение, система выдаст ошибку при попытке установить связь на порту 443.

Формирование JSON-тела запроса

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


ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();
ЗаписьJSON.ЗаписатьНачалоОбъекта();
ЗаписьJSON.ЗаписатьИмяСвойства("phone");
ЗаписьJSON.ЗаписатьЗначение("+380963876251");
ЗаписьJSON.ЗаписатьКонецОбъекта();

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

Важно помнить, что регистр имен свойств в JSON имеет значение. Если документация API требует orderId, то использование orderid приведет к ошибке 400 (Bad Request). Также обратите внимание на кодировку: банковские серверы ожидают UTF-8.

Реализация цифровой подписи (Signature)

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

Алгоритм подписи обычно выглядит так:

Берется тело запроса (строка JSON).
Вычисляется хеш-функция HMAC-SHA256 с использованием секретного ключа, выданного банком.
Результат переводится в формат Base64.

В стандартной платформе 1С (до последних версий) нет прямой функции HMAC_SHA256. Программисты часто используют возможности Windows через COM-объекты или внешние компоненты. Разберем логику формирования заголовков:


Заголовки = Новый Соответствие;
Заголовки.Вставить("Content-Type", "application/json; charset=utf-8");
Заголовки.Вставить("store-id", "ваш_id_магазина");

// Здесь должна быть функция расчета HMAC-SHA256
Подпись = СформироватьПодписьHMAC(СтрJSON, "ваш_секретный_ключ");
Заголовки.Вставить("signature", Подпись);

Запрос = Новый HTTPЗапрос("/api/client/validate", Заголовки);
Запрос.УстановитьТелоИзСтроки(СтрJSON, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);

Обратите внимание на Byte Order Mark (BOM). При установке тела из строки крайне рекомендуется использовать параметр ИспользованиеByteOrderMark.НеИспользовать. Наличие невидимых символов BOM в начале запроса часто становится причиной того, что сервер банка не может правильно рассчитать хеш и отклоняет запрос с ошибкой 401.

Пошаговая методика отладки

Если код возвращает ошибку, не спешите менять строки в 1С. Выясним причину с помощью системного подхода:

Использование внешних инструментов: Попробуйте выполнить запрос через Postman или cURL. Если запрос проходит там, значит проблема в коде 1С. Если не проходит и там — вы неправильно понимаете документацию API или используете неверные ключи.
Проверка параметров: Убедитесь, что вы обращаетесь к нужному "эндпоинту" (URL). Например, данные клиента нужно слать на /api/client/validate, а подтверждение заказа — на /api/order/confirm. Перепутанные URL — частая причина ошибки 404 или 405.
Анализ ответа сервера: Не ограничивайтесь просмотром кода состояния (например, 400). Всегда читайте тело ответа сервера. Банк часто присылает детальное описание ошибки в JSON-формате.

Рассмотрим, как получить текст ошибки в 1С:


Ответ = Соединение.ОтправитьДляОбработки(Запрос);
Если Ответ.КодСостояния <> 200 Тогда
    ТекстОшибки = Ответ.ПолучитьТелоКакСтроку();
    Сообщить("Ошибка API: " + Ответ.КодСостояния + " Подробности: " + ТекстОшибки);
КонецЕсли;

Заключение

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