Ezt a cikket utoljára ezen a napon módosítottuk: 2022.11.16. Mindent megteszünk, hogy naprakész információt szolgáltassunk oldalunkon, de előfordulhatnak elavult információk korábbi bejegyzéseinkben. Ha elavult információt találsz, kérjük, hogy jelezd ügyfélszolgálatunknak. Köszönjük!
Figyelem! A Bárhol Számla szolgáltatás 2023. január 31-gyel megszűnik!
A fejlesztők köszönik az eddigi bizalmat, és remélik minden ügyfél hamarosan megtalálja a megfelelő alteranítv megoldást.
Az üzleti teendők automatizálása kulcsfontosságú a hatékony ügyvitel szempontjából. Az egyik ilyen tennivaló a számlázás, ami még akkor is időigényes, ha online számlázunk, amennyiben ezt emberi beavatkozással, kézzel csináljuk. Ennek kiküszöbölésére nyújt kézenfekvő megoldást a Számla Agent API azáltal, hogy direkt hozzáférést biztosít az adatokhoz külső szoftvereknek, például webshopmotoroknak vagy digitális ügyviteli rendszereknek.
Ebben a cikkben Go programozási nyelven mutatunk egy megoldást az automatizált számlázásra a sixhz.com/szamlazzhu csomag segítségével.
Nézzük meg egy minta-webshophoz kapcsolódó számlázási lépések implementálását egy általános online értékesítési folyamat mentén, hogy kézzelfogható, ugyanakkor átfogó képet kapjatok az Agent API használatáról!
A Számla Agent API közelebbről
Egy programozó természetesen mindenből tud írni saját verziót, nem kivétel ez alól a számlázás sem. Van azonban egy “kis” bökkenő. A számlázásra és számlázó programokra szigorú jogszabályok vonatkoznak. Nézzük meg a legfontosabb dolgokat, amelyekre figyelnünk kell:
- a számla formai követelményeire, kötelező adattartalmára
- a NAV online számlaadat-szolgáltatási kötelezettség teljesítésére
- a számviteli bizonylatok archiválási szabályaira
- a számlázóprogram dokumentációjára vonatkozó előírásokra
A Számla Agentet használva a Számlázz.hu megoldja helyettünk a számlázó programokra vonatkozó előírások betartását, miközben nekünk csak utasítanunk kell egy API-hívással a Számlázz.hu rendszerét, hogy készítse el a számlát helyettünk. Végeredményben ugyanolyan könnyen és gyorsan készülnek a számlák, mintha magunknak írtunk volna programot, miközben a munka és a fejlesztés nehezét a Számlázz.hu végzi. A Számla Agent API-hoz természetesen részletes leírás tartozik, angol nyelven. Az API HTTP alapú, és bármilyen programozási nyelvből használható.
Példa az alkalmazásra: webshop integráció
Tegyük fel, hogy online értékesítünk – mondjuk almát. A webshopunkban lehet rendelést leadni, amit online vagy utánvéttel tud kifizetni a vevő. Eddig a Számlázz.hu webes felületét használtuk számlázásra kézzel, de mostantól szeretnénk a webshopot összekötni az Agent API-val, Go nyelven, a sixhz.com/szamlazzhu csomag segítségével. Az alábbi funkciókat kell integrálnunk az értékesítési folyamatba:
- Számla kibocsátása: új rendelés esetén a számla elkészítése.
- Számladokumentum lekérése: számla letöltése pdf formátumban nyomtatáshoz vagy e-mail csatolmányhoz.
- Befizetések kezelése: sikeres online kártyás fizetés esetén a kártyás tranzakciót összerendelni a számlával a könyvelés egyszerűsítéséhez.
- Sztornózás: ha az ügyfél visszamondja a rendelést.
API autentikáció
Első lépésként egy Számla Agent kulcsra van szükség, amivel a Számlázz.hu rendszere azonosít minket, így biztonságosan állíthatunk ki számlát a saját fiókunkból. Ilyen Agent kulcsot bejelentkezés után, a kezdőoldal alján, a kulcs ikonnal tudunk generálni.
Több API kulcsot is kérhetünk, ezért IT biztonsági okokból javasolt minden integrációhoz külön-külön kulcsot igényelni, például több webshop esetén minden áruházhoz egyet.
Számla kiállítása
Az Agent kulcs birtokában kedvenc Go programozói környezetünkben egyszerűen tudunk számlát kiállítani programozott módon. Az alábbi példa bemutatja azt az esetet, amikor a mintawebshopba beérkezik egy rendelés, amit a vevő kártyával fizet:
A fenti példa esetén a számla azért nem lesz automatikusan fizetettnek jelölve (Xmlszamla.Fizetve), mert a mintawebshopunkban ezt csak akkor szeretnénk megtenni, ha a vevő sikeresen fizetett bankkártyával (lásd lejjebb). Az elkészült számlák láthatóak lesznek a Számlázz.hu felületén, ahol ugyanúgy tudjuk kezelni őket, mint a webes felületen kiállított számlákat.
Befizetések kezelése
Amennyiben a vevő sikeresen ki is fizette a megrendelést, az Agent API-val tudjuk ezt rögzíteni a számla fizetési jegyzékében (“Befizetések”). Az xmlszamlakifiz.Additiv mezővel lehet megadni, hogy az API-hívás kiegészítse vagy felülírja a meglévő befizetéseket, ami különösen rugalmassá teszi az adminisztrációt.
Számla nyomtatása
A fizetés kezelése után ha ki szeretnénk nyomtatni a számlát vagy e-mail csatolmányként továbbítani az ügyfélnek (pl. a rendelés visszaigazolásával együtt), akkor az Agent API-val könnyen le tudjuk kérni a számlát pdf formátumban:
Sztornózás
Alkalmanként szükség lehet egy-egy számla sztornózására (pl. lemondott megrendelés esetén):
Az Agent API sztornózása idempotens, ezért a fenti kódot akárhányszor meghívhatjuk, egy számlához csak egy sztornó számla fog készülni.
Összegzés és tippek
Ahogy a példáinkból is látszik, a Számlázz.hu Agent API teljes értékű integrációt biztosít egy webshop vagy akár más külső szoftver számára. Alkalmazási területtől függően képes akár A4 méretben vagy keskeny (szalagnyomtató) formátumban is számlázni. Az elkészült számlák láthatóak a Számlázz.hu felületén is, de az Agent API segítségével is teljeskörűen kezelhetjük őket. Letölthetjük a kész számlákat pdf formátumban, elküldhetjük őket e-mailben, kezelhetjük a fizetési állapotukat, sztornózhatjuk is őket. Sőt, az Agent segítségével olyasmit is elvégezhetünk, amit a Számlázz.hu felületén nem: például nyugtákat készíthetünk, aminek részleteit egy következő cikkben mutatjuk majd be.
