Innokassa MDK (Module Development Kit) - набор программных средств на PHP для использования API облачной кассы Pangaea V2 от Innokassa, содержащий в себе всю необходимую логику для фискализации заказов интернет-магазинов (ИМ), с поддержкой мультисайтовости.
Для работы библиотеки требуется PHP
версии не ниже 7.1
с библиотекой curl
.
Описание:
- ОО стиль - все есть объект
- использует PSR-4 автозагрузку классов
- применяется стардарт PSR12
- оснащен
Unit
/Server
/System
тестами PHPUnit - не имеет зависимостей - концепция многократного использования без зависмостей, поэтому можно использовать в без-
composer
'ной среде
Клонирование репозитория:
git clone https://git.innokassa.ru/Byurrer/mdk.git
Через composer
:
composer require innokassa/mdk
В проектах не использующих composer
необходимо подключить автозагрузку классов:
require_once('mdk/src/autoload.php');
Перед использованием необходимо реализовать на стороне клиента:
- SettingsAbstract - получение настроек
- ReceiptStorageInterface - хранилище данных чеков
- ReceiptAdapterInterface - адаптер чеков под заказы, чтобы сервис
Automatic
мог формировать чек из заказа - ReceiptIdFactoryInterface - фабрика идентификаторов чеков, есть базовая реализация ReceiptIdFactoryMeta, в которой необходимо переопределить метод
getEngine
Для сериализации/десериализации данных чеков БД
<=>MDK
существует базовый конвертер ConverterStorage. При необходимости можно создать новую реализацию ConverterAbstract.
Для взаимодействия с сервером фискализации используется NetClientCurl. При необходимости можно создать новую реализацию NetClientInterface.
В базовом варианте использование MDK
осуществляется через класс Client
, посредством получения сервисов и лишь в редких случаях через компоненты (например при проверке настроек).
Клиент API Pangaea V2 состоит из:
- сервисов (для каждого сервиса существует базовая реализация):
- Autmotaic - автоматическая фискализация приходов заказов для выдачи чеков без вмешательства администратора ИМ, например при оплате заказа покупателем
- Pipeline - обработка очереди чеков когда сервер фискализации пробивает чеки не сразу
- Connector - проверка введенных настроек на соответсвие данным на кассе
- компонентов (для дополнительного взаимодействия с MDK):
После того как все необходимые интерфейсы реализованы можно создавать объект Client
:
// создание компонентов
$settings = new SettingsConcrete();
$storage = new ReceiptStorageConcrete(new ConverterStorage());
$adapter = new ReceiptAdapterConcrete();
$receiptIdFactory = new ReceiptIdFactoryMetaConcrete();
$transfer = new Transfer(
new NetClientCurl(),
new ConverterApi()
);
// создание сервисов
$automatic = new AutomaticBase(
$settings,
$storage,
$transfer,
$adapter,
$receiptIdFactory
);
$pipeline = new PipelineBase($settings, $storage, $transfer, $receiptIdFactory);
$connector = new ConnectorBase($transfer);
// создание клиента
$mdk = new Client(
$settings,
$storage,
$automatic,
$pipeline,
$connector
);
Перед сохранением настроек необходимо проверить корректность введенных данных на соответствие данным на кассе:
// ассоциативный массив новых настроек введенных пользователем в интерфейсе сайта
$settings = [
'actor_id' => 'actor_id',
'actor_token' => 'actor_token',
'cashbox' => 'cashbox',
'site' => 'https://example.com/',
'taxation' => Taxation::USN,
'scheme' => SettingsInterface::SCHEME_PRE_FULL,
'vat_shipping' => Vat::CODE_WITHOUT,
'type_default_items' => ReceiptItemType::PRODUCT,
'vat_default_items' => Vat::CODE_WITHOUT,
'order_status_receipt_pre' => 'payed',
'order_status_receipt_full' => 'delivered'
];
try {
// формирование трансфера с указанием минимальных данных для соединения
$transfer = new Transfer(
new NetClientCurl(),
new ConverterApi()
);
// создание коннектора и тестирование настроек
$conn = new ConnectorBase($transfer);
$conn->testSettings(new SettingsConcrete($settings));
} catch(SettingsException $e) {
throw new Exception($e->getMessage());
}
Автоматическая фискализация действует в контексте конкретного заказа.
Пример использования (список исключений, типы чеков):
try {
$automatic = $mdk->serviceAutomatic();
// автоматическое определение типа чека
$automatic->fiscalize($idOrder);
// указание конкретного типа чека, например полный расчет в момент передачи товара покупателю
// automatic->fiscalize($idOrder, 's1', ReceiptSubType::FULL);
} catch(Exception $e) {
throw $e;
}
Сервер фискализации может не сразу пробить чек по разным причинам, например ответив кодом 202. После чего необходимо узнать текущий статус чеков. Эту задачу решает Pipeline
(PipelineBase базовая реализация PipelineInterface), методы которого должны запускаться (каждый в отдельном экземпляре) в планировщике задач (например через cron
), желательно каждые 10 минут.
Существует несколько статусов чека, но все чеки со статусом подлежащим фискализации обработаются вместе.
Пример:
$pipeline = $mdk->servicePipeline();
// обновление статусов чеков
$pipeline->update();
Pipeline
также обрабатывает 50x коды ответов, ответы подобного рода не должны быть, но для предсказуемости введена обработка.
Сервисы и компоненты могут выбрасывать исключения, это однозначно означает что операция не удалась и с теми же данными не пройдет, за исключением проблем со связью. Каждый объект выбрасывает свойственные ему исключения (подробнее в исходном коде интерфейсов/классов).
Ответсвенность за обработку исключений ложится на клиентский код.
Рекомендации:
- при автоматических действиях оповещать пользователя интеграции через email или другими доступными средствами
Для разработки потребуется
docker compose
Репозиторий содержит docker-compose.dev.yml для организации среды разработки MDK
, состоит из двух контейнеров:
mdk-backend
- основан на php:7.1-cli с модификациями, внутри используетсяxdebug
(2.8.1) для отладки иcomposer
(2.2) для установки зависимостей разработкиmdk-db
- основан mysql:5.7 без модификаций (логин:пароль от БДroot
:root
)
Запуск контейнеров:
./dev.sh
После запуска будет развернута изолированная среда со всем необходимым ПО для разработки MDK
.
Запуск тестов исходного кода MDK
:
./test.sh
Рекомендуемые расширения для VS Code
(нужные настройки подгрузятся из конфига в репозитории):
Если при использовании библиотеки у вас возникли проблемы, вы можете составить Issue
.
Вы можете предложить свои изменения исходного кода, через Issue
/Pull request
.
Каждые внесенные изменения должны быть протестированы, а соответствующие тесты должны быть внесены в директорию с тестами.
Процент покрытия unit
тестами должен составлять >= 98%
MIT