sERPa súgó

Ablak kicsinyítése
Nagyobb betűk | Kisebb betűk
Oldalfejléc elrejtése
Részletek megjelenítése
Oldal nyomtatása
Visszajelzés e-mailben
Oldal megosztása
Oldal címének mentése

Navigáció: Pénzügy > Vevő > Napi folyamatok > Online számla adatszolgáltatás (OSA)

Online számla 2.0 változások

Általános módosítások

Korábbi két darab XSD (invoiceApi és invoiceData) szétválasztásra került. 2.0-ban a technikai érvénytelenítés (korábbi adatsolgáltatás érvényesítése) adatait az invoiceAnnulment XSD tartalmazza. Az invoiceData XSD-ben a korábbi választás eltűnik.

Bevezetésre kerül egy új XSD, invoiceMetrics XSD, amely a szolgáltatás működési metrikáit tartalmazza. Jelenleg nem aktív, később lesz dokumentálva.

Minden sémában új namespace kerül bevezetésre: http://schemas.nav.gov.hu/OSA/2.0/ (jelenleg a lap nem elérhető)

Eltérő verziók közötti általános összefüggések

Új főverzióhoz minden esetben új URL-ek és az új XML namespace tartozik. A kisverziók öröklik annak a főverziónak az URL és namespace adatait, amelynek a részét képezik. Az átállási idő alatt az XML API két eltérő verziója is egymás mellett működik, így azok között összefüggést biztosítottak, amelyek a következők:

•Az egyes főverziók tokenjei között nincs átjárás. (pl. létező 1.x-es tokennel nem lehet 2.x-es számla adatot beküldeni és fordítva sem)

•Minden beküldött /manageInvoice és /manageAnnulment kérés feldolgozási státuszát minimum a beküldéshez tartozó requestVersion értékű lekérdezéssel lehet csak lekérdezni, alacsonyabbal sosem. (pl. 1.1-es /manageInvoice feldolgozási státusza lekérdezhető 2.0-ás lekérdezéssel, fordítva viszont nem)

