Munkameneti süti (session cookie)
A Számla Agent működése olyan módon van optimalizálva, hogy a session cookie-k kezelése, azaz a munkameneti sütik tárolása és a hívások során történő használat biztosítása a hívó fél (pl. webáruház) felelőssége. Általában a webáruházak szerver-kliens architektúrát alkalmaznak, ahol a kliens oldalon csak a böngésző fut, mint "vékony kliens". Minden más feldolgozási folyamat a szerveren történik. Amikor a webáruház számlát szeretne kiállítani, akkor egy hívást kezdeményez a Számla Agent felé. Fontos, hogy az Agent a webáruházat egyetlen "felhasználóként" lássa, ebből kifolyólag minden hívás során ugyanazt a felhasználói hitelesítést alkalmazza.
A folyamat részleteiben
1. Első hívás a számla Agent felé: Ha a küldő fél (pl. webáruház) nem tartalmaz session cookie-t, az első XML fájl küldésekor az Agent érzékeli ezt, és létrehoz egy új session-t (generál egy session cookie-t) és megkezdi az XML fájl feldolgozását.
2. Első válasz: A kérésben szereplő válaszverziótól függően megérkezik a válasz: pl. PDF a válasz törzsében, valamint adatok a válasz fejlécében, például a munkameneti süti (JSESSIONID). Fontos, hogy mind a PDF fájlt, mind a sütit elmentsd.
3. Második hívás az Agent felé: Újra elküldöd az XML-t, ezúttal a kérés fejlécébe beillesztve az előzőleg kapott munkameneti sütit.
4. Második válasz: A válasz törzsében ismét PDF érkezik, és ugyanazt a munkameneti sütit kapod vissza, így nincs további teendő.
Ezután a 3. és 4. lépések ismétlődnek. Amennyiben 90 percig inaktív a session, a Számlázz.hu törli azt. Ekkor a következő hívásnál új session cookie generálódik.
Javasolt működési eljárás
1. XML fájl és a session cookie szükséges a Számla Agent híváshoz: Ha nincs cookie fájl, az Agent létrehoz egyet, amit a válaszban visszaküld. Amennyiben van cookie fájl, azt a hívás során használjuk fel.
2. Válasz kezelése: A beérkező válaszban lévő PDF/XML fájlt el kell menteni. A válaszban érkező munkameneti sütit is érdemes fájlba menteni. A meglévő süti fájl felülírható, mivel a webáruház a Számlázz.hu szemszögéből egy felhasználónak minősül (az API kulccsal hitelesítve).
Amennyiben a munkameneti sütik nem kerülnek a szerveren eltárolásra, az Agent minden kérésnél új sütit hoz létre és végig megy a hitelesítési folyamaton. Ez a folyamat többlet időráfordítást igényel. Bár néhány számla kezelésénél ennek hatása csekély lehet, ha a számlázási kérések száma eléri az ezres vagy tízezres nagyságrendet, az időbeli veszteség már jelentős lehet. Emiatt erősen ajánlott a session cookie-k tárolása és újrahasznosítása azokban a rendszerekben, amelyek nagy mennyiségben küldenek számlagenerálási kérést a Számla Agent felé.
Amennyiben változás történik a Számlázz.hu fiókadataiban, például a cégadatok vagy az e-mail cím módosul, javasolt egy új session cookie generálása. Ez azért szükséges, mert a változások csak így lépnek érvénybe.
Következő lépések
- Kérések küldése: az XML kérések felépítése és elküldése
- Hitelesítés: Agent kulcs beállítása
- Hibakezelés: a kérések során felmerülő hibák kezelése