Alapok

A különböző példák használatához hívjuk meg a csomagban található ../examples/autoload.php fájlt, amely automatikusan betölti azokat az osztályokat, amelyekre az Agent kérések elküldésénél szükségünk lesz. Ezt csupán egy alkalommal szükséges megtennünk, abszolút vagy akár relatív elérési útvonal megadásával, az igényünk szerint.

require_once(__DIR__ . '/../examples/autoload.php');

Az API a ‘SzamlaAgent’ névtéren (namespace) keresztül érhető el. A példáknál láthatod a helyes használatot. A fejlesztői környezetek (IDE) automatikusan kiegészítik az importálandó osztályok névtereit, ellenkező esetben ezeket neked kell pótolnod a következőképpen:

use \SzamlaAgent\SzamlaAgentAPI,
    \SzamlaAgent\Buyer,
    \SzamlaAgent\Item\InvoiceItem,
    \SzamlaAgent\Document\Invoice\Invoice;

A fenti példa egy papír- vagy e-számla kiállításához használt osztályokat importálja.

A példát megtalálod az API csomagban a következő helyen: ./examples/document/invoice/create_invoice_with_default_data.php

vigyázat

A Számla Agent PHP API használatához szükséges minimum PHP verzió: 5.6.0.

Karakterkódolás

Az Agent kérések és válaszok alapértelmezetten utf-8 karakterkódolást használnak.

Inicializálás

Az Agent kommunikáció előkészítéséhez hozzunk létre egy Agent példányt:

