API-шлюз для 1С 7.7: справочник HTTP API

Авторизация, команды, параметры, job_id, состояния, таймауты, PDF и ошибки HTTP.

Справочник текущего HTTP API-шлюза для 1С 7.7. Для примеров используется http://127.0.0.1:65443. Удалённый адрес задаётся при развёртывании.

Установка и настройка · Описание решения

Авторизация и формат

Отчётные, диагностические и административные методы требуют заголовок X-Api-Key со значением из config.json. GET /health доступен без ключа. Для JSON-запросов передавайте Content-Type: application/json; charset=utf-8.

Формат ответа отчёта определяется подключённым ERT. Шлюз передаёт JSON, а не SQL-запросы или произвольный код.

Методы

Метод	Путь	Назначение
GET	/health	Доступность HTTP и состояние one_c
GET	/queue	Текущее и ожидающие задания
POST	/api/1c	Принять задание и дождаться JSON отчёта
POST	/api/1c/submit	Принять задание и вернуть job_id без ожидания отчёта
GET	/api/1c/jobs/{job_id}	Состояние задания и результат
GET	/api/products	Список продукции с найденными PDF-спецификациями
GET	/api/products/specification?catalog=…	Скачать PDF по имени каталога
POST	/admin/restart	Запросить перезапуск процесса транспорта

Постановка задания

Для Telegram-бота удобно использовать асинхронную схему: submit, затем опрос status_url. Пример запроса на PowerShell:

