README

用于Magento 1/2的在线收银机集成模块

本模块旨在完全支持54号法对Magento 1和2互联网商店的要求

АТОЛ онлайн。模块支持服务版本АТОЛ v4 (ФФД 1.05)。
Чеконлайн。

模块功能

向在线收银机传输数据

发送账单/退货数据
- 在创建账单时自动发送（在配置中可设置）
- 在创建退货时自动发送（在配置中可设置）
- 通过一个控制台命令手动发送（见下文）
- 从管理后台手动发送，按钮位于账单或退货页面

再次向在线收银机传输数据（Resell）

（不要与调整凭证混淆）

取消先前的收据入库（按发票）并发送新的收据。
- 在管理后台点击按钮 Resell 手动执行
- 通过控制台命令（见下文）
- 另一个模块可以触发 \Mygento\Kkm\Api\Processor\SendInterface::proceedResellRefund

从АТОЛ获取数据

从АТОЛ获取账单/退货状态的数据
- 自动获取（在配置中可设置）。处理完数据后，АТОЛ将结果发送回（回调）。默认URL：http://shop.ru/kkm/frontend/callback
- 通过定时任务检查状态
- 从管理后台手动发送，按钮位于账单或退货页面
- 通过控制台命令 mygento:kkm:update-one {$uuid} 或 mygento:kkm:update-all {$storeId}

从Чеконлайн获取数据

Чеконлайн服务基于同步原则构建，服务中不存在“文档状态”的概念。相反，使用缓存响应。缓存键是Group, RequestId, ClientId字段，这意味着如果发送了具有相同指定字段的请求，则服务将返回缓存中的数据。缓存包含成功的响应和一些错误（请参阅Чеконлайн文档）

向在线收银机发送数据的流程

根据Invoice或Creditmemo实体，生成Mygento\Kkm\Api\Data\RequestInterface对象。1.1.在异步传输时，对象被放入队列（见Magento Queue Framework）。1.2.在同步传输时，将对象传递给Vendor类进行发送
注册数据发送尝试。创建状态为NEW（1）的Api\Data\TransactionInterface\TransactionAttemptInterface实体
以JSON格式发送数据

3.1.在成功传输的情况下（HTTP状态之一[200, 400, 401]）
- 创建交易 - Magento\Sales\Api\Data\TransactionInterface实体，记录请求的唯一标识符（UUID - Атол；RequestId - Чеконлайн）和所有传输数据。在管理后台这是Sales -> Transactions网格。
- 发送尝试实体TransactionAttemptInterface获得状态Sent（2）
- 为订单创建注释
- 交易获得收银机状态（kkm_status）
  - Атол - wait
  - Чеконлайн - done
    
    3.2.在失败传输的情况下（状态不同于[200, 400, 401]（也包括Чеконлайн的500），服务器无响应，发票或退货中数据不正确）
- 发送尝试实体TransactionAttemptInterface获得状态Error（3）
- 为订单创建包含错误描述的注释
- 订单获得"KKM失败"状态
- 如果抛出VendorBadServerAnswerException异常（服务器无响应等情况）并且启用了异步传输，则发送将被再次放入队列。
- 如果抛出异常 VendorNonFatalErrorException 并且启用了异步传输 - 则
  - Атол - 将执行生成新的 external_id 并将发送操作重新放入队列。
  - Чеконлайн - 事务实体获得状态 wait 并将发送操作重新放入队列而不会生成新的 external_id，因为非致命错误的响应不会被缓存。同样，在处理“云”服务时，可能会出现返回 HTTP 状态码 500 的错误和包含以下字段的错误结构：FCEError、ErrorDescription、Device 和 Fatal。值为 true 的 Fatal 字段表示重复执行请求会导致错误。如果 Fatal 字段值为 false，则发送操作也会被放入队列。
仅限阿特洛。模块会自动查询阿特洛的所有具有 wait 状态的交易。

4.1 当事务获得状态 done 时，将停止尝试更新状态。