$agent = SzamlaAgentAPI::create('agentApiKey’);

A Számla Agent kulcsot (‘apiKey’) abban a Számlázz.hu fiókban kell létrehoznod, amellyel az Agentet használni szeretnéd (figyelj arra, hogy ez olyan felhasználó legyen, aki csak egyetlen számlázási fiókhoz fér hozzá). A fentebbi metódus alkalmazásával az Agent kommunikációját biztosító PHP osztály létrejön az alapértelmezett beállításokkal együtt.

Erről bővebben itt olvashatsz.

• Sikeres válasz (response) esetén az adatok tartalmazni fogják a létrejött bizonylatot (1 példányban) PDF formátumban.
• A naplózási szint alapértelmezetten DEBUG, amelyet megváltoztathatsz például csak hibanaplózásra a következőképpen:

$agent = SzamlaAgentAPI::create('apiKey', true, Log::LOG_LEVEL_ERROR);

vagy külön paraméterezve:

$agent->setLogLevel(Log::LOG_LEVEL_ERROR);

Ha szeretnél e-mailben értesülni arról, hogy ha valami hiba történik az Agent működése közben, akkor ezt a következőképpen tudod beállítani:

$agent->setLogEmail(‘example@example.com’);

Alapértelmezett beállítások

Az alábbiakban bemutatjuk, hogy milyen beállításokat érhetsz el. Fontos, hogy a PHP a logs, xmls, pdf könyvtárakat képes legyen írni.

Naplózási szintek (logLevel)

Az alkalmazott logolás „szintjét” határozza meg.

0. nincs naplózás: a megadott érték inaktívvá teszi a naplózást.
1. hibák: csakis ‘error’ típusú eseményt rögzít, illetve igény szerint e-mailt küld erről.
2. figyelmeztetések: a hibanaplózáson felül rögzítésre kerülnek a figyelmeztetések is, amelyek nem befolyásolják feltétlenül az üzemszerű működést.
3. debug mód: a fentieken felül a funkciók üzemszerű működéséről is folyamatos tájékoztatást kapunk.

0: LOG_LEVEL_OFF   - nincs naplózás
1: LOG_LEVEL_ERROR - hibák naplózása
2: LOG_LEVEL_WARN  - hibák és figyelmeztetések naplózása
3: LOG_LEVEL_DEBUG - minden típus naplózása (fejlesztői mód)

Naplózási fájlok

Minden naplófájl alapértelmezett beállítások szerint a ./logs könyvtárába generálódik és napi bontásban tartalmazza a naplózott eseményeket, hibákat. A naplózás az alábbi módokon kapcsolható ki:

$agent = SzamlaAgentAPI::create('agentApiKey', true, Log::LOG_LEVEL_OFF);

Naplózási e-mail

Amennyiben kitöltjük, a honlap adminisztrátora e-mailt kap az error szintű eseményekről az itt megadott e-mail címére. Ha nem töltjük ki, akkor a funkció inaktív marad.

$agent->setLogEmail(‘example@example.com’);

PDF dokumentum a válaszban

Beállíthatjuk, hogy az egyes eljáráshívások válaszában (ahol alkalmazható), megkapjuk-e a bizonylatot pdf formátumban. Alapértelmezett beállítás szerint minden válasz tartalmazni fogja a pdf-et, ezért ezt csak akkor kell beállítanunk, ha nem szeretnénk megkapni azt. Ezt az alábbi módokon tehetjük meg:

$agent = SzamlaAgentAPI::create('apiKey', false);

vagy külön paraméterezve:

$agent->setDownloadPdf(false);

Az elmentett PDF fájl minden esetben a generált számla sorszáma szerint kerül elnevezésre.

Cookie és Session kezelés

Biztonsági és erőforrás-takarékossági szempontból egyaránt fontos, hogy az egyes eljáráshívások során a kliens egy felhasználónak látszódjon az Agent távoli rendszere felől. A Számla Agent API példányosításával az API automatikusan beállítja az Agent kérésekhez szükséges session sütit, amely biztosítja, hogy a további kérések során a Számlázz.hu rendszere egy munkamenetben kezelje a beérkező kéréseket. Ez a gyakorlatban azt jelenti, hogy alapértelmezetten minden egyes Számla Agent API példányhoz külön süti fájl fog tartozni, ami biztosítja, hogy a példányokhoz kapcsolódó számlázási fiókok felé elküldött kérések külön session-t használjanak.

Ha meg szeretnénk változtatni ennek útvonalát, az alábbiak szerint módosíthatjuk:

$agent->setCookieFileName('uj-cookie-fajlnév.txt');

Egy időben több számlázási fiókba való számlázás esetén erősen ajánlott az adatbázis mód használata, amely esetében egy bizonylat elküldése után a Számlázz.hu szerver válaszából kinyerhetővé válik a beállított session ID, amely adatbázisban eltárolható, majd a következő kérésnél megadható egy beállító metódussal.

Süti adatbázisban való kezelési módjának beállítása:

$agent->setCookieHandleMode(CookieHandler::COOKIE_HANDLE_MODE_DATABASE)

Süti lekérdezése egy bizonylat elkészítése után:

$result->getCookieSessionId();

Session ID beállítása (adatbázisban tárolt session ID alapján):

$agent->setCookieSessionId($sessionId);

Agent hívás

Az Agent API a legmodernebb CURL metódus használatával kommunikál. Bizonyos szerver konfigurációkon azonban előfordul, hogy a CURL telepítés hiányos vagy nem kerültek telepítésre a szükséges tanúsítvány csomagok, így ezekben az esetekben az eljáráshívás bármely visszajelzése hibába ütközhet. Ezt kiküszöbölendően integráltuk a tanúsítvány automatikus importálását. Bizonyos esetekben ez a megoldás is problémába ütközhet, például rendszerszintű tiltás esetén.

Hibák és kivételek kezelése

Ha a Számla Agent használata közben bármilyen hiba vagy kivétel keletkezik, arról az Agent egy egyéni kivételt dob (SzamlaAgentException), amelyet egy try-catch kivétel kezeléssel el tudunk kapni az alábbi módon:

try {
        $agent = SzamlaAgentAPI::create('agentApiKey');
        …
        …
        if ($result->isSuccess()) {
            ...
        }
    } catch (SzamlaAgentException $e) {
        $agent->logError($e->getMessage());
    } catch (\Exception $e) {
        $agent->logError($e->getMessage());
    }

Minden hibáról naplóbejegyzés készül a ./logs/{current-date} fájlba. Ahhoz, hogy minden hibát naplózzon az Agent, a naplózási szintet fejlesztői módba érdemes állítanunk:

$agent = SzamlaAgentAPI::create('apiKey', true, Log::LOG_LEVEL_DEBUG); 

vagy külön paraméterezve:

$agent->setLogLevel(Log::LOG_LEVEL_DEBUG);