API-шлюз для 1С 7.7: установка и настройка

Требования, установка, config.json, контракт ERT, запуск и подключение Telegram-бота.

HTTP API-шлюз связывает Telegram-бота или внешний сервис с подготовленными отчётами 1С 7.7. Он принимает задание, выполняет его в постоянном COM-сеансе и возвращает JSON. Это самостоятельная HTTP-интеграция; MCP-интерфейс в текущей реализации отсутствует.

Описание решения на ster.by · Справочник HTTP API

Как проходит запрос

Клиент передаёт команду и параметры по HTTP. Шлюз сохраняет JSON-запрос, ставит задание в очередь и последовательно выполняет отчёты в одном COM-сеансе 1С. Подготовленный ERT записывает JSON в назначенный файл результата. Клиент получает ответ сразу после выполнения либо запрашивает состояние по job_id.

Шлюз запускает настроенные отчёты. Произвольный текст запроса к БД или код 1С в HTTP API не передаётся.

Что требуется

Windows с установленной 1С 7.7 и зарегистрированным COM-объектом, доступным учётной записи запуска.
Python с пакетами из requirements.txt: fastapi, uvicorn, pywin32. Поставляемое окружение Python создаётся заново на целевом компьютере.
Разрешённый доступ к информационной базе и подготовленные внешние отчёты ERT с поддержкой JSON-выгрузки.
Права учётной записи транспорта на базу, отчёты и каталоги requests, results, logs. Для сетевых путей права проверяются именно под этой учётной записью.
Для выдачи спецификаций — отдельный каталог продукции с PDF. Telegram-бот и его сценарии настраиваются отдельно.

Файлы базы, ERT-отчёты, Telegram-бот и PDF-каталог не являются частью самого транспортного сервера.

Установка

Разместите комплект сервера в выбранном каталоге. Ниже используется пример C:\TransportOfRequests; замените его своим путём.

Set-Location C:\TransportOfRequests
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

В рабочий комплект входят server.py, config.json, requirements.txt и restart_transport.ps1. start_transport.ps1 используется для фонового запуска; transport_health_check.ps1 и transport_watchdog.ps1 — для контроля состояния. Скрипты запуска и перезапуска ожидают Python в .venv\Scripts\python.exe.

Настройка config.json

Пример ниже содержит только условные пути и демонстрационный ключ. Все имена ERT замените путями к вашим подготовленным отчётам. Указание файла в конфигурации само по себе не добавляет в него JSON-выгрузку.

{
  "host": "127.0.0.1",
  "port": 65443,
  "api_key": "REPLACE_WITH_A_LONG_RANDOM_KEY",
  "base_dir": "C:\\TransportOfRequests",
  "request_dir": "C:\\TransportOfRequests\\requests",
  "result_dir": "C:\\TransportOfRequests\\results",
  "log_dir": "C:\\TransportOfRequests\\logs",
  "timeout_seconds": 120,
  "soft_timeout_seconds": 120,
  "command_soft_timeout_seconds": {
    "tech_department_orders_by_date": 60,
    "raw_material_stock": 120
  },
  "startup_timeout_seconds": 180,
  "default_command_timeout_seconds": 300,
  "command_timeout_seconds": {
    "tech_department_orders_by_date": 120,
    "raw_material_stock": 300
  },
  "maintenance_retry_seconds": 60,
  "product_pdf": {
    "root_dir": "C:\\1C\\ProductPDF"
  },
  "one_c": {
    "com_object": "V77.Application",
    "database_dir": "C:\\1C\\Base",
    "connect_string": "/D\"C:\\1C\\Base\" /N\"API\" /M",
    "initialize_mode": "NO_SPLASH_SHOW",
    "report_files": {
      "stock_reserve": "C:\\1C\\Reports\\StockReserve.ert",
      "sales_by_periods": "C:\\1C\\Reports\\SalesByPeriods.ert",
      "raw_material_stock": "C:\\1C\\Reports\\RawMaterialStock.ert",
      "price_stock": "C:\\1C\\Reports\\PriceStock.ert",
      "tech_department_orders_by_date": "C:\\1C\\Reports\\TechDepartmentOrders.ert"
    }
  }
}

Замените api_key длинным случайным ключом. database_dir и /D в connect_string должны указывать на одну базу. /N — существующий пользователь 1С; приведённый пример рассчитан на вход без пароля. Если пароль необходим, строка подключения заполняется администратором и хранится как секрет. /M задаёт монопольный вход; при занятости базы чужие сеансы не закрывают и блокировки не обходят.

