Billingo integráció
A Billingo egy magyar online számlázási platform, amely megfelel a NAV Online Számla 3.0 követelményeinek. Ha a CADENSA-ban beállítod, az időbejegyzésekből közvetlenül állíthatsz ki jogilag érvényes magyar számlákat — automatikus NAV-adatszolgáltatással és partnerlista-szinkronizációval.
Előfeltételek
- Aktív Billingo-fiók (API-hozzáféréssel rendelkező csomag)
- Billingo v3 API-kulcs (lásd alább)
- Legalább egy beállított számlablokk a Billingo-ban
- CADENSA-egységen legalább Admin szerepkör
1. lépés — Billingo API-kulcs generálása
- Jelentkezz be az app.billingo.hu oldalon
- A bal oldali menüben kattints a Beállítások menüre
- Válaszd az API menüpontot
- Kattints a + Új API kulcs létrehozása gombra
- Adj nevet a kulcsnak (pl.
CADENSA) - Másold ki az azonnal megjelenő kulcsot — csak egyszer látható!
Soha ne oszd meg másokkal, és ne tárold verziókezelőben. A kulcs segítségével bárki számlákat hozhat létre a nevedben.
2. lépés — Beállítás CADENSA-ban
- Nyisd meg a Beállítások → Számla oldalt a CADENSA-ban
- Válaszd a Billingo 🇭🇺 szolgáltatót
- Megjelenik egy tájékoztató:
A Billingo API-kulcsot itt találod: app.billingo.hu → Beállítások → API → API kulcs létrehozása
- Illeszd be az API-kulcsodat az API Key mezőbe
- Kattints a Kapcsolat tesztelése gombra — zöld
jelzi a sikeres kapcsolatot - Kattints a Mentés gombra
A Mentés gomb addig inaktív, amíg a kapcsolatteszt nem sikerült. Teszteletlen vagy hibás API-kulcs nem menthető.
3. lépés — Alapértelmezett értékek beállítása
| Beállítás | Ajánlott érték (HU) | Leírás |
|---|---|---|
| Alapértelmezett pénznem | HUF | Új számlákon használt pénznem |
| Alapértelmezett ÁFA % | 27 | Magyar általános ÁFA-kulcs |
| Fizetési határidő (nap) | 8 vagy 30 | Fizetési határidő napokban |
| Alapértelmezett bizonylatfajta | Számla | Ez jelölődik be alapból a számlakészítő dialógban |
| Kibocsátó országa | HU | A cég ISO 3166-1 alpha-2 országkódja |
A Kibocsátó országa mező lehetővé teszi az intelligens ÁFA-javaslat funkciót (fordított adózás, exportdetekció). Nélküle a CADENSA a vevő belföldi ÁFA-kulcsát alkalmazza minden ügyletre.
4. lépés — Billingo-specifikus beállítások
| Beállítás | Leírás |
|---|---|
| Számlablokk (Invoice Block ID) | A használni kívánt Billingo-számlablokk. Ha üresen hagyod, a CADENSA automatikusan az első aktív blokkot választja. Konkrét blokk ID-hoz: Billingo → Beállítások → Bizonylattömbök. |
| Bankszámla-azonosító | Opcionális. A Billingo bankszámla ID-ja — megjelenik a számlán fizetési adatként. |
| Fizetési mód | Alapértelmezett fizetési mód az új számlákon (wire_transfer, cash, bankcard stb.). |
| Számla nyelve | A számla kiállítási nyelve (hu, en, de stb.). |
5. lépés — (Opcionális) Sandbox / Teszt mód
Engedélyezd a Sandbox módot a teszteléshez anélkül, hogy valódi NAV-bejelentett számlákat állítanál ki. Sandbox számlák:
- Nem jelennek meg a hivatalos Billingo-számlalistán
- Nem kerülnek bejelentésre a NAV-hoz
- A teszt után elvetésre kerülnek
Kapcsoló: Beállítások → Számla → Sandbox / Teszt mód
Számlakiállítás Billingo-n keresztül
A beállítás után a standard számlakiállítási folyamatot kövesd:
- Nyisd meg a Jelentések oldalt → állítsd be a dátumtartományt és a projekt-szűrőket
- Kattints a Számla generálása gombra
- A Bizonylatfajta mezőben válaszd a Számla lehetőséget — a kimeneti csatorna
Billingo-t jelez - (Opcionális) Válassz ügyfelet a partner picker-ből a Billingo-s partnerlista alapján
- Töltsd ki az ügyfél adatait, az ÁFA-kulcsot és a fizetési határidőt
- Kattints az Előnézet gombra → ellenőrizd a tételeket és összegeket
- Kattints a Számla kiállítása (Billingo) gombra
A CADENSA elküldi a számlát a Billingo API-nak, megkapja a számlaszámot, és letölti a PDF-et.
- Az új számla azonnal véglegesítésre kerül (ami kiosztja a Billingo-számlaszámot)
- A számla automatikusan bejelentésre kerül a NAV Online Számla 3.0 rendszerébe
- A véglegesített számla megjelenik a Billingo-ban: Számlák → Kimenő számlák
Partner picker
Amikor a Billingo be van állítva, a Számla generálása dialógban megjelenik egy partner picker — egy kereshető legördülő lista a Billingo-s partnereidről.
Egy partner kiválasztásakor automatikusan kitöltésre kerül:
- Cégnév
- Cím (utca, irányítószám, város, ország)
- Adószám
- E-mail cím
Ha az ügyfél nem szerepel a Billingo-s partnerlistán, a CADENSA automatikusan létrehozza. A partnerek a Billingo /partners végpontjáról kerülnek lekérésre (legfeljebb 100 partner).
A CADENSA kis- és nagybetű-érzéketlenül egyezteti a partnereket név alapján. Ha már létezik azonos nevű partner, a CADENSA frissíti a meglévő rekordot az új cím adataival.
ÁFA-kulcsok
A Billingo az alábbi ÁFA-kulcsokat támogatja:
| Kulcs | Felhasználás |
|---|---|
| 27% | Standard magyar ÁFA (általános forgalmi adó) |
| 5% | Csökkentett kulcs (pl. egyes élelmiszerek, gyógyszerek) |
| 0% | Adómentes, közösségen belüli értékesítés, export |
| AAM | Általános adómentesség (Áfa tv. 85. §) |
| TAM | Tárgyi adómentesség |
| EU | Közösségen belüli termékértékesítés |
| EUK | Közösségen belüli különleges értékesítés |
| MAA | Mezőgazdasági átalányadó-kompenzáció |
| F.AFA | Fordított ÁFA |
| K.AFA | Pénzforgalmi ÁFA |
| KBAUK | EU-n kívüli export |
Ha a fenti listán nem szereplő kulcsot adsz meg, a CADENSA alapértelmezetten 27%-ot alkalmaz. Szokásos esetekre használd a numerikus kulcsokat (0, 5, 27), speciális adókezeléshez a szöveges kódokat.
Nem HUF devizás számlák
A Billingo natívan HUF-ban működik. Más devizájú számlák esetén (EUR, USD, GBP stb.):
- A CADENSA automatikusan lekéri az aktuális HUF-árfolyamot a Frankfurter API-ból (Európai Központi Bank adata alapján)
- Az árfolyam (
conversion_rate) a Billingo által elvárt módon bekerül a számlakérésbe - Az árfolyam rögzítésre kerül a CADENSA számlarekordban auditálási célból
Ha az árfolyam-API nem elérhető, a CADENSA hozzávetőleges tartalék árfolyamokat alkalmaz (EUR ~400 HUF, USD ~370 HUF). Éles használatnál biztosítsd az api.frankfurter.app elérhetőségét.
Számlatörlés (Stornó)
Billingo-számla sztornózásához a CADENSA-ban:
- Nyisd meg a Számlázás → Számlatörténet oldalt
- Keresd meg a számlát, és kattints a Számla sztornózása gombra
- Erősítsd meg a törlést
A CADENSA meghívja a POST /documents/{id}/cancel végpontot. A Billingo-ban automatikusan stornószámla jön létre, és megtörténik a NAV-bejelentés.
A sztornózott számlákat nem lehet visszaállítani. Ha újra kell számlázni, a Jelentések oldalon generálj új számlát.
Hibaelhárítás
„Érvénytelen API-kulcs" / 401 Unauthorized
Az API-kulcs érvénytelen, lejárt vagy visszavonásra került.
Megoldás: Generálj új kulcsot a Billingo-ban (Beállítások → API → + Új API kulcs), és add meg újra a CADENSA-ban.
„Nem találhatók számlablokkok"
Nincs beállított számlablokk a Billingo-fiókban.
Megoldás: A Billingo-ban menj a Beállítások → Bizonylattömbök menüpontba, és hozz létre legalább egy aktív számlablokkot.
„INVOICE_NO_BILLABLE_ITEMS" hiba
Minden sor összege 0 — valószínűleg nincs beállított óradíj.
Megoldás: Menj a Beállítások → Díjak oldalra, és állíts be óradíjakat a projektekhez.
„Partner nem található" hiba
A partner automatikus létrehozása sikertelen — általában hiányzó kötelező mező (irányítószám, város, cím) miatt.
Megoldás: Győződj meg arról, hogy az ügyfél rekordjában legalább országkód és város meg van adva. Vagy hozd létre manuálisan a partnert a Billingo-ban, majd válaszd ki a partner picker-ből.
A PDF-en nincs számlaszám
A Billingo API-hívás sikeres volt, de a letöltött PDF nem tartalmazza a külső számlaszámot.
Megoldás: Töltsd le újra a PDF-et a Számlázás → Számlatörténet oldalról — a tárolt rekordban megtalálható a Billingo-számlaszám.
Kapcsolódó oldalak
- Számlázási szolgáltató beállítások — összes szolgáltató összehasonlítása, API-kulcs és alapértelmezések konfigurálása
- Számlagenerálás — hogyan generálj számlát időbejegyzésekből
- Előfizetési csomagok — melyik CADENSA-csomag szükséges