Webkassa iikoFront Adapter

Фискализация Webkassa непосредственно из iikoFront

Webkassa iikoFront Adapter регистрируется как внешний фискальный регистратор API V9. Плагин передаёт продажи и возвраты из iikoFront в локальный sidecar, который работает с Webkassa API v4, хранит результаты фискализации и обслуживает печать чеков и отчётов.

Текущий релиз 0.11.55-beta предназначен для тестовых и пилотных терминалов iikoFront 9.5. Версия, пакет и контрольная сумма на этой странице синхронизируются с опубликованным beta manifest.

Ссылки проекта

• Исходный код и README на GitHub ↗
• GitHub Release v0.11.55-beta ↗
• Индекс документации ↗
• Полная инструкция установки на терминал ↗
• Описание конфигурации ↗
• Полный CHANGELOG ↗
• Публичный beta manifest ↗

Возможности

• Фискальная продажа и возврат с сохранением основания исходной продажи
• Авторизация и фискальные операции через Webkassa API v4
• X- и Z-отчёты через локальный sidecar
• Печать официального формата чека Webkassa на принтер iiko или через Windows/PDF
• Offline-очередь до 72 часов и синхронизация после восстановления связи
• Машинное хранение секретов через Windows DPAPI
• Диагностика распространённых ошибок Webkassa и контроль срока лицензии/ОФД
• Beta/stable updater с проверкой размера и SHA-256 пакета
• Экспериментальный поток Национального каталога/NTIN/GTIN — по умолчанию отключён

Установка

1. Проверьте терминалПодтверждены Windows 11 Pro x64, iikoFront 9.5.x с API V9 и Node.js 22.22.1+. Для новых установок рекомендуется Node.js 24.x; Windows worker проверен на 24.16.0.
2. Скачайте и распакуйте ZIPИспользуйте пакет с этой страницы и перед установкой сверьте SHA-256. Сделайте резервную копию текущего плагина и конфигурации.
3. Запустите установщикОстановите iikoFront и выполните команду ниже из распакованной папки. Установщик создаст каталоги ProgramData, настроит ACL, развернёт плагин и локальную службу sidecar.

powershell -ExecutionPolicy Bypass -File .\install-iikofront-terminal.ps1 -IikoFrontUser "DOMAIN_OR_PC\iiko-user" -StopIikoFront

4. Введите настройки на этом терминалеОткройте «Настройки Webkassa» в iikoFront, укажите данные кассы и сохраните. DPAPI-секреты привязаны к компьютеру и не переносятся с другого терминала.
5. Запустите проверкуЗапустите или перезапустите службу WebkassaIikoFrontSidecar, выполните read-only тест подключения и проверьте продажу, возврат, X- и Z-отчёт на тестовой кассе.

Sidecar по умолчанию не запускается до ввода корректных реквизитов. Подробности и нестандартный путь плагинов описаны в terminal-install инструкции ↗.

Пример настройки

Основные параметры удобнее вводить через окно «Настройки Webkassa». Файл по умолчанию находится в %ProgramData%\WebkassaIikoFrontAdapter\config\webkassa-adapter.config.json.

{
  "environment": "production",
  "baseUrl": "https://kkm.webkassa.kz",
  "cashboxUniqueNumber": "YOUR_CASHBOX_NUMBER",
  "secretRefs": {
    "apiKey": "Webkassa API key",
    "login": "Webkassa login",
    "password": "Webkassa password"
  },
  "auth": { "mode": "apiKeyAndLoginPassword" },
  "fiscalization": {
    "protocolVersion": "2.0.3",
    "writeFiscalData": true
  },
  "offline": {
    "enabled": true,
    "maxOfflineHours": 72,
    "syncOnReconnect": true
  },
  "nationalCatalog": {
    "enabled": false,
    "dryRun": true
  },
  "sidecar": {
    "enabled": true,
    "baseUrl": "http://127.0.0.1:17777",
    "timeoutMs": 30000
  },
  "logging": {
    "level": "info",
    "redactSecrets": true,
    "retentionDays": 30
  }
}

Для production подтверждён только режим apiKeyAndLoginPassword. loginPasswordOnly остаётся compatibility mode и не заявляется как проверенный production-вариант. Не записывайте API key, пароль или токен открытым текстом: установочная утилита хранит реальные секреты в DPAPI-файлах.

Совместимость

История изменений

Открыть полный CHANGELOG на GitHub ↗

Известные проблемы и ограничения

Для технической проблемы beta создайте GitHub Issue ↗ и укажите версию адаптера, iikoFront, тип операции и обезличенные логи. Клиентская поддержка через форму iiko-plugin.kz будет объявлена отдельно. Не прикладывайте пароли, токены, DPAPI-файлы или данные клиентов.