Пути request_dir и result_dir должны быть доступны и Python, и запущенной через COM 1С. Внешние пути задавайте явно. Все пять report_files из примера следует проверить: при отсутствии отдельных записей сервер может подставлять встроенные значения, которые не относятся к вашей установке.

product_pdf.root_dir используется только методами списка продукции и PDF. Для отчётных команд он не заменяет путь к базе или ERT.

Пример слушает только 127.0.0.1. Для удалённого клиента настройте сетевую доступность согласно вашей схеме: защищённое подключение, HTTPS через обратный прокси либо VPN. Встроенная проверка ключа не шифрует HTTP-трафик.

Контракт внешнего отчёта

Шлюз открывает настроенный ERT как отчёт через COM и передаёт СписокЗначений. Отчёт должен принять параметры, сформировать данные и записать корректный JSON по указанному пути.

Параметр	Значение
ФайлЗапроса	Путь к JSON входящего задания
ФайлРезультата	Путь для записи JSON результата
РежимВыгрузки	JSON
АвтоСформировать	1
АвтоЗакрыть	1
Command	Имя HTTP-команды
Параметры отчёта	Скалярные значения из params с установленными переименованиями

Состав полей итогового JSON определяется конкретным ERT. Универсальная структура строк отчёта самим транспортом не задаётся. Переименование параметров описано в справочнике API.

Запуск и первая проверка

.\.venv\Scripts\python.exe server.py

Сервер создаёт служебные каталоги автоматически. При обычном запуске он начинает подключение к 1С. Проверьте HTTP и затем состояние COM-сеанса:

Invoke-RestMethod http://127.0.0.1:65443/health

Верхнее status=ok означает, что HTTP-приложение отвечает. Готовность к отчётам проверяется отдельно по one_c.status: для первого задания ожидается ready. Затем выполните один настроенный отчёт с коротким периодом и проверьте полученные данные.

Если появляется предложение пересчитать индексы, выбирают «Нет». Отказ монопольного входа из-за занятости базы является результатом проверки, а не основанием закрывать чужие сеансы.

Подключение Telegram-бота

Бот отправляет запрос на /api/1c/submit с командой, параметрами и заголовком X-Api-Key.
Получив job_id и status_url, бот сообщает пользователю о приёме задания и опрашивает status_url с тем же ключом.
При should_wait=true бот продолжает ожидание; при completed или completed_late использует result. При отказе или ошибке показывает понятный результат пользователю.
Ключ хранится на стороне сервера бота. В переписку с пользователем он не передаётся.

Готового Telegram-бота в комплекте шлюза нет. Клиент можно реализовать в боте, n8n или другом сервисе, который умеет выполнять HTTP-запросы.

Эксплуатация и перезапуск

Очередь ожидающих заданий и реестр текущих заданий находятся в памяти процесса. После перезапуска незавершённые задания автоматически не восстанавливаются. Файлы requests и results сохраняются на диске; доступный корректный файл результата можно получить по известному job_id.

Перед административным перезапуском проверьте /queue. POST /admin/restart прерывает текущие и ожидающие запросы транспорта. При жёстком таймауте автоматическое принудительное завершение 1С отключено. История запросов и результатов накапливается: правила хранения и очистки определяет администратор.

Поставляемые скрипты контроля используют порт 65443. При изменении порта в config.json проверьте также адреса и проверки порта в PowerShell-скриптах. Запуск службы через NSSM описан в install_service_example.txt; пути и учётную запись службы нужно настроить для целевого компьютера.

Диагностика

Признак	Что проверить
HTTP недоступен	Процесс Python, выбранный адрес/порт, правила сети и журналы запуска
HTTP работает, one_c не ready	COM-регистрацию, права учётной записи, строку подключения, занятость базы и сообщение one_c
400	JSON, разрешённую команду, report_files и параметры выбранной команды
401	Заголовок X-Api-Key и значение api_key
503	Состояние one_c и поля action_required / retry_after_seconds
Таймаут или 500	Этап в logs\api.log, выполнение ERT и файл результата конкретного задания

config.json содержит секреты. Файлы requests, results и журналы могут содержать данные организации. Публичная документация и примеры не должны содержать реальные ключи, пароли, клиентские запросы и внутренние сетевые адреса.

Проверка без подключения к 1С

.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v

Поставляемые тесты отключают COM-работник и проверяют таймауты, поздний JSON-результат и связанные состояния. Пять тестов прошли при подготовке комплекта. Эти проверки не заменяют реальное выполнение отчёта в целевой базе.

Перейти к справочнику HTTP API →