Billingo integráció
Ezen az oldalon
Definíció#
A Billingo integráció a QUiCK bevételoldali szinkronmotorja: a Billingóban kiállított vevői számlák automatikusan megjelennek a QUiCK bevételei között. Az összekötés egyszeri beállítás — utána a QUiCK a háttérben, rendszeres időközönként lekéri az új és módosított számlákat, a fizetettségi státuszukkal együtt; a számla PDF-képe külön háttérfolyamatban, némi késéssel csatolódik.
A funkciócsoport határa: az integráció kizárólag kimenő (vevői) számlákra vonatkozik — azokra, amelyeket a cég Billingóban a saját vevőinek állított ki. Bejövő (szállítói) számla ezen az integráción keresztül nem importálható; azok csatornái a manuális feltöltés, az e-mailes beküldés, a böngészőbővítmény és a NAV Online Számla integráció.
Cél és kontextus#
A bevételi oldal adatminősége azon múlik, hogy a kiállított számlák hiánytalanul és torzítás nélkül érnek-e be a nyilvántartásba. Kézi átvezetésnél ez a pont törik el a leggyakrabban: kimarad egy számla, elcsúszik egy összeg, lemarad egy fizetettség-frissítés. A Billingo integráció ezt a kézi lépést szünteti meg — a számla ott keletkezik, ahol kiállítják, és onnantól gépi úton, változatlan tartalommal kerül a QUiCK-be.
Az integráció nem egyszeri import, hanem élő kapcsolat: nemcsak az új számlákat hozza át, hanem követi a meglévők változásait is — ha egy számla módosul vagy kifizetés érkezik rá a Billingóban, a QUiCK-beli rekord frissül. A bevételek így a QUiCK-ben ugyanazt az állapotot mutatják, mint a számlázóban, és azonnal részt vesznek a havi eredményben, a likviditási képben és a könyvelés-előkészítésben.
Mikor ezt, mikor mást#
Az integráció annak való, aki Billingóban számláz, és a bevételeit a QUiCK-ben akarja látni és kezelni — kézi kettős rögzítés nélkül. A tipikus hozadék három rétegű: a számlaadat automatikusan beérkezik; a fizetettség követhető; a bevétel azonnal megjelenik a kontrolling-nézetekben.
A választóvonal a számla iránya: a Billingo integráció a kimenő oldal csatornája. A bejövő szállítói számlákhoz a NAV Online Számla integráció, az e-mailes beküldés, a böngészőbővítmény vagy a manuális feltöltés való. A két oldal együtt adja a teljes képet — az integráció önmagában a bevételi felét fedi le.
Fontos sorrendi szabály a NAV Online Számla integrációval szemben: ha a fiókban már aktív a NAV Online Számla integráció, a Billingo integráció nem kapcsolható be — fordítva viszont igen. Ha mindkét kapcsolatra szükség van, először a Billingo integrációt kell beállítani, és utána aktiválni a NAV Online Számla integrációt.
Belépési pontok#
Cégbeállítások → Integrációk → Billingo — az összekötés beállítása, a kulcsok megadása és a kapcsolat kezelése; a beállítást a fiók tulajdonosa vagy arra jogosult adminisztrátor végezheti
Billingo → Összekötések → QUiCK kiegészítő — az API-kulcs generálása a Billingo oldalán
Tranzakciók → Bevételek — a szinkronizált számlák megjelenési helye; a beérkezett számlák a normál bevételi listában élnek, minden szűréssel és művelettel
Előfeltételek#
Aktív QUiCK előfizetés az érintett cégnél.
Aktív Billingo fiók, fiók-tulajdonosi szintű hozzáféréssel — az API-kulcsok generálásához ez szükséges. Az API-kulcs generálás minden Billingo csomagban elérhető; az API-használat keretét a Billingo saját előfizetési feltételei szabályozzák.
V2 (2.0) típusú API-kulcs — az összekötéshez nyilvános és privát kulcspár kell; a QUiCK-kapcsolathoz a Billingóban 2.0-s kulcsot kell generálni.
Nincs aktív NAV Online Számla integráció a fiókban. Ha a NAV Online Számla integráció már be van kapcsolva, a Billingo integráció nem aktiválható; a fordított sorrend — előbb Billingo, utána NAV Online Számla — működik.
Működés lépésről lépésre#
A folyamat két részből áll: az egyszeri összekötésből és az azt követő, teljesen automatikus szinkronból.
1. Összekötés — egyszeri beállítás.
A Billingo fiókban az Összekötések menüpontban a QUiCK kiegészítő adatlapját kell megnyitni.
Az Összekötés fülön egy név megadása után a Mentés gomb legenerálja a kulcspárt. A nyilvános kulcs a listában látható; a privát kulcs a pajzs ikonra kattintva, a felugró ablakból másolható ki.
A QUiCK-ben a Cégbeállítások → Integrációk → Billingo felületen a két kulcsot a megfelelő mezőkbe kell illeszteni, majd menteni.
A mentéssel az összekötés aktív. A rendszer rögzíti az összekötés dátumát — ez határozza meg a szinkron kiindulópontját.
2. Kezdeti visszatöltés. Az összekötéskor a rendszer nemcsak az aznaptól kiállított számlákat kezdi szinkronizálni: a tárgyhónap és a tárgyhónapot megelőző hónap számlái is bekerülnek. Ennél korábbi számlák automatikusan nem töltődnek vissza — korábbi kezdődátum az ügyfélszolgálaton keresztül állítható be.
3. Automatikus szinkron. A rendszer 10–15 percenként ellenőrzi, hogy keletkezett-e új számla vagy érkezett-e kifizetés a Billingóban; egy kiállított számla jellemzően a kiállítást követő fél órán belül megjelenik a QUiCK-ben. A szinkron minden releváns számlatípust kezel: normál, előleg-, vég-, helyesbítő és sztornó számlát egyaránt.
4. Duplikátum-védelem és változáskövetés. Minden letöltött számlánál a rendszer ellenőrzi, hogy az szerepel-e már a QUiCK-ben — meglévő számláról nem jön létre duplikált rekord. Ha egy korábban szinkronizált számla a Billingóban módosult, a QUiCK az új verziót dolgozza fel.
5. Adatátvétel. A rendszer a számláról rögzíti: a számlaszámot, a teljesítési és kiállítási dátumot, a vevő nevét és adatait (cím, adószám), a tételeket, az összegeket (nettó, ÁFA, bruttó), a fizetési módot és a fizetettségi státuszt.
6. Fizetésimód-leképezés. A Billingo fizetési módjait a rendszer determinisztikusan a QUiCK belső kategóriáira fordítja:
„átutalás", „előre utalás" → Átutalás
„bankkártya", „PayPal", „Barion", „OTP Simple", „online bankkártya", „Szép kártya" és más online fizetési módok → Bankkártya
„készpénz", „postai csekk", „kompenzáció", „barter" és hasonlók → Készpénz
„utánvét", „pick pack pont" → Utánvétel
7. Számlakép csatolása. A számla PDF-képének letöltése külön háttérfolyamatban történik: az alapadatok (összeg, partner, státusz) a szinkronnal együtt jelennek meg, a PDF némi késéssel, automatikusan csatolódik a számlához. Ha a fiókban aktív a Számlaverzum-összekötés, a Számlázz.hu-ban is nyilvántartott Billingo-számlák archiválása a számlakép letöltésekor automatikusan elindul.
8. Hibaág — ha a kapcsolat megszakad. Ha az API-kulcsok érvénytelenné válnak (például törölték őket a Billingóban), a QUiCK a szinkront automatikusan felfüggeszti. A kapcsolat helyreállítása kézi lépés: új kulcspárt kell generálni a Billingóban, és beilleszteni a Cégbeállításokban. Átmeneti Billingo API-túlterhelésnél beavatkozásra nincs szükség: a rendszer a következő szinkronkörben pótolja a lekérést, adat nem vész el.
Állapotok és állapotváltások#
Integráció: inaktív → aktív. A kapcsolat a kulcsok QUiCK-beli mentésekor válik aktívvá — az összekötés dátuma ekkor rögzül, és ez jelöli ki a szinkron időbeli kiindulópontját (tárgyhó + előző hónap).
Integráció: aktív → felfüggesztett. Érvénytelen API-kulcs esetén a szinkron automatikusan leáll. A felfüggesztett kapcsolat magától nem áll helyre — új kulcsok megadása szükséges.
Számla: a Billingo a forrás. A szinkronizált számla tartalmi gazdája a Billingo: ha ott módosul a számla vagy kifizetés érkezik rá, a QUiCK-beli rekord a következő szinkronkörben frissül.
Duplikáció: kizárt. A már meglévő számla ismételt letöltése nem hoz létre új rekordot — a szinkron idempotens.
Számlakép: késleltetett csatolás. A számla alapadatokkal, kép nélkül jön létre; a PDF a külön háttérfolyamat lefutásakor csatolódik. A kép átmeneti hiánya nem hiba, hanem a folyamat normál sorrendje.
Átmeneti API-hiba: állapotsemleges. A kimaradt szinkronkör a következő futáskor pótlódik; a felfüggesztéssel ellentétben ez nem igényel beavatkozást.
Limitációk és specialitások#
Csak vevői számlák: az integráció kizárólag a Billingóban kiállított kimenő számlákat szinkronizálja — szállítói számla ezen a csatornán nem érkezhet.
Visszatöltési határ: az összekötéskor a tárgyhónap és az azt megelőző hónap számlái kerülnek be; ennél korábbi időszak kizárólag az ügyfélszolgálaton keresztül beállított kezdődátummal tölthető vissza.
NAV Online Számla sorrendfüggés: aktív NAV Online Számla integráció mellett a Billingo integráció nem kapcsolható be; a fordított sorrend működik. Ha mindkettő kell, a Billingóval kell kezdeni.
A szinkron nem valós idejű: a rendszer 10–15 percenként kérdezi le a Billingót; a számlák jellemzően a kiállítást követő fél órán belül jelennek meg. Azonnali megjelenés nem elvárható.
A számlakép késéssel érkezik: a PDF csatolása külön háttérfolyamat — az alapadatok és a kép megjelenése között idő telhet el.
Felfüggesztés után kézi helyreállítás: az érvénytelen kulcs miatt leállt kapcsolat nem áll helyre automatikusan; új kulcspár generálása és beillesztése szükséges.
Billingo API-feltételek: az API-kulcs generálása minden Billingo csomagban elérhető, az API-hívások keretét azonban a Billingo saját előfizetési konstrukciói szabályozzák — kétség esetén a Billingo-előfizetés API-feltételeit érdemes ellenőrizni.