tmrw-life/ntak-guru-php-sdk

PHP SDK for NTAK.guru API

Maintainers

Details

github.com/TMRW-Life/ntak.guru-php-sdk

Homepage

Source

Issues

Fund package maintenance!
TMRW-Life

Installs: 53

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 2

Forks: 0

Open Issues: 0

v1.0.1 2024-04-15 14:01 UTC

Requires

Requires (Dev)

MIT 0520b4e9801c0e5c5c456798025b863acc93fb45

  • Levente Otta <levente.otta.woop@tmrw.life>

phpsdkTMRW-Lifetmrwntak

This package is auto-updated.

Last update: 2024-04-29 01:08:36 UTC

README

Latest Version on Packagist Tests Total Downloads

NTAK.GURU is wrapper for NTAK to provide a much simpler interface.

Documentation

You can find the documentation here.

Soon the documentation of this package will be migrated to the website.

Installation

You can install the package via composer:

composer require tmrw-life/ntak-guru-php-sdk

Usage

Accommodation

$gateway = \TmrwLife\NtakGuru\Services\Accommodation::setup([
    'accessToken' => '<your-access-token>',
    'isProduction' => false, // default: false
]);

$accommodationId = '00000000-0000-0000-0000-0000000'; // Provided by NTAK.guru

// Retrieve accommodation
$response = $gateway->show($accommodationId);

// Update accommodation
$provider = (new \TmrwLife\NtakGuru\Entities\AccommodationProvider())
    ->setProviderName('Awesome provider Ltd')
    ->setProviderTaxNumber('12345678-1-41');
$response = $gateway->updateProvider($accommodationId, $provider);

$urls = (new \TmrwLife\NtakGuru\Entities\AccommodationUrl())
    ->setDailyCloseUrl('https://api.your-pms.com/v1/ntakguru/daily-close')
    ->setCallbackUrl('https://api.your-pms.com/v1/ntakguru/callback');
$response = $gateway->updateProvider($accommodationId, $urls);

// Activate accommodation
$response = $gateway->activate($accommodationId);

// Deactivate accommodation
$response = $gateway->deactivate($accommodationId);

Certificates

use TmrwLife\NtakGuru\Services\Certificate;

$accommodationId = '00000000-0000-0000-0000-0000000'; // Provided by NTAK.guru

$gateway = Certificate::setup([
    'accessToken' => '<your-access-token>',
    'isProduction' => false, // default: false
]);

// Generate certificate (private key)
$gateway->generate($accommodationId);

// Download certificate (certificate request)
$gateway->download($accommodationId);

// Upload certificate (certificate)
$gateway->upload($accommodationId, '<content-of-certificate', '<reporting_id-provided-by-government-NTAK>');

// Delete certificate (private key and certificate request)
$gateway->destroy($accommodationId);

Sending report

use TmrwLife\NtakGuru\Entities\Ntak\CheckIn;
use TmrwLife\NtakGuru\Entities\Ntak\CheckOut;
use TmrwLife\NtakGuru\Entities\Ntak\Reservation;
use TmrwLife\NtakGuru\Entities\Ntak\RoomChange;
use TmrwLife\NtakGuru\Services\Reporting\Ntak;

$accommodationId = '00000000-0000-0000-0000-0000000'; // Provided by NTAK.guru

$reporting = Ntak::setup([
    'accessToken' => '<your-access-token>',
    'isProduction' => false, // default: false
]);

// Check-in report
$checkIn = (new CheckIn())->setAttribute('...');
$response = $reporting->checkIn($accommodationId, $checkIn);

// Check-out report
$checkOut = (new CheckOut())->setAttribute('...');
$response = $reporting->checkOut($accommodationId, $checkOut);

// Reservation report
$reservation = (new Reservation())->setAttribute('...');
$response = $reporting->reservation($accommodationId, $reservation);

// Room change report
$roomChange = (new RoomChange())->setAttribute('...');
$response = $reporting->roomChange($accommodationId, $roomChange);

Entity builders

You can use the entity builders to create the entities.

We covered the 5 main report type with the entity builders.

Name Builder
Check-in \TmrwLife\NtakGuru\Entities\Ntak\CheckIn
Check-out \TmrwLife\NtakGuru\Entities\Ntak\CheckOut
Reservation \TmrwLife\NtakGuru\Entities\Ntak\Reservation
Room change \TmrwLife\NtakGuru\Entities\Ntak\RoomChange
Daily close \TmrwLife\NtakGuru\Entities\Ntak\DailyClose

And a few more for properties.

Name Builder
Guest \TmrwLife\NtakGuru\Entities\Ntak\Guest
Residential unit \TmrwLife\NtakGuru\Entities\Ntak\ResidentialUnit
Checkout Day Sale \TmrwLife\NtakGuru\Entities\Ntak\CheckOutDaySale
Expense \TmrwLife\NtakGuru\Entities\Ntak\Expense
Load \TmrwLife\NtakGuru\Entities\Ntak\Load
Residential unit night \TmrwLife\NtakGuru\Entities\Ntak\ResidentialUnitNight

