nedal-network / ntak-php
An easy to use NTAK PHP Api
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
README
Welcome to my little package, that helps you make NTAK RMS requests like a boss.
Table of Contents:
Installation
composer require nedal-network/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 );
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 singleNTAKClient
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() );
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 );
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 providedorderId
.
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.
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.
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.
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 git@github.com: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.