Mi a Billingo API, és kinek szól
Egy átlagos webáruház havonta több száz számlát állít ki, és mindegyik mögött ugyanaz a néhány adat áll: vevő, tétel, ár, áfakulcs. Ha ezt kézzel másolja valaki a rendelésből a számlázóba, előbb-utóbb hibázik.
A Billingo API erre a problémára ad programozott megoldást.
A Billingo API egy REST API, amelyen keresztül a saját rendszered közvetlenül éri el a Billingo számlázási funkcióit. Számlát, proforma számlát és sztornószámlát hozhatsz létre, partner- és termékadatokat kezelhetsz, PDF-et tölthetsz le, és e-mailben kiküldheted a bizonylatot.
A kiállított számlák a Billingón keresztül a NAV online számla adatszolgáltatás részévé válnak, így a megfelelőség technikai oldalát nem neked kell nulláról felépítened.
A tipikus használati esetek jól körülhatárolhatók:
Webáruház, amely sikeres fizetés után azonnal számlát állít ki. Mobilapp, amely havi előfizetési díjakat számláz automatikusan.
CRM vagy ERP, amelynek partneradatai szinkronban kell maradjanak a számlázóval. És belső vállalatirányítási rendszerek, ahol a számlázás csak egy lépés egy hosszabb üzleti folyamatban.
A legtöbb online anyag megáll egy-két végpont bemutatásánál.
Ez a cikk mást ad: egy teljes tervezési, fejlesztési és élesítési folyamatot, a hitelesítéstől a duplikációk megelőzésén át a sztornó kezeléséig.
Mert egy működő API-hívás még nem megbízható integráció.
Egy számla létrehozása öt perc alatt megvan. Az, hogy a rendszer egy hálózati hiba után se állítson ki kétszer számlát ugyanarra a rendelésre, már tervezési kérdés.
Kinek szól az útmutató? Magyar fejlesztőknek, akik most kezdenek Billingo-integrációba, digitális ügynökségeknek, akik ügyfélprojektekbe építik be a számlázást, és cégtulajdonosoknak, akik webshopot, appot vagy belső rendszert kötnének össze a számlázással, és szeretnék érteni, mit kérnek a fejlesztőtől.
A Billingo API v3 alapjai
Meglepően sok fejlesztő kezd hibás dokumentáció alapján.
A keresőkben még 2026-ban is előkerülnek régi, v2-re írt blogbejegyzések és kódrészletek, amelyek a jelenlegi API-val egyszerűen nem működnek.
Ezért mielőtt egyetlen sort írnál, érdemes tisztázni, pontosan melyik verzióval dolgozol.
A Billingo API v3 a jelenleg támogatott verzió. JSON formátumban kommunikál, szabványos HTTP-metódusokat (GET, POST, PUT, DELETE) használ, és erőforrás-alapú végpontokra épül: dokumentumok, partnerek, termékek, számlatömbök, bankszámlák.
Hogyan működik a hitelesítés
Az első lépés egy API-kulcs generálása. Ezt a Billingo fiókodban, a beállítások között található API menüpontban hozhatod létre.
A kulcs egyszer jelenik meg teljes formájában, ezért azonnal mentsd el egy biztonságos titokkezelőbe.
A v3 hitelesítése egyszerűbb, mint sokan gondolják.
Nincs szükség külön tokenkérésre vagy aláírt JWT-re: minden kérés fejlécében az X-API-KEY fejléc tartalmazza a kulcsot, például így: X-API-KEY: a_te_kulcsod.
A Billingo minden kérésnél ezt ellenőrzi, és ha hiányzik vagy érvénytelen, 401-es választ ad.
Gyakori hiba, hogy valaki a megszokott Authorization: Bearer formátumot használja, mert más API-knál így tanulta.
A v3-nál ez nem működik.
A kulcs gyakorlatilag egy hosszú élettartamú, statikus titok, amely addig érvényes, amíg te vissza nem vonod vagy újra nem generálod.
Pontosan ezért kell úgy bánni vele, mint egy adatbázis-jelszóval.
V2 és v3 közötti különbségek
A v2 API elavult.
Más végpontstruktúrát használt, és a hitelesítés is eltért: a régi verzió nyilvános és titkos kulcspárral, időbélyeggel aláírt JWT tokenekkel dolgozott.
Ez több mozgó alkatrészt jelentett, és gyakran okozott időszinkron-problémákat.
A gyakorlati szabály egyszerű.
Ha egy kódrészletben JWT-generálást, public/private key párt vagy a régi végpontneveket látod, az v2-es forrás, és nem érdemes rá támaszkodni.
Új fejlesztést kizárólag v3-ra építs, meglévő v2-es integrációnál pedig tervezz migrációt, mert az elavult verzió támogatása nem garantált.
Dokumentáció és támogatott nyelvek
A hivatalos v3 dokumentáció OpenAPI dokumentáció (Swagger) formátumban érhető el. Ez nemcsak olvasnivaló: a leírásból kliens kódot generálhatsz, és pontosan láthatod minden mező típusát, kötelezőségét és megengedett értékeit.
Miért érdemes mindig ott ellenőrizni a végpontokat? Mert a mezők és enumerációk (például fizetési módok, dokumentumtípusok) időnként bővülnek.
Egy két évvel ezelőtti blogbejegyzés nem fogja tudni, mi változott azóta.
PHP, Node.js, Python, Java, C# vagy bármilyen HTTP-kliens használható. Hivatalos SDK nem minden nyelvhez létezik, de az OpenAPI leírásból generált kliens vagy egy vékony, saját HTTP-réteg a legtöbb projektben elég.
Ez utóbbi előnye, hogy a hibakezelést és naplózást teljesen te irányítod.
A számlázási folyamat lépésről lépésre
A legtöbb hibás integráció ott csúszik el, hogy a számlázást egyetlen API-hívásnak tekinti. Valójában ez egy folyamat, amelynek minden lépése elbukhat, és mindegyiknél tudnod kell, mi történik utána.
Íme a teljes workflow egy tipikus webshop-integráció esetén:
- Fizetési esemény fogadása. A folyamat a fizetési szolgáltató (például Barion, SimplePay vagy Stripe) webhookjával indul. A webhook és eseménykezelés során ellenőrizd az esemény aláírását, és csak megerősített sikeres fizetésre indíts számlázást.
- Belső számlázási rekord létrehozása. Mielőtt bármit küldenél a Billingónak, rögzítsd a saját adatbázisodban a rendelésazonosítót “függőben” státusszal. Ez lesz a duplikáció elleni védelem alapja.
- Partner keresése vagy létrehozása. A partner API segítségével keress rá a vevőre adószám (cégeknél) vagy e-mail-cím alapján. Ha nincs találat, hozd létre, és a kapott partnerazonosítót mentsd el a saját rendszeredben, hogy legközelebb ne kelljen újra keresni.
- Tételek normalizálása. Minden rendelési tételt alakíts át egységes formára: SKU vagy cikkszám, mennyiség, mértékegység, nettó egységár, áfakulcs. Ha a termék API-ban már létezik a termék, hivatkozz rá, ha nem, add át a tételt közvetlenül a számlán.
- Számla létrehozása. A dokumentum végponton küldj egy JSON kérést a partnerazonosítóval, a számlatömb azonosítójával, a teljesítési és fizetési határidővel, a fizetési móddal, a pénznemmel és a tételekkel. A válaszban kapott dokumentumazonosítót azonnal mentsd el.
- PDF és e-mail kiküldés. A létrehozott számlát letöltheted PDF-ként, vagy a Billingóval kiküldetheted a vevőnek. Ezt külön lépésként kezeld, mert a számla létrejöhet akkor is, ha az e-mail-küldés elbukik.
- Státusz lezárása. Állítsd a belső rekordot “kiállítva” állapotra, és rögzítsd a Billingo dokumentumazonosítót és a számlaszámot. Hiba esetén “hiba” státusz és a teljes hibaüzenet kerüljön a naplóba.

