NAV Online Invoice reporter
PHP interface for Online Invoice Data Reporting System of Hungarian Tax Office (NAV), (*1)
PHP interfész a NAV Online számla adatszolgáltatásához, (*2)
Letöltés:
- Composer: packagist.org/packages/pzs/nav-online-invoice
- Legfrissebb verzió: v3.0.4 (zip)
- Példa fájlok: github.com/pzs/nav-online-invoice/tree/master/examples, (*3)
v3.0-ás API támogatás
A modul ezen verziója a NAV v3.0-ás API-ját támogatja. v2.0-ás API támogatáshoz használd a korábbi, v2.0.6 verziót.
Leírást a v3-as modulra való átálláshoz itt találsz., (*4)
, (*5)
Tartalom
Használat
A használathoz a NAV oldalán megfelelő regisztrációt követően létrehozott technikai felhasználó adatainak beállítása szükséges!, (*6)
Inicializálás
Technikai felhasználó és szoftver adatok beállítása, Reporter példány létrehozása:, (*7)
$userData = array(
"login" => "username",
"password" => "password",
// "passwordHash" => "...", // Opcionális, a jelszó már SHA512 hashelt változata. Amennyiben létezik ez a változó, akkor az authentikáció során ezt használja
"taxNumber" => "12345678",
"signKey" => "sign-key",
"exchangeKey" => "exchange-key",
);
$softwareData = array(
"softwareId" => "123456789123456789",
"softwareName" => "string",
"softwareOperation" => "ONLINE_SERVICE",
"softwareMainVersion" => "string",
"softwareDevName" => "string",
"softwareDevContact" => "string",
"softwareDevCountryCode" => "HU",
"softwareDevTaxNumber" => "string",
);
$apiUrl = "https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3";
$config = new NavOnlineInvoice\Config($apiUrl, $userData, $softwareData);
$config->setCurlTimeout(70); // 70 másodperces cURL timeout (NAV szerver hívásnál), opcionális
// "Connection error. CURL error code: 60" hiba esetén add hozzá a következő sort:
// $config->verifySSL = false;
$reporter = new NavOnlineInvoice\Reporter($config);
Adószám ellenőrzése (queryTaxpayer)
A modul automatikusan eltávolítja a namespace-eket a válasz XML-ből (lásd XML namespace-ek), így kényelmesebben használható az XML válasz., (*8)
try {
$result = $reporter->queryTaxpayer("12345678");
if ($result) {
print "Az adószám valid.\n";
print "Az adószámhoz tartozó név: $result->taxpayerName\n";
print "További lehetséges információk az adózóról:\n";
print_r($result->taxpayerShortName);
print_r($result->taxNumberDetail);
print_r($result->vatGroupMembership);
print_r($result->taxpayerAddressList);
} else {
print "Az adószám nem valid.";
}
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Token kérése (tokenExchange)
Ezt a metódust célszerű használni a technikai felhasználó adatainak (és a program) tesztelésére is., (*9)
Megjegyzés: a tokenExchange csak akkor hívható meg, ha a létrehozott technikai felhasználónak a "Számlák kezelése" jogosultság is hozzá van adva. Lásd: https://github.com/pzs/nav-online-invoice/issues/64, (*10)
try {
$token = $reporter->tokenExchange();
print "Token: " . $token;
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Adatszolgáltatás (manageInvoice)
Új, módosító és sztornó számla beküldésére., (*11)
try {
// Az $invoiceXml tartalmazza a számla (szakmai) SimpleXMLElement objektumot
$transactionId = $reporter->manageInvoice($invoiceXml, "CREATE");
print "Tranzakciós azonosító a státusz lekérdezéshez: " . $transactionId;
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Az adatszolgáltatás metódus automatikusan lekéri a tokent is (tokenExchange), így ezt nem kell külön megtenni., (*12)
Módosító vagy sztornó számlához használd a "MODIFY" és "STORNO" értéket a második paraméterben., (*13)
Több számla egyszerre való feladásához lásd a manageInvoice_multiple.php példát., (*14)
Elektronikus számlázásról (electronicInvoiceHash és completenessIndicator) lásd a manageInvoice_electronic_invoice.php példafájlt és az Elektronikus számlázás támogatása leírást., (*15)
:information_source: Oké, beküldtem a számlát, de mit csináljak Exception esetén? :interrobang:, (*16)
- Ha
NavOnlineInvoice\XsdValidationError Exception-t kaptál, akkor valamelyik XML-ben lesz hiba! Lehet a szakmai (számla) XML hibás (bár ezt már számlakészítéskor is célszerű ellenőrizni), de a boríték XML is lehet hibás (pl. megadtad a software adatokat, de rossz a formátuma). Fontos megjegyezni, hogy ez az Exception még a küldés előtt jön a nav-online-invoice által generálva.
- Ha
NavOnlineInvoice\CurlError vagy NavOnlineInvoice\HttpResponseError Exception-t kaptál, akkor mindenképp próbáld újraküldeni a számlát pár perc múlva, mert lehet csak épp nincs interneted, vagy a NAV szervere nem elérhető/furcsaságokat válaszol.
- Ha
NavOnlineInvoice\GeneralErrorResponse vagy NavOnlineInvoice\GeneralExceptionResponse az Exception, akkor a NAV válaszolt egy XML üzenettel, viszont ebben - az Exception típusának megfelelő típusú - hibaüzenet volt. Mind a kettő exception esetén az errorCode az $ex->getErrorCode() metódussal lekérhető, melyek értelmezését megtaláljuk a NAV által kiadott interfész specifikációban. Ugyan nem minden hibakód esetén, de az esetek többségében itt is érdemes próbálkozni az újraküldéssel.
- Más egyéb Exception esetén (
NavOnlineInvoice\GeneralExceptionResponse, NavOnlineInvoice\GeneralErrorResponse és \Exception) valószínűleg felesleges az újra próbálkozás, naplózd és ellenőrizd a hibaüzenetet ($ex->getMessage())!
Technikai érvénytelenítés (manageAnnulment)
Technikai érvénytelenítés beküldése., (*17)
try {
// Az $annulmentXml tartalmazza a technikai érvénytelenítést tartalmazó SimpleXMLElement objektumot
$transactionId = $reporter->manageAnnulment($annulmentXml);
print "Tranzakciós azonosító a státusz lekérdezéshez: " . $transactionId;
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Státusz lekérdezése (queryTransactionStatus)
Státusz lekérdezése a manageInvoice és manageAnnulment operációkhoz., (*18)
try {
$transactionId = "...";
$statusXml = $reporter->queryTransactionStatus($transactionId);
print "Válasz XML objektum:\n";
var_dump($statusXml);
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Az adatszolgáltatás addig nem tekinthető teljesítettnek, amíg a kliens az aszinkronfeldolgozás sikerességéről meg nem győződött és az adott számlához tartozó nyugtaüzenetet meg nem kapta. (NAV dokumentáció, #54), (*19)
Számla lekérdezése (queryInvoiceData)
Számla lekérdezése számlaszám alapján, mely kiállító és vevő oldalról is használható. Második paraméterben true-t átadva a metódus a dekódolt számla XML-t adja vissza invoiceDataResult helyett., (*20)
try {
$invoiceNumberQuery = [
"invoiceNumber" => "T20190001",
"invoiceDirection" => "OUTBOUND",
];
// Lekérdezés
$invoiceDataResult = $reporter->queryInvoiceData($invoiceNumberQuery);
print "Query results XML elem:\n";
var_dump($invoiceDataResult);
// Számla kézi dekódolása
$invoice = NavOnlineInvoice\InvoiceOperations::convertToXml($invoiceDataResult->invoiceData, $invoiceDataResult->compressedContentIndicator);
// Számla:
var_dump($invoice);
// *** VAGY ***
// Lekérdezés és számla automatikus dekódolása
$invoice = $reporter->queryInvoiceData($invoiceNumberQuery, true); // 2. paraméter jelzi az automatikus dekódolást
// Számla:
var_dump($invoice);
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Számla keresése (queryInvoiceDigest)
Lekérdező operáció, mely kiállító és vevő oldalról is használható., (*21)
try {
$invoiceQueryParams = [
"mandatoryQueryParams" => [
"invoiceIssueDate" => [
"dateFrom" => "2021-01-01",
"dateTo" => "2021-01-11",
],
],
"relationalQueryParams" => [
"invoiceDelivery" => [
"queryOperator" => "GTE",
"queryValue" => "2021-01-01",
],
// Több feltétel esetén ugyanazon elemhez tömbben adjuk át a gyerek elemeket
"paymentDate" => [
[
"queryOperator" => "GTE",
"queryValue" => "2021-01-01",
],
[
"queryOperator" => "LTE",
"queryValue" => "2021-01-28",
],
],
],
];
$page = 1;
$invoiceDigestResult = $reporter->queryInvoiceDigest($invoiceQueryParams, $page, "OUTBOUND");
print "Query results XML elem:\n";
var_dump($invoiceDigestResult);
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Tranzakciók lekérése (queryTransactionList)
A kérésben megadott időintervallumban, a technikai felhasználóhoz tartozó adószámhoz beküldött számlaadat-szolgáltatások listázására szolgál., (*22)
try {
$config = new NavOnlineInvoice\Config($apiUrl, $userData, $softwareData);
$reporter = new NavOnlineInvoice\Reporter($config);
$insDate = [
"dateTimeFrom" => "2020-03-01T06:00:00Z",
"dateTimeTo" => "2020-03-05T18:00:00Z",
];
$page = 1;
$transactionListResult = $reporter->queryTransactionList($insDate, $page);
print "Result:\n";
print_r($transactionListResult);
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Számlalánc lekérése (queryInvoiceChainDigest)
A queryInvoiceChainDigest egy számlaszám alapján működő lekérdező operáció, amely a számlán szereplő kiállító és a vevő oldaláról is használható. Az operáció a megadott keresőfeltételeknek megfelelő, lapozható számlalistát ad vissza a válaszban. A lista elemei a megadott alapszámlához tartozó számlalánc elemei. A válasz nem tartalmazza a számlák összes üzleti adatát, hanem csak egy kivonatot (digest-et), elsősorban a módosításra és tételsorok számára vonatkozóan., (*23)
try {
$config = new NavOnlineInvoice\Config($apiUrl, $userData, $softwareData);
$reporter = new NavOnlineInvoice\Reporter($config);
$invoiceChainQuery = [
"invoiceNumber" => "SZML-123",
"invoiceDirection" => "OUTBOUND", // OUTBOUND or INBOUND
"taxNumber" => "12345678", // optional
];
$page = 1;
$invoiceChainDigestResult = $reporter->queryInvoiceChainDigest($invoiceChainQuery, $page);
print "Result:\n";
print_r($invoiceChainDigestResult);
} catch(Exception $ex) {
print get_class($ex) . ": " . $ex->getMessage();
}
Számla (szakmai) XML validálása küldés nélkül
// Az $invoiceXml tartalmazza a számla (szakmai) SimpleXMLElement objektumot
$errorMsg = NavOnlineInvoice\Reporter::getInvoiceValidationError($invoiceXml);
if ($errorMsg) {
print "A számla nem valid, hibaüzenet: " . $errorMsg;
} else {
print "A számla valid.";
}
Számla validálásának másik módját lásd a validateInvoices.php példában., (*24)
REST hívás részletei
A REST hívások naplózása és hibakeresés végett lehetőség van az utolsó REST hívás adatainak lekérésére:, (*25)
// Bármilyen operáció után, pl.:
// $reporter->manageInvoice($invoiceXml, "CREATE");
// hívható (Exception esetén is):
$data = $reporter->getLastRequestData();
print "<br /><br />Request URL: " . htmlspecialchars($data['requestUrl']);
print "<br /><br />Request body: " . htmlspecialchars($data['requestBody']);
print "<br /><br />Response body: " . htmlspecialchars($data['responseBody']);
print "<br /><br />Request ID: " . htmlspecialchars($data['requestId']);
A requestBody ezen modul által összeállított XML string-et tartalmazza, a responseBody pedig a NAV által visszaadott üzenetet, mely az esetek többségében egy XML string., (*26)
Dokumentáció
Config osztály
Config példány létrehozásakor a paraméterek megadása kötelező:, (*27)
-
$baseUrl tipikusan a következő:
- teszt környezetben:
https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3
- éles környezetben:
https://api.onlineszamla.nav.gov.hu/invoiceService/v3
-
$user array tartalmazza a NAV oldalán létrehozott technikai felhasználó adatait.
-
$software array tartalmazza a számlázó szoftver adatait. 2.0-ás verziótól ennek megadása kötelező, formátumát pedig a NAV által kiadott XSD biztosítja.
A $user és $software paraméter lehet 1-1 JSON fájl elérési útvonala is, ahol a JSON fájl tartalmazza a kívánt adatokat., (*28)
Metódusok, (*29)
__construct(string $baseUrl, $user, $software)setBaseUrl($baseUrl)-
useApiSchemaValidation([$flag = true]): NAV szerverrel való kommunikáció előtt a kéréseket (envelop XML) validálja az XSD-vel. A példány alapértelmezett értéke szerint a validáció be van kapcsolva.
setSoftware($data)loadSoftware($jsonFile)setUser($data)loadUser($jsonFile)-
setCurlTimeout($timeoutSeconds): NAV szerver hívásánál (cURL hívás) timeout értéke másodpercben. Alapértelmezetten nincs timeout beállítva. Megjegyzés: manageInvoice hívásnál 2 szerver hívás is történik (token kérés és számlák beküldése), itt külön-külön kell érteni a timeout-ot.
-
setCurlOptions($curlOptions): NAV szerver hívásánál (cURL hívás) további cURL beállítások, pl. proxy beállítások
-
setRequestIdGenerator(RequestIdGeneratorInterface $obj): opcionálisan egyedi request id generátor állítható be.
Reporter osztály
A Reporter osztály példányosításakor egyetlen paraméterben a korábban létrehozott Config példányt kell átadni., (*30)
Ezen az osztályon érhetjük el a NAV interfészén biztosított szolgáltatásokat. A metódusok nevei megegyeznek a NAV által biztosított specifikációban szereplő operáció nevekkel., (*31)
__construct(Config $config)-
manageInvoice($invoiceOperationsOrXml [, $operation]): A számla beküldésére szolgáló operáció. Visszatérési értékként a transactionId-t adja vissza string-ként. Paraméterben a beküldendő számla XML-t kell átadni, illetve a hozzá tartozó műveletet (ManageInvocieOperationType): CREATE, MODIFY, STORNO. Átadható egyszerre több számla is, ilyenkor első paraméterben InvoiceOperations példányt kell átadni (második paraméternek nincs szerepe ilyenkor).
-
manageAnnulment($invoiceOperationsOrXml): Technikai érvénytelenítés beküldésére szolgáló operáció. Paraméterben a technikai érvénytelenítést leíró XML-t, vagy egy InvoiceOperations példányt kell átadni. Utóbbi esetben az InvoiceOperations példány több XML-t is tartalmazhat. A metódus visszaadja a transactionId-t, mellyel lekérdezhető a tranzakció eredménye.
-
queryInvoiceData($invoiceNumberQuery [, $returnDecodedInvoiceData = false]): Számla lekérdezése számlaszám alapján, mely kiállító és vevő oldalról is használható. Paraméterben az invoiceNumberQuery-nek megfelelően összeállított lekérdezési adatokat kell átadni (SimpleXMLElement példány). Visszatérési értéke a visszakapott XML invoiceDataResult része (SimpleXMLElement példány), vagy a számla XML, ha 2. paraméterben true-t adtunk át.
-
queryInvoiceDigest($invoiceQueryParams, $page = 1, $direction = "OUTBOUND"): Lekérdező operáció, mely kiállító és vevő oldalról is használható. Paraméterben az invoiceQueryParams-nak megfelelően összeállított lekérdezési adatokat kell átadni (SimpleXMLElement), az oldalszámot és a keresés irányát (OUTBOUND, INBOUND). A válasz XML invoiceDigestResult része.
-
queryTransactionStatus(string $transactionId [, $returnOriginalRequest = false]): A számla adatszolgáltatás feldolgozás aktuális állapotának és eredményének lekérdezésére szolgáló operáció
-
queryTransactionList($insDate [, $page = 1]): A kérésben megadott időintervallumban, a technikai felhasználóhoz tartozó adószámhoz beküldött számlaadat-szolgáltatások listázására szolgál
queryInvoiceChainDigest($invoiceChainQuery [, $page = 1])-
queryTaxpayer(string $taxNumber): Belföldi adószám validáló és címadat lekérdező operáció. Visszatérési éréke lehet null nem létező adószám esetén, false érvénytelen adószám esetén, vagy TaxpayerDataType XML elem név és címadatokkal valid adószám esetén
-
tokenExchange(): Token kérése manageInvoice művelethez (közvetlen használata nem szükséges, viszont lehet használni, mint teszt hívás). Visszatérési értékként a dekódolt tokent adja vissza string-ként.
-
getLastRequestData(): Utolsó REST hívás adatainak lekérdezése naplózási és hibakeresési céllal. A visszaadott array a következő elemeket tartalmazza: requestUrl, requestBody, responseBody és requestId. Megjegyzés: bizonyos műveletek (manageAnnulment és manageInvoice) kettő REST hívást is indítanak, a tokenExchange hívást, illetve magát az adatküldést. Sikeres hívás esetén csak a tényleges adatküldés eredménye érhető el, Exception esetén pedig mindig az utolsó hívás adata.
-
getLastResponseXml(): Utolsó válasz XML lekérdezése (operáció hívása után)
InvoiceOperations osztály
manageInvoice és manageAnnulment híváshoz használandó collection, melyhez a feladni kívánt számlákat lehet hozzáadni. Ez az osztály validálja is az átadott szakmai XML-t az XSD-vel. Elektronikus számlázáshoz lásd ezt a leírást., (*32)
-
__construct($compression = false): compression: gzip tömörítés engedélyezése, részletek: NAV dokumentáció, 1.6.5 Tömörítés és méretkorlát
-
useDataSchemaValidation([$flag = true]): Számla adat hozzáadásakor az XML-t (szakmai XML) validálja az XSD-vel. Alapértelmezetten be van kapcsolva a validáció.
-
add(SimpleXMLElement $xml [, $operation = "CREATE"][, $electronicInvoiceHash = null]): Számla XML hozzáadása a listához
isTechnicalAnnulment()getInvoices()
Exception osztályok
-
XsdValidationError: XSD séma validáció esetén, ha hiba történt (a requestXML-ben vagy szakmai XML-ben; a válasz XML nincs vizsgálva). Ez az exception a kliens oldali XML ellenőrzéskor keletkezhet még a szerverrel való kommunikáció előtt.
-
CurlError: cURL hiba esetén, pl. nem tudott csatlakozni a szerverhez (pl. nincs internet, nem elérhető a szerver).
-
HttpResponseError: Ha nem XML válasz érkezett, vagy nem sikerült azt parse-olni.
-
GeneralExceptionResponse: NAV által visszaadott hibaüzenet, ha nem sikerült náluk technikailag valamit feldolgozni (lásd NAV-os leírás Hibakezelés fejezetét).
-
GeneralErrorResponse: NAV által visszaadott hibaüzenet, ha az XML válaszban GeneralErrorResponse érkezett, vagy ha a funcCode !== 'OK'.
PHP verzió és modulok
A NavOnlineInvoice modul tesztelve PHP 5.5 és 7.2 alatt., (*33)
Szükséges modulok:, (*34)
- cURL
- OpenSSL
- PHP 7.1.0 alatt SHA3 hash algoritmust implementáló könyvtár, például:
Linkek
- https://onlineszamla-test.nav.gov.hu/dokumentaciok
- https://onlineszamla-test.nav.gov.hu/
- https://onlineszamla.nav.gov.hu/
- https://github.com/nav-gov-hu/Online-Invoice, kiemelve a CHANGELOG_2.0 leírást
További modulok NAV API-hoz
- NodeJS: https://github.com/angro-kft/nav-connector
- Scala (JVM): https://github.com/enlivensystems/invoicing-hungarian
License
MIT, (*35)
Copyright (c) 2018-2024 github.com/pzs, (*36)
https://github.com/pzs/nav-online-invoice, (*37)
Wallogit.com
