Руководство системного программиста
> ТС ПИоТДата обновления: 30 октября 2026 г.
Руководство описывает установку, настройку, контроль и структуру локальной и сетевой частей. Действия кассового администратора в интерфейсе — в руководстве пользователя. Пошаговая установка на кассу — в инструкции по установке.
Версия 0.0.1.1030 обращается только к тестовому контуру: регистрация cdn01.am.crptech.ru:19100, операционные CDN cdn01.am.crptech.ru:19101, cdn02.am.crptech.ru:19101, cdn03.am.crptech.ru:19101.
1. Назначение и структура
| Процесс | Файл | Порт | Кто вызывает |
|---|---|---|---|
| Служба локального ТС ПИоТ | PiotLocal.exe |
HTTP 127.0.0.1:5090 |
интерфейс, экземпляр, драйвер |
| Интерфейс | PiotLocalAdmin.exe |
HTTP 127.0.0.1:5091 |
браузер администратора |
| Экземпляр | внутри процесса PiotLocal |
HTTPS 127.0.0.1:<порт> от 50000 |
кассовое ПО |
| Веб-ТС ПИоТ | PiotWebApi |
снаружи 443, внутри контейнера 5065 | локальная часть |
| ЛМ ЧЗ | внешний модуль | HTTP 127.0.0.1:5995 |
локальная часть |
| ГИС МТ | внешний контур | 19100 и 19101 | только веб-часть, TLS 1.3 |
Локальная часть не устанавливает TLS-сессию с *.crptech.ru сама. Она вызывает REST веб-части, а веб-часть держит TLS-сессию ГИС МТ.
2. Установка локальной части
Установщик Windows ставит две службы:
| Имя службы | Отображаемое имя | Командная строка | Запуск |
|---|---|---|---|
PiotLocal |
ТС ПИоТ | Server\PiotLocal.exe |
автоматически |
PiotLocalAdmin |
ТС ПИоТ Админ | Admin\PiotLocalAdmin.exe --no-browser |
автоматически |
Каталог: C:\Program Files (x86)\PiotLocal.
Идентификатор установки пишется один раз в HKLM\SOFTWARE\RBSOFT\PiotLocal\InstanceId и при удалении не стирается. Для работы с ККТ нужна 32-разрядная программа Windows: драйвер РР-Электро — 32-разрядная COM-библиотека.
Драйвер — 32-битная COM-библиотека AddIn.DrvFR. После Connect программа выставляет PiotEnabled = true и ProtocolType = 2. Перед разрывом возвращает транспортный ProtocolType и снимает PiotEnabled: обрыв в режиме ТС ПИоТ оставляет TCP-стек кассы без слушателя до её перезагрузки. На стенде проверен драйвер РР-Электро 7.0.37.
Проверка служб:
sc query PiotLocal
sc query PiotLocalAdmin
В браузере: http://127.0.0.1:5091/devices — код 200, в шапке версия 0.0.1.1030.
3. Каталоги данных
Корень задаётся переменной PIOTLOCAL_DATA. Если она пуста:
%ProgramData%\RBSOFT\Piot\Local
| Путь | Содержимое |
|---|---|
StaticSettings.json |
общие настройки |
config_<id>.json |
карточка экземпляра |
cache\<id>_cdn_cache.json |
кэш площадок CDN |
licenses.json |
кэш лицензий |
log\ |
журнал службы |
certs\instance-https.pfx |
сертификат HTTPS экземпляров, пароль PFX зафиксирован в программе |
%ProgramData%\RBSOFT\Piot\Log\Admin |
журнал интерфейса |
Журналы можно перенести переменной PIOTLOCAL_LOGS.
Сертификат создаётся автоматически: RSA 2048, SHA-256, EKU serverAuth, SAN localhost, 127.0.0.1 и локальные адреса. Срок переиздания — когда до окончания остаётся меньше 30 суток.
4. Настройка локальной службы
Файл appsettings.json рядом с PiotLocal.exe.
| Параметр | Значение поставки | Смысл |
|---|---|---|
Kestrel:Port |
5090 | порт службы |
InstancePorts:InstanceBasePort |
50000 | первый порт экземпляра |
InstancePorts:MaxPort |
65535 | верхняя граница |
InstancePorts:DefaultNetworkIp |
127.0.0.1 |
адрес экземпляра по умолчанию |
NetworkPart:BaseUrl |
https://piot.rbsoft.ru |
веб-часть |
NetworkPart:LocalBaseUrl |
http://127.0.0.1:5090 |
собственный API для шифрования и драйвера |
NetworkPart:CdnEndpoint |
cdn01.am.crptech.ru:19101 |
запасная операционная площадка |
NetworkPart:TestCdnEndpoints |
три хоста :19101 |
запасной список, если aux_data пуст |
Driver:RrElectroProgId |
AddIn.DrvFR |
ProgID драйвера |
Driver:CodesCheckTimeout |
1800 |
запасной таймаут, мс |
Интерфейс читает свой appsettings.json: Kestrel:Port = 5091, PiotLocal:BaseUrl = http://localhost:5090.
Адреса тестового контура на кассе менять не нужно.
5. ЛМ ЧЗ
Локальная служба обращается к модулю по адресу http://{host}:{port}/api/v2/.... Заголовок Authorization: Basic, заголовок X-ClientId — заводской номер ФН.
| Метод | Вызов |
|---|---|
| Состояние | GET /api/v2/status |
| Инициализация после ДКС | POST /api/v2/safe_init |
| Регистрация клиента | POST /api/v2/registerClient |
| Обновление токена | POST /api/v2/refreshToken |
| Серый список | POST /api/v2/greyList |
| Офлайн-проверка | POST /api/v2/cis/outCheck |
| Продажа | POST /api/v2/cis/sell |
| Возврат | POST /api/v2/cis/return |
| Список проданных | GET /api/v2/cis/sold |
| Факт продажи | POST /api/v2/cis/sold/check |
Таймаут outCheck в настройках экземпляра — 1500 мс (outCheckTimeoutMs). Это не таймаут oismCheckTimeout из getconf.
Порядок инициализации модуля, если статус not_configured: открыть ДКС-сессию на хосте регистрации, POST /api/v2/safeActivate через доверенный канал, передать полученный JSON в safe_init без изменений, включить серый список, дождаться готовности, выполнить registerClient с tsp_id. Серый список программа включает всегда.
Версия модуля на стенде, прочитанная из status: 2.6.1-7. В отчёт о конфигурации она уходит как tsp_lm_version.
6. API локальной службы
Префикс http://127.0.0.1:5090. Интерфейс пользуется этими методами. Кассовое ПО их не вызывает: для кассы есть только порт экземпляра.
| Метод | Путь | Назначение |
|---|---|---|
| GET | /piot/list, /piot, /piot/meta |
список, карточка, версия и порты |
| POST, PUT | /piot |
создать и изменить экземпляр |
| POST | /piot/initialize, /piot/status |
регистрация в ГИС МТ и опрос состояния |
| DELETE, POST | /piot, /piot/reg-remove |
снятие регистрации |
| POST | /piot/lm/initialize, /piot/lm/status, /piot/lm/grey-list, /piot/lm/refresh-token |
ЛМ ЧЗ |
| POST | /piot/lm/sell, /piot/lm/return, /piot/lm/sold, /piot/lm/sold-check |
выбытие и возврат кода в модуле |
| POST | /piot/operator, /piot/operator/sign-in, /piot/operator/sign-out |
учётная запись пользователя ТС ПИоТ |
| POST | /piot/events/km-user-msg, /piot/events/user-decision |
сообщения пользователю и его решение |
| GET, POST | /piot/monitoring/summary, /events, /kkt-logs, /kkt-logs/flush |
журнал |
| GET, POST | /piot/license/check, /activate, /deactivate |
лицензия |
| POST | /piot/driver/dks-build, /dks-decrypt, /encrypt-data, /decrypt-data |
криптография ФН через драйвер |
| POST | /piot/driver/ecr-info, /connected-ecr-list, /tspiot-events-count, /tspiot-events-list |
сведения ККТ и журнал FF81 |
7. API экземпляра
Только HTTPS.
| Метод | Путь |
|---|---|
| GET | /health |
| GET | /api/v1/info, /api/v2/info, /api/v3/info |
| POST | /api/v1/codes/check, /api/v2/codes/check, /api/v3/codes/check |
info и codes/check требуют действующую лицензию. codes/check дополнительно требует инициализированный экземпляр, заводской номер ФН и tsp_id.
Таймаут онлайн-проверки — целое cdnCodesCheckTimeout из JSON конфигурации CDN, диапазон 10…30000 мс, по умолчанию 1500.
8. Веб-решение
Публичный адрес: https://piot.rbsoft.ru. На кассу не ставится. Проверка готовности: GET /healthz (30.10.2026 ответ Healthy).
От локального решения веб-решение принимает TLS 1.2 и TLS 1.3. В ГИС МТ запрос уходит по TLS 1.3. На каждый фискальный накопитель держится одно соединение с площадкой: повторная проверка кодов того же ФН отправляется по нему же.
Пределы работающего веб-решения:
| Параметр | Значение |
|---|---|
| Живых сессий с ГИС МТ | до 50000 |
| Время жизни сессии | 60 минут с последнего запроса, короче — если площадка прислала свой срок |
| Таймаут запроса к ГИС МТ | 20 секунд |
| Одновременных запросов | до 20000 |
Методы, которые вызывает локальное решение:
| Путь веб-решения | Куда уходит в ГИС МТ |
|---|---|
POST /api/Authentication/session/start |
POST /api/v4/auth, операция запроса контрольного значения |
POST /api/Authentication/session/finish |
завершение аутентификации на том же TLS |
POST /api/Authentication/session/bind |
привязка сессии к ФН |
POST /api/Authentication/session/rechallenge |
повтор контрольного значения, раздел 6.2 |
POST /api/Dks/exchange |
POST /api/v4/dks |
POST /api/CodesCheck/check-session |
POST /api/v4/cdn/codes/check |
POST /api/CodesCheck/health-session |
POST /api/v4/cdn/health/check |
POST /api/Configuration/getconf-session |
POST /api/v4/cdn/getconf |
POST /api/Configuration/register-instance |
операции регистрации раздела 9 |
POST /api/Configuration/kkt-config-report-session |
POST /api/v4/cdn/kktConfigReport |
POST /api/Configuration/kkt-logs-session |
POST /api/v4/cdn/kkt-logs |
Перед открытием сессии веб-часть проверяет лицензию ККТ. При отказе — HTTP 403. При исчерпании числа сессий — HTTP 503 и заголовок Retry-After: 1.
9. Контроль и диагностика
| Симптом | Куда смотреть |
|---|---|
| Нет интерфейса | служба PiotLocalAdmin, порт 5091 не занят другим процессом |
| Интерфейс есть, карточки не грузятся | служба PiotLocal, порт 5090, журнал %ProgramData%\RBSOFT\Piot\Local\log |
| Ошибка связи с веб-частью | https://piot.rbsoft.ru/healthz, исходящий 443, TLS 1.2 или 1.3 |
Регистрация не получает tsp_id |
доступность тестового хоста :19100 именно с площадки веб-части, а не с кассы; текст в журнале инициализации |
| ЛМ ЧЗ недоступен | процесс модуля, порт 5995, Basic-учётные данные |
codes/check сразу 403 |
лицензия ККТ |
codes/check сразу 503 |
нет tsp_id или нет заводского номера ФН |
codes/check код 514 |
ни CDN, ни ЛМ ЧЗ не ответили в таймаут |
| Код 203 | в конфигурации CDN включён emergencyMode |
| После обрыва связи касса не слушает TCP | перезагрузить ККТ: транспорт остался в ProtocolType = 2 |
Повтор документов в ГИС МТ выполняется на уровне операций протокола: коды 902 и 906 при проверке регистрации повторяются до трёх раз с паузой 20 секунд. Опрос состояния REG_WAIT продолжается, пока не придёт иное состояние. Повтор отправки журнала выполняется фоновой задачей, пока площадка не подтвердит приём.
10. Сообщения
Тексты ошибок пользователю — на русском, их формирует локальная служба («Не задан IP/хост ЛМ ЧЗ», «Экземпляр не инициализирован в ГИС МТ», «Лицензия для данной ККТ отсутствует или недействительна»). Коды результата codes/check (0, 203, 204, 514 и коды площадки) возвращаются в JSON кассовому ПО и на экран кассы выводит уже кассовое ПО.