NTAK RMS PHP API / SDK

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

name	value string
DARAB	darab
LITER	liter
KILOGRAMM	kilogramm
EGYSEG	egyseg

NTAKCategory

name	value string
ETEL	Étel
ALKMENTESITAL_HELYBEN	Helyben készített alkoholmentes ital
ALKMENTESITAL_NEM_HELYBEN	Nem helyben készített alkoholmentes ital
ALKOHOLOSITAL	Alkoholos Ital
EGYEB	Egyéb

NTAKSubcategory

name	value string
REGGELI	reggeli
SZENDVICS	szendvics
ELOETEL	előétel
LEVES	leves
FOETEL	főétel
KORET	köret
SAVANYUSAG_SALATA	savanyúság/saláta
KOSTOLO	kóstolóétel, kóstolófalat
PEKSUTEMENY	péksütemény, pékáru
DESSZERT	desszert
SNACK	snack
FOETEL_KORETTEL	főétel körettel
ETELCSOMAG	ételcsomag
EGYEB	egyéb
VIZ	víz
LIMONADE_SZORP_FACSART	limonádé / szörp / frissen facsart ital
ALKOHOLMENTES_KOKTEL	alkoholmentes koktél, alkoholmentes kevert ital
TEA_FORROCSOKOLADE	tea, forrócsoki és egyéb tejalapú italok
ITALCSOMAG	italcsomag
KAVE	kávé
ROSTOS_UDITO	rostos üdítő
SZENSAVAS_UDITO	szénsavas üdítő
SZENSAVMENTES_UDITO	szénsavmentes üdítő
KOKTEL	koktél, kevert ital
LIKOR	likőr
PARLAT	párlat
SOR	sör
BOR	bor
PEZSGO	pezsgő
SZERVIZDIJ	szervizdíj
BORRAVALO	borravaló
KISZALLITASI_DIJ	kiszállítási díj
NEM_VENDEGLATAS	nem vendéglátás
KORNYEZETBARAT_CSOMAGOLAS	környezetbarát csomagolás
MUANYAG_CSOMAGOLAS	műanyag csomagolás
KEDVEZMENY	kedvezmény

NTAKDayType

name	value string
ADOTT_NAPON_ZARVA	Adott napon zárva
FORGALOM_NELKULI_NAP	Forgalom nélküli nap
NORMAL_NAP	Normál nap

NTAKOrderType

name	value string
NORMAL	Normál
SZTORNO	Storno
HELYESBITO	Helyesbítő

NTAKPaymentType

name	value string
KESZPENZHUF	Készpénz huf
KESZPENZEUR	Készpénz eur
SZEPKARTYA	Szépkártya
BANKKARTYA	Bankkártya
ATUTALAS	Átutalás
EGYEB	Egyéb
VOUCHER	Voucher
SZOBAHITEL	Szobahitel
KEREKITES	Kerekítés

NTAKVat

name	value string
A_5	5%
B_18	18%
C_27	27%
D_AJT	Ajt
E_0	0%

NTAKVerifyStatus

name	value string
BEFOGADVA	BEFOGADVA
TELJESEN_HIBAS	TELJESEN_HIBAS
RESZBEN_SIKERES	RESZBEN_SIKERES
TELJESEN_SIKERES	TELJESEN_SIKERES
UJRA_KULDENDO	UJRA_KULDENDO

Contribution

git clone [email protected]: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.