A partner- és termékadatok konzisztenciája többet számít, mint gondolnád.
Az adószám formátuma (12345678-1-42 vagy 12345678142), az irányítószám, a cím tagolása, az EAN-kód és a cikkszám mind eltérhet a különböző forrásrendszerekben.
Ha ezeket nem egységesíted az API-hívás előtt, duplikált partnerek és 422-es validációs hibák lesznek a vége.
Tesztfiók és sandbox használata
Az első kérdés mindig ugyanaz: hol tesztelek úgy, hogy ne állítsak ki véletlenül valódi számlát?
A biztonságos megoldás egy különálló tesztfiók, saját API-kulccsal, amelyet soha nem keversz az éles fiókkal.
A sandbox tesztelés korlátait viszont előre érdemes tisztázni.
- Amit nyugodtan kipróbálhatsz. Hitelesítést, partner- és termékkezelést, számlatömbök lekérdezését, a JSON struktúra validálását, valamint a hibaágakat (szándékosan hibás adószám, hiányzó mező, érvénytelen kulcs).
- Amit tesztkörnyezetben nem tudsz teljesen szimulálni. A valós NAV-adatszolgáltatás teljes útját, a valódi adózói adatokkal futó ellenőrzéseket és az éles könyvelési következményeket.
- Amire figyelj. Ha a tesztfiók valós cégadatokhoz kapcsolódik, az ott kiállított számlák is valódi bizonylatok lehetnek. Tesztelés előtt tisztázd a könyvelőddel és a fiókbeállításokkal, mi számít próbának és mi nem.
Felkészülés az éles indulásra
Az élesítés napja nem a fejlesztés vége, hanem a legkockázatosabb pillanata.
Az alábbi checklist a leggyakoribb meglepetéseket szűri ki:
- Számlatömb beállítása. Ellenőrizd, hogy az éles fiókban létezik a megfelelő számlatömb, és a kódban az éles azonosító szerepel, nem a tesztfiókbeli.
- Adózási adatok ellenőrzése. Cégnév, adószám, székhely, áfakulcsok és alanyi adómentesség esetén a megfelelő jogcím: ezeket egyeztesd a könyvelővel.
- Automatikus e-mail-küldés tesztelése. Küldj ki egy valódi számlát egy belső címre, és nézd meg, hogyan jelenik meg a levél, a tárgy és a PDF.
- Rollback folyamat megtervezése. Döntsd el előre, mi történik, ha az integráció hibásan működik: ki kapcsolja ki, hogyan áll vissza a kézi számlázás, és ki sztornózza a hibás bizonylatokat.
Biztonság, hibakezelés és duplikációk

