Merge pull request #32 from pzs/dev/3.0

Upgrade to API v3.0

README.md

@@ -12,39 +12,31 @@ __Letöltés:__
 
 NAV Online számla oldala: [onlineszamla.nav.gov.hu](https://onlineszamla.nav.gov.hu/)
 
-## :mega: 2.0-ás API támogatás
+## :fire: v3.0-ás API támogatás :fire:
 
-A modul ezen verzió a NAV 2.0-ás API-ját támogatja.
+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.4](https://github.com/pzs/nav-online-invoice/tree/v2.0.4) verziót.
 
-## Frissítés v2.0-ás API-ra
+## :information_source: Frissítés v3.0-ás API-ra
 
 <details>
 <summary>Kattints ide a leírás megjelenítéséhez!</summary>
 
-:information_source: A NAV 2.0-ás API teszt és éles környezetben is elérhető már.
-
-:warning: 2020. július 1-jétől kizárólag a 2.0-ás API lesz alkalmazható az éles környezetben ([forrás](https://onlineszamla.nav.gov.hu/))
-
-A 2.0-ás `nav-online-invoice` modulra való frissítés után a következő módosításokat kell végrehajtanod:
-
+v3.0-ás `nav-online-invoice` modulra történő frissítés után - a modult érintően - csak az URL-t kell átírnod `v3`-asra, más teendőd nincs, de ajánlott elolvasni az itt lévő változásokat:
 
 - `NavOnlineInvoice\Config` példányosításakor:
-    - apiUrl a következőre változott: `https://api-test.onlineszamla.nav.gov.hu/invoiceService/v2`, illetve "-test" rész nélkül éles környezetben,
-    - software adatok megadása kötelező lett,
-- SHA3-512-es hash algoritmust kell használni, melyhez PHP 7.1.0-ás verzió, vagy újabb szükséges. Ha ennél régebbit használsz, akkor külső könyvtárat kell betölteni, melyet _nem_ tartalmaz a `nav-online-invoice` modul:
-    - [n-other/php-sha3](https://github.com/n-other/php-sha3), MIT license ([packagist](https://packagist.org/packages/n-other/php-sha3)),
-    - vagy [desktopd/php-sha3-streamable](https://notabug.org/desktopd/php-sha3-streamable), LGPL 3+ license,
-    - a fenti kettő könyvtár közül elég az egyiket telepítened/behivatkoznod, s azt automatikusan használni fogja a `nav-online-invoice`.
-- technikai érvényesítést mostantól nem a `manageInvoice()` hívással, hanem `manageAnnulment()` hívással kell beküldened,
-- a státusz lekérdezés metódus át lett nevezve `queryInvoiceStatus()`-ról `queryTransactionStatus()`-ra,
-- a `queryInvoiceData()` metódus változott: ezzel mostantól csak egy számla adatait lehet lekérni számlaszám alapján (kiállító és vevő oldalról is), keresni pedig az új `queryInvoiceDigest()` metódussal lehet,
-- a `queryTaxpayer()` metódus visszatérési értékében a címadatokat más formában adja vissza a NAV, illetve kibővül más információkkal is,
-- továbbá a 2.0-ás API-n új operációk is elérhetőek lettek: `queryTransactionList` és `queryInvoiceChainDigest`, lásd a leírást és példákat.
+    - apiUrl a következőre változott: `https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3`, illetve "-test" rész nélkül éles környezetben,
+    - Esetleg használhatod a beépített `NavOnlineInvoice\Config::TEST_URL` és `NavOnlineInvoice\Config::PROD_URL` változókat, így a jövőben nem kell bajlódni az URL átírásával,
 
-Új funkció a `nav-online-invoice` modulban:
-- naplózást és hibakeresést segítő `$reporter->getLastRequestData()` metódus, lásd a [példafájlt](examples/log.php), illetve a [leírást](#rest-hívás-részletei).
+- Változások:
+    - A boríték XML-ből a namespace-eket automatikusan törli a modul, erről (és segédletről a namespace-ekhez) itt találsz leírást: [XML namespace-ek](docs/xml_namespaces.md).
+    - Elektronikus számlázásról (`electronicInvoiceHash` és `completenessIndicator`) lásd a [manageInvoice_electronic_invoice.php](examples/manageInvoice_electronic_invoice.php) példafájlt és az [Elektronikus számlázás támogatása](docs/electronic_invoice.md) leírást.
+    - Config osztályban a `$verifySSL` értéke alapértelmezetten `true` lett, így ha bármi rosszul beállított certificate miatt nem kapcsolódna a modul a NAV-hoz, `$config->verifySSL = false;`-ra állításával ki tudod kapcsolni a `cURL`-ben az SSL ellenőrzést.
+    - `$reporter->getLastRequestData()`-en belül a `lastRequestId` át lett nevezve `requestId`-ra.
 
-Ha ezekkel megvagy, akkor már csak az adatsémákat kell átírnod, melyhez segítséget a NAV-os dokumentációkban, illetve fórumokon találsz, de ha megpróbálod beküldeni a régi adat XML-t, akkor az interfész is ki fogja írni a sémavalidálási hibát. NAV-os changelog: [CHANGELOG_2.0](https://github.com/nav-gov-hu/Online-Invoice/blob/master/src/schemas/nav/gov/hu/OSA/CHANGELOG_2.0.md)
+- Új funkció a `nav-online-invoice` modulban:
+    - `$reporter->getLastResponseXml()` metódus, mely visszaadja az utolsó válasz XML-t (ez a namespace nélküli változat, lásd [XML namespace-ek](docs/xml_namespaces.md)).
+
+Ha ezekkel megvagy, akkor már csak az adatsémákat kell átírnod, melyhez segítséget a NAV-os dokumentációkban, illetve fórumokon találsz, de ha megpróbálod beküldeni a régi adat XML-t, akkor az interfész is ki fogja írni a sémavalidálási hibát. NAV-os changelog: [CHANGELOG_3.0](https://github.com/nav-gov-hu/Online-Invoice/blob/master/src/schemas/nav/gov/hu/OSA/CHANGELOG_3.0.md)
 
 </details>
 
@@ -54,9 +46,6 @@ Ha ezekkel megvagy, akkor már csak az adatsémákat kell átírnod, melyhez seg
 
 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!
 
-:information_source: Ez a verziójú `nav-online-invoice` modul csak az új, v2.0-ás NAV-os interfésszel tud kommunikálni. Ha még a hamarosan kivezetésre kerülő v1.1-es NAV interfészt használod, akkor a [korábbi verziót](https://github.com/pzs/nav-online-invoice/releases/tag/v1.1.0) töltsd le.
-
-
 ### Inicializálás
 
 Technikai felhasználó és szoftver adatok beállítása, Reporter példány létrehozása:
@@ -82,7 +71,7 @@ $softwareData = array(
     "softwareDevTaxNumber" => "string",
 );
 
-$apiUrl = "https://api-test.onlineszamla.nav.gov.hu/invoiceService/v2";
+$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
@@ -94,7 +83,7 @@ $reporter = new NavOnlineInvoice\Reporter($config);
 
 ### Adószám ellenőrzése (`queryTaxpayer`)
 
-Megjegyzés: a modul automatikusan eltávolítja az `ns2` namespace-t a válasz XML-ből (lásd [#20](https://github.com/pzs/nav-online-invoice/issues/20)), így kényelmesebben használható az XML válasz. Ez a működés szükség szerint kikapcsolható a `$config->removeNamespaces` `false`-ra állításával.
+A modul automatikusan eltávolítja a namespace-eket a válasz XML-ből (lásd [XML namespace-ek](docs/xml_namespaces.md)), így kényelmesebben használható az XML válasz.
 
 ```php
 try {
@@ -161,12 +150,14 @@ Módosító vagy sztornó számlához használd a "MODIFY" és "STORNO" értéke
 
 Több számla egyszerre való feladásához lásd a [manageInvoice_multiple.php](examples/manageInvoice_multiple.php) példát.
 
+Elektronikus számlázásról (`electronicInvoiceHash` és `completenessIndicator`) lásd a [manageInvoice_electronic_invoice.php](examples/manageInvoice_electronic_invoice.php) példafájlt és az [Elektronikus számlázás támogatása](docs/electronic_invoice.md) 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 újrapróbálkozás, naplózd és ellenőrizd a hibaüzenetet (`$ex->getMessage()`)!
+- 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`)
@@ -360,7 +351,7 @@ $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['lastRequestId']);
+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.
@@ -374,8 +365,8 @@ A `requestBody` ezen modul által összeállított XML string-et tartalmazza, a
 `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/v2`
-    - éles környezetben: `https://api.onlineszamla.nav.gov.hu/invoiceService/v2`
+    - 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.
 
@@ -412,16 +403,17 @@ Ezen az osztályon érhetjük el a NAV interfészén biztosított szolgáltatás
 - `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 lastRequestId. 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.
+- `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.
+`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](docs/electronic_invoice.md).
 
 - `__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"])`: Számla XML hozzáadása a listához
+- `add(SimpleXMLElement $xml [, $operation = "CREATE"][, $electronicInvoiceHash = null])`: Számla XML hozzáadása a listához
 - `isTechnicalAnnulment()`
 - `getInvoices()`
 

docs/electronic_invoice.md

@@ -0,0 +1,53 @@
+
+# Elektronikus számlázás támogatása
+
+_A koncepció megértéséhez lásd a NAV specifikáció, 2.6. fejezetét: Elektronikus számlázás támogatása. A lenti leírás csak a `nav-online-invoice` modul használatára terjed ki._
+
+
+## Példafájl
+
+Lásd: [manageInvoice_electronic_invoice.php](../examples/manageInvoice_electronic_invoice.php)
+
+
+## completenessIndicator=false esetén
+
+Ebben az esetben a felhasználó képezi a hash értéket az elektronikus számláról (pl. PDF fájlról) és ezt a hash értéket adja át számla beküldéskor. Használandó hash algoritmus: SHA3-512.
+
+Példa:
+
+```php
+$invoices = new NavOnlineInvoice\InvoiceOperations();
+
+$pdfFileContent = "...";
+$electronicInvoiceHash = NavOnlineInvoice\Util::sha3_512($pdfFileContent);
+
+$invoices->add($invoiceXmlObject, "CREATE", $electronicInvoiceHash);
+
+$transactionId = $reporter->manageInvoice($invoices);
+```
+
+_Megjegyzés: itt a NAV API elfogadná az SHA-256 hash-t is, viszont a `nav-online-invoice` modulban fixen rögzítve van a SHA3-512-es cryptoType mező, így csak ez utóbbi használható._
+
+
+## completenessIndicator=true esetén
+
+Ebben az esetben a hash-t az adatszolgáltatásban használt XML-ről (base64 kódolás után) kell képezni. Mivel a base64-es változatot a `nav-online-invoice` modul képezi az XML-ből, így a modul a hash-t is elkészíti automatikus, ha `completenessIndicator=true` (ezt nem kell külön átadni, maga a modul ellenőrzi az átadott számla $xml-ben ezt a mezőt).
+
+Az elkészült hash-t opcionálisan lekérhetjük.
+
+Példa:
+
+```php
+$invoices = new NavOnlineInvoice\InvoiceOperations();
+
+$invoices->add($invoiceXmlObject, "CREATE");
+
+$electronicInvoiceHash = $invoices->getLastInvoiceHash();
+var_dump($electronicInvoiceHash);
+
+$transactionId = $reporter->manageInvoice($invoices);
+```
+
+Ha az átadott xml-ben a `completenessIndicator=true` és kézileg is átadnánk 3. paraméterben egy hash-t értéket, akkor a modul Exception-t fog dobni.
+
+