README

欢迎来到我的小包，它可以帮助您像老板一样轻松地发出 NTAK RMS 请求。

目录

• 安装
• 使用
  • 创建 API 客户端实例
  • 创建订单项实例
  • 创建支付实例
  • 创建订单实例
  • 存储、更新、销毁订单（Rendelésösszesítő）
  • 日终（Napzárás）
  • 验证（Ellenőrzés）
• 枚举
• 贡献
• 结语

安装

composer require nedal-network/ntak-php

此包需要 PHP ^8.1，因为它围绕 PHP 枚举构建。

对于 PHP 7，请参阅 Natsu007/ntak-php 分支。

使用

实例

创建 API 客户端实例

use Kiralyta\Ntak\NTAKClient;

$client = new NTAKClient(
    taxNumber:         'NTAK client tax nr',         // without `-` chars
    regNumber:         'NTAK client registration nr',
    softwareRegNumber: 'NTAK RMS registration id',
    version:           'NTAK RMS version',
    certPath:          '/path/to/your.pem',
    testing:           false
);

您的 .pem 文件基本上是您的 .cer 和 .key 文件的连接文件。

建议在单个请求周期内使用一个单例 NTAKClient 实例。这意味着，您可以使用单个 NTAKClient 实例创建多个请求。

您可以从客户端获取最后请求、响应和响应时间（以毫秒为单位）。

$client->lastRequest();     // Returns an array
$client->lastResponse();    // Returns an array
$client->lastRequestTime(); // Returns an integer

创建订单项实例

use Carbon\Carbon;
use Kiralyta\Ntak\Enums\NTAKAmount;
use Kiralyta\Ntak\Enums\NTAKCategory;
use Kiralyta\Ntak\Enums\NTAKSubcategory;
use Kiralyta\Ntak\Enums\NTAKVat;
use Kiralyta\Ntak\Models\NTAKOrderItem;

$orderItem = new NTAKOrderItem(
    name:            'Absolut Vodka',             // Any kind of string
    category:        NTAKCategory::ALKOHOLOSITAL, // Main category
    subcategory:     NTAKSubcategory::PARLAT,     // Subcategory
    vat:             NTAKVat::C_27,
    price:           1000,
    amountType:      NTAKAmount::LITER,
    amount:          0.04,
    quantity:        2,
    when:            Carbon::now()
);

• NTAKCategory
• NTAKSubcategory
• NTAKVat
• NTAKAmount

创建支付实例

use Kiralyta\Ntak\Enums\NTAKPaymentType;
use Kiralyta\Ntak\Models\NTAKPayment;

$payment = new NTAKPayment(
    paymentType:     NTAKPaymentType::BANKKARTYA,
    total:           2000 // Total payed with this method type
);

• NTAKPaymentType

创建订单实例

use Carbon\Carbon;
use Kiralyta\Ntak\Enums\NTAKOrderType;
use Kiralyta\Ntak\Models\NTAKOrderItem;
use Kiralyta\Ntak\Models\NTAKOrder;
use Kiralyta\Ntak\Models\NTAKPayment;

$order = new NTAKOrder(
    orderType:   NTAKOrderType::NORMAL,         // You can control whether to store, update, or destroy an order
    orderId:     'your-rms-order-id',           // RMS Order ID
    orderItems:  [new NTAKOrderItem(...)],      // Array of the order items
    start:       Carbon::now()->addMinutes(-7), // Start of the order
    end:         Carbon::now(),                 // End of the order
    payments:    [new NTAKPayment(...)],        // Array of the payments

    // Take away handled automatically
    // Vat changed to 27 in all OrderItems that have a category "Helyben készített alkoholmentes ital" in case of isAtTheSpot is false
    isAtTheSpot: true,

    // Discount and service fee are automatically managed by the package
    // You don't have to manually add the OrderItem(s) with "KEDVEZMENY" / "SZERVIZDIJ" subcategories
    // Vats are handled automatically as well
    // If both discount and service fee are provided, the service fee will be calculated from the discounted total
    // The following means 20% discount (defaults to 0) and 10% service fee (defaults to 0)
    discount:    20,
    serviceFee:  10,

    // Only on update / destroy
    ntakOrderId: 'your-previous-order-id'
);

当您更新/销毁订单时，您需要在每个请求中提供（生成）一个新的 orderId。

在这些情况下，ntakOrderId 总是最后提供的 orderId。

• NTAKOrderType
• NTAKOrderItem
• NTAKPayment

消息（请求）

存储、更新、销毁订单（Rendelésösszesítő）

use Carbon\Carbon;
use Kiralyta\Ntak\Models\NTAKOrder;
use Kiralyta\Ntak\Models\NTAKPayment;
use Kiralyta\Ntak\NTAK;

$processId = NTAK::message($client, Carbon::now())
    ->handleOrder(new NTAKOrder(...));

返回 NTAK 进程 ID 字符串。

• NTAKOrder

日终（Napzárás）

use Carbon\Carbon;
use Kiralyta\Ntak\Enums\NTAKDayType;
use Kiralyta\Ntak\NTAK;

$processId = NTAK::message($client, Carbon::now())
    ->closeDay(
        start:   Carbon::now()->addHours(-10), // Opening time (nullable)
        end:     Carbon::now(),                // Closing time (nullable)
        dayType: NTAKDayType::NORMAL_NAP,      // Day type
        tips:    1000                          // Tips (default 0)
    );

返回 NTAK 进程 ID 字符串。

• NTAKDayType

验证（Ellenőrzés）

use Carbon\Carbon;
use Kiralyta\Ntak\Enums\NTAKDayType;
use Kiralyta\Ntak\NTAK;

$response = NTAK::message($client, Carbon::now())
    ->verify(
        processId: 'NTAK Process ID'
    );

返回 NTAKVerifyResponse 实例

$response->successful();         // Check whether our message was processed successfully
$response->unsuccessful();       // Check whether our message was processed unsuccessfully
$response->status;               // Returns an NTAKVerifyStatus
$response->successfulMessages;   // Returns an array of the successful messages
$response->unsuccessfulMessages; // Returns an array of the unsuccessful messages
$response->headerErrors;         // Returns an array of the header errors

如果您遇到不成功的消息，应进一步检查 NTAKVerifyStatus。建议在第一次尝试验证进程 ID 之前至少等待 60 秒。

枚举

枚举的命名空间

namespace Kiralyta\Ntak\Enums;

您可以使用任何枚举的 values() 静态方法，以获取可用的值。

NTAKAmount

NTAKCategory

NTAKSubcategory

NTAKDayType

NTAKOrderType

NTAKPaymentType

NTAKVat

NTAKVerifyStatus

贡献

git clone git@github.com:kiralyta/ntak-php.git
cd ntak-php
composer install --dev

运行测试

将您的 cer.cer 和 pem.pem 文件放入 ./auth 目录，然后运行

vendor/bin/phpunit src/Tests

结语

我不承担此包使用过程中的任何责任。

这只是一个个人项目，可以帮助其他软件工匠向 MTÜ 发送请求。

即使在使用此包的情况下，也建议您阅读 RMS 接口的文档。

如果您遇到问题，请随时提出。