README

该包提供了一个方便的接口，用于与 Модуль.Кассы API 通信，以发送销售数据到税务服务。该包简化了将网店与 Модуль.Кассы 税务服务集成的模块开发。

部分描述与原始文档重复 Модуль.Кассы API 文档

要求

• php ^7.1
• guzzlehttp/guzzle (或任何符合 \GuzzleHttp\ClientInterface 接口的客户端)
• ext-json
• curl

安装

您可以使用 composer 安装此包

composer require bigperson/modulpos-php-api-client

对于 PHP 5.4-7.0，您可以使用旧版本

composer require bigperson/modulpos-php-api-client 1.0

使用

税务流程的方案在 API 文档 中详细说明。简而言之，需要将销售点与网店连接起来，设置销售数据的发送，并检查销售数据的发送状态。

创建账户和零售点的关联

首先，您需要在 Модуль.Кассы 的个人账户中创建零售点，激活其 用于打印网店文档的功能，并获取其 uuid 标识符。然后调用关联操作

$login = 'test@test.ru'; // Логин от аккаунта Модуль.Кассы
$password = 'password'; // Пароль от аккаунта Модуль.Кассы
$retailPointUuid = 'uuid'; // Идентификатор розничной точки
$testMode = true; // Тестовый режим
$associate = new \Bigperson\ModulposApiClient\Associate($login, $password, $retailPointUuid, $testMode);
$result = $associate->init();

在 $result 中，我们将获得一个包含 userName 和 password 的数组，这些信息将用于后续的 API 调用。需要将这些信息保存在某个地方，例如数据库中。

将销售数据发送到税务服务器的服务器（创建文档）

首先，需要形成销售数据本身。为此，只需为您的模型实现 ModulposOrderInterface 接口（用于订单），ModulposOrderItemInterface 接口（用于订单中的商品），ModulposPaymentItemInterface 接口（用于支付方式）。您还可以使用包中的实体，或从它们继承并重写自己的方法。

use Bigperson\ModulposApiClient\Entity\Order;
use Bigperson\ModulposApiClient\Entity\Cashier;
use Bigperson\ModulposApiClient\Entity\OrderItem;
use Bigperson\ModulposApiClient\Entity\PaymentItem;

$dateTime =  new \DateTime('NOW');
// Создаем заказ
$order = Order::create([
    'documentUuid'     => uniqid(),
    'checkoutDateTime' => $dateTime->format(DATE_RFC3339),
    'orderId'          => rand(100000, 999999),
    'typeOperation'    => 'SALE',
    'customerContact'  => 'test@example.com',
]);

// Созадем товары
$orderItem1 = OrderItem::create([
    'price' => 100,
    'quantity' => 1,
    'vatTag' => OrderItem::VAT_NO,
    'name' => 'Test Product1'
]);

$orderItem2 = OrderItem::create([
    'price' => 200,
    'quantity' => 1,
    'vatTag' => OrderItem::VAT_NO,
    'name' => 'Test Product2'
]);

//Создаем способ оплаты
$paymentItem = PaymentItem::create([
    'type' => 'CARD',
    'sum' => 300
]);

// Добавляем товары и способ оплаты к заказу
$order->addItem($orderItem1);
$order->addItem($orderItem2);
$order->addPaymentItem($paymentItem);

//Создаем кассира
$cashier = Cashier::create([
    'name' => 'Test Cashier',
    'inn' => '123456789012',
    'position' => 'salesman',
]);

然后，将订单对象传递给客户端，也可以传递 responseURL 并在收银机上打印销售数据

$login = 'test@test.ru'; // Логин полученный на первом шаге
$password = 'password'; // Пароль полученный на первом шаге
$testMode = true; // Тестовый режим
$client = new \Bigperson\ModulposApiClient\Client($login, $password, $testMode);
$responseUrl =  'https://internet.shop.ru/order/982340931/checkout?completed=1';
$printReceipt = true; // Печатать ли чек на кассе
$result = $client->sendCheck($order, $responseUrl, $printReceipt, $cashier);

除了 $order 之外的所有参数都是可选的。如果没有传递 ModulposCashierInterface 对象，则将使用商店设置中的数据。

响应将返回一个包含文档处理状态和 fiscal storage 状态的数组。

检查文档状态

如果传递了 responseURL，则税务服务的结果将被发送到该 URL，如果没有设置参数，则可以自行检查文档的状态

$login = 'test@test.ru'; // Логин полученный на первом шаге
$password = 'password'; // Пароль полученный на первом шаге
$testMode = true; // Тестовый режим
$documentId = 'efbafcdd-113a-45db-8fb9-718b1fdc3524'; // id документа
$client = new \Bigperson\ModulposApiClient\Client($login, $password, $testMode);
$result = $client->getStatusDocumentById($documentId);

响应将返回一个包含 status 状态的数组，该状态可以取以下值

• QUEUED - 文档已接受处理队列；
• PENDING - 文档已由收银机接收以打印；
• PRINTED - 成功税务化；
• COMPLETED - 税务化结果已发送到源服务（如果已填写 responseURL 字段）；
• FAILED - 税务化过程中发生错误。

数组还将包含 fnState - 税务存储状态，可以取以下值

• ready - 与税务存储器的连接已建立，状态允许税务化销售数据；
• associated - 成功关联了零售点，但收银机尚未建立联系并报告其状态。
• 失败 - 获取税务存储器状态出现问题。此状态不会阻碍添加文档进行税务化。所有文档都将添加到服务器队列中，等待现金柜准备进行税务化。

此外，您可以单独调用税务存储器状态检查方法（税务化服务）。

$client = new \Bigperson\ModulposApiClient\Client($login, $password, $testMode);
$result = $client->getStatusFiscalService();

软件包开发

为了积极开发软件包，建议创建拉取请求，而不仅仅是错误报告（问题）。对于任何问题，建议打开详细的错误报告，包括问题描述和重现错误的操作步骤。

许可证

MIT