Interface: Repeated Transaction

Szerző: Billzone.eu | Létrehozva: 2019. szeptember. 26 | Módosítva: 2021. október. 26

TransactionResult: A tranzakciók eredményét a rendszer TransactionResult típusú objektumban adja vissza, melynek a tulajdonságai a következők:

A TransactionId annak a tranzakciónak az azonosítóját tartalmazza, melyhez a ResultCode tartozik.

Ha a megadott tranzakció azonosítóval korábban már indítottak tranzakciót, akkor a RepeatedTransaction tulajdonsága true lesz. Amennyiben az eredeti tranzakció már befejeződött, úgy annak az eredményét kapjuk, különben a 62024 hibakódot.

A számlabeküldés implementálásakor a válasz feldolgozása során a következő eseteket érdemes megkülönböztetni:

• Bizonytalan esetekben, mikor kommunikációs hiba miatt (pl timeout esetén) nem kapta meg az interfészben specifikált választ, vagy pl hívás közben leállt a hívó process és az eredményt már nem tudta menteni: Ebben az esetben az ismételt kérést úgy kell beküldeni, hogy a korábban beküldött tranzakciós azonosítót használják újra. Az API innen tudja, hogy nem kell új számlát kiállítani, ha az előző kérést már befogadta:

• Ha korábban már befogadta a kérést, és az végre is hajtódott már, akkor visszaadja annak az eredményét (nem jön létre ismételten egy számla; a válaszban RepeatedTransaction=true).
• Ha befogadta, de még nem hajtotta végre a kérést, akkor ezt egy speciális hibakóddal jelzi (62024). Ilyenkor újra kell próbálkozni később, tranzakció azonosítót nem kell változtatni. (nem jön létre ismételten egy számla, sem most, sem a következő ismételt kérésnél, csak az eredeti kérés szerinti; a válaszban RepeatedTransaction=true )
• Ha az API nem fogadta be korábban a kérést, akkor elkezdi a számla kiállítását és visszaadja az eredményét. (mivel korábban még nem fogadta be a kérést, ezért most eredeti kérésként megteszi azt, és létrehozza a számlát; a válaszban RepeatedTransaction=false)

• Bármi egyéb hiba, amit az interfészen specifikáltunk (nagy valószínűséggel valami nálunk nem sikerült, vagy a kéréssel volt a baj): Itt meg lehet különböztetni tranziens és permanens hibákat:
• permanens hiba: minden hiba permanens, aminél nem várható, hogy változatlan adatokkal más eredményt kapunk (pl az összes validációs hibánk ilyen, ha nem változik közben valami adat, akkor nem várható, hogy eltérő választ kapjunk).
• tranziens: minden olyan hiba, ami környezeti hibára utal, pl timeout, vagy ismeretlen hibakódok (a 61002 emiatt tipikusan tranziens hiba), azt tranziens hibaként kell kezelni. Opcionálisan kezelhető külön a permanens hiba, amire a kliens rendszer felhívja a felhasználója figyelmét, hogy itt be kell avatkozzon (nem rögzített vevőt vagy terméket billzone-ban, csak hivatkozott rá, rosszul van beállítva a számlatömb azonosító, stb), amit javítás után kézzel újraküldhet (új tranzakciós azonosítóval). De általánosan igaz, hogy egyértelmű hibakód esetén az ismételt kérésnél új tranzakciós azonosítót kell adni, hogy az API ne az előző eredményét adja vissza, hanem próbálja meg újból kiállítani a számlát.

A fenti esetekkel teljesen lefedhető a retry logika, és kiszámítható módon, csak akkor indul el a számla létrehozás folyamata, amikor a kliens erre először utasítja az API-t. Talán a legegyszerűbb implementálása ennek, ha a megrendelés sorra (vagy amiből a számlát létrehozza) felvesznek egy BillzoneTransactionId-t, ami automatikusan kap egy értéket, és minden beküldésnél ezt a mezőt használja a kliens a tranzakció azonosító kitöltésére. A válasz feldolgozásakor azonban a fenti logikákat figyelembe véve, megfelelő esetekben újragenerálja azt. Így szükség esetén az ismételt beküldéskor már az új tranzakció azonosító lesz a mezőben. Ez működik akkor is, ha valamiért a válasz megjött, csak menteni nem sikerült, mivel változatlan tranzakció azonosítóval fogja a kliens megismételni a kérést és visszakapja RepeatedTransaction-ként az eredeti kérés válaszát.