A működés részletei
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é.
Push jellegű működés
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.
Az azonosító kulcs hibája esetén a fogadó rendszer képes ezt a Számlázz.hu felé jelezni a válaszüzenetben. Ennek hatására bontjuk a regisztrációt, és egy e-mailt küldünk a felhasználónak. A számlák újraküldését az azonosító kulcs újbóli megadásával lehet kezdeményezni.
Protokoll és formátum
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 |
Átadott bizonylattípusok
A következő típusú (kimenő) bizonylatokat a Számlázz.hu átadja a fogadó rendszer felé:
- számlák
- sztornó számlák
- helyesbítő számlák
- előlegszámlák
- végszámlák
- díjbekérők
- szállítólevelek
Ha a fogadó rendszernek valamelyik bizonylattípusra nincs szüksége, akkor az <alap> tagen belüli <tipus> tag alapján szűrhet.
Számlaküldést indukáló események
A Számlázz.hu egy kibocsátott számlát többször is átküldhet a fogadó rendszer felé. Minden egyes átküldés során átadja a kérdéses számla összes (aktuális) adatát (XML formában). A következő események indukálják azt, hogy a számla (először vagy ismételten) elküldésre kerül a fogadó rendszer felé:
- számla kibocsátása
- számla kifizetettségi állapotának megváltozása
- számla utólag módosítható adatainak változása, nevezetesen:
- könyvelés dátuma
- vevő főkönyvi szám
- vevő főkönyvi azonosító
- számla „folyamatos teljesítés” állapot
- bármely számlatétel árbevétel főkönyvi száma
- bármely számlatétel áfa főkönyvi száma
- bármely számlatétel gazdasági eseménye
- bármely számlatétel áfa gazdasági esemény
- bármely számlatétel elszámolási időszakának kezdete
- bármely számlatétel elszámolási időszakának vége
Ezek az adatok a számla adatlapján módosíthatók.
Kimenő számla feladás
A kimenő számlák feladása XML formátumban történik, és az alábbi XSD-nek felel meg: https://www.szamlazz.hu/szamla/docs/xsds/szamla/szamla.xsd
Elvárt válasz
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.
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.
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.
Fizetési módok kezelése
A Számlázz.hu-ban kézi számlakészítéskor vagy jóváírások adminisztrálása során fix értékkészletből választható a fizetés módja, de a Számla Agenttel készített számlákon a küldő rendszer tetszőleges stringet adhat át a fizetés módjaként. Emiatt a számlák online feladásakor a fizetési módot kétféleképpen küldjük az XML-ben:
- A
<fizmod>tag tartalmazza a fizetési módként tárolt tetszőleges értékű stringet (gyakorlatilag ez a fizetési mód szerepel a számlán). - A
<fizmodunified>tag pedig ennek normalizált értéke. Az értékkészlet: átutalás, készpénz, bankkártya, csekk, utánvét, ajándékutalvány, barion, barter, csoportos beszedés, OTP Simple, kompenzáció, kupon, PayPal, PayU, SZÉP kártya, utalvány, egyéb. Ha a<fizmod>értéke ezek valamelyikéhez nem rendelhető hozzá egyértelműen, akkor az érték “egyéb” lesz. Az értékek az XSD-ben is megtalálhatóak. - A
<keszpenz>értéke true, ha készpénzes a fizetés, egyébként false.
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ó.
Mi történik akkor, ha díjbekérő alapján történik számlakibocsátás?
- Ilyenkor a frissen kibocsátott számlát elküldjük a fogadó rendszer felé, de a díjbekérőt nem küldjük újra.
- A frissen kibocsátott számla az
<alap><hivdijbekszam>tagben tartalmazza majd a díjbekérő számlaszámát. A díjbekérő iktatószámát viszont nem tartalmazza. - A díjbekérő attól függően törlődik, hogy a beállítások között mi szerepel (Beállítások/Fiók beállításai).
- Díjbekérő törléséről a Számlázz.hu semmilyen üzenetet nem küld a fogadó rendszer felé.