Egy kiszivárgott Billingo API-kulccsal bárki számlát állíthat ki a cégед nevében.
Ez nem elméleti kockázat: a publikus GitHub-repókba véletlenül feltöltött kulcsokat automatizált botok percek alatt megtalálják.
A biztonság és a hibakezelés ezért az integráció alapja, nem utólagos finomítás.
A HTTP státuszkódok a hibakeresés első támpontjai. A leggyakoribb hibák és a diagnosztikai lépések:
- 401 Unauthorized: hiányzó vagy hibás kulcs. Ellenőrizd, hogy a fejléc neve pontosan X-API-KEY, nincs-e szóköz vagy sortörés a kulcs végén, és hogy a kulcsot nem generálták-e újra időközben a fiókban.
- 402 Payment Required: előfizetési korlát. A fiók csomagja nem tartalmazza az API-hozzáférést, vagy lejárt az előfizetés. Ilyenkor nem a kód hibás, hanem a fiók állapota, ezt az adminisztrátornak kell rendeznie.
- 403 Forbidden: jogosultsági probléma. A kulcs érvényes, de az adott művelethez vagy erőforráshoz nincs hozzáférés. Nézd meg, a megfelelő fiókhoz tartozó kulcsot használod-e, és létezik-e az a számlatömb vagy partner, amelyre hivatkozol.
- 422 Unprocessable Entity: validációs hiba az átküldött adatban. A válasz törzse megmondja, melyik mező a hibás: naplózd a teljes választ, ne csak a státuszkódot. Tipikus okok a hiányzó kötelező mező, az érvénytelen adószám-formátum vagy a nem támogatott áfakulcs.
- 429 és 5xx hibák, időtúllépés: túl sok kérés vagy átmeneti szerverhiba. Ezeknél van értelme az újrapróbálkozásnak, exponenciálisan növekvő várakozással, de csak akkor, ha a duplikáció elleni védelem már működik.
API-kulcs tárolása biztonságosan
A szabály rövid: az API-kulcs kizárólag szerveroldalon létezhet. A szerveroldali hitelesítés nem opcionális, mert minden más megoldás kiteszi a kulcsot a nyilvánosságnak.
- Soha ne kerüljön mobilappba. Egy lefordított Android- vagy iOS-alkalmazásból a beégetett kulcs visszafejthető. Az app a saját backendedet hívja, és a backend beszél a Billingóval.
- Soha ne kerüljön frontend JavaScriptbe. Ami a böngészőben fut, azt a böngésző fejlesztői eszközeivel bárki láthatja.
- Soha ne kerüljön repóba. Használj környezeti változót vagy titokkezelőt (például AWS Secrets Manager, HashiCorp Vault, Doppler), és add hozzá a .env fájlt a .gitignore-hoz.
- Soha ne kerüljön naplófájlba. A kérésnaplózásnál maszkold a fejléceket, mert a logok gyakran kevésbé védett helyeken landolnak, mint a titkok.
- Használj külön kulcsot környezetenként. Fejlesztés, staging és éles környezet mind saját kulcsot kapjon, beszédes névvel, hogy szivárgás esetén pontosan tudd, mit kell visszavonni.
Duplikált számlák megelőzése
Képzeld el: elküldöd a számlakérést, a Billingo létrehozza a számlát, de a válasz egy hálózati hiba miatt nem ér vissza.
A kódod időtúllépést lát, és újrapróbálkozik.
Az eredmény… két számla ugyanarra a rendelésre.
Az idempotencia azt jelenti, hogy egy művelet ismételt végrehajtása ugyanazt az eredményt adja, és pontosan ezt kell megtervezned.
- Belső rendelésazonosító hozzárendelése. Minden számlakérés egy egyedi rendelésazonosítóhoz tartozzon, amelyre adatbázis-szintű egyediségi megkötés vonatkozik. Ugyanarra a rendelésre így nem indulhat két párhuzamos számlázás.
- Státuszkezelés. A függőben, kiállítva és hiba állapotok egyértelműen mutatják, hol tart a folyamat. Kiállított státuszú rendelésre a rendszer soha ne indítson új számlát.
- Ellenőrzés újrapróbálkozás előtt. Időtúllépés után ne küldd újra vakon a kérést. Előbb kérdezd le a Billingóban a dokumentumokat (például a rendelésazonosítót a megjegyzés vagy belső hivatkozás mezőben tárolva), és csak akkor hozz létre újat, ha biztosan nem létezik.
- Sztornó- és módosítószámla kezelése. Az API-n keresztül sztornószámla és módosítószámla is kiállítható, de ez nem helyettesíti a saját üzleti logikát. Neked kell eldöntened, ki sztornózhat, milyen feltételekkel, és minden ilyen művelet kerüljön auditnaplóba a felhasználóval, időponttal és indoklással együtt.
Kész integráció vagy egyedi fejlesztés
Nem minden projekthez kell egyedi fejlesztés.
Sőt, sok cég túlfizeti a számlázási integrációt, mert egy egyszerű problémára épít egyedi megoldást.
A fordítottja viszont legalább ilyen gyakori: valaki egy kész pluginnal próbál lefedni egy összetett folyamatot, és fél év múlva kézzel javítgatja a hibás számlákat.
Mikor elég egy kész összekötés
Kész plugin vagy modul akkor elég, ha egyszerű, egyirányú számlázásról van szó egy szabványos webáruház-platformon. WooCommerce, Shopify vagy UNAS alatt léteznek Billingo-összekötők, amelyek a sikeres rendelés után automatikusan kiállítják a számlát.
Ez a megoldás akkor működik jól, ha nincsenek egyedi szabályaid.
Egy pénznem, néhány áfakulcs, standard szállítási díj, és nincs szükség arra, hogy más rendszerek is lássák a számlaadatokat.
Ilyenkor napok alatt élesíthető, és a karbantartást a plugin fejlesztője végzi.
Mikor éri meg egyedi fejlesztés
Egyedi fejlesztés indokolt, ha a számlázás nem a folyamat vége, hanem a közepe.
Ilyen eset, ha egyedi számlázási szabályaid vannak (részletfizetés, előleg- és végszámla, kedvezmények bonyolult logikával), ha több rendszert kell szinkronizálni (CRM, ERP, mobilapp, könyvelési export), vagy ha a hosszú távú karbantartás és skálázhatóság a cél.

