Как работать с API в 1С: практическое руководство

Работа с API в 1С сводится к двум противоположным задачам: вызывать внешние сервисы из кода 1С и, наоборот, предоставлять данные 1С наружу через собственные HTTP-сервисы. Для первой задачи платформа даёт объекты HTTPСоединение и HTTPЗапрос, для второй — объект метаданных «HTTP-сервис», публикуемый на веб-сервере.

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

Ниже разобраны оба направления с примерами кода, типичными ошибками и проверками результата. Материал ориентирован на управляемые формы и актуальные версии платформы 1С:Предприятие 8.3.

Какие средства интеграции есть в платформе 1С

Платформа предлагает несколько встроенных механизмов обмена, и выбор зависит от задачи. Для синхронных запросов к внешним REST API основной инструмент — программная HTTP-клиентская модель: HTTPСоединение, HTTPЗапрос и HTTPОтвет. Она работает и на сервере, и на толстом клиенте, поддерживает HTTPS и прокси.

Для приёма входящих запросов используются HTTP-сервисы — объект метаданных, где разработчик описывает шаблоны URL и обработчики. Альтернатива — веб-сервисы (SOAP), но они нужны в основном для интеграций со старыми системами, где требуется WSDL-описание.

Если обмен идёт между двумя базами 1С, часто рациональнее использовать не «голый» API, а планы обмена или формат EnterpriseData. Это снимает часть работы по сериализации объектов и контролю версий данных.

Как выполнить HTTP-запрос к внешнему API

Базовый сценарий вызова внешнего API состоит из четырёх шагов: создать соединение с указанием сервера, сформировать объект HTTPЗапрос с адресом ресурса и заголовками, выполнить метод (GET, POST и другие), прочитать ответ и его код состояния.

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

SSL = Новый ЗащищенноеСоединениеOpenSSL();
Соединение = Новый HTTPСоединение("api.example.com", 443, , , , 30, SSL);
Запрос = Новый HTTPЗапрос("/v1/orders");
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Запрос.Заголовки.Вставить("Accept", "application/json");
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
    ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
КонецЕсли;

Методы соединения соответствуют HTTP-глаголам: Получить (GET), ОтправитьДляОбработки (POST), Записать (PUT), Удалить (DELETE). Для POST и PUT тело запроса задаётся методом УстановитьТелоИзСтроки с указанием кодировки, либо УстановитьТелоИзДвоичныхДанных для файлов.

Признак успешной отработки — код состояния 2xx и корректно распарсенное тело ответа. Коды 4xx означают ошибку в запросе (неверный токен, формат, права), 5xx — сбой на стороне сервиса, и такие запросы имеет смысл повторить с паузой.

Как отправить и разобрать JSON

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

// Формирование JSON
Данные = Новый Структура;
Данные.Вставить("number", "АБ-000123");
Данные.Вставить("sum", 1500.50);
Запись = Новый ЗаписьJSON;
Запись.УстановитьСтроку();
ЗаписатьJSON(Запись, Данные);
ТелоЗапроса = Запись.Закрыть();

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

Три частые проблемы при обмене JSON: кодировка тела (всегда указывайте КодировкаТекста.UTF8 и заголовок Content-Type: application/json), даты (в 1С дата без типа сериализуется в строку, формат нужно согласовать с контрагентом API) и обязательные поля, отсутствие которых внешний сервис встречает ошибкой валидации.

Авторизация: токены, Basic и OAuth 2.0

Самый простой вариант — Basic-авторизация: логин и пароль передаются прямо в конструктор HTTPСоединение. Это допустимо только по HTTPS и только если внешний сервис не предлагает более надёжной схемы. Логин и пароль не должны храниться в коде — используйте безопасное хранилище данных или константы с ограниченным доступом.

Чаще встречаются API-ключи и Bearer-токены, которые передаются в заголовке Authorization. Токены обычно имеют срок жизни: корректная интеграция хранит токен и время его истечения, обновляет заранее и обрабатывает ответ 401 как сигнал к повторной авторизации, а не как фатальную ошибку.

Схема OAuth 2.0 с редиректом пользователя в браузер сложнее: 1С не имеет встроенного браузерного клиента для таких сценариев, поэтому первичное получение кода авторизации часто выполняют вручную или через служебную обработку, а дальше работают с refresh-токеном из кода.

Обработка ошибок, таймаутов и повторных попыток

Внешний API — ненадёжная среда: сеть падает, сервисы перегружены, лимиты запросов исчерпываются. Минимальный набор устойчивой интеграции: таймаут соединения, конструкция Попытка/Исключение вокруг вызова, анализ кода состояния и журналирование каждого обмена с сохранением тела запроса и ответа.

Для кодов 429 (превышен лимит) и 5xx разумно реализовать повторные попытки с нарастающей паузой — например, через 1, 5 и 15 минут, но не более 3–5 раз. Бесконечный цикл повторов при постоянной ошибке на стороне сервиса создаст очередь зависших заданий.

Обязательно проверяйте не только код ответа, но и содержимое: некоторые сервисы возвращают 200 с описанием ошибки в теле. Также учитывайте идемпотентность — если запрос создаёт документ или платёж, повторная отправка после таймаута может создать дубликат. Используйте уникальные внешние идентификаторы, если API их поддерживает.

Как опубликовать собственный HTTP-сервис в 1С

Чтобы внешние системы могли обращаться к 1С, в конфигураторе создаётся объект «HTTP-сервис»: задаётся корневой URL, добавляются шаблоны URL с параметрами и обработчики методов (GET, POST и другие). В обработчике доступен объект HTTPСервисЗапрос, из которого читаются параметры, заголовки и тело, а возвращается HTTPСервисОтвет с кодом и телом.

Сервис публикуется на веб-сервере (Apache или IIS) через диалог публикации в конфигураторе: указывается имя публикации, каталог и отмечается флаг публикации HTTP-сервисов. После публикации обработчик доступен по адресу вида /ИмяПубликации/hs/КорневойURL/Шаблон.

Критический вопрос — безопасность. По умолчанию анонимный доступ к HTTP-сервису означает, что любой, кто знает адрес, может вызывать ваши обработчики. Минимальные меры: включить аутентификацию на веб-сервере или в публикации, проверять токен в заголовке внутри обработчика, ограничить доступ по IP средствами веб-сервера и никогда не возвращать в ответе внутренние детали ошибок.

1. 1
   Создайте в конфигураторе объект «HTTP-сервис», задайте корневой URL.
2. 2
   Добавьте шаблон URL и обработчик метода (например, GET) с чтением параметров и формированием ответа.
3. 3
   Назначьте пользователя, от имени которого будет выполняться сеанс, и настройте его права минимально необходимыми.
4. 4
   Опубликуйте сервис через Администрирование → Публикация на веб-сервере, отметив публикацию HTTP-сервисов.
5. 5
   Проверьте вызов из браузера или curl: корректный ответ, код 200, отказ при неверном токене.

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

Отлаживать исходящие запросы удобнее всего в два этапа: сначала повторить запрос во внешнем инструменте (curl, Postman), чтобы отделить проблемы самого API от проблем кода 1С, затем перенести работающий набор заголовков и тела в конфигуратор. Многие сервисы предоставляют тестовые контуры — начинайте с них.

Для диагностики ведите регистр или журнал обмена: дата, направление, URL, код ответа, хеш или полное тело запроса и ответа. Это позволяет быстро находить расхождения и доказывать контрагенту, что именно было отправлено. Тела с персональными данными и токенами в журнале маскируйте.

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