Általános működés
Ha a számlázási fiókban beállítottad a fogadó rendszert, az azonosító kulcsot és a dátumo(ka)t, akkor a Számlázz.hu “megkezdi” a számla- és/vagy nyugta- és/vagy tranzakcióadatok átküldését a fogadó rendszer felé.
🧠 Adatküldés működése
Az átküldés PUSH jellegű, tehát amikor a Számlázz.hu-ban számlakibocsátás történik, létrejön banki tranzakció vagy nyugta, akkor a Számlázz.hu erről üzenetet küld a fogadó rendszer felé. Nincs lehetőség arra, hogy a fogadó rendszer “lekérdezze” a számlaadatokat.
Az adatok átadása aszinkron módon történik. Az adatküldést a számla kibocsátását követő 15 percen belül hajtja végre a Számlázz.hu. A banki tranzakciókat is kötegelve, időszakonként adjuk át. A nyugtákat szintén kötegelve, viszont naponta csak egyszer küldjük.
🔑 Azonosító kulcs
Az azonosító kulcs a fogadó rendszerben azonosítja az ügyfelet. Érvényes azonosító kulcsot csak a fogadó rendszer adminisztrátora tud adni ügyfeleinek, akik ezt a kulcsot a számlakibocsátó fiókjukban tudják beállítani. A kulcs beállításakor ellenőrizzük a célrendszer-specifikus postfixet, amely gyakorlatban a kulcs utolsó 5 karaktere. Ezt az 5 jegyű azonosítót a célrendszer regisztrációja során paraméterezzük fel a Számlázz.hu rendszerében, és csak olyan kulcsot engedünk az ügyfélnek beállítani, ami ennek megfelel.
Az azonosító kulcs maximális hossza 40 karakter, és minden egyes adatcsomaggal együtt ez is megérkezik a fogadó rendszerhez.
Ha az azonosító kulcs hibás, a fogadó rendszer ezt visszajelzi a Számlázz.hu-nak a válaszüzenetben. Ezt követően megszakítjuk a regisztrációt, és értesítést küldünk a felhasználónak e-mailben. A számlák újbóli elküldéséhez szükséges az azonosító kulcs újbóli megadása.
🌐 Kommunikációs protokoll
Az adatok küldése HTTP vagy HTTPS protokollon történik, és a HTTP/HTTPS kéréssel együtt egy XML fájlt is küld a Számlázz.hu.
Ez az XML fájl tartalmazza a számla/nyugta/tranzakció összes adatát. Egy XML fájl egy számla/nyugta/tranzakció adatait tartalmazza, tehát a fogadó rendszer feladott adatonként egy darab HTTP kérést kap, amely HTTP kérés egy darab XML fájlban egy darab számla/tranzakció részletes adatait tartalmazza. Gyakorlatilag az XML-ben minden rendelkezésre álló számla- és/vagy tranzakcióadatot elküldünk, továbbá igény esetén magát a számla PDF-et is base64 kódolva. A PDF küldés opcionális, a rendszered regisztrációja során kell a Számlázz.hu-ban paraméterezni, hogy a számlák online feladása során szükséges-e a számlaképet is elhelyezni az XML-ben.
A fogadó rendszer felelőssége, hogy ezt a HTTP kérést fogadja, értelmezze és feldolgozza az ebben kapott XML fájlt (a számla adatait). A HTTP kérés POST-os kérés, melynek content-type-ja application/xml, karaterkódolása UTF-8.
A HTTP kérés fejléce X-Szamlazzhu-Key kulccsal tartalmazza azt az azonosító kulcsot, amelyet a számlakibocsátó beállított a számlakibocsátó fiókban (amikor kiválasztotta a fogadó rendszert és aktiválta a számlaadatok átadása szolgáltatást). Ez az a kulcs, amellyel a fogadó rendszer be tudja azonosítani, hogy melyik ügyfele számlakibocsátó fiókjából érkeznek az adatok.
További paraméterezési lehetőségként a Számlázz.hu képes a fogadó URL-t a kulccsal felparaméterezni, vagyis ha a fogadó rendszer úgy várja el, akkor lehetőség van a rendszer szinten beállított URL mögé a cég szinten beállított kulcs értékét hozzáfűzni.
Példa:
| addkeytourl | rendszer URL | key | feladási URL |
|---|---|---|---|
| false | https://ab.cd/ef/ | 3412syste | https://ab.cd/ef/ |
| true | https://ab.cd/ef/ | 3412syste | https://ab.cd/ef/3412syste |
Elvárt válaszok
A Számlázz.hu-nak érzékelnie kell, hogy az általa küldött HTTP kérést a fogadó rendszer “átvette”, értelmezte és kezelte. A számlaválasznak az alábbi XSD-nek kell megfelelnie: https://www.szamlazz.hu/szamla/docs/xsds/szamla/szamlavalasz.xsd
Ehhez három dolog szükséges:
- A HTTP válasz státuszkódja legyen
200 (OK). - A válasz legyen helyesen formázott XML.
- A válaszban a Számlázz.hu kapja meg a feladott számla fogadó rendszerben kiosztott iktatószámát.
Az iktatószámról
A Számlázz.hu lehetővé teszi azt, hogy a fogadó rendszer egy egyedi iktatószámot rendeljen a frissen befogadott számlához. Ezt az iktatószámot a számla első befogadásakor, válaszként kell elküldeni a Számlázz.hu felé. Ha a válaszban érkezik iktatószám, akkor:
- azt a Számlázz.hu eltárolja a számla adatai között (a számla pdf-en nem jelenik meg!)
- a számla ismételt átküldésekor ezt az iktatószámot is elküldjük a számla többi adatával együtt.
Fentebb részleteztük, hogy a számla adatait a Számlázz.hu mindig teljes körűen átküldi a fogadó rendszer felé, továbbá hogy a számla adatai többször is átküldésre kerülhetnek (Számlaküldést indukáló események). A számlaadatok első átküldésekor az iktatószám mindig üres. A számla adatok második (vagy későbbi) átküldésekor az iktatószám mezőben lehet adat attól függően, hogy a korábbi átküldésre válaszul a Számlázz.hu kapott-e iktatószámot a fogadó rendszertől.
Kulcshiba kezelés
Hibás kulcs esetén a válaszban lehetőség van két speciális paramétert küldeni a hibakodTipus-on belül:
KEY_ERR: hibás kulcs. Az átküldött kulcs nem található a fogadó rendszerben, ilyenkor a bizonylatot a következő változásáig nem küldjük újra.
KEY_DEL: törlendő kulcs. Törölni kell az online feladáshoz szükséges információkat a számlázási fiókból. Ezen válasz hatására a fiókgazda e-mailben fog értesülni arról, hogy a fiókjában kikapcsoltuk a fogadó rendszer felé az online kapcsolatot. Mivel a küldés aszinkron, a már feladásra jelölt bizonylatokat átadhatjuk a törlés tényének regisztrálása után is.
Számla első adatfogadása vagy újraküldött számlaadatok fogadása
Számla adatok fogadásakor a fogadó rendszernek teljes (100%-os) biztonsággal el kell döntenie, hogy a fogadott számlaadat:
- egy új számla, ami most először érkezik a fogadó rendszerbe (insert)
- vagy ez a számla korábban már tárolásra került a fogadó rendszerben, és mivel ez egy ismételt (újra) adatküldés, a már letárolt számla adatait kell aktualizálni (update)
Ennek megállapítására NEM javasoljuk az iktatószám mezőt. Tapasztalatok szerint ennek eldöntésére a legmegfelelőbb adat a <szamla> alatt lévő <alap> fürtben lévő <id> adat. Ez az az egyedi adat, amellyel a fogadó rendszerben az átküldött (fogadott) számla egyértelműen beazonosítható.
⚠️ Hibakezelés
A hibás működés részletei
A Számlázz.hu rendszere érzékeli, ha az általa elküldött adatokat (HTTP/HTTPS kérés formájában) a célrendszer nem tudja fogadni, vagy ha nem érkezik helyes XML válasz. Ebben az esetben az adat küldését meghatározott időközönként újra megkíséreljük a fogadó rendszerbe eljuttatni. Ha 72 órán belül a külső rendszer nem képes fogadni a számlát, nyugtát vagy tranzakciót, akkor az adott tétel kikerül a küldési sorból, és nem próbáljuk többé újraküldeni. Ezáltal ún. "parkolópályára" kerül.
Ha egy fogadó rendszer hosszabb ideig helytelen választ ad, lelassul, vagy egyáltalán nem válaszol, akkor ezeket a fogadó rendszereket inaktiváljuk. Az adatkapcsolatot azonban nem bontjuk meg a beállított számlázási fiókoknál; inkább leállítjuk az adatátvitelt végző háttérfolyamatot.
A rendszer újbóli aktiválása manuálisan történik. A fogadó rendszer adminisztrátorának értesítenie kell minket, ha a hibát elhárították, hogy az adatáramlás folytatódhasson.
A fogadó rendszerrel szemben támasztott követelmények
A fogadó rendszernek fel kell készülnie arra, hogy a Számlázz.hu rendszerétől HTTP/HTTPS kérés érkezik hozzá. A pontos URL-t a Regisztráció oldalon leírt regisztrációs folyamat során kell beállítani. Ha az adott URL-re az adatküldés sikertelen, akkor az előző fejezetben leírtak szerint járunk el.
Ha a fogadó rendszer hosszabb ideig nem fogadja be szabályosan a küldött adatokat, vagy a befogadás lassú, vagy hibát kapunk vissza, akkor az adatküldő háttérfolyamat megszakad, a rendszer kikerül az adatátadásból. A küldést visszakapcsolni ügyféljelzésre a Számlázz.hu IT support tudja.