Локальный API программы
Программа поднимает на своём компьютере HTTPS API для ваших систем — кассового ПО, учётной системы, собственных сервисов. API работает, пока программа запущена.
Адрес
https://<адрес-компьютера>:8443/api/v1- В новой установке API выключен: включите «Настройки» → «Входящий API» → «Принимать запросы от панели и магазинов» и перезапустите программу.
- Порт по умолчанию — 8443. Формат — JSON в UTF-8, поля в
snake_case. С версии 2.2.1 подключение кег и постановка на учёт отклоняют поля с другими именами (например,connectDate) ошибкой 400, а не пропускают их молча. - Сертификат самоподписанный: клиент не проверяет цепочку, а закрепляет открытый ключ сертификата (pinning).
- API рассчитан на локальную сеть или VPN. Не открывайте его в интернет.
Ключи и роли
Каждый запрос, кроме GET /health, передаёт ключ в заголовке X-Api-Key. Ключи хранятся в файле
api_keys.json рядом с программой; при первом открытии окна ключей файл создаётся со случайными ключами.
Для каждого ключа задаются роль, доступные организации и, при необходимости, разрешённые IP-адреса.
- panel — все методы: токены, подключение и учёт кег, состояние документов, проверка кодов.
- retail — чтение кег и остатков и проверка кодов, только по перечисленным организациям.
Методы, которые обращаются в ГИС МТ, работают только для организаций с действующим правом (пробный период или оплаченная
подписка организации в кабинете). Без права такие запросы отклоняются с причиной (403 license_denied, подробности — в руководстве).
Лимиты: 120 запросов в минуту на ключ panel, 60 — на ключ retail; после 30 неудачных попыток аутентификации в минуту адрес
временно блокируется (ответ 429 с Retry-After).
Методы
Пути указаны от базового адреса. Справочник версии 2.2.0: 13 методов,
14 HTTP-операций с HEAD /health.
| Метод | Назначение | Роль ключа | Карточка |
|---|---|---|---|
GET, HEAD /health | Проверка доступности. Доступность API, версия программы и среда ГИС МТ | без ключа | Параметры, ответы и ошибки |
GET /tokens | Организации и состояние токенов. Организации программы и состояние токенов (без значений токенов) | panel | Параметры, ответы и ошибки |
GET /tokens/current | Действующий токен организации. Действующий UUID-токен организации; получает новый, если до конца меньше 5 мин | panel | Параметры, ответы и ошибки |
POST /tokens/rotate | Перевыпустить токен. Принудительный перевыпуск токена организации | panel | Параметры, ответы и ошибки |
POST /kegs/connect | Подключить кеги к оборудованию (CONNECT_TAP). Подписать и отправить в ГИС МТ документ CONNECT_TAP (подключение кег к оборудованию) | panel | Параметры, ответы и ошибки |
GET /documents/{doc_id} | Статус документа CONNECT_TAP. Статус документа CONNECT_TAP | panel | Параметры, ответы и ошибки |
GET /kegs | Кеги на учёте. Кеги на учёте программы | retail и panel | Параметры, ответы и ошибки |
GET /kegs/{cis} | Одна кега или сведения ГИС МТ о коде. Кега на учёте с last_info; refresh=true — обновить из ГИС МТ; не на учёте + client — живой запрос в ГИС МТ | retail и panel | Параметры, ответы и ошибки |
GET /kegs/rests/fias | Остатки разливного по адресам ФИАС. Остатки разливного по адресам ФИАС: адрес -> товар -> кеги | retail и panel | Параметры, ответы и ошибки |
POST /kegs/track | Поставить кеги на учёт. Поставить на учёт программы кеги, уже подключённые в ГИС МТ | panel | Параметры, ответы и ошибки |
DELETE /kegs/{cis} | Снять кегу с учёта. Снять кегу с учёта программы | panel | Параметры, ответы и ошибки |
GET /codes/check | Проверка кода маркировки. Сведения ГИС МТ об одном коде и статус продажи | retail и panel | Параметры, ответы и ошибки |
POST /codes/check | Проверка списка кодов. То же для списка до 1000 кодов | retail и panel | Параметры, ответы и ошибки |
Параметр client — название организации, как оно задано в профиле программы. Коды маркировки принимаются
в любом распространённом виде: с разделителем GS, в скобочной записи, с префиксом сканера.
Пример
Pin сертификата — в окне программы «⋯» → «Сертификат и подключение API…» (там же адрес API и готовая команда). Проверка доступности, без ключа:
curl.exe --insecure --pinnedpubkey "sha256//<pin из окна программы>" https://localhost:8443/api/v1/healthЧтение с ключом — организации и состояние токенов (ключ с ролью panel). Значение ключа храните в файле mge-api-key.txt строкой X-Api-Key: <ключ>, а не в командной строке:
curl.exe --insecure --pinnedpubkey "sha256//<pin>" -H @mge-api-key.txt https://localhost:8443/api/v1/tokens--insecure выключает только проверку цепочки самоподписанного сертификата и допустим только вместе с --pinnedpubkey: без закрепления соединение не защищено от подмены сервера. С другого компьютера вместо localhost — адрес из вкладки «API-журнал». Сертификат и закрепление.
Быстрый старт в руководстве — следующие шаги и примеры для PowerShell и 1С.
Ошибки возвращаются в JSON с кодом и описанием: 400 — некорректный запрос, 401 — нет или неверный ключ, 403 — нет доступа
к организации или нет права организации (license_denied), 429 — превышен лимит, 502/503 — ошибка ГИС МТ, подписи
или нет токена.
Полный справочник
Руководство интегратора — подключение и закрепление сертификата, карточка каждого метода с полями, ошибками и примерами, повторы и длительные операции, примеры cURL, PowerShell и 1С. Версия справочника по умолчанию выбирается по версии программы на странице загрузок.
На странице загрузок — программа версии 2.1.0. Справочника этой версии нет, по умолчанию показан справочник 2.2.0 — самой ранней из описанных версий; методы и поля более ранних версий могут отличаться.
- Версия 2.2.1 подготовлено к выпуску — на странице загрузок этой версии пока нет
- Версия 2.2.0 подготовлено к выпуску — на странице загрузок этой версии пока нет (по умолчанию)
- Руководство интегратора 2.2.0 — HTML, открывается в браузере, работает без интернета, 178 КБ
- Схема OpenAPI 3.1 для 2.2.0 — YAML, 30 КБ
- Примеры запросов — ZIP: HTTP, cURL, Windows PowerShell, 1С; для версий 2.2.0 и 2.2.1, 26 КБ
Вошедшим в личный кабинет тот же справочник с быстрым стартом доступен в разделе «API и документация».
API приёма чеков
Отдельный серверный API для передачи чеков продаж из 1С, ОФД и других систем (для актов списания ЕГАИС) ещё не опубликован. Его описание появится в этом разделе вместе с запуском; локальный API программы он не заменяет.