README

PHP语言的HTTP客户端，用于e-Kasa API解决方案，由Nine Digit, s.r.o.公司提供。

安装

库与PHP 7.4、8.1及以上版本兼容。

通过Packagist安装

库可在https://packagist.org.cn/packages/ninedigit/ekasa-clientphp找到。

使用以下命令安装最新版本

composer require ninedigit/ekasa-clientphp

使用以下命令安装特定版本

composer require ninedigit/ekasa-clientphp:0.0.1

通过GitHub仓库安装

编辑composer.json文件，并在repositories集合中添加新的仓库

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/ninedigit/ekasa-clientphp"
    }
  ]
}

安装包

使用以下命令安装最新版本

composer require ninedigit/ekasa-clientphp

使用以下命令安装特定版本

composer require ninedigit/ekasa-clientphp:0.0.1

有关安装私有仓库的更多信息，请参阅Composer文档。

使用

当前库仅覆盖注册文档的功能。如果您有兴趣进行扩展，请通过info@ninedigit.sk提出疑问。

库可以以两种模式使用

通过本地网络

服务在安装后默认在端口3010（https://:3010）上可用。

如下实例化客户端类

$clientOptions = new ApiClientOptions(EKasaServer::LOCALHOST);
$client = new ApiClient($clientOptions);

提示：如果您是集成器并且需要测试eKasa API实例，请按照本指南进行操作。

通过带Expose服务的互联网

如果使用此库的PHP应用程序安装在其他计算机上（服务器或云），则需要确保与本地安装的eKasa API的网络连接。

解决方案正是服务Expose，该服务将为您的本地安装的eKasa API分配使用安全HTTPS协议的URL地址。

无需任何路由器设置或从互联网服务提供商处获取静态IP地址。
连接是加密的
对eKasa API服务的访问受设置访问密钥的保护，该密钥可以随时更新。

要激活此服务并获取登录凭据，请联系我们info@ninedigit.sk。

如下实例化客户端类以使用Expose服务

$url = EKasaServer::exposeProduction("{vas_nazov_domeny}");
$accessTokenSource = AccessTokenSource::queryString("access_token");
$accessTokenOptions = new ApiClientAuthenticationAccessTokenOptions("{vas_bezpecnostny_kluc}", $accessTokenSource);
$authentication = new ApiClientAuthenticationOptions(null, $accessTokenOptions);
$clientOptions = new ApiClientOptions($url, $authentication);
$client = new ApiClient($clientOptions);

示例

示例在examples目录中。

创建收据示例

// Vytvorenie klienta
$clientOptions = new ApiClientOptions(EKasaServer::LOCALHOST);
$client = new ApiClient($clientOptions);

// Nastavenia tlače
$posPrinterOptions = new PosReceiptPrinterOptions();
$posPrinterOptions->openDrawer = true;
$print = new PosRegisterReceiptPrintContextDto($posPrinterOptions);

// Položka
$receiptItem = new ReceiptItemDto(
    ReceiptItemType::POSITIVE,  // Kladný typ položky
    "Coca Cola 0.25l",          // Názov
    1.29,                       // Jednotková cena
    20.00,                      // Daňová hladina
    new QuantityDto(2, "ks"),   // Množstvo
    2.58                        // Cena
);

// Požiadavka registrácie
$receipt = ReceiptBuilder::cashRegister("88812345678900001", $items)
    ->setHeaderText("Nine Digit, s.r.o.") // Voliteľná hlavička dokladu
    ->setFooterText("Ďakujeme za nákup!") // Voliteľná pätička dokladu
    ->addPayment(new ReceiptPaymentDto(2.60, ReceiptPaymentName::CASH))
    ->addPayment(new ReceiptPaymentDto(-0.02, "Výdavok"))
    ->build();

$request = new RegisterReceiptRequestDto($receipt);
$requestContext = new RegisterReceiptRequestContextDto($print, $request);

// Registrácia
$result = $client->registerReceipt($requestContext);

四舍五入

在将数学运算的结果放入变量中之前，建议对变量进行四舍五入。

单价四舍五入到小数点后6位。
价格四舍五入到小数点后2位。
数量四舍五入到小数点后4位。

开发

安装Composer

php -r "copy('https://getcomposer.org.cn/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

安装库依赖项

php composer.phar install

在创建新类（在单独的文件中）后，需要调用

php composer.phar dump-autoload

测试

要执行集成测试，需要在tests\integration中创建一个名为settings.json的文件，其格式为JSON，其结构应与ApiClientOptions类相同。

例如

{
  "url": "https://test.expose.ninedigit.sk",
  "proxyUrl": "192.168.1.218:9090",
  "authentication": {
    "credentials": {
      "userName": "admin",
      "password": "admin"
    },
    "accessToken": {
      "value": "31d6cfe0d16ae931b73c59d7",
      "source": {
        "name": "queryString",
        "keyName": "access_token"
      }
    }
  }
}

可以使用以下命令运行测试

./vendor/bin/phpunit --verbose tests

要运行特定测试，需要指定带有测试方法名称的--filter开关。

例如

./vendor/bin/phpunit --verbose tests --filter testRegisterCashRegisterReceiptUsingPosPrinter

检查PHP兼容性

./vendor/bin/phpcs --standard=PHPCompatibility --extensions=php --runtime-set testVersion 8.1- ./src

ninedigit / ekasa-clientphp

维护者

详细信息