Egy gyakorlati példa: a CompletApp webalkalmazásokba és mobilappokba épít Billingo-integrációt.
Egy apartmankezelő rendszerben például a foglalás és a fizetés után automatikusan készül el a számla, a vendég adatai a foglalási rendszerből érkeznek, a tételek pedig a szállásdíjat, az idegenforgalmi adót és a kiegészítő szolgáltatásokat külön kezelik.
Ezt egy kész plugin nem tudja, mert a logika az adott üzlethez tartozik.
Az ilyen projekteknél a CompletApp fix terjedelemmel és áttekinthető mérföldkövekkel dolgozik: először az adatmodell és a hibakezelés tervezése, utána a fejlesztés, majd a tesztfiókos validáció és az élesítés. A megrendelő minden fázis végén látja, mi készült el, és nincs nyitott végű óradíjas elszámolás.
A fejlesztő felelőssége a helyes adatátadás. Az, hogy egy adott ügylet milyen áfakulccsal, milyen jogcímen számlázandó, könyvelői döntés, nem kódolási kérdés.
Ez a NAV-megfelelőség felelősségi körének lényege.
Az integráció garantálja, hogy a megadott adatok pontosan, hiánytalanul és a megfelelő formátumban jussanak el a Billingóhoz.
Azt viszont nem tudja automatikusan eldönteni, hogy egy fordított adózású ügylet vagy egy EU-n belüli szolgáltatás hogyan számlázandó.
Ezeket a szabályokat a könyvelővel kell rögzíteni, és utána a kódba építeni.
Következő lépés az integrációhoz
A döntés egyszerűbb, mint amilyennek látszik.
Ha a számlázási folyamatod standard, egy webshop, egyirányú adatáramlás, egyedi szabályok nélkül, kezdj kész modullal.
Ha egyedi logika, több rendszer összekötése vagy hosszú távú skálázás a cél, tervezz egyedi fejlesztést a kezdetektől, ne utólag foltozd a kész megoldást.
Bármelyik utat választod, a következő konkrét lépés egy technikai felmérés. Ez néhány kérdést tisztáz még az első kódsor előtt:
Milyen adatmodellel dolgozol, és honnan érkeznek a partner- és termékadatok?
Mi történik időtúllépés, validációs hiba vagy sztornó esetén?
És ki felel a karbantartásért, amikor a Billingo bővíti az API-t, vagy változnak a számlázási szabályok?
Ha ezekre élesítés előtt van válaszod, az integráció évekig stabilan működhet.
Ha nincs, a hibák az első forgalmas hónapban jelentkeznek.
Általában péntek délután.
A Billingo API önmagában eszköz. A megbízható integráció a tervezésen és a hibatűrésen múlik, nem azon, hány végpontot ismersz fejből.