¶ Введение
Утилита tspiot-add-kkt — графический инструмент на PowerShell (WinForms) для управления экземплярами ККТ в локальном сервисе ЕСМ/ТС ПИоТ (оркестратор ЕСМ, по умолчанию 127.0.0.1:51077). Позволяет визуально добавлять, проверять и удалять экземпляры ККТ без ручного набора запросов в PowerShell или Postman.
Используется, когда к одному ЕСМ/ТС ПИоТ нужно подключить дополнительную кассу (ККТ). Основана на инструкции «Добавление дополнительной ККТ к ЕСМ/ТС ПИоТ».
Утилиту следует запускать на кассовом ПК, где установлен и запущен сервис ЕСМ/ТС ПИоТ.
¶ Требования
- Windows PowerShell 2.0 или выше — утилита совместима даже с Windows 7 без установки дополнительных компонентов (WMF). Запросы выполняются через
System.Net.HttpWebRequest. - Запущенный локальный сервис ЕСМ/ТС ПИоТ на кассовом ПК.
- Для шага регистрации — запущенный агент-сервис драйвера АТОЛ (ДККТ), gRPC-порт по умолчанию
4041.
¶ Загрузка и запуск
-
Скачайте утилиту: tspiot-add-kkt.zip (или отдельный файл tspiot-add-kkt.ps1) и распакуйте на кассовый ПК.
-
Запустите утилиту одним из способов:
-
правый клик по
tspiot-add-kkt.ps1→ «Выполнить с помощью PowerShell»; -
либо в консоли:
powershell -ExecutionPolicy Bypass -File .\tspiot-add-kkt.ps1
-
Если запросы нужно выполнять с другого ПК, впишите в поле «Адрес ЕСМ/ТС ПИоТ» IP-адрес кассового компьютера вместо
127.0.0.1.
¶ Интерфейс утилиты
Окно разделено на блоки.
¶ Параметры подключения
| Поле | Назначение | По умолчанию |
|---|---|---|
| Адрес ЕСМ/ТС ПИоТ | Хост сервиса оркестратора | 127.0.0.1 |
| Порт оркестратора | Порт ЕСМ/ТС ПИоТ | 51077 |
¶ Параметры нового экземпляра ККТ
| Поле | Назначение |
|---|---|
Серийный номер ККТ (id = kktSerial) |
Серийный номер кассы. Является идентификатором экземпляра. |
port |
Сетевой порт экземпляра. Должен быть уникальным для каждой ККТ. |
softPort |
Программный порт экземпляра. Должен быть уникальным. В кассовом ПО указывается как «Порт ЕСМ». |
dkktPort (gRPC АТОЛ) |
gRPC-порт драйвера АТОЛ. По умолчанию 4041, общий для всех ККТ. |
Серийный номер ФН (fnSerial) |
Серийный номер фискального накопителя. |
ИНН (kktInn) |
ИНН организации. |
Уникальность портов. Для каждой кассы берите следующую свободную пару
port/softPort, например:50401/51401,50402/51402,50403/51403, … ПортdkktPort(4041) общий для всех касс. Можно добавлять любое число касс — меняйте серийный номер и пару портов.
¶ Порядок добавления ККТ (5 шагов)
Кнопки запускаются по порядку. Результат каждого шага выводится в текстовое поле (ответ в UTF-8).
| Шаг | Кнопка | Запрос | Что делает |
|---|---|---|---|
| 1 | 1. Список ККТ | GET /api/v1/instances/info |
Показывает текущие экземпляры — убедиться, что нужная ККТ ещё не создана. |
| 2 | 2. Создать (POST) | POST /api/v1/tspiot |
Создаёт экземпляр сервиса с параметрами { id, port, softPort, dkktPort }. |
| 3 | (вручную) | — | В драйвере АТОЛ переключите связь на нужную кассу и проверьте соединение (gRPC 4041). Кнопки нет — это ручной шаг. |
| 4 | 4. Регистрация (PUT) | PUT /api/v1/tspiot |
Регистрирует ККТ с параметрами { id, kktSerial, fnSerial, kktInn }. В ответе приходит tspiotId. |
| 5 | 5. Проверить список | GET /api/v1/instances/info |
Контрольная проверка — созданный экземпляр должен присутствовать в списке. |
Шаг 3 обязателен перед регистрацией (PUT). Если связь драйвера АТОЛ не переключена на нужную кассу, шаг 4 завершится ошибкой
2046.
После успешной регистрации в кассовом ПО для этой кассы укажите «Порт ЕСМ» = её softPort.
¶ Удаление экземпляра
Кнопка «Удалить экземпляр» (DELETE /api/v1/tspiot/{id}) защищена от случайного срабатывания тремя уровнями:
- Предохранитель — кнопка неактивна, пока не включён чекбокс «Разрешить удаление».
- Проверка существования — введённый
idсверяется со списком; при опечатке удаление отменяется, запрос не отправляется. В подтверждении показываются параметры цели. - Type-to-confirm — нужно повторно ввести
idвручную.
После успешного удаления чекбокс «Разрешить удаление» снимается автоматически.
¶ Произвольный запрос
Блок «Произвольный запрос» позволяет отправить любой метод (GET/POST/PUT/DELETE) на произвольный URL с опциональным телом (JSON) — для исследования API и нестандартных операций.
¶ Маршруты API
Подтверждены на реальном ТС ПИоТ:
GET /api/v1/instances/info — список экземпляров
POST /api/v1/tspiot — создать { id, port, softPort, dkktPort }
PUT /api/v1/tspiot — зарегистрировать { id, kktSerial, fnSerial, kktInn }
DELETE /api/v1/tspiot/{id} — удалить экземпляр по серийному номеру
¶ Расшифровка кодов ошибок
Утилита поясняет наиболее частые коды ответа:
| Код | Причина и решение |
|---|---|
1010 |
Сервис с таким id уже существует. Проверьте список (шаг 1) — возможно, ККТ уже создана. |
1001 |
Некорректное тело запроса. Проверьте поля (id, порты, ФН, ИНН). |
1015 |
Не запущен агент-сервис ДККТ. Запустите службу «ATOL: Fptr grpc service» и проверьте dkktPort (обычно 4041). |
2046 |
Служба ЕСМ не зарегистрирована/не запущена. Проверьте связь драйвера с нужной ККТ (шаг 3) и повторите PUT. |
¶ Почему PowerShell, а не браузер
Сервис ТС ПИоТ не отдаёт CORS-заголовки (Access-Control-Allow-Origin), поэтому браузер блокирует запросы POST/PUT/DELETE к 127.0.0.1:51077 со страницы. Обойти это на стороне браузера нельзя.
Поэтому рабочим инструментом является именно tspiot-add-kkt.ps1 — он выполняет запросы напрямую через System.Net.HttpWebRequest, где CORS не применяется. Браузерный вариант tspiot-add-kkt.html (с тем же интерфейсом) оставлен как генератор готовых PowerShell-команд.
Для сравнения: ЛМ ЧЗ (порт
5995) CORS-заголовки отдаёт, поэтому аналогичные HTML-утилиты для него работают прямо в браузере. У ТС ПИоТ это отключено.
¶ Типовые проблемы
| Симптом | Причина и решение |
|---|---|
Ошибка 1010 при создании |
ККТ с таким серийным номером уже создана. Проверьте список (шаг 1). |
Ошибка 1015 |
Не запущен агент-сервис драйвера АТОЛ. Запустите службу «ATOL: Fptr grpc service», проверьте dkktPort. |
Ошибка 2046 при регистрации (PUT) |
Драйвер АТОЛ не переключён на нужную кассу. Выполните шаг 3 и повторите PUT. |
| Кириллица в ответе отображается «кракозябрами» | Запустите оригинальный .ps1 (без перекодировки). Файл должен быть в UTF-8 с BOM. |
| Кнопка «Удалить экземпляр» неактивна | Это предохранитель. Включите чекбокс «Разрешить удаление». |
| Запросы не проходят с другого ПК | Впишите IP кассового ПК в поле «Адрес ЕСМ/ТС ПИоТ» вместо 127.0.0.1; проверьте доступность порта 51077. |