$headers = @{ "X-Api-Key" = $env:TRANSPORT_API_KEY }
$body = @{
    command = "sales_by_periods"
    params = @{ StartDate = "01.10.2026"; EndDate = "02.10.2026" }
} | ConvertTo-Json -Depth 5
$job = Invoke-RestMethod `
    -Uri "http://127.0.0.1:65443/api/1c/submit" `
    -Method Post -Headers $headers `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$job

TRANSPORT_API_KEY в примере — переменная окружения клиента запроса, которую предварительно задаёт администратор. Сам сервер читает ключ из config.json.

Пример ответа при принятии задания; конкретное execution_status зависит от того, успел ли работник начать выполнение:

{
  "status": "accepted",
  "job_id": "0123456789abcdef0123456789abcdef",
  "command": "sales_by_periods",
  "execution_status": "queued",
  "should_wait": true,
  "contact_developer": false,
  "soft_timeout_seconds": 120,
  "hard_timeout_seconds": 300,
  "status_url": "/api/1c/jobs/0123456789abcdef0123456789abcdef"
}

Получение состояния

Invoke-RestMethod `
    -Uri ("http://127.0.0.1:65443" + $job.status_url) `
    -Headers $headers

job_id — 32 шестнадцатеричных символа в нижнем регистре. При успехе ответ содержит result с исходным JSON отчёта. Ориентируйтесь на execution_status и should_wait, а не только на HTTP-код.

execution_status	Поведение клиента
accepted / queued / running	Задание принято или выполняется; при should_wait=true продолжать опрос
slow	Мягкий порог превышен; отчёт продолжает выполняться, should_wait=true
completed	Результат доступен в result
completed_late	Корректный результат появился после зафиксированного таймаута; доступен в result
timeout	Жёсткий лимит превышен; should_wait=false, требуется диагностика
failed	Ошибка выполнения; показать сообщение и проверить диагностику
not_started	Задание отклонено до запуска; проверить one_c, code и action_required

При незавершённом задании отвечающий сервер обычно возвращает HTTP 200. Таймаут асинхронного задания также отражается в JSON execution_status=timeout; это отличается от HTTP 504 синхронного метода. Не пересоздавайте задание автоматически из-за статуса slow: это поставит второй отчёт в очередь.

Синхронный запрос

POST /api/1c принимает такое же тело, как submit, и удерживает HTTP-соединение до результата. Успех — JSON конкретного отчёта без обёртки result. Для долгих отчётов предпочтительна схема submit и опрос состояния.

Команды

Команда должна входить в список ALLOWED_COMMANDS и иметь настроенный файл в one_c.report_files. Наличие имени команды в коде не гарантирует наличия соответствующего ERT у заказчика.

Команда	Сценарий
stock_reserve	Остатки с учётом резерва
sales_by_periods	Анализ продаж по периодам
raw_material_stock	Остатки сырья и списание в производство
price_stock	Цены и остатки; текущая реализация фиксирует склады 3, 5, 54, 81
tech_department_orders_by_date	Заказы технического отдела за период
stock_today / buh_totals / sales_today / test	Резервные имена; требуются отдельно настроенные report_files и отчёты

У price_stock параметр product_or_container принимает products/product/продукция/продукты/1 для продукции и container/containers/тара/0 для тары; также допустимы 0/1 и boolean. Он преобразуется в ПродИлиТара. Передача пользовательского набора складов этой команде отклоняется с HTTP 400. Это ограничение текущей прикладной команды, а не универсальная настройка транспорта.

Параметры отчёта

params — объект. В список параметров 1С передаются строки, числа и boolean; boolean становится 1 или 0. Вложенные объекты, массивы и null не передаются как параметры отчёта.

Имя HTTP	Имя в 1С
date	Дата
StartDate	НачДата
EndDate	КонДата
warehouse_code	СкладКод
tmc_code	НоменклатураКод
supplier_code	ПоставщикКод
Другое скалярное имя	Передаётся без переименования

Даты и другие прикладные значения должны соответствовать контракту конкретного ERT. В примерах отчётов используются даты ДД.ММ.ГГГГ. Русские имена параметров передаются в UTF-8. В n8n выражения дат должны быть вычислены до отправки, а не приходить в 1С текстом выражения.

Таймауты

Команда / этап	Мягкий порог	Жёсткий лимит
tech_department_orders_by_date	60 секунд	120 секунд
raw_material_stock	120 секунд	300 секунд
Остальные команды при базовых настройках	120 секунд	300 секунд
Запуск COM	Отдельный порог startup_timeout_seconds	По базовой конфигурации 180 секунд — диагностический порог запуска

Значения настраиваются в config.json. Мягкий порог не останавливает отчёт. Жёсткий таймаут фиксирует проблему; транспорт не завершает принудительно процесс 1С. Если корректный JSON появится позднее, опрос может вернуть completed_late.

Состояние и очередь

GET /health возвращает верхний status=ok при работающем HTTP-приложении и вложенный one_c. Для отчётов требуется готовность one_c: ready; busy и slow означают, что работник занят и может принимать задания в очередь.

При starting, starting_slow, maintenance_required, unresponsive, error или другом неготовом состоянии новые отчётные задания могут быть отклонены с HTTP 503. Смотрите message, code, action_required, retry_after_seconds и contact_developer; отсутствие ошибки HTTP у /health не доказывает готовность базы.

GET /queue показывает worker_status, pids, current, pending и queue_size. Задания выполняются последовательно, очередь ожидающих хранится в памяти. Методу требуется ключ, поскольку он раскрывает команды, параметры и служебные пути.

Продукция и PDF

GET /api/products читает каталоги из product_pdf.root_dir и возвращает products и count. В элементе находятся catalog, name и specification_url. Архивные каталоги исключаются. PDF сопоставляется с названием каталога до служебного суффикса ^; регистр и пробелы нормализуются.

Полученный specification_url запрашивают с тем же X-Api-Key. Это относительный путь на том же сервере. Имя catalog передаётся с URL-кодированием. Список и файл спецификации выдаются из файловой системы и не требуют выполнения отчёта в 1С.

HTTP-коды

Код	Смысл
200	Успех HTTP-метода; состояние задания проверяется в JSON
202	Принята административная команда перезапуска
400	Неверный JSON, команда, job_id, каталог или параметры; отсутствует настройка отчёта
401	Отсутствует либо неверен X-Api-Key
404	Задание, каталог или спецификация не найдены
500	Ошибка выполнения / некорректный файл результата
503	Работник 1С не готов либо не запущен
504	Таймаут при синхронном вызове /api/1c

Административный перезапуск

POST /admin/restart требует тот же ключ и возвращает 202. Сервер запускает restart_transport.ps1. Перезапуск прерывает текущее и ожидающие в памяти задания; автоматическое принудительное завершение оставшегося процесса 1С отключено. Перед командой проверьте /queue. В обычный пользовательский сценарий бота этот метод включать не следует.

Границы реализации

API не содержит гарантии идемпотентности повторной отправки, автоматического восстановления очереди после рестарта или универсального контракта данных для всех ERT. Сохраняйте job_id и не считайте повторный HTTP POST продолжением прежнего задания. Полноценная проверка интеграции включает реальный запуск выбранного отчёта и сверку результата в разрешённой базе.

Установка и настройка →