NAV M2M hibakódok és eredménykódok

Azonosítás

A hívás azon a ponton állt meg, ahol a NAV azt állapítja meg, ki a küldő és kinek a nevében jár el. Az üzleti tartalom feldolgozása ilyenkor még el sem kezdődik.

• Érvényes-e a hozzáférési token. A NAV dokumentációja szerint a token biztonsági okból korlátozott érvényességű.
• Teljes-e az aláíró kulcs. Két részből áll össze: az egyik felét az API Key tartalmazza, a másikat a nonce beváltása adja vissza. Elmaradt vagy megismételt beváltás esetén az aláírás hibás lesz.
• A nonce egyszer használatos, újrafelhasználásra a specifikáció szerint nem alkalmas.
• Az aláírás a releváns üzleti tartalom alapján képződik. Ha a tartalom az aláírás után módosult, az aláírás nem fog egyezni.
• A beküldő és az adózó két külön fogalom: az egyik azt azonosítja, ki hívja a szolgáltatást, a másik azt, kinek a nevében.

Jogosultság

Az azonosítás sikeres volt, de a művelethez vagy az adott adózóhoz nincs jogosultság. Ez jogosultsági, nem fejlesztési kérdés.

• A NAV használati feltétele szerint a kliensprogram felhasználójának megfelelő képviseleti jogosultsággal kell rendelkeznie arra az adózóra, akinek a nevében műveletet végez.
• A jogosultság bizonylattípusonként eltérhet: az egyik típus beküldésére szóló jogosultság nem terjed ki a másikra.
• Könyvelőirodánál ez ügyfelenként külön beállítás, nem egyszeri lépés.
• Ha a válasz-tárhely azonosítója nem engedélyezett, a beküldés jogosultsági feltételei teljesülhetnek — ilyenkor a válasz célhelyét kell tisztázni.

Adat és séma

A beküldött állomány szerkezete vagy tartalma nem felel meg annak, amit a bizonylat adott verziója elvár.

• A bizonylattípus és a bizonylatverzió együtt azonosít. A helyes típus téves verzióval ugyanúgy elutasításra kerül.
• Az új formátumú bizonylatok a NAV szerint bizonylatonként egyedi XSD-vel rendelkeznek. A séma a nyomtatvány repositoryból szerezhető be, típus- és verziószinten.
• A validáció és a kalkuláció XPATH-okat tartalmazó XSLT-k futtatásán alapul, és a specifikáció szerint a kliens gépén is elvégezhető. Beküldés előtt érdemes lefuttatni.
• Karakter- és kódolási hiba esetén elsőként az állomány karakterkódolását célszerű ellenőrizni, nem a tartalmát.

Fájl és csatolmány

Az állomány vagy a csatolmány kezelése akadt el: a mérete, a tömörítése, az ellenőrzőösszege vagy az azonosítója miatt.

• A fájlazonosító egyszer használatos: felhasználás után ugyanazzal az azonosítóval nem lehet újra hivatkozni.
• Az ellenőrzőösszeg-hiba jellemzően azt jelzi, hogy a feltöltött tartalom eltér attól, amiről a hash készült. Ilyenkor a feltöltési lépést érdemes megismételni.
• A csatolmányok a NAV fogalomkészlete szerint részbizonylatonként kapcsolódnak a bizonylathoz. Ha a csatolmány nem található, elsőként ezt a hozzárendelést érdemes ellenőrizni.
• Vírusjelzés esetén az állomány a beküldő oldalán nem javítható: új, ellenőrzött fájlt kell előállítani.

Nincs találat

A hívás technikailag rendben volt, de a lekérdezett körre nincs adat. Ez sok esetben nem hiba, hanem érvényes válasz.

• Érdemes ellenőrizni a lekérdezett időszakot: elképzelhető, hogy arra az időszakra nem keletkezett adat.
• A lekérdezés-azonosító és az ügyazonosító külön életciklusú. Lejárt vagy hibásan megadott azonosító ugyanígy adat nélküli választ eredményez.
• Az integráció ne kezelje hibaként. A felhasználó számára ez azt jelenti, hogy nincs ilyen tétel — nem azt, hogy a szolgáltatás meghibásodott.

Folyamatban

A művelet elindult, de még nem zárult le. Ezek nem hibák, hanem köztes állapotok.

• A bizonylat a specifikáció szerint több állapoton halad át — előellenőrzés, ellenőrzés, beküldés —, ezért a végeredményt lekérdezéssel kell bevárni.
• A lekérdezés üteme legyen mértéktartó: a NAV forgalomkorlátozást alkalmaz, és a túl sűrű hívás önmagában hibát okoz.
• A köztes állapotot érdemes a felhasználó felé is megjeleníteni, különben megismétli a beküldést.

Sikeres

A művelet lefutott. Bizonylat beküldésénél a sikeres válasz mellett az érkeztetési szám is megérkezik.

• A sikeres séma- és előellenőrzés nem azonos a bevallás tartalmi helyességével: a formai megfelelés nem adózási jóváhagyás.
• Az érkeztetési számot érdemes eltárolni, mert utólag ez azonosítja a beküldést.

Egyéb

Gyűjtőkategória. A specifikáció maga is fenntart általános hibakódot, és ide tartoznak a forgalmi korlátok, valamint a nem támogatott lekérdezések.

• Az általános hibakód nem ad diagnózist. A kérés adatait és a válasz azonosítóit érdemes naplózni, mert támogatási megkeresésnél ezek jelentik a kiindulópontot.
• Az üzenetazonosítót és a korrelációs azonosítót a specifikáció külön fejlécmezőként kezeli. Naplózásuk nélkül egy hiba utólag nem visszakereshető.
• Forgalomkorlátozás esetén nem a kérés tartalma hibás, hanem a hívások üteme.

Hivatalos NAV-lista ez?

A kódlista a NAV M2M OpenAPI-leírásaiból készült, és minden kódnál feltüntetjük, melyik enumban szerepel, így a forrásnál ellenőrizhető. A csoportosítás és az ellenőrzési szempontok szerkesztői kiegészítések, mert a NAV az OpenAPI-ban nem közöl kódonkénti magyarázatot.

Miért nem szerepel minden kódhoz külön magyarázat?

Mert hivatalos forrás nélkül az feltételezés volna. Ahol a NAV nem közöl értelmezést, ott mi sem közlünk: a kódokat ok szerint csoportosítjuk, és a csoporthoz adunk ellenőrzési szempontokat.

Ezek eÁFA-hibakódok?

Nem. Ezek a NAV M2M interfész eredménykódjai. Az eÁFA M2M külön csatorna, saját sémával és saját hibakészlettel. Az eÁFA XML séma szerinti ellenőrzéséhez az ingyenes XML-ellenőrzőnk használható.

Frissül a lista?

A NAV nyilvános tárhelyén verziózott OpenAPI-fájlok találhatók. Új verzió megjelenésekor a listát újrageneráljuk, és az oldal minden esetben feltünteti, mely specifikációverziókból készült.