Merge pull request #1 from pzs/update-v013

Frissítés az Online számla 0.13-as verzióra

README.md

@@ -6,35 +6,35 @@ _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
 
 Technikai felhasználó (és szoftver) adatok beállítása, Reporter példány létrehozása:
 
 ```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
 
 

src/NavOnlineInvoice/BaseExceptionResponse.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace NavOnlineInvoice;
+use Exception;
+
+
+abstract class BaseExceptionResponse extends Exception {
+
+    protected $xml;
+
+
+    function __construct($xml) {
+        $this->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;
+    }
+
+}

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);
         }

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;
-    }
-
 }

src/NavOnlineInvoice/GeneralExceptionResponse.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace NavOnlineInvoice;
+use Exception;
+
+
+class GeneralExceptionResponse extends BaseExceptionResponse {
+
+    public function getResult() {
+        return (array)$this->xml;
+    }
+
+}

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");

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);
     }
 

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;