Skip to content
Backend Szerző: Kiss János 13 perc olvasás

Billingo API: teljes útmutató fejlesztőknek és vállalkozásoknak

Lépésről lépésre: hitelesítés, számlakiállítás, sztornó és duplikációk elkerülése a Billingo API-val. Gyakorlati tippek fejlesztőknek és cégeknek.

Billingo API integration dashboard showing invoice automation and data sync between business software
Ezen az oldalon▾

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.

A REST API nyelvfüggetlen.

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

Step-by-step diagram, Billingo számlázási workflow. 1. Fizetés, Webhook esemény fogadása; 2. Rögzítés, Függőben státusz…

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.

  1. 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).
  2. 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.
  3. 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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

Billingo API hibakezelés és duplikációk elleni védelem folyamatábrája biztonságos számlázási integrációhoz

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.

Comparison table, Kész modul vs Egyedi fejlesztés. Bevezetés, Kész modul: Napok alatt élesíthető; Egyedi fejlesztés:…

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.

Gyakran ismételt kérdések

Van ingyenes Billingo API?

Nem minden Billingo-csomag tartalmaz API-hozzáférést. Az API használata előfizetési csomaghoz kötött, és ha a fiókod csomagja nem tartalmazza, 402-es hibát kapsz. Fejlesztés előtt nézd meg a Billingo aktuális csomagajánlatát, és ellenőrizd, melyik szint tartalmazza az API-t, mert a csomagstruktúra időnként változik.

Hol találom a Billingo API dokumentációt?

A hivatalos v3 dokumentáció a Billingo fejlesztői oldalán érhető el, OpenAPI (Swagger) formátumban. Mindig ezt kövesd, ne régi blogbejegyzéseket vagy fórumválaszokat. A régebbi források gyakran a v2-es API-ra vonatkoznak, amely más hitelesítést és végpontokat használt, így a kódrészletek a jelenlegi verzióval nem működnek.

Hogyan lehet Billingo API-kulcsot létrehozni?

API-kulcsot a Billingo fiók beállításai között, az API menüpontban hozhatsz létre. Adj a kulcsnak beszédes nevet (például "webshop-eles" vagy "crm-staging"), és minden integrációhoz, környezethez külön kulcsot generálj. A kulcsot azonnal mentsd titokkezelőbe, és ha egy integrációt megszüntetsz, vond vissza a hozzá tartozó kulcsot is.

Milyen API-val lehet automatikusan számlázni Billingóban?

Automatikus számlázáshoz a Billingo API v3-at kell használni. Ez egy REST API, amelyen keresztül számlát, proforma számlát, sztornó- és módosítószámlát állíthatsz ki, valamint partnereket és termékeket kezelhetsz. Bármilyen programozási nyelvből hívható, amely HTTP-kérést tud küldeni.

Hogyan kapcsolható össze a Billingo egy webáruházzal?

A Billingo kétféleképpen köthető össze egy webáruházzal: kész pluginnal vagy egyedi API-integrációval. Szabványos platformokon (WooCommerce, Shopify, UNAS) a kész modul gyors és olcsó megoldás egyszerű folyamatokra. Ha egyedi számlázási szabályaid vannak, vagy a webshop mellett más rendszereket is szinkronizálni kell, egyedi webshop-integráció a tartósabb választás.

Miért kapok 401-es vagy 422-es hibát a Billingo API használatakor?

A 401-es hiba hitelesítési, a 422-es pedig adatvalidációs problémát jelez. 401 esetén leggyakrabban hibás formátumban vagy rossz fejlécben érkezik a kulcs (például Authorization: Bearer formában X-API-KEY helyett), vagy a kulcsot időközben visszavonták. 422 esetén hiányzik egy kötelező mező, vagy érvénytelen az adószám formátuma: a válasz törzse megmondja, pontosan melyik mezővel van gond.
Összes cikk
Megosztás Link kimásolva

Magyar vállalkozás vagy? A fejlesztés egy része DIMOP Plusz digitalizációs pályázatból is finanszírozható. Megnézem, mit fizet a pályázat

Kapcsolódó munkák

Olvass tovább