kiralyta/ntak-php

An easy to use NTAK PHP Api

1.1.43 2024-05-05 00:04 UTC

Requires

• php: ^8.1
• gamegos/jws: ^1.0
• guzzlehttp/guzzle: ^7.0
• nesbot/carbon: ^2.66

Requires (Dev)

• illuminate/collections: ^10.1
• phpunit/phpunit: ^10.1
• ramsey/uuid: ^4.7
• symfony/var-dumper: ^6.2

MIT

• Tamás Király

README

Welcome to my little package, that helps you make NTAK RMS requests like a boss.

Table of Contents:

• Installation
• Usage
  • Create an API Client Instance
  • Create an Order Item Instance
  • Create a Payment Instance
  • Create an Order Instance
  • Store, Update, Destroy Order (Rendelésösszesítő)
  • Close Day (Napzárás)
  • Verify (Ellenőrzés)
• Enums
• Contribution
• Last Words

Installation

composer require kiralyta/ntak-php

The package requires PHP ^8.1 since it was built around PHP enums.

For PHP 7, see Natsu007/ntak-php fork.

Usage

Instances

Create an API Client Instance

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                         // whether to hit the test NTAK API
);

Your .pem file is basically a concatenated file of your .cer and .key files.

It is recommended to have a singleton NTAKClient instance during one request cycle. This means, you can create multiple requests with a single NTAKClient instance.

You can get the last request, response and respone time (in milliseconds) from the client.

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

Create an Order Item Instance

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

Create a Payment Instance

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

Create an Order Instance

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'
);

When you are updating / destroying an order, you need to provide (generate) a new orderId with each requests.

In these cases, the ntakOrderId is always the last provided orderId.

• NTAKOrderType
• NTAKOrderItem
• NTAKPayment

Messages (Requests)

Store, Update, Destroy Order (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(...));

Returns the NTAK process ID string.

• NTAKOrder

Close Day (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)
    );

Returns the NTAK process ID string.

• NTAKDayType

Verify (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'
    );

Returns an NTAKVerifyResponse instance

$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

If you encounter an unsuccessful message, you should further examine NTAKVerifyStatus. It's recommended to wait at least 60 seconds before the first verification attempt of a processs ID. You can verify multiple order with verifyALl(array of process ids) - which returning an array of NTAKVerifyResponse instance

Enums

Namespace of the enums:

namespace Kiralyta\Ntak\Enums;

You can use the values() static method on any of the enums, in order to get the available values.

NTAKAmount

NTAKCategory

NTAKSubcategory

NTAKDayType

NTAKOrderType

NTAKPaymentType

NTAKVat

NTAKVerifyStatus

Contribution

git clone [e-mail]:kiralyta/ntak-php.git
cd ntak-php
composer install --dev

Run Tests

Put your cer.cer and pem.pem files in ./auth directory, then run:

vendor/bin/phpunit src/Tests

Last Words

I am not taking any responsiblities for the use of this package.

This is simply a personal project that could help other fellow software artisans to make requests to MTÜ.

It's still recommended to read the documentation of the RMS Interface, even in case of using this package.

Please feel free to open an issue if you encounter one.