README

PHP библиотека классов для работы с кассовыми аппаратами (ККТ) через KKM Server. Предоставляет удобный API для создания команд, печати чеков и управления сменами в кассовых аппаратов.

📋 Описание

KKM Server Classes — это PHP библиотека, разработанная для взаимодействия с кассовыми аппаратами (ККТ) через KKM Server. Библиотека имеет функции:

📝 Печать чеков с поддержкой различных типов платежей
🔄 Управление сменой (открытие/закрытие)
📊 Получение отчётов (X-отчёты, Z-отчёты)
💳 Обработка платежей (наличные, электронные, авансовые)
💰 Инкассация и пополнение кассы
🏪 Работа с устройствами и получение данных ККТ

Библиотека полностью совместима с российской системой фискализации и поддерживает все основные функции современных кассовых аппаратов.

🎯 Основные возможности

Команды ККТ

Команда	Описание
`Cheque`	Печать товарного чека с поддержкой различных видов платежей
`OpenShift`	Открытие смены на кассовом аппарате
`CloseShift`	Закрытие смены с выведением Z-отчёта
`XReport`	Печать X-отчёта (внутренний отчёт смены)
`ZReport`	Печать Z-отчёта (итоговый отчёт смены)
`PaymentCash`	Инкассация (изъятие) наличных денежных средств
`DepositingCash`	Пополнение кассы наличными среди наличными
`GetDataKKT`	Получение технических данных о кассовом аппарате
`DeviceList`	Получение информации о подключённых устройствах

Типы платежей

💵 Наличные (Cash)
💳 Электронные платежи (Electronic)
🎫 Предоплата (Advanced)
📋 Кредит (Credit)
🏦 Кассовое обеспечение (CashProvision)

Типы чеков

✅ Продажа/Приход
🚫 Возврат продажи
🚫 Корректировка продажи
🚫 Покупка/Расход
🚫 Возврат покупки
🚫 Корректировка покупки

📦 Требования

PHP >= 8.1
Composer
OpenSSL PHP extension

Зависимости

php: ^8.1
twig/twig: ^3.23
twbs/bootstrap: 5.3.8
symfony/http-foundation: ^8.0
symfony/serializer: ^8.0
symfony/property-access: ^8.0
phpdocumentor/reflection-docblock: ^6.0
symfony/serializer-pack: ^1.3
ramsey/uuid: ^4.9
monolog/monolog: ^3.10

🚀 Установка

Через Composer

composer require djalone/kkm-server-classes

💡 Использование

Меню работы с ККТ

<?php
...
/* Получите ИНН и ФИО кассира обычным для вас способом */
    $cashierINN = $lib->getCashierInn();
    $cashierName = $lib->getCashierName();
...
/* Выведите ссылку на меню */
echo "<a href=\"path-to-your-vendor-dir/frontend/menu.php?cashierName={$cashierName}&cashierVatin={$cashierVatin}\">Меню работы с ККТ </a>";
...

При переходе будет меню для работы

Базовый пример: Печать чека

<?php

use Djalone\KkmServerClasses\Cheque;
use Djalone\KkmServerClasses\Cheque\Enums\PaymentTypes;
use Djalone\KkmServerClasses\Cheque\Items\Position;
use Djalone\KkmServerClasses\Services\CustomGUID;
use Djalone\KkmServerClasses\Services\Serializer;
use Djalone\KkmServerClasses\Services\Helper;

require_once 'vendor/autoload.php';

// Создание чека
$cheque = new Cheque(
    'Иванов И.И.',                // Имя кассира
    '123-----12',                 // ИНН кассира
    '',                           // Номер ККТ (опционально)
    CustomGUID::getCommandGuid()  // Уникальный идентификатор команды
);

// Установка информации о клиенте
$cheque
    ->setClientAddress('+791-------')
    ->setClientInfo('Иванов Иван Иванович');

// Добавление товара в чек
$cheque->addItem(
    (new Position('Товар 1', 1000, 2000))  // название, цена в копейках, количество в тысячных долях
        ->setPaymentType(PaymentTypes::Electronic)
);
// Определите ссылку callBack для получения ответа от фронтенда
$callBackUrl = '/my-callback-url.php';

...
// Выведите форму на экран с разу выполните переход
    echo Helper::echoForm($cheque,$callBackUrl);
...

После вызова, вы будете переброшены на страницу для работы печатью

📁 Структура проекта

src/
├── Command.php                         # Базовый класс для всех команд
├── Cheque.php                          # Класс чека
├── OpenShift.php                       # Команда открытия смены
├── CloseShift.php                      # Команда закрытия смены
├── XReport.php                         # X-отчет
├── GetDataKKT.php                      # Получение данных ККТ
├── PaymentCash.php                     # Инкассация наличных
├── DepositingCash.php                  # Пополнение кассы
├── DeviceList.php                      # Список устройств
├── Cheque/                             # Элементы для работы с чеком
│   ├── Enums/                          # Перечисления (типы оплаты, налоги и т.д.)
│   │   ├── PaymentTypes.php            # Тип платежа за услугу
│   │   ├── ChequeType.php              # Тип чека
│   │   ├── Tax.php                     # Налоговые ставки
│   │   ├── MeasureOfQuantity.php       # Единицы измерения товаров
│   │   ├── SignMethodCalculation.php   # Признак способа расчета
│   │   └── SignCalculationObject.php   # Признак предмета расчета
│   └── Items/                          # Элементы документа (позиции, текст, изображения)
│       ├── Position.php                # Позиция чека (товар или услуга)
│       ├── Text.php                    # Текст в чеке (нефискальная печать)
│       ├── Image.php                   # Изображение на чеке
│       └── Barcode/                    # Штрих-коды
└── Services/                           # Сервисы для помощи в работе с библиотекой
    ├── Serializer.php                  # Сериализация в JSON
    ├── Logger.php                      # Логирование
    ├── Helper.php                      # Вспомогательные функции
    ├── CustomGUID.php                  # Генерация GUID
    └── ...

