Локальный API программы
Программа поднимает на своём компьютере HTTPS API для ваших систем — кассового ПО, учётной системы, собственных сервисов. API работает, пока программа запущена.
Адрес
https://<адрес-компьютера>:8443/api/v1- Порт по умолчанию — 8443. Формат — JSON в UTF-8, поля в
snake_case. - Сертификат самоподписанный: клиент не проверяет цепочку, а закрепляет открытый ключ сертификата (pinning).
- API рассчитан на локальную сеть или VPN. Не открывайте его в интернет.
Ключи и роли
Каждый запрос, кроме GET /health, передаёт ключ в заголовке X-Api-Key. Ключи хранятся в файле
api_keys.json рядом с программой; при первом открытии окна ключей файл создаётся со случайными ключами.
Для каждого ключа задаются роль, доступные организации и, при необходимости, разрешённые IP-адреса.
- panel — все методы: токены, подключение и учёт кег, состояние документов, проверка кодов.
- retail — чтение кег и остатков и проверка кодов, только по перечисленным организациям.
Лимиты: 120 запросов в минуту на ключ panel, 60 — на ключ retail; после 30 неудачных попыток аутентификации в минуту адрес
временно блокируется (ответ 429 с Retry-After).
Методы
| Метод | Путь | Роль | Назначение |
|---|---|---|---|
GET | /health | — | Проверка доступности, без ключа |
GET | /tokens | panel | Список организаций и сроки их токенов True API |
GET | /tokens/current?client=… | panel | Действующий токен организации |
POST | /tokens/rotate?client=… | panel | Обновить токен организации |
POST | /kegs/connect | panel | Подключить кеги к оборудованию для розлива |
GET | /documents/{doc_id} | panel | Статус документа подключения кег (CONNECT_TAP) |
GET | /kegs?client=… | retail | Кеги на учёте: объём, продано, остаток, срок |
GET | /kegs/{cis} | retail | Сведения по одной кеге |
GET | /kegs/rests/fias | retail | Остаток разливного по ФИАС-адресам |
POST | /kegs/track | panel | Поставить кеги на учёт |
DELETE | /kegs/{cis} | panel | Снять кегу с учёта |
GET | /codes/check?cis=… | retail | Проверка кода маркировки и статус продажи |
POST | /codes/check | retail | Проверка списка до 1000 кодов |
Параметр client — название организации, как оно задано в профиле программы. Коды маркировки принимаются
в любом распространённом виде: с разделителем GS, в скобочной записи, с префиксом сканера.
Пример
curl -k -H "X-Api-Key: <ключ>" "https://<адрес>:8443/api/v1/codes/check?cis=<код>"Ошибки возвращаются в JSON с кодом и описанием: 400 — некорректный запрос, 401 — нет или неверный ключ, 403 — нет доступа к организации, 429 — превышен лимит, 502/503 — ошибка ГИС МТ, подписи или нет токена.
Полный справочник
Поля запросов и ответов каждого метода, коды ошибок и журнал запросов описаны в справочнике, который поставляется вместе с программой (файл README.txt в архиве, раздел «Входящий API»). Текущая версия программы.
API приёма чеков
Отдельный серверный API для передачи чеков продаж из 1С, ОФД и других систем (для актов списания ЕГАИС) ещё не опубликован. Его описание появится в этом разделе вместе с запуском; локальный API программы он не заменяет.