Hibakezelés, hibakódok
Ha egy Számla Agent kérés sikertelen (pl. nem készül el a számla vagy a nyugta), az ok általában a kérés adataiban vagy paramétereiben van. Ugyanazzal a kéréssel történő ismételt próbálkozás nem oldja meg a problémát.
Ne próbálkozz újra ciklusban
Ne úgy programozd a rendszert, hogy sikertelen kéréseket automatikusan újra és újra elküldi, amíg sikerül. Volt olyan eset, amikor éjszaka több tízezer felesleges kérés érkezett, és túlterhelte a szervert. Ha egy kérés sikertelen, javítsd a kérést (vagy várj az ügyfélszolgálat/felelős intézkedésére), és csak ezután küldj új, javított kérést.
Tesztkörnyezet: maximum 500 számla 10 percenként
A tesztelési fázis során ne generálj több mint 500 számlát 10 percen belül a tesztkörnyezetben. A tesztfiók létrehozásáról és használatáról (a felhasználó be- és kikapcsolhatja) a tudástárban találsz részleteket.
Próbálkozási limit
Legfeljebb 5 próbálkozás egy kérésre
Ugyanazt a kérést a Számla Agentnek legfeljebb ötször küldheted el. Ha mind az öt próbálkozás sikertelen, állj meg, és vedd fel a kapcsolatot az üzlet felelősével (vagy a megfelelő felelőssel). Addig ne foglalkozz a számlával/nyugtával, amíg emberi beavatkozással meg nem oldódik a hiba.
A Számla Agent nem vállal felelősséget, ha a számla vagy nyugta nem készülhetett el. A szabályok ismételt megsértése (pl. túlzott újrapróbálkozás vagy indokolatlan szerverterhelés) kitiltáshoz vezethet.
Szöveges hibaüzenet formátuma
Ha a <valaszVerzio> értéke 1 (vagy nincs megadva), hiba esetén a válasz törzse szöveges üzenet, nem XML. A formátum:
[ERR] Hibaüzenet szövege. ---------- t.getMessage(): Hibaüzenet szövege.
---------- [CEG:NNN] [MODUL:...] [INSTANCE:...] részletek [LOCATION:...]
OsztályNév.metódus(Fájl.java:sor)
...
java.lang.Thread.run(Thread.java:662)
A fontos rész az [ERR] és a ------------ közötti szöveg. A többi figyelmen kívül hagyható.
Ezzel a formátummal érintett műveletek: számla készítés, sztornó számla készítés, jóváírás rögzítése, bizonylat lekérése PDF-ben.
Hibakódok és üzenetek
A válaszban kapott kódot az alábbi táblázatból meg tudod nézni, és ennek megfelelően módosítani a kérést vagy a folyamatot. Az első oszlopban a hibakód, a másodikban a válaszban kapott üzenet (magyarul), a harmadikban a leírás.
| Hibakód | Hibaüzenet | Leírás |
|---|---|---|
1 | Rendszerkarbantartás, kérem próbálja meg pár perc múlva. | Belső, tervezett karbantartás vagy hiba a Számla Agent-ben. Ebben az esetben a webshop részéről nincs szükség intézkedésre, a Számlázz.hu karbantartó csapata már dolgozik az ügyön. |
3 | Sikertelen bejelentkezés | A felhasználónév vagy jelszó nem megfelelő. |
53 | Hiányzó XML fájl. | Az XML nem fájlként lett elküldve, hanem feltételezhetően HTML bemeneti tartalomként, tehát a rendszer nem kapott értelmezhető XML fájlt a küldő féltől. |
54 | E-számla készítés nincs engedélyezve. | Az elektronikus számla kibocsátása nem engedélyezett. A felhasználóhoz tartozó előfizetési csomag valószínűleg nem tartalmazza, vagy nincs saját tanúsítvány feltöltve. Ebben az esetben el kell fogadni, hogy a KBOSS.hu Kft. saját tanúsítványt használhat a számlákhoz. |
55 | E-számla aláírása sikertelen. | Az elektronikus számla aláírása meghiúsult. A tanúsítvány lejárt vagy az időbélyegző szerverhez nem lehetett kapcsolódni. |
57 | XML beolvasási hiba. | Hibás a küldött XML fájl. A válasz törzse további információkat tartalmaz. Az XSD-validáláson elbukó XML is ezt a kódot kaphatja, lásd Kérések küldése / XML-validálás és elgépelt mezőnevek. |
71 | Már létező rendelésszám. Az ismétlődés engedélyezhető a Beállítások oldalon. | A rendelésszám már létezik. A fiókban be van kapcsolva a „Rendelésszám ismétlődés tiltása” beállítás, és azonos típusú bizonylaton már szerepel ez a rendelésszám. Lásd a Számla létrehozás / Rendelésszám és duplikáció-ellenőrzés oldalt. |
135 | Számla Agent futtatásához kérjük böngészőkében lépjen ki a Számlázz.hu rendszerből | Ha egy böngészőablakban be vagy jelentkezve a Számlázz.hu-ba, és egy másikban teszteled az XML-t, például egy teszt HTML fájllal vagy curl POST kéréssel, akkor ez a Számlázz.hu rendszerében hibákat okozhat. |
136 | Bejelentkezési hiba ... Kérjük lépjen be a Számlázz.hu rendszerébe böngészőn keresztül. | Valamiért nem tudod használni a Számla Agentet. Lehetséges okok: az előfizetés lejárt; van egy függőben lévő számlád a Számlázz.hu felé; késés van a fizetésben. Ilyen esetekben jelentkezz be a Számlázz.hu rendszerbe, és ellenőrizd az előfizetésedet a Szolgáltatáscsomagom menüpontban. |
152 | Már létező rendelésszám: XXX. Az ismétlődés engedélyezhető a Beállítások oldalon. | Ugyanaz, mint a 71-es hiba, de az üzenet a duplikált rendelésszámot is tartalmazza. Lásd a Számla létrehozás / Rendelésszám és duplikáció-ellenőrzés oldalt. |
164 | Ezt a funkciót csak olyan felhasználó veheti igénybe, aki egyetlen Számlázz.hu-s fiókhoz férhet hozzá. Több fiókhoz történő hozzáférés kizárja a funkció használatát. | Az adott felhasználó több számlázási fiókhoz is hozzáfér, így ez a funkció nem használható. Érdemes ebben az esetben Agent kulcsot generálni (Hitelesítés (API kulcs) oldal) és azzal végrehajtani az authentikációt. |
202 | A megadott számlaszám előtag nem megfelelő. Agent használat során, csak a Számlázz.hu rendszerében korábban regisztrált előtagokat lehet használni. | A kérésben szereplő <szamlaszamElotag> mező üres, vagy olyan előtagot tartalmaz, ami nincs rögzítve a számlázási fiókban. A használható előtagok a Számlázz.hu felületén a Beállítások / Előtagok menüpontban láthatóak. |
259 | A tétel nettó értéke nem megfelelő; nettó érték = nettó egységár x mennyiség. Termék: ... | A tétel nettó értéke helytelen; <nettoErtek> = <nettoEgysegar> * <mennyiseg>. A válasz szövegtörzse a hibás tétel nevét tartalmazza a "Termék" szó után. |
260 | A tétel áfa értéke nem megfelelő; áfa érték = tétel nettó értéke x áfakulcs mértéke / 100. Termék: ** | A tétel ÁFA értéke helytelen; <afaErtek> = <nettoErtek> * <afakulcs> / 100. A válasz szövegtörzse a hibás termék nevét tartalmazza a "Termék" szó után. |
261 | A tétel bruttó értéke nem megfelelő; bruttó érték = tétel nettó értéke + tétel áfa értéke. Termék: ** | A tétel bruttó értéke helytelen; <bruttoErtek> = <nettoErtek> + <afaErtek>. A válasz szövegtörzse a hibás termék nevét tartalmazza a "Termék" szó után. Forintos nyugtán ez az ellenőrzés pontos egyezést követel, lásd a Tételösszegek és kerekítés oldalt. |
262 | A tétel nettó értéke nem megfelelő; nettó érték = nettó egységár x mennyiség. Termék: ** | A tétel nettó értéke helytelen; <nettoErtek> = <nettoEgysegar> * <mennyiseg>. A válasz szövegtörzse a hibás termék nevét tartalmazza a "Termék" szó után. |
263 | A tétel áfa értéke nem megfelelő; áfa érték = tétel nettó értéke x áfakulcs mértéke / 100. Termék: ** | A tétel ÁFA értéke helytelen; <afaErtek> = <nettoErtek> * <afakulcs> / 100. A válasz szövegtörzse a hibás tétel sorszámát tartalmazza a "Termék" szó után. |
264 | A tétel bruttó értéke nem megfelelő; bruttó érték = tétel nettó értéke + tétel áfa értéke. Termék: ** | A tétel bruttó értéke helytelen; <bruttoErtek> = <nettoErtek> + <afaErtek>. A válasz szövegtörzse a hibás tétel sorszámát tartalmazza a "Termék" szó után. |
363 | A tétel bruttó értékének egész számnak kell lennie. Termék: ** | Csak nyugtánál: forintos nyugtán a tétel bruttó értéke (<brutto>) csak egész szám lehet. Lásd a Tételösszegek és kerekítés oldalt. |
364 | A tétel nettó értéke maximum 2 tizedes jegyet tartalmazhat. Termék: ** | Csak nyugtánál: forintos nyugtán a tétel nettó értéke (<netto>) legfeljebb 2 tizedesjegyet tartalmazhat. Lásd a Tételösszegek és kerekítés oldalt. |
365 | A tétel áfa értéke maximum 2 tizedes jegyet tartalmazhat. Termék: ** | Csak nyugtánál: forintos nyugtán a tétel áfa értéke (<afa>) legfeljebb 2 tizedesjegyet tartalmazhat. Lásd a Tételösszegek és kerekítés oldalt. |
537 | Agent-en maximálisan 400 törlőkód adható egy tételhez. | Egy tételhez kérhető adattörlő kódok számának maximumát elérted. A hibaüzenet mindig megadja a maximális számot. |
538 | Adattörlő kód demo-ban és tesztfiókban nem használható. | Az adattörlő kód nem használható demo és tesztfiókban. |
539 | Nincs bekapcsolva az adattörlőkód használata a beállítások menüben | Az adattörlő kód használata nincs bekapcsolva a beállításokban. A számlázási beállítások menüben kapcsold be az adattörlő kódot. |
551 | Egyszerűsített számlakép bekapcsolt OSS és nem magyar adószám esetén nem használható. | Az egyszerűsített számlakép nem használható, ha a fiókban be van kapcsolva az OSS (közösségi) adózás, vagy az eladó adószáma nem magyar. Ilyen esetben minden simpleItems=true Agent-kérés ezzel a hibával hasal el. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
552 | Egyszerűsített számlakép esetén maximum két tétel adható meg | Egyszerűsített számlaképpel (simpleItems=true) legfeljebb két tétel szerepelhet a bizonylaton; kivétel a végszámla, ahol a mínuszos tételek miatt legfeljebb négy tétel lehet (2 mínuszos + 2 új). Ez az ellenőrzés az áfakulcs-ellenőrzés előtt fut le. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
553 | Egyszerűsített számlakép esetén érvénytelen adókulcs. | Érvénytelen áfakulcs egyszerűsített számlakép mellett. Csak magyar áfakulcs használható: 0, 5, 18, 27, TAM, AAM, K.AFA, F.AFA. Már egyetlen érvénytelen áfakódú tétel is a teljes bizonylat elutasítását okozza. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
554 | Egyszerűsített számlaképet használó számlát nem lehet helyesbíteni. | Egyszerűsített számlaképpel kiállított számla nem helyesbíthető, akkor sem, ha a helyesbítő kérés nem tartalmazza a simpleItems mezőt. Ilyen számlára az egyetlen negatív irányú bizonylat a sztornó. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
555 | Egyszerűsített számlakép esetén a tételek áfakulcsai nem különbözhetnek | Egyszerűsített számlaképű végszámlán a tételek áfakulcsainak egyezniük kell az előlegszámláéval; a tételek sorrendje nem számít. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
556 | Egyszerűsített számlaképet szállítólevél és helyesbítő számla esetén nem lehet használni | Az egyszerűsített számlakép szállítólevélre és helyesbítő számlára nem használható. Lásd az Egyszerűsített tételadatok utazásszervezőknek oldalt. |
Következő lépések
- Munkameneti süti: a session kezelés működése és fontossága
- Kérések küldése: kérések helyes felépítése a hibák elkerüléséhez
- Hitelesítés: Agent kulcs beállítása