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 response - pl. tartalmaz PDF-et a response body-ban, valamint adatokat a response header-ben, például a session cookie-t (jelölve: JSESSIONID). Fontos, hogy mind a PDF fájlt, mind a session cookie-t elmentsük.
3. Második hívás az Agent felé: Újra elküldjük az XML-t, ezúttal a kérés header-jébe beillesztjük az előzőleg kapott session cookie-t is.
4. Második válasz: A response body-ban ismét PDF érkezik, és ugyanazt a session cookie-t kapjuk vissza, így nincs szükség további tennivalóra.
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ő cookie-t is érdemes fájlba menteni. A meglévő cookie 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 authentikálva).
Amennyiben a session cookie-k nem kerülnek a szerveren eltárolásra, az Agent minden kérésnél új session cookie-t hoz létre és végig megy az authentikálá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.