•Minden sikeresen befogadott számla lekérdezhető teljes adattartalmában, ha a lekérdezés requestVersion értéke azonos az aktuálisan támogatott főverzió értékével. Az egyes főverziók között viszont alulról nincs átjárás, az alacsonyabb verziók csak a saját beküldéseiket kereshetik. (pl. 2.x-es lekérdezések rálátnak teljes körően az 1.x és 2.x-es számla adatokra is, míg az 1.x-es lekérdezések csak a saját 1.0-ás és 1.1-es adataikat látják

•Minden alapszámlához csak olyan módosító vagy stornó számláról szóló adatszolgáltatás fűzhető, amelynek a requestVersion értéke minimum azonos az alapszámla requestVersion értékével, alacsonyabbal sosem. (pl. 1.1-es alapszámlához beküldhető 2.0-ás stornó adatszolgáltatás, fordítva viszont nem

API XSD általános módosítások

1.Minden request és response saját komplex típust kapott

2.Minden requestben kötelező a software adatok megadása a sémában definiált mezőkkel

3.Minden requestben változik a requestSignature számításának módja.

Request signature számítása

Számítás manageInvoice és manageAnnulment operáció esetén

A requestSignature alapját manageInvoice és manageAnnulment operáció esetén a requestSignature egy parciális hitelesítésből, illetve 1-100 közötti index hash értékek összefűzéséből és további SHA3512 hash műveletből számítódik. A parciális hitelesítést következő értékek összefűzéséből lehet megállapítani:

•a requestId értéke

•a timestamp tag értéke YYYYMMDDhhmmss maszkkal, UTC időben

•a technikai felhasználó aláíró kulcsának literál értéke

Az összefűzéskor a timestamp maszkoláshoz ki kell venni a dátum-és időpont szeparátorokat, valamint az időzónát.

Az index hash értékeket az egyes indexek alatt álló operation és base64 tartalom összefűzését követő nagybetűs SHA3-512 hash értékéből lehet megállapítani:

•invoiceOperation vagy annulmentOperation literál értéke

•az invoiceData vagy invoiceAnnulment tagban található base64 tartalom

A kiszámított index hash-eket a parciális hash mögé kell fűzni az indexek által leírt sorrendben. Az ily módon és sorrendben konkatenált string nagybetűs SHA3-512 hash eredménye lesz a requestSignature értéke.

Számítás manageInvoice és manageAnnulment operáción kívül

A manageInvoice és manageAnnulment operáció kivételével minden más operációban – mivel ezekben nem merül fel a adatbeküldés – a requestSignature egyenlő a parciális hitelesítés SHA3-512 hash értékével, amelyet a következő értékek összefűzéséből lehet megállapítani:

•a requestId értéke

•a timestamp tag értéke yyyyMMddHHmmss maszkkal, UTC időben - a technikai felhasználó aláíró kulcsának literál értéke

Az ily módon és sorrendben konkatenált string nagybetűs SHA3-512 hash eredménye lesz a requestSignature értéke.

API XSD operációk módosításai

1.Bevezetésre került a /manageAnnulment operáció. A kérésben van lehetőség technikai érvénytelenítést beküldeni, tehát a 2.0-ban a technikai érvénytelenítést már nem a /manageOperáció alatt kell beküldeni. 1.9.1 fejezet

2.A /manageInvoice operáció típusából törlésre került a korábbi technicalAnnulment boolean, valamint külön típust kapott az operáció, melynek megadható értékei csak CREATE, MODIFY, STORNO

3.3) A korábbi heterogén /queryInvoiceData lekérdező operáció szétválasztásra került három részre:

a. /queryInvoiceCheck, amely számlaszám alapján csak a számla létezését ellenőrzi, a számla adatainak visszaadása nélkül

b./queryInvoiceDigest, amely paraméteres számla lekédezési lehetőséget biztosít, és lapozható válaszban csak a számlák meghatározott üzleti adatait (kivonatát) adja vissza

c.a szétválasztás után a /queryInvoiceData operációnak egyetlen felelősségi köre marad, hogy számlaszám alapján a számla teljes adattartalmát lekérdezhetővé tegye

d.mind a három lekérdezés használható kiállítói és vevői oldalról is, a részletekről lásd a megfelelő operációk leírásait az 1.9.3, 1.9.4 és 1.9.5 fejezetekben

4.Az interfész szolgáltatásai között megjelent a /queryServiceMetrics operáció, amely a rendszer és a számla fogadó szolgáltatás üzleti metrikáit teszi lekérdezhetővé. A szolgáltatás jelenleg nem aktív, a későbbiekben kerül megnyitásra és dokumentálásra.

5.A számlák feldolgozási státuszát visszaadó /queryInvoiceStatus operáció átnevezésre került /queryTransactionStatus névre. A szolgáltatás tranzakció azonosító alapján képes technikai érvénytelenítéseket tartalmazó tranzakció esetén visszaadni a jóváhagyás státuszát és egyéb üzleti adatait. Ezen felül a válaszban visszaadott pointer tag kiegészítésre került az originaInvoiceNumber taggal, ami MODIFY és STORNO adatszolgáltatás esetén lesz töltve.

6.Az adószám lekérdezésre használt /queryTaxpayer operáció válasza létező adószám lekérdezésekor tartalmazza az adózó rövid nevét és az adózó ÁFA csoport tagságát, ha volt ilyen. A belső címadatok nem saját típusból, hanem a data sémaleíró DetailedAddressType típusából öröklődnek.

7.A rövid név jelenleg még nem kerül töltésre egy hiányzó adatkapcsolati fejlesztés miatt. Amint a fejlesztés megvalósul, külön hírt tesznek közzé a rövid név elérhetőségéről.

Törölt szinkron hibaüzenetek

•INVALID_OPERATION

•BAD_QUERY_PARAM

Új szinkron hibaüzenetek, hibák okai, teendők

1.MULTIPLE_QUERY_RESULT_FOUND - 17

1.1.Hiba oka: a keresett számlaszám többször szerepel érvényesként a rendszerben

1.2.Teendő: A hibaüzenet a /queryInvoiceData és /queryInvoiceCheck operációkban adható vissza akkor, ha a lekérdezett számlaszám többször érvényesként szerepel a rendszerben. Ebben az esetben a számlaszámot technikailag érvényteleníteni kell, majd a jóváhagyást követően az adatszolgáltatást meg kell ismételni a helyes adatokkal.

2.BAD_QUERY_PARAM_OVERLAP – 18

2.1.Hiba oka: dátumátfedés a lekérdező paraméterekben

2.2.Teendő: A hibaüzenet a /queryInvoiceDigest operációban adható vissza akkor, ha a kötelező keresőparaméterek (invoiceIssueDate vagy insDate) dátumai átfedik egymást. A paraméterek között legfeljebb egyenlőség engedélyezett. Javítani kell!

3.BAD_QUERY_PARAM_RANGE_EXCEEDED – 19

3.1.Hiba oka: túl nagy lekérdezési intervallum

3.2.Teendő: A hibaüzenet a /queryInvoiceDigest operációban adható vissza akkor, ha a kötelező keresőparaméterek (invoiceIssueDate vagy insDate) dátumai közötti távolság nagyobb, mint 35 nap. Szűkíteni kell a keresett intervallumot.

4.BAD_QUERRY_PARAM_EQ_NOT_DTANDALONE – 20

4.1.Hiba oka: egyenlőségre történő keresés nem önmagában áll

4.2.Teendő: A hibaüzenet a /queryInvoiceDigest operációban adható vissza akkor, ha a relációs kereső paraméterek között valamelyik csomópont kétszer van megképezve, és a kettő közül az egyikben az EQ keresőfeltétel szerepel. Az EQ kereső operator adott csomóponton csak önmagában állhat, javítani kell!

5.BAD_QUERRY_PARAM_OPERATOR_COLLOSION -21

5.1.Hiba oka: hibás intervallum meghatározás a lekérdezésben

5.2.Teendő: A hibaüzenet a /queryInvoiceDigest operációban adható vissza akkor, ha a relációs kereső paraméterek között valamelyik csomópont kétszer van megképezve, és a keresőfeltételek nyitott intervallumot határoznak meg (pl: GT és GT, vagy LT és LTE kereső operátorok állnak párban) Az intervallumos keresésnél a keresőoperátorok közül az egyiknek GT vagy GTE, míg a másiknak LT vagy LTE értéket kell adni.

6.BAD_QUERRY_PARAM_SUPPLIER_NOT_EXPECTED -22

6.1.Hiba oka: kiállítóként kereséskor nem szabad a kiállító adószámára szűrni

6.2.Teendő: A hibaüzenet mindhárom számla lekérdező operációban visszaadható akkor, ha a keresést számlaszám megadásával végezzük, a keresés kiállítóként történik és a kiállítói adószámra szűrés ki van töltve. A kérésből törölni kell a supplierTaxNumber taget!

7.BAD_QUERRY_PARAM_SUPPLIER_EXPECTED -23

7.1.Hiba oka: vevői kereséskor többértelmű eredményhalmaz, szűrni kell a kiállító adószámára

7.2.Teendő: A hibaüzenet mindhárom számla lekérdező operációban visszaadható akkor, ha a keresést számlaszám megadásával végezzük, a keresés vevőként történik és a keresett számlaszámot több kiállító is kiállította ugyan azon vevő részére. A kérésben meg kell adni a supplierTaxNumber taget. A szűrésre használható adószámok listáját a /queryInvoiceDigest operációból lehet megállapítani.

Mindegyik üzenetre igaz, hogy:

•http válasz: http 400 BAD_REQUEST

•Response body: GeneralErrorResponse XML tag

•funcCode: Error

CREATE adattartalom változásai

Az invoiceData séma változásai

•a számla legfelső szintjére kiemelésre került a számla sorszáma és a kiállításának dátuma

•a lineExpressionIndicator tag kötelezővé vált, default értéke false a többi boolean mezőben összhangban

•a PostalCodeType új patternt kapott, a bevitt érték kötelező hossza 4-ről 3-ra csökkent és elfogadott a szóköz és a kötőjel is, amennyiben a stringben nem kezdő vagy záró pozíción áll

•a lineDescription tag 512 hosszú lett

•ProductCodeCategoryType új enummal bővült (TESZOR), a maximális hossza 6-ra változott

•a productCodeOwnValue tag 255 hosszú lett

•a számlafejben a számla további üzleti adatait leíró korábbi invoiceData csomópont átnevezésre került invoiceDetail névre

•az invoiceDeliveryDate tag kötelezővé vált

•új tartalomként bekerült a számla üzleti adatai közé a kisadózó jelzése (smallBusinessIndicator) és az időszakos elszámolás (periodicalSettlement) jelzése

•új tartalomként opcionális elemként bekerült a számlasorok adatai közé a termék/szolgáltatás minősítésére használható lineNatureIndicator, a kitöltési útmutatóról szóló segédlethez ld: 2.3.17

•új tartalomként a normál és egyszerűsített számlasorok, valamint a normál és egyszerűsített számláknál használt számla összesítők is kiegészítésre kerültek azon monetáris kifejezések párjával, amelyek eddig vagy csak a számla pénznemében, vagy csak forintban voltak kifejezve, a módosítást követően minden monetáris kifejezésnek létezik a számla pénznemében és forintban is kifejezett összege a következők szerint:

oegységár forintban (line/unitPriceHUF)

otétel nettó összege forintban (invoiceLines/line/lineAmountsNormal/lineNetAmountData/lineNetAmountHUF)

otétel bruttó összege forintban (invoiceLines/line/lineAmountsNormal/lineGrossAmountData/lineGrossAmountNor malHUF)

otétel bruttó összege forintban (invoiceLines/line/lineAmountsSimplified/lineGrossAmountSimplifiedHUF)

oszámla bruttó összege forintban (invoiceSummary/summaryGrossData/invoiceGrossAmountHUF)

oszámla nettó összege forintban (invoiceSummary/summaryNormal/invoiceNetAmountHUF)

oszámla adótartalom bruttó összege forintban (invoiceSummary/summarySimplified/vatContentGrossAmountHUF)

oadómérték nettó összege forintban (invoiceSummary/summaryNormal/summaryByVatRate/vatRateNetData/vatRateNet AmountHUF)

oadómérték bruttó összege forintban (invoiceSummary/summaryNormal/summaryByVatRate/vatRateGrossData/vatRateG rossAmountHUF)

oExchangeRateType definiciójában a <xs:minInclusive value="0"/> <xs:minExclusive value="0"/>-ra változott, ezért oda az átháritott áfa/áfaösszesen kerül vagy ha ez nincs akkor 1. (132 verziótól)

MODIFY és STORNÓ adattartalom változásai

•Megszűnnek a korábbi modificationIssueDate, modificationTimestamp és lastModificationReference elemek.

•A módosító okirat kiállítási dátumát a számla kiállítási dátumát tartalmazó invoiceIssueDate elemben kell közölni ugyan úgy, ahogy számla esetében is.

•Plusz elemként megjelenik a modificationIndex, amely a módosítás logikai sorrendjét írja le a számlának. A részletszabályokról ld: 2.2.1 fejezet.

Technikai érvénytelenítés új indoka

A számla kiállítási dátumának kiemelésével logikailag módosíthatatlanná vált az invoiceIssueDate tag értéke. A technikai jellegű helyesbítéshez a technikai érvénytelenítés okát leíró annulmentCode új enummal, az ERRATIC_INVOICE_ISSUE_DATE értékkel bővült