produman-org/kassa-php

Produman.Kassa API 的 PHP 库

维护者

详细信息

github.com/produman-org/kassa-php

源代码

安装: 394

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 3

分支: 0

1.0.2 2024-08-13 09:13 UTC

Requires

Requires (Dev)

MIT b9846afe7e67587785da02fc820f8f0e6ce7b09c

  • Produman <kassa.woop@produman.org>

apikassaproduman

This package is auto-updated.

Last update: 2024-09-13 10:09:19 UTC

README

根据API开发的用于 Produman 在线收银机的客户端

内容

要求

PHP 7.4.0 (及以上) 且具有 json 和 curl 扩展

安装

使用 Composer 在控制台

  1. 安装 Composer 包管理器。
  2. 在控制台运行以下命令
composer require produman-org/kassa-php

在您的项目 composer.json 文件中

  1. 将 "produman-org/kassa-php": "^1.0" 添加到 composer.json 文件中项目的依赖项列表
...
    "require": {
        "php": ">=7.4.0",
        "produman-org/kassa-php": "^1.0"
...
  1. 更新项目依赖。在包含 composer.json 的目录中，运行以下命令
composer update
  1. 在您的项目代码中引入我们的客户端自动加载文件
require __DIR__ . '/vendor/autoload.php';

客户端使用流程

  1. 对于主要 API 请求（如指南、操作或订单），使用 buildClient 命令创建客户端实例，设置客户端令牌、应用程序标识符和秘密密钥（可在 Produman 的个人账户中获取）。
use ProdumanApi\Builder;

$client = Builder::buildClient(
    'someClientToken',
    'someAppId',
    'someAppSecret'
);

  1. 对于服务 API 请求（如Webhooks和集成），使用 buildApplicationClient 命令创建客户端实例（与上面的示例类似，但不需要指定 clientToken）。

  2. 此外，在创建客户端时，可以调整 curl 请求的 timeout 参数，在 logger 参数中使用 Psr\Log\LoggerInterface 日志记录器，以及在 language 参数中指定传递 Accept-Language 头部。

  3. 在 $client 对象中调用所需的 API 方法。

  4. 对于每个 API 请求，客户端都包含相应的 方法。如果需要，方法可以接受 ProdumanApi\Request\... 类的请求对象作为参数。方法返回 ProdumanApi\Response\... 类的响应对象。

  5. 此外，还支持 ProdumanApi\Exception\... 异常。例如，使用 ProdumanApi\Exception\ApiException 异常来显示 处理 API 错误 部分中描述的数据。

  6. Produman API 对请求的数量和频率有限制 RateLimit。在客户端对象中存在相应的获取当前限制的方法。

主要 API 方法的使用示例

1. 客户端初始化

use ProdumanApi\Builder;
use ProdumanApi\Client\Client;
use Example\Logger;

/** @var Client $client */
$client = Builder::buildClient(
    'someClientToken',
    'someAppId',
    'someAppSecret',
    30,
    new Logger(),
    'ru'
);

2. 收银机指南

use ProdumanApi\Request\Cashboxes\ListRequest;
use ProdumanApi\Response\Cashboxes\ListDto;
use ProdumanApi\Response\Cashboxes\CashboxDto;

// касса по id
/** @var CashboxDto $response */
$response = $client->cashboxes->get('1ee57a8d-f1b4-6764-9ec7-a537555944ab');

// список касс без фильтра
/** @var ListDto $response */
$response = $client->cashboxes->list();

// список касс по фильтру
$request = new ListRequest();
$request->limit = 2;
$request->status = 'ACTIVE';
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->cashboxes->list($request);

3. 收入和支出分类指南

use ProdumanApi\Request\CashMovementCategories\ListRequest;
use ProdumanApi\Response\CashMovementCategories\ListDto;

// список категорий внесений и выплат без фильтра
/** @var ListDto $response */
$response = $client->cashMovementCategories->list();

// список категорий внесений и выплат по фильтру
$request = new ListRequest();
$request->limit = 2;
$request->type = 'IN';
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->cashMovementCategories->list($request);

4. 合作伙伴指南

use ProdumanApi\Request\Counterparties\ListRequest;
use ProdumanApi\Response\Counterparties\ListDto;

// список контрагентов без фильтра
/** @var ListDto $response */
$response = $client->counterparties->list();

// список контрагентов по фильтру 
$request = new ListRequest();
$request->limit = 2;
$request->search = '123456789';
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->counterparties->list($request);

5. 员工指南

use ProdumanApi\Request\Employees\ListRequest;
use ProdumanApi\Response\Employees\ListDto;

// список сотрудников без фильтра
/** @var ListDto $response */
$response = $client->employees->list();

// список сотрудников по фильтру
$request = new ListRequest();
$request->limit = 2;
$request->status = 'ACTIVE';
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->employees->list($request);

6. 操作处理

use ProdumanApi\Request\Operations\CashEditRequest;
use ProdumanApi\Request\Operations\CreateCashIn;
use ProdumanApi\Request\Operations\CreateKktInfo;
use ProdumanApi\Request\Operations\ListRequest;
use ProdumanApi\Request\Operations\CreateSell;
use ProdumanApi\Request\Operations\CreateShiftOpen;
use ProdumanApi\Request\Operations\CreateShiftClose;
use ProdumanApi\Request\Operations\CreateXReport;
use ProdumanApi\Request\Operations\DetailsShiftCloseModel;
use ProdumanApi\Request\Operations\Model\ClientModel;
use ProdumanApi\Request\Operations\Model\DetailsCashModel;
use ProdumanApi\Request\Operations\Model\DetailsSellModel;
use ProdumanApi\Request\Operations\Model\DetailsShiftCloseModel;
use ProdumanApi\Request\Orders\Model\AgentSchemeModel;
use ProdumanApi\Request\Orders\Model\PositionModel;
use ProdumanApi\Request\Orders\Model\SupplierModel;
use ProdumanApi\Response\Operations\ListDto;
use ProdumanApi\Response\Operations\OperationDto;

// операция по id
/** @var OperationDto $response */
$response = $client->operations->get('1ee57a8d-f1b4-6764-9ec7-a537555944ab');

// список операций без фильтра
/** @var ListDto $response */
$response = $client->operations->list();

// список операций по фильтру
$request = new ListRequest();
$request->limit = 2;
$request->status = 'COMPLETE';
$request->operationType = 'SELL';
$request->createdAtFrom = new \DateTime('- 1 year');
$request->createdAtTo = new \DateTime('now');
$request->operationIds = [
    '1ee57a8d-f1b4-6764-9ec7-a537555944ab',
];
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->operations->list($request);

// повтор операции по id
/** @var OperationDto $response */
$response = $client->operations->retry('1ee57a8d-f1b4-6764-9ec7-a537555944ab');

// редактирование операции с наличными
$request = new CashEditRequest();
$request->cashMovementCategoryId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->comment = 'Тестовый комментарий';
 /** @var OperationDto $response */
$response = $client->operations->cashMovementEdit('1ee57a8d-f1b4-6764-9ec7-a537555944ab', $request);

//создание операции X-отчет
$request = new CreateXReport();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var OperationDto $response */
$response = $client->operations->create($request);

// создание операции открытия смены
$request = new CreateShiftOpen();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var OperationDto $response */
$response = $client->operations->create($request);

// создание операции закрытия смены
$details = new DetailsShiftCloseModel();
$details->onlyCashbox = true;
$request = new CreateShiftClose();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->details = $details;
/** @var OperationDto $response */
$response = $client->operations->create($request);
    
// создание операции информации о ККТ
$request = new CreateKktInfo();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var OperationDto $response */
$response = $client->operations->create($request);
    
// создание операции внесения наличных
$details = new DetailsCashModel();
$details->cashMovementCategoryId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$details->comment = 'Тестовый комментарий';
$details->amount = 10.00;
$request = new CreateCashIn();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->details = $details;
/** @var OperationDto $response */
$response = $client->operations->create($request);

// создание операции прихода без заказа с действием формирования чека (actionType="PREPARE")
$operationClient = new ClientModel();
$operationClient->name = 'Тестовый клиент';
$operationClient->inn = '485466710568';
$supplier = new SupplierModel();
$supplier->name = 'Тестовый поставщик';
$supplier->inn = '485466710568';
$supplier->phone = '+79999999999';
$agentScheme = new AgentSchemeModel();
$agentScheme->agentSign = 'ANOTHER_AGENT';
$agentScheme->supplier = $supplier;
$position = new PositionModel();
$position->name = 'Тестовая позиция';
$position->quantity = 2;
$position->price = 10.00;
$position->paymentVat = 'WITHOUT';
$position->paymentObject = 'PRODUCT';
$position->paymentMethod = 'FULL_PAYMENT';
$position->excisable = false;
$position->agentScheme = $agentScheme;
$position->marks = [
  '010641944077751221s40h&mLFSVODA93TEST',
];
$details = new DetailsSellModel();
$details->actionType = 'PREPARE';
$details->taxationSystem = 'OSN';
$details->client = $operationClient;
$details->positions = [$position];
$request = new CreateSell();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->details = $details;
/** @var OperationDto $response */
$response = $client->operations->create($request);

// создание операции прихода без заказа с действием регистрации чека (actionType="EXECUTE")
$paymentSolution = new PaymentSolutionModel();
$paymentSolution->id = 1;
$paymentSolution->amount = 20.0;
$operationClient = new ClientModel();
$operationClient->name = 'Тестовый клиент';
$operationClient->inn = '485466710568';
$supplier = new SupplierModel();
$supplier->name = 'Тестовый поставщик';
$supplier->inn = '485466710568';
$supplier->phone = '+79999999999';
$agentScheme = new AgentSchemeModel();
$agentScheme->agentSign = 'ANOTHER_AGENT';
$agentScheme->supplier = $supplier;
$position = new PositionModel();
$position->name = 'Тестовая позиция';
$position->quantity = 2;
$position->price = 10.00;
$position->paymentVat = 'WITHOUT';
$position->paymentObject = 'PRODUCT';
$position->paymentMethod = 'FULL_PAYMENT';
$position->excisable = false;
$position->agentScheme = $agentScheme;
$position->marks = [
  '010641944077751221s40h&mLFSVODA93TEST',
];
$details = new DetailsSellModel();
$details->actionType = 'EXECUTE';
$details->taxationSystem = 'OSN';
$details->client = $operationClient;
$details->receiptContact = 'test@test.ru';
$details->print = true;
$details->settlementPlace = 'Россия, Москва';
$details->paymentSolutions = [$paymentSolution];
$details->positions = [$position];
$request = new CreateSell();
$request->cashboxId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->details = $details;
/** @var OperationDto $response */
$response = $client->operations->create($request);

// остальные типы операций создаются аналогично

7. 订单处理

use ProdumanApi\Request\Orders\CreateRequest;
use ProdumanApi\Request\Orders\ListRequest;
use ProdumanApi\Request\Orders\Model\AgentSchemeModel;
use ProdumanApi\Request\Orders\Model\ClientModel;
use ProdumanApi\Request\Orders\Model\DeliveryModel;
use ProdumanApi\Request\Orders\Model\PaymentAgentModel;
use ProdumanApi\Request\Orders\Model\PositionModel;
use ProdumanApi\Request\Orders\Model\ReceivePaymentsOperatorModel;
use ProdumanApi\Request\Orders\Model\SupplierModel;
use ProdumanApi\Request\Orders\Model\TransferOperatorModel;
use ProdumanApi\Response\Orders\ListDto;
use ProdumanApi\Response\Orders\OrderDto;

// заказ по id
/** @var OrderDto $response */
$response = $client->orders->get('1ee57a8d-f1b4-6764-9ec7-a537555944ab');

// список заказов без фильтра
/** @var ListDto $response */
$response = $client->orders->list();

// список заказов по фильтру
$request = new ListRequest();
$request->limit = 2;
$request->totalAmountFrom = 100;
$request->totalAmountTo = 100000;
$request->createdAtFrom = new \DateTime('- 1 year');
$request->createdAtTo = new \DateTime('now');
$request->cursor = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
/** @var ListDto $response */
$response = $client->orders->list($request);

// создание заказа
$orderClient = new ClientModel();
$orderClient->name = 'Тестовый клиент';
$orderClient->inn = '485466710568';
$orderClient->email = 'test@test.ru';
$orderClient->phone = '+79999999999';
$delivery = new DeliveryModel();
$delivery->courierId = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$delivery->address = 'Россия, Москва';
$delivery->dateFrom = new \DateTime('- 1 min');
$delivery->dateTo = new \DateTime('+ 1 min');
$delivery->status = 'MOVED';
$delivery->comment = 'Тестовый комментарий';
$delivery->prepaid = false;
$paymentAgent = new PaymentAgentModel();
$paymentAgent->phone = '+79999999999';
$paymentAgent->operation = 'Пополнение счета';
$transferOperator = new TransferOperatorModel();
$transferOperator->name = 'ПАО КИВИ БАНК';
$transferOperator->inn = '485466710568';
$transferOperator->phone = '+79999999999';
$transferOperator->address = 'Россия, Москва';
$supplier = new SupplierModel();
$supplier->name = 'Тестовый поставщик';
$supplier->inn = '485466710568';
$supplier->phone = '+79999999999';
$agentScheme = new AgentSchemeModel();
$agentScheme->agentSign = 'BANK_PAYING_AGENT';
$agentScheme->paymentAgent = $paymentAgent;
$agentScheme->transferOperator = $transferOperator;
$agentScheme->supplier = $supplier;
$position = new PositionModel();
$position->name = 'Тестовая позиция';
$position->quantity = 2;
$position->price = 10.00;
$position->paymentVat = 'WITHOUT';
$position->paymentObject = 'PRODUCT';
$position->paymentMethod = 'FULL_PAYMENT';
$position->excisable = false;
$position->agentScheme = $agentScheme;
$position->marks = [
  '010641944077751221s40h&mLFSVODA93TEST',
];
$request = new CreateRequest();
$request->createdById = '1ee57a8d-f1b4-6764-9ec7-a537555944ab';
$request->externalId = '1234567890';
$request->taxationSystem = 'OSN';
$request->client = $orderClient;
$request->delivery = $delivery;
$request->positions[] = $position;
/** @var OrderDto $response */
$response = $client->orders->create($request);

// обновление заказа по id (запрос с таким же объектом $request, что и при создании)
/** @var OrderDto $response */
$response = $client->orders->update('1ee57a8d-f1b4-6764-9ec7-a537555944ab', $request);

// удаление заказа по id
$client->orders->delete('1ee57a8d-f1b4-6764-9ec7-a537555944ab');

服务 API 方法的使用示例

1. 服务请求客户端初始化

use ProdumanApi\Builder;
use ProdumanApi\Client\ApplicationClient;
use Example\Logger;

/** @var ApplicationClient $client */
$client = Builder::buildApplicationClient(
    'someAppId',
    'someAppSecret',
    30,
    new Logger(),
    'ru'
);

2. Webhooks

use ProdumanApi\Request\Webhooks\EndpointCreateRequest;
use ProdumanApi\Request\Webhooks\EndpointListRequest;
use ProdumanApi\Request\Webhooks\EndpointTestRequest;
use ProdumanApi\Response\Webhooks\EndpointDto;
use ProdumanApi\Response\Webhooks\EndpointListDto;

// эндпоинт по id
/** @var EndpointDto $response */
$response = $client->webhooks->endpointGet('1ee30707-89ed-696a-8501-a1e907a309b2');

// список эндпоинтов без фильтра
/** @var EndpointListDto $response */
$response = $client->webhooks->endpointList();

// список эндпоинтов по фильтру
$request = new EndpointListRequest();
$request->limit = 2;
$request->status = 'ACTIVE';
/** @var EndpointListDto $response */
$response = $client->webhooks->endpointList($request);

// создание эндпоинта
$request = new EndpointCreateRequest();
$request->status = 'INACTIVE';
$request->url = 'https://rra.ru';
$request->authType = 'BEARER_TOKEN';
$request->secret = '1234567890';
$request->events = ['OPERATION_FAILED'];
/** @var EndpointDto $response */
$response = $client->webhooks->endpointCreate($request);

// обновление эндпоинта по id (запрос с таким же объектом $request, что и при создании)
/** @var EndpointDto $response */
$response = $client->webhooks->endpointUpdate('1eeed9f2-a669-6fde-ad9f-1982a8a5337a', $request);

// удаление эндпоинта
$client->webhooks->endpointDelete('1ee921aa-9827-69d6-b16d-9f7549035bae');

// тестовая отправка вебхука с заданным событием
$request = new EndpointTestRequest();
$request->event = 'INTEGRATION_REQUEST_COMPLETED';
$request->skipVerify = true;
$client->webhooks->endpointTest($request);

3. 集成

use ProdumanApi\Request\Integrations\CreateConnectRequest;
use ProdumanApi\Response\Integrations\IntegrationConnectDto;
use ProdumanApi\Response\Integrations\IntegrationDto;

// интеграция по id
/** @var IntegrationDto $response */
$response = $client->integrations->get('1ee879f7-0eff-6092-9dc9-5d26875ad7b4');

// деактивация интеграции по id
$client->integrations->deactivate('1ee879f7-0eff-6092-9dc9-5d26875ad7b4');

// запрос на создание новой интеграции
$request = new CreateConnectRequest();
$request->email = 'test@test.ru';
 /** @var IntegrationConnectDto $response */
$response = $client->integrations->create($request);

异常处理示例

use ProdumanApi\Builder;
use ProdumanApi\Response\Cashboxes\CashboxDto;
use ProdumanApi\Exception\ApiException;
use ProdumanApi\Exception\HttpException;
use ProdumanApi\Exception\JsonResponseException;

$client = Builder::buildClient(
    'someClientToken',
    'someAppId',
    'someAppSecret'
);

try {
  // касса по id
  /** @var CashboxDto $response */
  $response = $client->cashboxes->get('1ee879f7-0eff-6092-9dc9-5d26875ad7b4');
} catch (ApiException $e) {
    var_dump('API error: ' . $e->getApiMessage()
        . '|' . $e->getApiCode() . '|' . print_r($e->getApiDetails(), true) . '|' . $e->getStatusCode());
} catch (HttpException $e) {
    var_dump('HTTP error: ' . $e->getMessage());
} catch (JsonResponseException $e) {
    var_dump('JSON response error: ' . $e->getMessage());
} catch (\Exception $e) {
    var_dump('Other error: ' . get_class($e) . ': ' . $e->getMessage());
}

RateLimit 使用示例

use ProdumanApi\Builder;

$client = Builder::buildClient(
    'someClientToken',
    'someAppId',
    'someAppSecret'
);
  
// квота  
var_dump($client->getLastXRateLimitRemaining());

// текущий остаток квоты
var_dump($client->getLastXRateLimitLimit());

// HTTP-код ответа последнего запроса
var_dump($client->getLastStatusCode());

返回顶部