HTTP klient v jazyku PHP pre e-Kasa API riešenie spoločnosti Nine Digit, s.r.o..
Knižnica je kompatibilná s PHP vo verzii 7.4, 8.1 a vyššej.
Knižnica je dostupná na https://packagist.org/packages/ninedigit/ekasa-clientphp.
Najnovšiu verziu balíka nainštalujete príkazom:
composer require ninedigit/ekasa-clientphp
Inštaláciu špecifickej verzie nainštalujete príkazom:
composer require ninedigit/ekasa-clientphp:0.0.1
- Upravte súbor
composer.json
a do kolekcierepositories
pridajte nový repozitár:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/ninedigit/ekasa-clientphp"
}
]
}
- Nainštalujte balík
Najnovšiu verziu balíka nainštalujete príkazom:
composer require ninedigit/ekasa-clientphp
Inštaláciu špecifickej verzie nainštalujete príkazom:
composer require ninedigit/ekasa-clientphp:0.0.1
Viac informácii o inštalácii privátnych repozitárov nájdete v Composer dokumentácii.
Knižnica aktuálne pokrýva iba funkcionalitu registrácie dokladu. Ak máte záujem o rozšírenie, zadajte prosím dopyt na info@ninedigit.sk.
Knižnicu je možné používať v dvoch režimoch:
Služba je po inštalácií štandardne dostupná na porte 3010
(http://localhost:3010
).
Klientskú triedu inštanciujte nasledovne:
$clientOptions = new ApiClientOptions(EKasaServer::LOCALHOST);
$client = new ApiClient($clientOptions);
TIP: Ak ste integrátor a potrebujete testovaciu eKasa API inštanciu, postupujte podľa tohto návodu.
Ak je vaša PHP aplikácia používajúca túto knižnicu nasadená na inom počítači (na serveri resp. v cloude), je potrebné zabezpečiť sieťové spojenie s lokálne nainštalovanou eKasa API.
Riešením je práve služba Expose, ktorá priradí k vašej lokálne nainštalovanej eKasa API URL adresu s použitím zabezpečeného HTTPS protokolu.
- Nie je potrebné žiadne nastavenie smerovača (routra) či obstarávanie statickej IP adresy u internetového poskytovateľa.
- Nadviazané spojenie je šifrované
- Prístup k eKasa API službe je chránený nastaveným prístupovým kľúčom, ktorý je možné kedykoľvek aktualizovať.
Pre aktiváciu služby a získanie prihlasovacích údajov nás kontaktujte na e-mailovej adrese info@ninedigit.sk.
Pri použití Expose služby inštanciujete klientskú triedu nasledovne:
$url = EKasaServer::exposeProduction("{vas_nazov_domeny}");
$accessTokenSource = AccessTokenSource::queryString("access_token");
$accessTokenOptions = new ApiClientAuthenticationAccessTokenOptions("{vas_bezpecnostny_kluc}", $accessTokenSource);
$authentication = new ApiClientAuthenticationOptions(null, $accessTokenOptions);
$clientOptions = new ApiClientOptions($url, $authentication);
$client = new ApiClient($clientOptions);
Príklady sú dostupné v adresári examples.
// Vytvorenie klienta
$clientOptions = new ApiClientOptions(EKasaServer::LOCALHOST);
$client = new ApiClient($clientOptions);
// Nastavenia tlače
$posPrinterOptions = new PosReceiptPrinterOptions();
$posPrinterOptions->openDrawer = true;
$print = new PosRegisterReceiptPrintContextDto($posPrinterOptions);
// Položka
$receiptItem = new ReceiptItemDto(
ReceiptItemType::POSITIVE, // Kladný typ položky
"Coca Cola 0.25l", // Názov
1.29, // Jednotková cena
20.00, // Daňová hladina
new QuantityDto(2, "ks"), // Množstvo
2.58 // Cena
);
// Požiadavka registrácie
$receipt = ReceiptBuilder::cashRegister("88812345678900001", $items)
->setHeaderText("Nine Digit, s.r.o.") // Voliteľná hlavička dokladu
->setFooterText("Ďakujeme za nákup!") // Voliteľná pätička dokladu
->addPayment(new ReceiptPaymentDto(2.60, ReceiptPaymentName::CASH))
->addPayment(new ReceiptPaymentDto(-0.02, "Výdavok"))
->build();
$request = new RegisterReceiptRequestDto($receipt);
$requestContext = new RegisterReceiptRequestContextDto($print, $request);
// Registrácia
$result = $client->registerReceipt($requestContext);
V prípade, ak do premenných vkladáte výsledky matematických operácii, pred priradením je vhodné premenné zaokrúhliť.
- Jednotkové ceny sú zaokrúhľované na 6 desatinných miest.
- Ceny sú zaokrúhľované na 2 desatinné miesta.
- Množstvá sú zaokrúhľované na 4 desatinné miesta.
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
Inštalácia závislostí knižnice:
php composer.phar install
Po vytvorení nových tried (v separátnych súboroch) je nutné vyvolať
php composer.phar dump-autoload
Pre vykonanie integračných testov je nutné vytvoriť súbor settings.json
v tests\integration
vo formáte JSON so štruktúrou zhodnou s triedou ApiClientOptions
.
Napríklad:
{
"url": "https://test.expose.ninedigit.sk",
"proxyUrl": "192.168.1.218:9090",
"authentication": {
"credentials": {
"userName": "admin",
"password": "admin"
},
"accessToken": {
"value": "31d6cfe0d16ae931b73c59d7",
"source": {
"name": "queryString",
"keyName": "access_token"
}
}
}
}
Testy je možné spustiť príkazom:
./vendor/bin/phpunit --verbose tests
Pre spustenie konkrétneho testu je nutné uviesť prepínač --filter
s názvom testovaciej metódy.
Napríklad:
./vendor/bin/phpunit --verbose tests --filter testRegisterCashRegisterReceiptUsingPosPrinter
./vendor/bin/phpcs --standard=PHPCompatibility --extensions=php --runtime-set testVersion 8.1- ./src