tests/
├── CloseShiftTest.php
├── OpenShiftTest.php
├── PaymentCashTest.php
├── XReportTest.php
├── GetDataKKTTest.php
├── DepositingCashTest.php
└── ...

frontend/                               # Фронтенд (PHP + HTML + JavaScript)
├── js/                                 # Обработка JS
│   ├── base/                           # Общие для всего фронтенда скрипты
│   │   ├── baseFunctions.js            # Базовые функции для работы с сервером ККМ
│   │   ├── kkmSwitcher.js              # Переключатель между ККТ
│   │   ├── moment-with-locales.js      # Библиотека работы с датами
│   │   └── operationsModal.js          # Всплывающее окно информации о поведении
│   ├── menu/                           # Скрипты для работы в меню
│   │   ├── inOutCash.js                # Обработка внесения наличных и инкассации
│   │   ├── kkmServer.js                # Работа со статусом ККТ
│   │   └── simpleOperations.js         # Простые операции (открытие/закрытие смены, отчеты и т.д.)
│   ├── printer/                        # Скрипты для работы с чеком
│   │   ├── callBack.js                 # Обработчик обратного вызова в систему
│   │   ├── interface.js                # Автономные функции интерфейса
│   │   └── printer.js                  # Работа с ККТ для печати чека
├── templates/                          # Twig-шаблоны для интерфейса
├── menu.php                            # Меню взаимодействия с ККТ
└── printer.php                         # Фронтенд для печати чека
backend/                                # Бэкенд для работы с фронтендом

🧪 Тестирование

Проект включает полный набор unit-тестов с использованием PHPUnit.

Запуск всех тестов

php vendor/bin/phpunit tests

Запуск тестов конкретного класса

php vendor/bin/phpunit tests/ChequeTest.php

Запуск тестов с отчётом о покрытии

php vendor/bin/phpunit --coverage-html coverage/

🛠️ Разработка и инструменты

Исправление стиля кода

Проект использует PHP CS Fixer для автоматического исправления стиля кода:

php vendor/bin/php-cs-fixer fix src/
php vendor/bin/php-cs-fixer fix tests/

Статический анализ

PHPStan используется для статического анализа кода:

php vendor/bin/phpstan analyse src/ --level=9

Рефакторинг

Rector помогает автоматизировать рефакторинг кода:

php vendor/bin/rector process src/

📝 API Документация

Класс Cheque

Основной конструктор

public function __construct(
    string $cashierName = '',
    string $cashierVatin = '',
    string $kktNumber = '',
    string $idCommand = ''
)

Основные методы

addItem(Item $item): self — добавить товар/элемент
setChequeType(ChequeType $type): self — установить тип чека
setClientEmail(string $email): self — установить email клиента
setClientPhone(string $phone): self — установить телефон клиента
setClientAddress(string $address): self — установить адрес клиента
setClientInfo(string $info): self — установить ФИО/названия компании
setClientINN(string $inn): self — установить ИНН клиента
toArray(): array — получить массив параметров команды

Класс Position

Конструктор

public function __construct(
    string $name,           // Название товара
    int $price,            // Цена в копейках
    int $quantity          // Количество в тысячных долях (1000 = 1 шт)
)

Методы

setPaymentType(PaymentTypes $type): self — установить тип платежа
setTax(Tax $tax): self — установить налоговую ставку
setDepartment(int $id): self — установить номер отдела
setMeasureOfQuantity(MeasureOfQuantity $measure): self — установить единицу измерения

Сервис Serializer

public static function serializeCheque(Cheque $cheque): string
// Возвращает JSON-строку команды чека

public static function deserializeCheque(string $json): Cheque
// Десериализует JSON обратно в объект Cheque

Сервис Logger

Logger::getInstance()->info('Сообщение', ['дополнительные' => 'данные']);
Logger::getInstance()->error('Ошибка');
Logger::getInstance()->warning('Предупреждение');

📊 Примеры интеграции

Интеграция с веб-приложением

Смотрите папку frontend/ и backend/ для примеров практической интеграции:

frontend/menu.php         # Интерфейс меню управления ККТ
frontend/printer.php      # Обработчик печати чеков
backend/testCallback.php  # Пример обработчика callback

🐛 Обработка ошибок

Все команды наследуют базовый класс Command, который включает обработку ошибок:

$cheque = new Cheque(...);
// ... конфигурация ...

if ($cheque->isValid()) {
    $json = Serializer::serializeCheque($cheque);
} else {
    $errors = $cheque->getErrors();
    // Обработка ошибок
}

🔐 Безопасность

Все входные данные обрабатываются и валидируются
Используются типизированные свойства PHP 8.1+
Поддержка UUID для уникальных идентификаторов команд
Логирование всех операций с ККТ

📄 Лицензия

MIT License - смотрите файл LICENSE для деталей.

👤 Автор

Egor Ermilov

Email: egor.ermilov1992@gmail.com

🤝 Вклад

Улучшения, исправления ошибок и новые функции приветствуются!

djalone / kkm-server-classes

Maintainers

Package info

Statistics

Security