Программный интерфейс 1С: что это и зачем он нужен

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

Когда бухгалтер нажимает кнопку «Провести документ», за этим стоит программный вызов. Когда интернет-магазин получает из 1С остатки товаров, это тоже работа программного интерфейса — только внешнего. Понимание того, какие интерфейсы существуют и чем они отличаются, позволяет грамотно выбрать способ интеграции и не тратить время на неподходящий инструмент.

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

Что именно называют программным интерфейсом в 1С

Термин «программный интерфейс» (API) в контексте 1С употребляется в двух смыслах, и их важно различать. Первый смысл — интерфейс прикладного решения: совокупность экспортных процедур и функций общих модулей, программных объектов (справочников, документов, регистров) и методов работы с ними. Именно этот интерфейс использует разработчик, когда пишет код на встроенном языке: создаёт документ вызовом Документы.РеализацияТоваровУслуг.СоздатьДокумент(), получает остатки запросом к виртуальной таблице регистра.

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

Внутренний программный интерфейс: модули и объектная модель

Основа внутреннего API — общие модули с экспортными процедурами и функциями. В типовых конфигурациях принято группировать их по подсистемам: например, модуль работы с контрагентами, модуль расчёта цен, модуль обмена данными. Хорошо спроектированный интерфейс скрывает детали реализации: вызывающий код не знает, как именно устроено хранение данных, он просто вызывает функцию вида ПолучитьЦену(Номенклатура, Дата) и получает результат.

Второй слой — объектная модель платформы. Каждый тип прикладного объекта предоставляет программные методы: создание, запись, проведение, поиск по реквизитам, выборка. Регистры сведений и накопления читаются через менеджеры записей и запросы, документы — через объектную модель или запросы к таблицам. Знание этой модели обязательно для любой доработки конфигурации.

Отдельно стоит упомянуть язык запросов 1С — фактически это тоже часть программного интерфейса: декларативный способ получать данные из таблиц, включая виртуальные таблицы регистров с готовыми итогами и остатками.

// Пример программного создания и проведения документа
НовыйДок = Документы.РеализацияТоваровУслуг.СоздатьДокумент();
НовыйДок.Дата = ТекущаяДатаСеанса();
НовыйДок.Контрагент = Контрагент;
НовыйДок.Записать(РежимЗаписиДокумента.Проведение);

Внешние интерфейсы интеграции: обзор вариантов

Когда обращаться к 1С нужно извне — из другой программы, сайта или скрипта — используются сетевые интерфейсы. У каждого есть своя область применения, и неправильный выбор приводит либо к избыточной разработке, либо к проблемам с производительностью и безопасностью.

OData — автоматический REST-интерфейс, который платформа генерирует по структуре конфигурации. Достаточно включить публикацию на веб-сервере, и справочники, документы и регистры становятся доступны по HTTP в формате Atom/JSON. Подходит для простых сценариев чтения и записи без дополнительного кодирования, но не позволяет реализовать произвольную бизнес-логику и требует аккуратной настройки прав.

HTTP-сервисы — полностью программируемый вариант: разработчик сам описывает шаблоны URL, методы (GET, POST и другие) и обработчики на встроенном языке. Это основной способ построить собственный API под конкретную задачу — например, отдать сайту остатки в нужном формате или принять заказ с проверками.

Веб-сервисы (SOAP) — классический вариант с описанием в формате WSDL. Их удобно использовать, когда внешняя система умеет работать с SOAP «из коробки» и требуется строгий контракт данных через XDTO-пакеты.

COM-соединение — механизм связи одной базы 1С с другой напрямую через COM-объект (V83.COMConnector). Работает только в среде Windows и требует, чтобы обе базы были доступны с одного сервера. Часто применяется для регламентных выгрузок между базами.

Как выбрать подходящий интерфейс под задачу

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

Второй критерий — формат и нагрузка. Для высокочастотных запросов с небольшими порциями данных HTTP-сервисы с JSON обычно удобнее и легче сопровождать. Для разовых регламентных выгрузок больших объёмов между двумя базами 1С часто практичнее COM-соединение или планы обмена с форматом EnterpriseData.

Третий фактор — среда исполнения. COM недоступен на Linux-сервере 1С, OData и HTTP-сервисы требуют публикации на веб-сервере (IIS или Apache) и грамотной настройки аутентификации. Если база работает в файловом режиме без веб-сервера, внешние HTTP-интерфейсы опубликовать не получится.

Как опубликовать и проверить HTTP-сервис

Типовой порядок действий при создании собственного API на HTTP-сервисах выглядит так. В конфигураторе добавляется объект «HTTP-сервис», в нём описываются шаблоны URL (например, /stock/{warehouse}) и методы, для каждого метода пишется обработчик на встроенном языке. Затем сервис публикуется на веб-сервере через диалог публикации в конфигураторе либо вручную настройкой IIS/Apache.

После публикации обязательна проверка: запрос к сервису выполняется из браузера или утилиты вроде curl, сначала с корректными параметрами, затем с ошибочными — чтобы убедиться, что обработчик возвращает осмысленные коды ответа, а не падает с исключением. Отдельно проверяется аутентификация: анонимный доступ к API, отдающему коммерческие данные, недопустим.

1. 1
   Создайте в конфигураторе объект HTTP-сервис и опишите шаблоны URL и методы
2. 2
   Напишите обработчики: разбор параметров, вызов бизнес-логики, формирование ответа в JSON
3. 3
   Опубликуйте сервис на веб-сервере и задайте аутентификацию
4. 4
   Проверьте запросы с корректными и с ошибочными параметрами
5. 5
   Проверьте права: пользователь сервиса должен иметь доступ только к нужным объектам

Безопасность и типичные риски

Любой опубликованный интерфейс — это точка входа в базу, поэтому правила безопасности здесь не формальность. Пользователь, от имени которого работает сервис, должен иметь минимально необходимые права: если API только отдаёт остатки, ему не нужны права на запись документов. Передача данных должна идти по HTTPS, особенно если сервис доступен извне локальной сети.

Отдельный риск — прямая запись объектов через OData или COM в обход бизнес-логики. Внешняя система может записать документ без проверок, которые выполняются при интерактивном вводе, и получить неконсистентные данные. Поэтому для записи предпочтительнее сервисы с собственными обработчиками, где проверки выполняются явно.

Отладка и сопровождение интерфейсов

Отладка серверного кода сервисов выполняется стандартными средствами конфигуратора: включается отладка на сервере, в обработчике ставится точка останова, и при входящем запросе исполнение останавливается. Для диагностики полезно логировать входящие запросы и ответы в регистр сведений или журнал регистрации — это сильно упрощает разбор инцидентов, когда внешняя система утверждает, что «всё отправила правильно».

При изменении конфигурации помните об обратной совместимости: внешние системы зависят от состава реквизитов и структуры ответов API. Удаление или переименование реквизита, который читает интеграция, приведёт к сбою на той стороне. Устойчивая практика — версионировать API (например, префикс /v1/ в URL) и согласовывать изменения с владельцами внешних систем.

Частые вопросы о программном интерфейсе 1С