README

Innokassa模块开发工具包

Innokassa MDK (模块开发工具包) - 使用PHP编写的软件工具包，用于通过Innokassa的Pangaea V2 API进行云计费，包含用于实现在线商店（IM）订单的物理化所需的所有逻辑，支持多站点。

运行此库需要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方法

对于收据数据的序列化和反序列化，存在一个基本转换器ConverterStorage。如果需要，可以创建新的实现ConverterAbstract。

用于与税务服务器交互的是NetClientCurl。如果需要，可以创建新的实现NetClientInterface。

客户端

在基本版本中，使用MDK是通过获取服务和仅在极少数情况下通过组件（例如，在检查设置时）通过类Client进行的。

Pangaea V2 API客户端由以下部分组成

服务（每个服务都有基本实现）
- 自动 - 自动化处理订单收入以生成收据，无需管理员干预，例如在顾客支付订单时
- 管道 - 处理收据队列，当税务服务器不立即打印收据时
- 连接器 - 检查输入的设置是否符合收银机上的数据
组件（用于与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响应代码，这种类型的响应不应该出现，但为了可预测性，已经进行了处理。

错误处理

服务和组件可能会抛出异常，这明确表示操作失败，并且使用相同的数据不会成功，除非是连接问题。每个对象都会抛出其特有的异常（更多详细信息请参阅接口/类的源代码）。

处理异常的责任在于客户端代码。

建议

在自动操作时，通过电子邮件或其他可用的手段通知用户集成

开发

开发需要 docker compose

存储库包含用于设置开发环境的 docker-compose.dev.yml，由两个容器组成

mdk-backend - 基于 php:7.1-cli 并进行修改，内部使用 xdebug（2.8.1）进行调试和 composer（2.2）安装开发依赖项
mdk-db - 基于 mysql:5.7 未进行修改（数据库登录名：密码为 root:root）

启动容器

./dev.sh

启动后，将部署一个包含所有必需开发软件的隔离环境

启动 MDK 的源代码测试

./test.sh

推荐用于 VS Code 的扩展（所需的设置将从存储库中的配置文件加载）

问题和贡献

如果您在使用库时遇到问题，可以创建 Issue。

您可以通过 Issue/Pull request 提出对源代码的更改。

每次提交的更改都必须经过测试，并且应在测试目录中添加相应的测试。

单元测试覆盖率应大于等于 98%

许可

MIT

innokassa / mdk

维护者

详情

README

Innokassa模块开发工具包

目录

安装

使用

客户端实现

客户端

初始化

设置

自动

流水线

错误处理

开发

问题和贡献

许可