Download the PHP package pzs/nav-online-invoice without Composer

NAV Online Invoice reporter

PHP interface for Online Invoice Data Reporting System of Hungarian Tax Office (NAV)

PHP interfész a NAV Online számla adatszolgáltatásához

Letöltés:

• Composer: packagist.org/packages/pzs/nav-online-invoice
• Legfrissebb verzió: v3.0.3 (zip)
• Példa fájlok: github.com/pzs/nav-online-invoice/tree/master/examples

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.

Tartalom

• Használat
  • Inicializálás
  • Adószám ellenőrzése (queryTaxpayer)
  • Token kérése (tokenExchange)
  • Adatszolgáltatás (manageInvoice)
  • Technikai érvénytelenítés (manageAnnulment)
  • Státusz lekérdezése (queryTransactionStatus)
  • Számla lekérdezése (queryInvoiceData)
  • Számla keresése (queryInvoiceDigest)
  • Tranzakciók lekérése (queryTransactionList)
  • Számlalánc lekérése (queryInvoiceChainDigest)
  • Számla (szakmai) XML validálása küldés nélkül
  • REST hívás részletei
• Dokumentáció
  • Config osztály
  • Reporter osztály
  • InvoiceOperations osztály
  • Exception osztályok
  • PHP verzió és modulok
  • Linkek
• További modulok NAV API-hoz
• License

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!

Inicializálás

Technikai felhasználó és szoftver adatok beállítása, Reporter példány létrehozása:

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.

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.

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

Adatszolgáltatás (manageInvoice)

Új, módosító és sztornó számla beküldésére.

Az adatszolgáltatás metódus automatikusan lekéri a tokent is (tokenExchange), így ezt nem kell külön megtenni.

Módosító vagy sztornó számlához használd a "MODIFY" és "STORNO" értéket a második paraméterben.

Több számla egyszerre való feladásához lásd a manageInvoice_multiple.php példát.

Elektronikus számlázásról (electronicInvoiceHash és completenessIndicator) lásd a Elektronikus számlázás támogatása leírást.

:information_source: Oké, beküldtem a számlát, de mit csináljak Exception esetén? :interrobang:

• 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.

Státusz lekérdezése (queryTransactionStatus)

Státusz lekérdezése a manageInvoice és manageAnnulment operációkhoz.

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)

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.

Számla keresése (queryInvoiceDigest)

Lekérdező operáció, mely kiállító és vevő oldalról is használható.

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.

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.

Számla (szakmai) XML validálása küldés nélkül

Számla validálásának másik módját lásd a validateInvoices.php példában.

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:

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.

Dokumentáció

Config osztály

Config példány létrehozásakor a paraméterek megadása kötelező:

• $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.

Metódusok

• __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.
• 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.

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.

• __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.

• __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.

Szükséges modulok:

• cURL
• OpenSSL
• PHP 7.1.0 alatt SHA3 hash algoritmust implementáló könyvtár, például:
  • n-other/php-sha3, MIT license (packagist),
  • vagy desktopd/php-sha3-streamable, LGPL 3+ license,

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

Copyright (c) 2018-2024 github.com/pzs

https://github.com/pzs/nav-online-invoice