Hogyan működik?
A kapcsolat beállítása két módon történhet:
Publikus kapcsolat esetén: A számlázási fiókban a Fiók Beállítások > Online pénzügyi adatkapcsolat menüpontban a legördülő menüből kiválasztható a kialakítandó pénzügyi adatkapcsolat és paraméterezhető. Ha beállítottad a fogadó rendszert, az azonosító kulcsot és a dátumokat, 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é.
Rejtett kapcsolat esetén: A regisztrációt követően az IT Support csapatunk beállítja számodra a kért kapcsolatot.
🧠 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 az azonosító kulcs megváltoztatása szükséges.
A kapcsolatot a számlázási fiókban a Beállítások > Fiók beállításai > Online pénzügyi adatkapcsolat > Kapcsolatok szekcióban a „Módosítom” gombra kattintva tudod beállítani (az azonosító kulcs megváltoztatását is itt végezheted el).
🌐 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.
Fontos: Az azonosító kulcsot mindig küldjük minden adatcsomaggal a X-Szamlazzhu-Key HTTP fejlécben. Ez alapértelmezett funkció, nem kell külön beállítani. A kulcs konkatenálás (addkeytourl) egy külön, opcionális funkció, ami a kulcsot az URL végére fűzi.
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.
🔗 URL és kulcs kezelés
Hogyan működik az adatküldés?
A Számlázz.hu egyetlen URL-en keresztül küldi el az összes partner adatait a fogadó rendszernek. Ez a megoldás egyszerűbb és hatékonyabb mindkét fél számára.
Mit kell tudnod?
- Egy URL-en fogadhatod az összes ügyfél adatait - nincs szükség külön URL-ekre minden céghez
- A kulcs segít megkülönböztetni - minden adatcsomag tartalmazza az ügyfél azonosító kulcsát
- A szétosztás a te rendszeredben történik - te döntöd el, hogyan kezeled a különböző ügyfelek adatait
Kulcs hozzáfűzési lehetőség
Ha szeretnéd, a kulcsot hozzáfűzhetjük az URL végéhez (addkeytourl beállítás). Ez segíthet a fogadó oldalon a különböző ügyfelek megkülönböztetésében.
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 |
- Csak egy végpontot kell karbantartanod a fogadó oldalon
- Nincs szükség külön URL-ekre minden ügyfélhez
- A kulcs minden adatcsomagban megvan az azonosításhoz
- Rugalmas szétosztás a saját rendszeredben
Elvárt válaszok
Csak olyan végponttal működik megbízhatóan a kapcsolat, amely HTTP 200 (OK) státusszal és a helyes válasz XML-lel tér vissza egyetlen HTTP-válasz törzsében. Nem támogatjuk azokat a végpontokat, amelyek fogadáskor csak HTTP 302 (átirányítás) választ adnak, például a Google Apps Script (vagy hasonló "web appok"). Bővebben: Regisztráció.
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 válasznak az adattípusnak megfelelő XSD-nek kell megfelelnie:
- Kimenő számlák: szamlavalasz.xsd - dokumentáció
- Bejövő számlák: szamlabevalasz.xsd - dokumentáció
- Banki tranzakciók: banktranzvalasz.xsd - dokumentáció
- Nyugták: nyugtavalasz.xsd - dokumentáció
Ehhez négy dolog szükséges:
- A HTTP válasz státuszkódja legyen
200 (OK). - A válasz legyen helyesen formázott XML.
- Kimenő és bejövő számlák esetén: A válaszban kötelező szerepelnie az
<id>mezőnek, és annak egyeznie kell a kapott számla XML-ben érkező<id>értékkel (kimenő/bejövő számlák esetén is:<alap><id>...</id></alap>). Ha nem egyezik, a válasz elutasításra kerül. Részletek: Kimenő számlák – Elvárt válasz, Bejövő számlák – Elvárt válasz. - A válaszban opcionálisan megadható a feladott számla fogadó rendszerben kiosztott iktatószám (számlák esetén).
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.