We also have some enums to help you with the attributes.

Name Enum
Charge item category \TmrwLife\NtakGuru\Enums\ChargeItemCategory
DocumentType \TmrwLife\NtakGuru\Enums\DocumentType
Gender \TmrwLife\NtakGuru\Enums\Gender
Market segment \TmrwLife\NtakGuru\Enums\MarketSegment
Payment option \TmrwLife\NtakGuru\Enums\PaymentOption
Payment option subtype \TmrwLife\NtakGuru\Enums\PaymentOptionSubtype
Residential unit \TmrwLife\NtakGuru\Enums\ResidentialUnit
Sales channel \TmrwLife\NtakGuru\Enums\SalesChannel
Tourist tax \TmrwLife\NtakGuru\Enums\TouristTax

For example:

use TmrwLife\NtakGuru\Entities\Ntak\Reservation;
use TmrwLife\NtakGuru\Enums\MarketSegment;
use TmrwLife\NtakGuru\Enums\ResidentialUnitType;
use TmrwLife\NtakGuru\Enums\SalesChannel;

$reservation = (new Reservation())
    ->setReservationNumber(23597)
    ->setOccurredAt('2023-04-19 14:00:23')
    ->setReservedAt('2023-04-19 13:46:04')
    ->setCancelled(false)
    ->setNationality('hu')
    ->setArrival('2023-04-21')
    ->setDeparture('2023-04-23')
    ->setSalesChannel(SalesChannel::DIRECT_ONLINE)
    ->setMarketSegment(MarketSegment::BUSINESS_GROUP)
    ->setGrossAmount(98700)
    ->setGuestCount(2)
    ->addBookedResidentialUnits(type: ResidentialUnitType::APARTMENT, capacity: 2);

Daily close response

In order to respond to the daily close request, you can use the DailyClose entity builder class.

use TmrwLife\NtakGuru\Crypt;
use TmrwLife\NtakGuru\Entities\Ntak\CheckOutDaySale;
use TmrwLife\NtakGuru\Entities\Ntak\DailyClose;
use TmrwLife\NtakGuru\Entities\Ntak\Expense;
use TmrwLife\NtakGuru\Entities\Ntak\Load;
use TmrwLife\NtakGuru\Entities\Ntak\ResidentialUnit;
use TmrwLife\NtakGuru\Entities\Ntak\ResidentialUnitNight;

$dailyClose = (new DailyClose())
    ->setClosedDay('2023-04-20')
    ->setResidentialUnits(
        all: 15,
        ooo: 0,
        oos: 2,
        occupied: 10,
        available: 3,
    )
    ->addAfterStayExpense(new Expense())
    ->addAfterStayLoad(new Load())
    ->addCheckOutDaySale(new CheckOutDaySale())
    ->addOtherExpense(new Expense())
    ->addOtherLoad(new Load())
    ->addOutOfOrderResidentialUnit(new ResidentialUnit())
    ->addResidentialUnitNight(new ResidentialUnitNight());

return $data; // JSON response to NTAK.guru

Or if the accommodation is no operating

use TmrwLife\NtakGuru\Crypt;
use TmrwLife\NtakGuru\Entities\Ntak\DailyClose;

$dailyClose = (new DailyClose())
    ->setClosedDay('2023-04-20')
    ->setResidentialUnits(
        all: $all = $this->faker->randomDigit(),
        ooo: $ooo = $this->faker->randomDigit(),
        oos: $oos = $this->faker->randomDigit(),
        occupied: $occupied = $this->faker->randomDigit(),
        available: $available = $this->faker->randomDigit(),
    )
    ->accommodationNotOperating();

return $data; // JSON response to NTAK.guru

VIZA

Sending report

use TmrwLife\NtakGuru\Entities\Ntak\CheckIn;
use TmrwLife\NtakGuru\Entities\Ntak\CheckOut;
use TmrwLife\NtakGuru\Services\Reporting\Viza;

$accommodationId = '00000000-0000-0000-0000-0000000'; // Provided by NTAK.guru

$reporting = Viza::setup([
    'accessToken' => '<your-access-token>',
    'isProduction' => false, // default: false
]);

// Check-in report
$checkIn = (new CheckIn())->setAttribute('...');
$response = $reporting->checkIn($accommodationId, $checkIn);

// Check-out report
$checkOut = (new CheckOut())->setAttribute('...');
$response = $reporting->checkOut($accommodationId, $checkOut);

Entity builders

You can use the entity builders to create the entities.

We covered the 2 main report type with the entity builders.

Name Builder
Check-in \TmrwLife\NtakGuru\Entities\Viza\CheckIn
Check-out \TmrwLife\NtakGuru\Entities\Viza\CheckOut

And a few more for properties.

Name Builder
Guest \TmrwLife\NtakGuru\Entities\Viza\Guest
Guest Document \TmrwLife\NtakGuru\Entities\Ntak\GuestDocument

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.