API в 1С: как использовать для интеграции и обмена данными

API в 1С — это набор программных интерфейсов, через которые внешние системы (сайты, мобильные приложения, CRM, банковские сервисы) читают и записывают данные в информационную базу. На практике используются три основных подхода: стандартный OData-интерфейс, собственные HTTP-сервисы и классические веб-сервисы (SOAP). Выбор зависит от задачи: OData подходит для простого чтения справочников и документов, HTTP-сервисы — для произвольной логики, SOAP — для интеграции с корпоративными системами, где требуется строгое описание контракта.

Любой из этих механизмов требует публикации базы на веб-сервере (Apache или IIS), потому что обращения извне приходят по HTTP/HTTPS, а веб-сервер передаёт их рабочим процессам 1С. Файловая база без веб-сервера отдавать данные по API не сможет — только через агенты вроде COM-соединения, что для внешних интеграций считается устаревшим и небезопасным решением.

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

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

Платформа 1С:Предприятие предоставляет три встроенных механизма внешнего доступа. Первый — автоматический REST-интерфейс OData: после включения публикации все разрешённые объекты конфигурации (справочники, документы, регистры) становятся доступны по URL вида /base/odata/standard.odata/Catalog_Номенклатура. Никакого программирования не требуется, но и изменить логику нельзя — отдаётся то, что есть в базе.

Второй механизм — HTTP-сервисы, которые разработчик создаёт в конфигураторе самостоятельно. Здесь вы определяете шаблоны URL, методы (GET, POST, PUT, DELETE) и пишете обработчики на встроенном языке. Это даёт полный контроль: можно возвращать только нужные поля, выполнять проверки, проводить документы, формировать ответ в JSON.

Третий вариант — веб-сервисы (SOAP). Они описываются WSDL-файлом и используются там, где внешняя система требует строгого контракта: например, при интеграции с корпоративными шинами данных или устаревшими банковскими клиентами. Для новых проектов SOAP применяют редко из-за громоздкости XML-протокола.

Как включить стандартный OData-интерфейс

OData — самый быстрый способ открыть доступ к данным. Для его включения нужно опубликовать базу на веб-сервере и отметить опцию публикации стандартного интерфейса OData. В конфигураторе это делается через меню «Администрирование» → «Публикация на веб-сервере», где ставится флажок «Публиковать стандартный интерфейс OData». В клиент-серверном варианте публикацию можно выполнить и через консоль кластера или утилиту webinst.

После публикации список доступных сущностей возвращается по адресу http://server/base/odata/standard.odata с метаданными в $metadata. Чтение данных выполняется GET-запросами с параметрами $filter, $select, $top, а запись — POST и PATCH. Формат ответа по умолчанию XML, для JSON добавляется параметр $format=json или заголовок Accept.

1. 1
   Убедитесь, что база работает на веб-сервере (Apache или IIS) и публикация выполняется без ошибок.
2. 2
   В конфигураторе откройте «Администрирование» → «Публикация на веб-сервере» и включите флажок публикации стандартного интерфейса OData.
3. 3
   Создайте отдельного пользователя и выдайте ему роли только на нужные объекты.
4. 4
   Запросите в браузере или Postman адрес /odata/standard.odata/$metadata и проверьте наличие нужных сущностей.
5. 5
   Выполните тестовый GET-запрос с фильтром и убедитесь, что возвращаются только ожидаемые данные.

Важный нюанс: OData применяет права пользователя, под которым идёт обращение. Если у пользователя нет права чтения справочника, сущность вернёт ошибку доступа. Поэтому «пустой ответ» чаще всего означает не поломку API, а нехватку прав.

Как создать собственный HTTP-сервис

HTTP-сервис создаётся в конфигураторе в ветке «Общие» → «HTTP-сервисы». Для сервиса задаётся корневой URL (например, api), затем добавляются шаблоны URL — например, /goods/{code}, и для каждого шаблона — методы с обработчиками. В обработчике доступны параметры запроса, тело запроса, заголовки, а результат формируется объектом HTTPСервисОтвет с кодом состояния и телом.

Типовой обработчик чтения остатков выглядит так: из параметров URL извлекается код номенклатуры, выполняется запрос к регистру остатков, результат сериализуется в JSON через объект ЗаписьJSON, формируется ответ с кодом 200. При отсутствии данных корректно возвращать код 404, при ошибках в параметрах — 400 с описанием проблемы.

Функция ПолучитьОстаток(Запрос)
    КодТовара = Запрос.ПараметрыURL["code"];
    Ответ = Новый HTTPСервисОтвет(200);
    Ответ.Заголовки.Вставить("Content-Type", "application/json");
    // запрос к регистру, запись результата в JSON
    Ответ.УстановитьТелоИзСтроки(РезультатJSON);
    Возврат Ответ;
КонецФункции

После создания сервиса его нужно опубликовать: в настройках публикации на веб-сервере на закладке «HTTP-сервисы» отметить нужные сервисы. Обращение будет идти по адресу http://server/base/hs/api/... — префикс hs является стандартным для HTTP-сервисов 1С.

Аутентификация и безопасность API

Базовая аутентификация (логин и пароль пользователя 1С в заголовке Authorization) — встроенный и рабочий механизм, но передавать учётные данные можно только по HTTPS. Открытый HTTP означает, что логин и пароль передаются практически в открытом виде и легко перехватываются. Для серьёзных интеграций настраивают SSL-сертификат на веб-сервере и закрывают порт 80 либо делают редирект на HTTPS.

Дополнительные меры: отдельный пользователь для каждой внешней системы (чтобы можно было отозвать доступ точечно), роли с минимальным набором прав, ограничение доступа по IP на уровне веб-сервера или файрвола, журналирование обращений. Внутри HTTP-сервиса можно реализовать проверку токена в заголовке, если базовой аутентификации недостаточно.

Как обращаться к API из внешних систем

Со стороны клиента работа с API 1С ничем не отличается от любого другого REST API. Для тестирования удобен Postman или curl: указывается URL, тип аутентификации Basic Auth с логином и паролем пользователя 1С, заголовки Accept и Content-Type. Успешный ответ — код 200 с телом JSON или XML.

Из скриптовых языков обращение выполняется стандартными HTTP-клиентами: requests в Python, HttpClient в C#, fetch в JavaScript. При работе с OData учитывайте, что значения дат и ссылок имеют специфический формат, а строковые значения в фильтрах заключаются в одинарные кавычки с экранированием.

curl -u "api_user:password" -H "Accept: application/json" "http://server/base/odata/standard.odata/Catalog_Номенклатура?$format=json&$top=10"

Для двустороннего обмена (когда 1С сама вызывает внешний API) используется объект HTTPСоединение и HTTPЗапрос во встроенном языке. Это отдельный сценарий: 1С выступает клиентом, например при отправке заказов в службу доставки или получении курсов валют.

Типичные ошибки и как их диагностировать

Ошибка 404 при обращении к HTTP-сервису чаще всего означает, что сервис не опубликован или URL не совпадает с шаблоном. Ошибка 401 — неверный логин/пароль или пользователь отключён. Ошибка 500 — исключение в обработчике: смотрите журнал регистрации базы, там фиксируется текст ошибки. Пустой ответ OData при корректном запросе — признак нехватки прав у пользователя.

Ограничения и альтернативы

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

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

Частые вопросы об API в 1С