Введение

Утилита tspiot-add-kkt — графический инструмент на PowerShell (WinForms) для управления экземплярами ККТ в локальном сервисе ЕСМ/ТС ПИоТ (оркестратор ЕСМ, по умолчанию 127.0.0.1:51077). Позволяет визуально добавлять, проверять и удалять экземпляры ККТ без ручного набора запросов в PowerShell или Postman.

Используется, когда к одному ЕСМ/ТС ПИоТ нужно подключить дополнительную кассу (ККТ). Основана на инструкции «Добавление дополнительной ККТ к ЕСМ/ТС ПИоТ».

ИНФОРМАЦИЯ

Утилиту следует запускать на кассовом ПК, где установлен и запущен сервис ЕСМ/ТС ПИоТ.

Требования

• Windows PowerShell 2.0 или выше — утилита совместима даже с Windows 7 без установки дополнительных компонентов (WMF). Запросы выполняются через System.Net.HttpWebRequest.
• Запущенный локальный сервис ЕСМ/ТС ПИоТ на кассовом ПК.
• Для шага регистрации — запущенный агент-сервис драйвера АТОЛ (ДККТ), gRPC-порт по умолчанию 4041.

Загрузка и запуск

1. Скачайте утилиту: tspiot-add-kkt.zip (или отдельный файл tspiot-add-kkt.ps1) и распакуйте на кассовый ПК.

2. Запустите утилиту одним из способов:

   • правый клик по 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}) защищена от случайного срабатывания тремя уровнями:

1. Предохранитель — кнопка неактивна, пока не включён чекбокс «Разрешить удаление».
2. Проверка существования — введённый id сверяется со списком; при опечатке удаление отменяется, запрос не отправляется. В подтверждении показываются параметры цели.
3. 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.