diff --git a/README.md b/README.md index ad8c422..5235ac1 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,13 @@ _PHP interfész a NAV Online számla adatszolgáltatásához_ https://github.com/pzs/nav-online-invoice — https://packagist.org/packages/pzs/nav-online-invoice -Jogszabályok: https://onlineszamla-test.nav.gov.hu/jogszabalyok +NAV Online számla oldala: https://onlineszamla-test.nav.gov.hu/ ## 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! -:warning: Jelenleg a NAV szerverén csak a következő operáció érhető el: `tokenExchange`, `manageInvoice` és `queryInvoiceStatus`, a többi még fejlesztés alatt részükről (2018.04.13.). - ### Inicializálás @@ -22,19 +20,21 @@ Technikai felhasználó (és szoftver) adatok beállítása, Reporter példány ```php $apiUrl = "https://api-test.onlineszamla.nav.gov.hu/invoiceService"; -$config = new NavOnlineInvoice\Config($apiUrl, "userData.json", "softwareData.json"); +$config = new NavOnlineInvoice\Config($apiUrl, "userData.json"); $config->useApiSchemaValidation(); // opcionális $reporter = new NavOnlineInvoice\Reporter($config); ``` -Minta JSON fájlok: [userData.json](tests/testdata/userData.sample.json), [softwareData.json](tests/testdata/softwareData.json). JSON fájl helyett az értékeket tömbben is át lehet adni (lásd lent, Dokumentáció / Config osztály fejezet). +Minta JSON fájlok: [userData.json](tests/testdata/userData.sample.json), [softwareData.json](tests/testdata/softwareData.json). +JSON fájl helyett az értékeket tömbben is át lehet adni (lásd lent, Dokumentáció / Config osztály fejezet). +A konstruktor 3. paraméterében a software adatokat is át lehet adni opcionálisan, ez nem kötelező a NAV részéről. ### Adószám ellenőrzése (`queryTaxpayer`) -:warning: Ez az endpoint a NAV onlineszamla test oldalán jelenleg nem elérhető. +:warning: Ez az endpoint a NAV onlineszamla test oldalán jelenleg nem elérhető. (2018.05.25.) ```php try { @@ -98,6 +98,8 @@ try { ### Státusz lekérdezése (`queryInvoiceStatus`) +Az adatszolgáltatás operációval beküldött számla státuszának lekérdezésére szolgáló operáció. `$transactionId`-nak a `manageInvoice` metódus által visszaadott azonosítót kell megadni. + ```php try { $transactionId = "..."; @@ -115,7 +117,10 @@ try { ### Számla adatszolgáltatások lekérdezése (`queryInvoiceData`) -:warning: Ez az endpoint a NAV onlineszamla test oldalán jelenleg nem elérhető. +Beküldött számlák lekérdezése/keresése. + +:warning: Ezt az interfészt még tesztelni (és szükség szerint javítani) kell. + ```php try { @@ -207,7 +212,7 @@ Ezen az osztályon érhetjük el a NAV interfészén biztosított szolgáltatás - `__construct(Config $config)` - `manageInvoice(InvoiceOperations $invoiceOperations)`: A számla adatszolgáltatás beküldésére szolgáló operáció. Visszatérési értékként a transactionId-t adja vissza string-ként. -- `queryInvoiceData($queryType, $queryData)`: A számla adatszolgáltatások lekérdezésére szolgáló operáció +- `queryInvoiceData(string $queryType, array $queryData [, int $page = 1])`: A számla adatszolgáltatások lekérdezésére szolgáló operáció - `queryInvoiceStatus(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ó - `queryTaxpayer(string $taxNumber)`: Belföldi adószám validáló és címadat lekérdező operáció. Visszatérési éréke lehet `false` invalid 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. @@ -227,10 +232,11 @@ Ezen az osztályon érhetjük el a NAV interfészén biztosított szolgáltatás ### Exception osztályok -- `CurlError`: cURL hiba esetén, pl. nem tudott csatlakozni a szerverhez -- `HttpResponseError`: Ha nem XML válasz érkezett, vagy nem sikerült azt parse-olni -- `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) -- `GeneralErrorResponse`: Ha az XML válaszban `GeneralErrorResponse` érkezett, vagy ha a `funcCode !== 'OK'` +- `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 @@ -252,7 +258,7 @@ Szükséges modulok: ## TODO -- Műveletek (queryTaxpayer, queryInvoiceStatus, queryInvoiceData) manuális tesztelése, amint elérhető lesz az interfész a NAV szerverén +- Műveletek (queryTaxpayer, queryInvoiceData) manuális tesztelése, amint elérhető lesz az interfész a NAV szerverén - További tesztek írása, ami a NAV szerverét is meghívja teszt közben diff --git a/src/NavOnlineInvoice/BaseExceptionResponse.php b/src/NavOnlineInvoice/BaseExceptionResponse.php new file mode 100644 index 0000000..898e97e --- /dev/null +++ b/src/NavOnlineInvoice/BaseExceptionResponse.php @@ -0,0 +1,57 @@ +xml = $xml; + $message = $this->getResultMessage(); + + parent::__construct($message); + } + + + public function getXml() { + return $this->xml; + } + + + /** + * Return the result field of the XML in array format + * @return Array + */ + abstract public function getResult(); + + + public function getResultMessage() { + $result = $this->getResult(); + + if (empty($result["message"])) { + $message = $result["errorCode"]; + } elseif (empty($result["errorCode"])) { + $message = $result["message"]; + } else { + $message = "$result[message] ($result[errorCode])"; + } + + return $message; + } + + + public function getErrorCode() { + $result = $this->getResult(); + + if (isset($result["errorCode"])) { + return (string)$result["errorCode"]; + } + + return null; + } + +} diff --git a/src/NavOnlineInvoice/Connector.php b/src/NavOnlineInvoice/Connector.php index 4bb68bd..c92d53e 100644 --- a/src/NavOnlineInvoice/Connector.php +++ b/src/NavOnlineInvoice/Connector.php @@ -51,6 +51,10 @@ public function post($url, $requestXml) { throw new HttpResponseError($result, $httpStatusCode); } + if ($responseXml->getName() === "GeneralExceptionResponse") { + throw new GeneralExceptionResponse($responseXml); + } + if ($responseXml->getName() === "GeneralErrorResponse") { throw new GeneralErrorResponse($responseXml); } diff --git a/src/NavOnlineInvoice/GeneralErrorResponse.php b/src/NavOnlineInvoice/GeneralErrorResponse.php index 77e0cd2..e22aa25 100644 --- a/src/NavOnlineInvoice/GeneralErrorResponse.php +++ b/src/NavOnlineInvoice/GeneralErrorResponse.php @@ -4,39 +4,10 @@ use Exception; -class GeneralErrorResponse extends Exception { - - protected $xml; - - - function __construct($xml) { - $this->xml = $xml; - $result = $this->getResult(); - - if (empty($result["message"])) { - $message = $result["errorCode"]; - } elseif (empty($result["errorCode"])) { - $message = $result["message"]; - } else { - $message = "$result[message] ($result[errorCode])"; - } - - parent::__construct($message); - } - - - public function getXml() { - return $this->xml; - } - +class GeneralErrorResponse extends BaseExceptionResponse { public function getResult() { return (array)$this->xml->result; } - - public function getErrorCode() { - return (string)$this->xml->result->errorCode; - } - } diff --git a/src/NavOnlineInvoice/GeneralExceptionResponse.php b/src/NavOnlineInvoice/GeneralExceptionResponse.php new file mode 100644 index 0000000..c64482e --- /dev/null +++ b/src/NavOnlineInvoice/GeneralExceptionResponse.php @@ -0,0 +1,13 @@ +xml; + } + +} diff --git a/src/NavOnlineInvoice/ManageInvoiceRequestXml.php b/src/NavOnlineInvoice/ManageInvoiceRequestXml.php index 5f56b76..75ebcf4 100644 --- a/src/NavOnlineInvoice/ManageInvoiceRequestXml.php +++ b/src/NavOnlineInvoice/ManageInvoiceRequestXml.php @@ -39,6 +39,9 @@ protected function addInvoiceOperations() { $operationsXml->addChild("technicalAnnulment", $this->invoiceOperations->getTechnicalAnnulment()); + // NOTE: the compression is currently not supported + $operationsXml->addChild("compressedContent", false); + // Számlák hozzáadása az XML-hez foreach ($this->invoiceOperations->getInvoices() as $invoice) { $invoiceXml = $operationsXml->addChild("invoiceOperation"); diff --git a/src/NavOnlineInvoice/QueryInvoiceDataRequestXml.php b/src/NavOnlineInvoice/QueryInvoiceDataRequestXml.php index 6758865..0361a8d 100644 --- a/src/NavOnlineInvoice/QueryInvoiceDataRequestXml.php +++ b/src/NavOnlineInvoice/QueryInvoiceDataRequestXml.php @@ -9,13 +9,18 @@ class QueryInvoiceDataRequestXml extends BaseRequestXml { private static $queryTypes = ["invoiceQuery", "queryParams"]; - function __construct($config, $queryType, $queryData) { + function __construct($config, $queryType, $queryData, $page) { if (!in_array($queryType, self::$queryTypes)) { throw new Exception("Érvénytelen queryType: $queryType"); } + if (!is_int($page) or $page < 1) { + throw new Exception("Érvénytelen oldalszám: " . $page); + } + parent::__construct("QueryInvoiceDataRequest", $config); + $this->xml->addChild("page", $page); $this->addQueryData($this->xml, $queryType, $queryData); } diff --git a/src/NavOnlineInvoice/Reporter.php b/src/NavOnlineInvoice/Reporter.php index 78a7352..be12c99 100644 --- a/src/NavOnlineInvoice/Reporter.php +++ b/src/NavOnlineInvoice/Reporter.php @@ -51,10 +51,11 @@ public function manageInvoice($invoiceOperations) { * függően attól, hogy konktér számla sorszámot, vagy általános * lekérdezési paramétereket adunk át. * @param Array $queryData A queryType-nak megfelelően összeállított lekérdezési adatok + * @param Int $page Oldalszám (1-től kezdve a számozást) * @return SimpleXMLElement $responseXml A teljes visszakapott XML, melyből a 'queryResults' elem releváns */ - public function queryInvoiceData($queryType, $queryData) { - $requestXml = new QueryInvoiceDataRequestXml($this->config, $queryType, $queryData); + public function queryInvoiceData($queryType, $queryData, $page = 1) { + $requestXml = new QueryInvoiceDataRequestXml($this->config, $queryType, $queryData, $page); $responseXml = $this->connector->post("/queryInvoiceStatus", $requestXml); return $responseXml; diff --git a/src/NavOnlineInvoice/xsd/invoiceApi.xsd b/src/NavOnlineInvoice/xsd/invoiceApi.xsd index 5115679..32fe834 100644 --- a/src/NavOnlineInvoice/xsd/invoiceApi.xsd +++ b/src/NavOnlineInvoice/xsd/invoiceApi.xsd @@ -3,7 +3,7 @@ # Projekt: Magyar Online Számla Rendszer invoiceApi XML XSD séma # Author: NAV Informatikai Intézet -# Version: v1.0 2018/03/11 +# Version: v1.0 2018/04/19 --> @@ -170,6 +170,15 @@ + + + Lapozó paraméter típus + Page parameter type + + + + + Kérés azonosító típus @@ -323,12 +332,6 @@ Transaction ID of the invoice if it was exchanged via M2M interface - - - Ha a számlára érkezett technikai érvénytelenítés, akkor jelöli, hogy azt felhasználó jóváhagyta-e már - If the invoice is affected with technical invalidation, the element indicates whether the user has already verified it - - @@ -490,6 +493,101 @@ + + + Kivonatos lekérdezési eredmények + Digest query results + + + + + + + + Kivonatos lekérdezési eredmény + Digest query result + + + + + Számla vagy módosító okirat sorszáma - ÁFA tv. 169. § b) vagy 170. § (1) bek. b) pont + Sequential number of the original invoice or modifiation document - section 169 (b) or section 170 (1) b) of the VAT law + + + + + Számlaművelet típus + Invoice operation type + + + + + A számla típusa + Type of invoice + + + + + Számla kelte, vagy ha módosító okiratban nincs külön megadva, akkor a módosító okirat kiállításának dátuma + Invoice issue date, or if not provided explicitly in the modification document, the date of issue of the modification document + + + + + A vevő adószáma + The buyer's tax number + + + + + Fizetés módja + Method of payment + + + + + A számla megjelenési formája + Form of appearance of the invoice + + + + + Az adatszolgáltatás forrása + Data exchange source + + + + + Számla teljesítési dátuma + Invoice delivery date + + + + + A számla pénzneme + Currency of the invoice + + + + + A számla nettó összege + Invoice net amount + + + + + A számla forint alapú ÁFA összege + The HUF based VAT amount of the invoice + + + + + Az adatszolgátatás tranzakció azonosítója + Transaction identifier of the data exchange + + + + A kéréshez tartozó kötegelt számlaműveletek @@ -502,6 +600,12 @@ Data exchange invalidation due to technical flaws + + + Tömörített tartalom jelzése a feldolgozási folyamat számára + Compressed content indicator for the processing flow + + A kéréshez tartozó számlaművelet @@ -542,13 +646,13 @@ Invoice query parameters - + Számla kiállítás intervallumának kezdete Interval start of the invoice issue date - + Számla kiállítás intervallumának vége Interval end of the invoice issue date @@ -584,13 +688,13 @@ Data exchange source - + Számla teljesítési dátumának nagyobb mint paramétere Greater than parameter of the invoice delivery date - + Számla teljesítés dátumának kisebb mint paramétere Less than parameter of the invocie delivery date @@ -640,6 +744,18 @@ Invoice query results + + + A jelenleg lekérdezett lapszám + The currently queried page count + + + + + A lekérdezés eredménye szerint elérhető utolsó lapszám + The highest available page count matching the query + + Számla lekérdezési eredmény @@ -653,26 +769,20 @@ Számla lekérdezési eredmény Invoice query result - - + + - Számla adatok BASE64-ben kódolt tartalma - Invoice data in BASE64 encoded form - - - - - A számla audit adatai - Invoice audit data + Számlaszámra történő lekérdezés eredménye, teljes adattartalommal + Complete content result of invoice number based query - + - A módosítás hivatkozási adatai - Modification reference data + Kivonat a paraméter szerint lekérdezett számlákra, vagy a számlaszámra hivatkozó módosításokra + Digest content result of parameter based query, or the modifications referencing to the invoice - + @@ -720,6 +830,38 @@ + + + Számlaszámra történő lekérdezés eredménye + Invoice number based query result + + + + + Számla adatok BASE64-ben kódolt tartalma + Invoice data in BASE64 encoded form + + + + + A számla audit adatai + Invoice audit data + + + + + A módosítás hivatkozási adatai + Modification reference data + + + + + Jelöli, ha az invoice tartalmát a BASE64 dekódolást követően még ki kell tömöríteni az olvasáshoz + Indicates if the content of the invoice needs to be decompressed to be read following the BASE64 decoding + + + + Feldolgozási kurzor adatok @@ -789,6 +931,12 @@ Business validation messages + + + Jelöli, ha az originalRequest tartalmát a BASE64 dekódolást követően még ki kell tömöríteni az olvasáshoz + Indicates if the content of the originalRequest needs to be decompressed to be read following the BASE64 decoding + + Számla adatok BASE64-ben kódolt tartalma @@ -1004,6 +1152,17 @@ + + + Az összes REST operációra vonatkozó kivétel válasz root elementje + General exception response of every REST operation + + + + + + + A POST /manageInvoice REST operáció kérésének root elementje @@ -1058,20 +1217,28 @@ - - - - Számla lekérdezés adatai - Invoice query data - - - + + - Számla lekérdezési paraméterek - Invoice query parameters + A lekérdezni kívánt lap száma + The queried page count - + + + + Számla lekérdezés adatai + Invoice query data + + + + + Számla lekérdezési paraméterek + Invoice query parameters + + + + diff --git a/src/NavOnlineInvoice/xsd/invoiceData.xsd b/src/NavOnlineInvoice/xsd/invoiceData.xsd index 46196d6..96dd84b 100644 --- a/src/NavOnlineInvoice/xsd/invoiceData.xsd +++ b/src/NavOnlineInvoice/xsd/invoiceData.xsd @@ -1,9 +1,9 @@ - + @@ -32,7 +32,7 @@ Type of bank account number - + @@ -95,7 +95,9 @@ Dátum típus Date type - + + + @@ -1183,8 +1185,8 @@ - Annak jelzése, hogy a módosítás olyan alapszámlára hivatkozik, melyről a módosítás pillanatáig nem történt adatszolgáltatás - Indicates whether the modification references to a not exchanged original invoice + Annak jelzése, hogy a módosítás olyan alapszámlára hivatkozik, amelyről nem történt és nem is fog történni adatszolgáltatás + Indicates whether the modification references to an original invoice which is not and will not be exchanged