A kérés beküldése után: különböző esetek és a megbízó teendői
Ez az oldal azt írja le, mi történik a beküldött action-agent_ceg_mb kéréssel, és mi kell ahhoz, hogy a kapcsolat éljen:
- mi történik a csatlakozási kérelem beküldését követően - a lehetséges esetek attól függően, hogy létezik-e már fiók a megadott adószámmal,
- a megbízó teendői: aktiválás és jóváhagyás - mit kell tennie a megbízónak, és mi történik addig,
- és a válasz és a hibakezelés - hogyan érkezik a válasz, és melyek a hívás leggyakoribb hibái.
A kérés összeállítása: A kérés és az XML felépítése; a folyamat áttekintése: Kapcsolat kialakítása API-val.
Mi történik a csatlakozási kérelem beküldését követően?
Ugyanaz az XML kérés eltérően fut le attól függően, hogy létezik-e már fiók a megadott adószámmal (<cegtaxnumber>):
| Eset | Viselkedés | Válasz (XML_AGENT_RESPONSE) |
|---|---|---|
| Nincs fiók ezzel az adószámmal | Új megbízói fiók jön létre, és fiókgazdai meghívó e-mail megy a <cegemail> címre. | DONE |
| Létező fiók, de még nincs fiókgazdája | Nem jön létre új fiók; a fiókgazdai meghívó e-mail újraküldésre kerül. | „Már létező fiók, nincs fiókgazdája. Fiókgazdai meghívó (megbízott számlakibocsátás) email újraküldve." |
Létező fiók fiókgazdával, és ugyanerre a <usremail>-re már van függő kérelem | A meglévő csatlakozási kérelem e-mail újraküldésre kerül a fiókgazdának. | „Már létező fiók fiókgazdával. A csatlakozási kérelem emailt újraküldtük a fiókgazdának." |
| Létező fiók fiókgazdával, nincs függő kérelem ehhez a felhasználóhoz | Új csatlakozási kérelem jön létre (a <cegszamlaszamelotag>-ban megadott előtaggal), és a fiókgazda e-mail értesítést kap. | „Már létező fiók fiókgazdával. Csatlakozási kérelmet küldtünk a fiókgazdának." |
A már létező fiókkal kapcsolatos esetek részletes leírása és a kapcsolódó hibakódok: Hibakezelés - már létező fiók a megadott adószámmal.
A <cegMb> blokkból a rendszer ilyenkor csak az adószámot (a fiók azonosításához) és a számlaszám előtagot (a kérelem részeként) használja; a cégnév, a cím, a bankszámlaszám, az e-mail címek és a többi mező a meglévő fiókban változatlan marad. A <usrMb> blokknál: ha a megadott <usremail> felhasználó már létezik a rendszerben, a csatlakozási kérelem ehhez a meglévő felhasználóhoz jön létre (a küldött jelszó és név nem módosítja); ha még nem létezik, a rendszer létrehozza.
A megbízotti és a megbízói fiók teszt/éles kombinációit (mikor készül tesztbizonylat, és mikor keletkezik díj) az általános áttekintő Költségviselés szakaszának táblázata foglalja össze.
A megbízó teendői: aktiválás és jóváhagyás
A beküldött kérés után a folyamat a megbízó oldalán folytatódik:
- Új fióknál a fiók nem lesz azonnal számlázásra kész: a Számlázz.hu a
<cegemail>címre aktiváló levelet küld, és a megbízónak birtokba kell vennie a fiókot, aktiválnia, majd engedélyeznie a megbízotti számlázást. - Meglévő fióknál a megbízó fiókgazdája e-mail értesítést kap a kérelemről, és a vezérlőpultján fogadja el (vagy utasítja el) azt. Az elfogadáshoz nem kötelező az e-mailben érkező link: ha a fiókgazda belép a számlázási fiókjába, a függő kérelmet a vezérlőpulton is látja, és ott is elfogadhatja. Ha a fiókgazda elutasítja a kérelmet, a megbízott erről e-mail értesítést kap; a kérelem lezárul, de később új kérelem küldhető - akár ugyanannak az XML kérésnek az újraküldésével.
- Ha a kérés tartalmazott egyeztetett számlaszám-előtagot (
<cegszamlaszamelotag>), elfogadáskor létrejön az ahhoz tartozó számlatömb, a megbízotthoz kötve. Ha az előtag ütközne egy, a megbízó adószámával már használt előtaggal, az elfogadás meghiúsul, és a megbízott e-mail értesítést kap; lásd: Előtagkezelés. - Amikor ez megtörtént, a megbízott visszaigazoló e-mailt kap, hogy a fiók készen áll.
A jóváhagyás után a <usrMb> dedikált felhasználó „megbízott számlakibocsátó" szerepkört kap a megbízó fiókjában (számlázói jogosultságokkal): ezzel a felhasználóval küldhetők a számlakiállítási Agent hívások a megbízó fiókjába, és ugyanezzel be lehet lépni a webes felületre is (ott csak a saját maga által kiállított bizonylatokat látja).
A kapcsolat csak a megbízó jóváhagyása után él. Addig a <usrMb> felhasználóval a belépési és számlázási próbálkozások így hiúsulnak meg:
- Új, még birtokba nem vett fióknál a hívás 250-es hibával áll le: „Ez a fiók nem használható, mert a fiókgazda még nem regisztrált. Üzenetet küldtünk a fiókgazdának, hogy vegye birtokba a fiókját (e-mail cím)." - a rendszer ilyenkor automatikusan újra kiküldi a fiókgazdai meghívót.
- Meglévő fióknál, amíg a fiókgazda nem fogadta el a kérelmet, a felhasználó nem fér hozzá a megbízó fiókjához, így a hívás 3-as (sikertelen bejelentkezés) hibával áll le.
A kapcsolat állapotához nincs külön státusz-lekérdező API. A jóváhagyásról a megbízott e-mail visszaigazolást kap; programozottan a hívások eredményéből tudod követni az állapotot: amíg a <usrMb> felhasználóval indított hívás a fenti 250-es vagy 3-as hibával tér vissza, a kapcsolat még nem él - az első sikeres hívás jelzi, hogy a megbízó jóváhagyta a kapcsolatot.
Ha az aktiváló / értesítő levél elveszett, két lehetőséged van: küldd be újra ugyanazt az XML kérést (a rendszer ilyenkor újraküldi a fiókgazdai meghívót, illetve a függő csatlakozási kérelmet - lásd a fenti táblázatot), vagy jelentkezz be egyszer a <usrMb> felhasználóval - a belépés a fenti 250-es hibával sikertelen lesz, de újraindítja a fiókgazdai meghívó e-mailt.
Válasz és hibakezelés
Sikeres hívásnál az eredmény az XML_AGENT_RESPONSE HTTP válasz headerben érkezik (pl. XML_AGENT_RESPONSE=DONE). Hiba esetén a hiba a szlahu_error és szlahu_error_code headerekben jön vissza, mint a többi Agent hívásnál; lásd: Hibakezelés.
A hívás leggyakoribb hibái:
| Kód | Mikor fordul elő |
|---|---|
| 3 | Sikertelen bejelentkezés; a bejelentkező felhasználónak pontosan egy fiókhoz kell tartoznia |
| 7 | Hiányzó kötelező adat, pl. hiányzó <cegszamlaszamelotag> (számlaszám előtag) vagy hiányzó bejelentkezési adat |
| 68 | Már létezik cég ezzel az adószámmal és számlaszám előtaggal |
| 101 | Csak új megbízói fiók létrehozásakor: a <usremail> bejelentkezési név már foglalt. Meglévő fiókhoz való csatlakozásnál ez nem hiba - a rendszer a meglévő felhasználóhoz hozza létre a kérelmet (részletek a fenti információs blokkban). |
| 137 | A fiókodnak nincs engedélye ehhez az interfészhez. A pontos üzenet: „Jelenleg nincs jogosultsága ahhoz, hogy ilyen módon hozzon létre számlázási fiókot. Ha mégis szeretne, vegye fel a kapcsolatot ügyfélszolgálatunkkal (szamlazz.hu/kapcsolat)" - engedélyt az ügyfélszolgálaton tudsz kérni |
| 309 | Érvénytelen adat, pl. hibás formátumú adószám. Az adószámot beküldés előtt automatikusan ellenőrizheted a Számla Agent adószám-lekérdezés interfészével: először kérdezd le az adószámot, és csak sikeres ellenőrzés után indítsd rá a csatlakozási kérést. |
| 337 | A számlaszám előtag formátuma hibás. A pontos üzenet: „Az előtag csak nagybetűket és számokat tartalmazhat, és hossza legfeljebb 5 karakter lehet." |
A teljes lista, pontos üzenetekkel és teendőkkel: Hibakezelés.
Következő lépések
Ha a megbízó jóváhagyta a kapcsolatot, indulhat a számlázás a megbízó fiókjában: Számlakiállítás megbízottként.