4.2 最大尝试次数由模块配置设置。
在 传输失败 的情况下，将进行多次发送尝试，间隔时间逐渐增加（例如，1 分钟、5 分钟、15 分钟、30 分钟、1 小时）。

5.1 间隔设置可在模块的配置中找到。

5.2 最大尝试发送次数也受模块配置限制。

5.3 当达到最大尝试发送次数时，尝试计数器将被重置，并在一天后重新开始发送。

数据重新发送过程（Resell）

仅适用于已发送并具有状态 Done 的收据。

根据发票创建退货收据（refund）并将其发送到在线收银机。
根据该发票的先前发送 sell 创建新的付款事务记录。
当发送状态变为 Done（对于 Чеконлайн，在成功时立即变为 Done）时，将形成并发送新的收据接收（sell）。
为新的收据接收创建新的付款事务记录，该记录是先前收据退货（p.2）事务的子记录。
Resell 被视为完成，如果新的收据接收（p.3）获得状态 Done。状态更新方式与其他所有情况相同（对于 Чеконлайн，由于服务按同步方式运行，因此不会更新状态）。

报告

模块将发送数据的报告发送到邮箱（在配置中）。失败发送显示在此邮件中，并提供额外细节。此外，您还可以在控制台中查看此报告。

每周（上周），每日（当天），每日（昨天）
邮件布局。文件 view/adminhtml/templates/email/kkm_report-mjml.mjml 包含邮件布局。使用 https://mjml.io/ 服务进行编辑

支持新版本的阿特洛在线服务

模块支持 v3 和 v4 版本的服务。如果推出新版本，则需要执行以下步骤：

创建类 RequestForVersionX，它是抽象类 Request 的子类
发布其 JSON 表示形式 - 方法 jsonSerialize()
在 Mygento\Kkm\Model\Atol\RequestFactory 中添加创建请求对象的对象
在 Mygento\Kkm\Model\Source\ApiVersion 中添加关于新版本服务的说明

使用队列

向在线收银机发送消息可以以两种模式进行
- 同步（在实体保存后立即或手动发送）；
- 异步（通过 Magento 的原生消息队列机制）。
工作模式在配置中设置

手动发送数据

在实体页面上发送数据
使用指定实体 IncrementId 的控制台命令发送数据

消息记录

在启用 Stores -> Configuration -> Mygento Extensions -> Extensions and Support 中的 Debug 模式时，模块将记录所有请求（和响应）。
请求日志可在模块配置页面上查看

重写列表

无

事件和插件列表，动作描述及原因

事件

sales_order_invoice_save_commit_after:
- 在保存发票后发送发票数据。
sales_order_creditmemo_save_commit_after:
- 在保存退货后发送退货数据。

插件

在 Magento\Backend\Block\Widget\Button\Toolbar::pushButtons 方法上，before 插件 ExtraSalesViewToolbarButtons 向后台实体页面添加“发送至在线收银机”和“检查状态”按钮

可用的API实现列表

无

内置测试列表，以及它们如何进行测试

无

定时任务

kkm_statuses
- 仅适用于阿特洛。更新状态：作业更新状态为 wait 的交易状态。默认每分钟执行一次。
kkm_proceed_scheduled_attempt
- 根据指定的计划时间（scheduled_at）执行发送请求的重复尝试。
kkm_report
- 报告：发送报告作业。频率在模块设置页面配置。默认每天00:07。

控制台命令

mygento:kkm:report - 显示报告。参数：today、yesterday、week
mygento:kkm:refund - 发送退货。参数：实体的 IncrementId
mygento:kkm:sell - 发送账单。参数：实体的 IncrementId
mygento:kkm:resell - 启动 resell 流程。发送当前账单的退款。参数：实体的 IncrementId。如果指定了键 -f，则增加 external_id。
mygento:kkm:update-all - 仅适用于阿特洛。请求具有状态 wait 的所有发送数据的状态。参数：StoreID
mygento:kkm:update-one - 仅适用于阿特洛。请求指定发送的状态。参数：UUID

mygento / kkm

维护者

详细信息