Hogyan működik a kassza?

Egy webshopban tipikusan így születik a számla: a vevő fizet, a rendszered meghívja a kasszát, a kassza elküldi a kérést a Számlázz.hu Számla Agentnek, az elkészült számla PDF-je visszajön, a vevő pedig e-mailben is megkapja.

Mi történik egy hívás alatt?#

1. Validáció. A kassza még a kérés előtt ellenőrzi a bemenetet: kötelező mezők, ismert áfakulcs, érvényes dátum, a mellékletek száma és mérete. Ha valami hibás, validation kategóriájú SzamlazzError jön, és kérés el sem megy.
2. Kerekítés. Minden tételnél kiszámolja a nettó, áfa és bruttó értéket a hivatalos kerekítési szabályok szerint, így a Számlázz.hu nem utasítja el a számlát 259–264-es hibával.
3. XML összeállítása. A kassza saját, sorrendtartó XML-írót használ, mert az Agent XSD-je kötött elemsorrendet követel. Számlánál az Agent kulcs a <beallitasok> blokkba kerül.
4. Küldés. multipart/form-data POST kérés megy a https://www.szamlazz.hu/szamla/ címre, a művelethez tartozó form mezőben. Ha van tárolt session cookie, a kassza visszaküldi.
5. Válasz értelmezése. A Számlázz.hu hibát jelezhet fejlécben, XML-ben vagy [ERR] szövegben. A kassza mindhármat felismeri, és kódot, kategóriát, magyar tippet ad.
6. Eredmény. Sikernél típusos objektumot kapsz, például CreatedInvoice-t számlaszámmal, összegekkel és a PDF-fel.
7. Értesítés. Ha a vevőnek van e-mail címe, a Számlázz.hu elküldi neki a számlát. Ezt a buyer.sendEmail: false kapcsolja ki.

Újrapróbálás és dupla számla#

A számla létrehozása nem idempotens: ha egy kérés kétszer ér be, két számla készül. Ezért a kassza a számlakészítést soha nem küldi újra magától, a nyugtát pedig csak akkor, ha callId védi a duplikációtól. A lekérdezéseket (PDF, számlaadatok, nyugta, adószám) hálózati hiba, időtúllépés vagy karbantartás esetén alapból háromszor próbálja meg, egyre hosszabb várakozással. A próbálkozások száma a maxAttempts opcióval legfeljebb 5-re emelhető, mert a Számlázz.hu ennél többet nem enged egy kérésre.

Ha egy számlakészítés bizonytalan hibával ér véget, például megszakadt a kapcsolat, a helyes lépés a rendelésszám alapján lekérdezni, hogy elkészült-e:

const letezik = await kassza.invoices.find({ orderNumber: 'REND-1001' })

A részleteket a Hibakezelés, hibakódok oldal írja le.

Következő lépések#