Billingo számlázás OpenCart 4-hez

Telepítési és felhasználói kézikönyv

Modulverzió: 4.0.1 · OpenCart 4.1.x · Billingo API v3

Tartalomjegyzék

Az oldalszámokat a Word megnyitáskor frissíti – ha rákérdez a mezők frissítésére, válaszd az Igen gombot.

1. Bevezetés

A Billingo modul összeköti az OpenCart 4 webáruházat a Billingo online számlázóval. A rendelések adataiból (vevő, termékek, kedvezmények, szállítás, fizetési mód, pénznem) a modul a Billingo API-n keresztül számlát vagy díjbekérőt készít. A számla NAV felé történő jelentését a Billingo végzi.

1.1 Mit tud a modul?

• Automatikus számlázás rendelésállapot-váltáskor: számla, díjbekérő vagy sztornó a beállított állapotokra.

• Kézi műveletek az admin rendelés-adatlapján: számla és díjbekérő készítése, díjbekérő átalakítása számlává, sztornó, a számla megnyitása.

• Céges vevők kezelése: a cégnév és az adószám (egy kiválasztható OpenCart egyéni mezőből) a számlára kerül.

• Kedvezmények helyes kezelése: akciós ár külön kedvezménysorként, a kupon / utalvány / hűségpont kedvezmény ÁFA-kulcsonként arányosan szétosztva.

• ÁFA-felülírások: például alanyi adómentes vállalkozásnak (AAM) vagy 0%-os termékekhez, mentességi jogcímmel.

• Devizás rendelések: a számla a rendelés pénznemében készül, a NAV-hoz szükséges HUF-árfolyamot a modul a Billingótól kéri le.

• Fizetési mód leképezés: minden OpenCart fizetési módhoz hozzárendelhető a megfelelő Billingo fizetési mód.

1.2 Követelmények

✔ Javaslat

Élesítés előtt egy Billingo teszt (sandbox) fiókkal és néhány tesztrendeléssel ellenőrizd a beállításokat. A sandboxban kiállított számlák nem kerülnek a NAV-hoz.

2. Telepítés

Az alábbi menüneveket angolul adjuk meg, ahogy az angol nyelvű OpenCart adminban látszanak; zárójelben a magyar megfelelő. A Billingo modul saját beállítási oldala mindig magyar nyelvű, az admin nyelvétől függetlenül.

2.1 A csomag feltöltése

1. Nyisd meg: Extensions → Installer (Bővítmények → Telepítő).

2. Az Upload gombbal töltsd fel a billingo.ocmod.zip fájlt.

3. A listában megjelenik a „Billingo számlázás” (4.0.1, code4flow). Kattints a sor zöld Install (+) gombjára – ez kicsomagolja a fájlokat.

⚠ A fájlnév számít

A fájlnévnek pontosan billingo.ocmod.zip-nek kell lennie. Az OpenCart a .ocmod.zip végződést ellenőrzi („Invalid file type!” hiba), és a név elejéből képzi a bővítmény mappáját. Egy letöltéskor átnevezett fájl (pl. billingo (1).ocmod.zip) hibás telepítést okoz.

2.2 A modul aktiválása

1. Nyisd meg: Extensions → Extensions (Bővítmények → Bővítmények), a típusválasztóban válaszd a Modules (Modulok) lehetőséget.

2. A Billingo sorban kattints az Install (+) gombra.

3. Ezután a ceruza (Edit) gombbal nyílik a modul beállítási oldala.

2.3 Mit hoz létre a telepítés?

✔ Alapértékek telepítéskor

A telepítés biztonságos alapértékeket ment: Számla típusa = Számla, Számla nyelve = Magyar, Egységár és Szállítási költség típusa = NET, Fizetési határidő = 8 nap, Státusz = Engedélyezve, Automatikus számlázás = Letiltva, ÁFA-felülírás nincs. Ezután már csak az API kulcsot, a Számlatömböt és a fizetési módokat kell beállítani.

2.4 Jogosultságok más admin csoportoknak

Ha nem csak a fő adminisztrátor számlázik (például a „rendelésfeldolgozó” csoport is), a jogot kézzel kell megadni: System → Users → User Groups (Rendszer → Felhasználók → Felhasználói csoportok), a csoportnál az Access és a Modify listában is jelöld be az extension/billingo/module/billingo útvonalat.

Jog hiányában a hibaüzenet: „Figyelmeztetés: Nincs jogosultsága a Billingo modul módosításához!”

2.5 Eltávolítás és frissítés

A modul eltávolítása (Extensions → Extensions → Modules → Billingo → Uninstall) törli a két saját táblát, a „Billingo” attribútumot, az eseményeket és az összes modulbeállítást, az API kulcsot is. A Billingóban kiállított számlák természetesen megmaradnak.

⚠ Duplikált számla veszélye

Eltávolítás után a modul „elfelejti”, melyik rendeléshez készült már számla. Újratelepítés után a rendelés-adatlapon újra a „Billingo számla generálása” gomb jelenik meg, és egy állapotváltás újra számlát generálhat. Frissítéshez ezért ne használd az eltávolítás + telepítés utat, ha elkerülhető; ha mégis szükséges, előtte ments adatbázis-mentést a billingo_invoice tábláról.

3. Beállítások

A beállítási oldal öt fülből áll: Fő beállítások, Számlák, Adófelülírás, Fizetési módok, Környezet. Jobb felül a Mentés (kék floppy) és a Mégse gomb található. Sikeres mentés után az oldal visszavisz a Modulok listára (külön sikerüzenet nem jelenik meg).

3.1 Fő beállítások fül

✔ Hibás API kulcs jele

Ha a kulcs hibás vagy a Billingo nem elérhető, a Számlatömb lista üres marad (csak „---”). Ez a legegyszerűbb ellenőrzés: ha a mentett kulccsal megjelennek a tömbök, a kapcsolat rendben van.

3.2 Számlák fül

Ez a fül a számlázás beállításait tartalmazza (nem számlalista – a modulban nincs számlalista, a bizonylatokat a Billingo felületén vagy a rendelés-adatlapon éred el).

Mentéskor a modul ellenőrzi, hogy a számla-, díjbekérő- és sztornó-állapot (a Letiltva kivételével) különböző legyen. Ha kettő egyezik, a hibaüzenet: „Figyelmeztetés: az automatikus számla-, díjbekérő- és sztornó-állapot nem lehet azonos! A beállítások nem lettek elmentve.”

⚠ Nettó vagy bruttó? – a leggyakoribb beállítási hiba

Az OpenCart a termékárat, a szállítási díjat és a kuponkedvezményt nettó összegként tárolja; az ÁFA-t az adóosztály adja hozzá. A modul ezeket az összegeket változtatás nélkül adja át, csak megjelöli, hogy nettó vagy bruttó. Ha itt GROSS-ra állítod (vagy egy korábbi verzióból GROSS maradt), a Billingo a nettó összeget bruttónak tekinti, és a számla végösszege az ÁFA-tartalommal kevesebb lesz a rendelés végösszegénél – hibaüzenet nélkül.

GROSS csak akkor helyes, ha a boltban az árakat bruttóban, adóosztály nélkül rögzítetted. Beállítás után egy tesztszámlán mindig vesd össze a számla és a rendelés végösszegét!

3.3 Adófelülírás fül

Alapesetben a modul minden tétel ÁFA-kulcsát a termék (illetve a szállítási mód) adóosztályából számolja (részletek: 5.5). Az Adófelülírás fülön ezt lehet felülbírálni.

⚠ Ellenőrizd a jogcímet

Ha felülírást választasz, a jogcím mező automatikusan a lista első elemére áll be. Mentés előtt mindig ellenőrizd, hogy a helyes jogcím van-e kiválasztva. Mentességi kódok és jogcímek választásáról könyvelőddel egyeztess – a hibás ÁFA-kód NAV-megfelelőségi kockázat.

Tipikus beállítások

3.4 Fizetési módok fül

Minden telepített OpenCart fizetési módhoz (a letiltottakhoz is) tartozik egy sor: bal oldalon az OpenCart fizetési mód, jobb oldalon a Billingo fizetési mód legördülő listája. A számlára a hozzárendelt Billingo fizetési mód kerül.

⚠ Minden használt fizetési módot párosíts

Ha egy fizetési mód „Válassz...”-on marad, vagy a modul beállításainak utolsó mentése után telepítettél új fizetési modult, a számlakészítés hibára fut. Új fizetési modul telepítése után mindig nyisd meg és mentsd újra a Billingo beállításokat.

3.5 Környezet fül

Csak tájékoztató: a modul verziószáma (4.0.1). A modul hibái nem itt, hanem az OpenCart hibanaplójában jelennek meg (lásd 6.1).

4. A számlázás működése

4.1 Automatikus számlázás

Minden rendelésállapot-váltáskor lefut a modul. Ez történhet a vásárló rendelésleadásakor, a fizetési szolgáltató visszajelzésekor (pl. sikeres kártyás fizetés), vagy amikor az admin a rendelés-adatlapon új előzményt / állapotot rögzít. Ha az Automatikus számlázás engedélyezve van, a modul az új állapotot összeveti a beállított állapotokkal:

Fontos szabályok:

• Csak a pontos állapot-egyezés számít: a bizonylat az adott állapotra váltás pillanatában készül, nem „onnantól kezdve”.

• Egy rendelésnek egyszerre egy aktív bizonylata lehet. Sztornó / archiválás után a rendelés újra számlázható.

• Díjbekérő → számla: ha a rendelésnek aktív díjbekérője van és a számlázási állapotba kerül, a modul a díjbekérőt automatikusan számlává alakítja. Kézzel a „Proforma konvertálása számlává” gombbal is megteheted.

• Sikeres művelet után a modul bejegyzést ír a rendelés előzményeibe, pl. „Billingo számla generálva. Számla azonosító: …”. Számlánál, átalakításnál, sztornónál és archiválásnál a vásárló az OpenCart rendelésfrissítő e-mailjét is megkapja; díjbekérő készítésekor nem.

• Letiltott Státusz mellett semmilyen automatikus művelet nem fut.

✔ Hiba az automatikus feldolgozásban

Ha az automatikus számlakészítés hibára fut (pl. párosítatlan fizetési mód, hibás API kulcs), a rendelésleadás és az állapotváltás ettől nem akad meg. A rendelés előzményeibe a következő bejegyzés kerül, értesítés nélkül: „Billingo: az automatikus bizonylatkezelés hibára futott, részletek a hibanaplóban…”. A hiba részletei csak a hibanaplóba kerülnek, mert az előzményeket a vásárló is látja a fiókjában. A beállítás javítása után a bizonylatot a kézi gombbal pótolhatod.

4.2 Javasolt állapot-beállítások

Ha a Számlák megjelölése kifizetettként be van kapcsolva, az utánvétes és átutalásos számlák is „fizetve” jelöléssel mennek ki – ilyen boltokban hagyd kikapcsolva.

4.3 Kézi műveletek a rendelés-adatlapon

A Sales → Orders (Értékesítés → Rendelések) menüben egy rendelést megnyitva az oldal tetején „Billingo:” feliratú sáv jelenik meg. A látható gombok a rendelés aktuális bizonylatától függnek:

• A sztornó / archiválás előtt a modul megerősítést kér.

• Az eredmény (zöld siker- vagy piros hibaüzenet) a gombok mellett jelenik meg; sikeres művelet után az oldal magától újratöltődik.

• Díjbekérőnél a gombok felirata: „Díjbekérő archiválása”, „Billingo díjbekérő megtekintése”.

• A megtekintés gomb új fülön nyitja meg a bizonylat Billingo oldalát, ahonnan a PDF letölthető.

• A kézi gombok az Automatikus számlázás kapcsolótól függetlenül működnek. A kézi műveletről magyar bejegyzés kerül az előzményekbe a számlaszámmal, pl. „Billingo számla generálva (kézi). Számla azonosító: …”; a vásárló ilyenkor nem kap OpenCart értesítőt.

• A kézi és az automatikus műveletek ugyanazt a nyilvántartást használják: ha már készült számla, újabb nem készül, amíg sztornózásra nem kerül.

4.4 Számla és díjbekérő, sztornó és archiválás

5. Mi kerül a számlára?

5.1 Vevő (partner) és adószám

Adószám mező beállítása

1. Customers → Custom Fields (Ügyfelek → Egyéni mezők): hozz létre egy szöveges mezőt, pl. „Adószám”, elhelyezés: Account vagy Address, nem kötelező, engedélyezve.

2. A Billingo beállításokban a Számlák fülön az Adószám mező listában válaszd ki, majd ments.

3. Céges vásárlásnál a vevő töltse ki a Cégnév és az Adószám mezőt. A modul a formátumot nem ellenőrzi.

⚠ A partneradatok nem frissülnek

A modul a Billingo partnert az e-mail cím + telefonszám alapján egyszer hozza létre, és később újrahasználja. Ha egy visszatérő vevő először magánszemélyként, később céges adatokkal vagy új címmel rendel ugyanazzal az e-mail címmel és telefonszámmal, a számlán a régi adatok szerepelnek. Ilyenkor a Billingóban kézzel javítsd a partner adatait.

5.2 Terméktételek

• Minden rendelt termékből egy tétel: termék neve, mennyiség, egység „db”, egységár, ÁFA-kulcs.

• Az egységár a termék alapára (a terméktörzsből), a rendelés pénznemére átváltva. A választott termékopciók nem jelennek meg a tétel nevében.

5.3 Kedvezmények

Termékszintű kedvezmény (akciós ár)

Ha a termék eladási ára alacsonyabb az alapáránál (akció, vevőcsoport- vagy mennyiségi kedvezmény), a modul a terméket alapáron számlázza, és alá külön negatív sort tesz: „Kedvezmény - ”, a termék ÁFA-kulcsával.

Rendelésszintű kedvezmény (kupon, utalvány, hűségpont)

A kupon, utalvány és hűségpont kedvezmények összegét a modul a kosár termékeinek ÁFA-kulcsai szerint, az eladási érték arányában osztja szét: minden ÁFA-csoportra egy „Kupon kedvezmény” nevű negatív sor kerül. Így vegyes ÁFA-s kosárnál is helyes az ÁFA-bontás és a végösszeg. A termék- és a rendelésszintű kedvezmény egymástól független, mindkettő megjelenik.

5.4 Szállítás

Ha a rendelésnek van szállítási módja, egy tétel kerül a számlára a szállítási mód nevével, a rendelés szállítási díjával (ingyenes szállításnál 0 összeggel), a szállítási mód adóosztálya szerinti vagy felülírt ÁFA-val. Letölthető (szállítás nélküli) termékeknél nincs szállítási sor.

5.5 ÁFA-kulcs meghatározása

• Felülírás nélkül: a termék adóosztályának első százalékos adószabálya, egész számra kerekítve lefelé (pl. 27%). Adóosztály nélküli termék: 0%.

• A fix összegű adók (pl. „Eco Tax”) kimaradnak; a földrajzi zónát a modul nem vizsgálja. Magyar boltnál, adóosztályonként egy százalékos szabállyal ez nem okoz gondot.

• Felülírások sorrendje egy terméknél: normál ÁFA felülírás → (ha 0%) 0% ÁFA felülírás → adóosztály szerinti kulcs.

5.6 Pénznem és árfolyam

A bizonylat a rendelés pénznemében készül (EUR-ban leadott rendelésből EUR számla). Minden összeget a modul a rendeléskor rögzített árfolyammal vált át, az OpenCart saját kerekítési szabályai szerint. Nem forintos számlánál a modul a Billingótól lekéri a NAV-hoz szükséges aktuális HUF-árfolyamot; ha ez nem sikerül, a számla nem készül el.

A teljesítés dátuma és a fizetési határidő kezdőnapja mindig a bizonylat elkészítésének napja, nem a rendelés dátuma.

5.7 Törlési kód

A Billingo tételenként „törlési kódot” tud generálni (pl. szoftverlicenc jellegű termékeknél). Használata: a Számlák fülön a Törlési kód attribútum neve mezőbe írd be: Billingo Törlési Kód, majd az érintett termékekhez (Catalog → Products → Attribute fül) rendeld hozzá ezt az attribútumot (értéke tetszőleges). Ha a mező üres, a funkció nem működik.

5.8 Számpélda – kuponos, vegyes ÁFA-s kosár

Beállítás: egységár és szállítás típusa NET, nincs ÁFA-felülírás, forintos rendelés. Kosár: „A” termék 2 db × 10 000 Ft nettó (27%); „B” könyv alapár 4 000 Ft, akciós ár 3 000 Ft nettó (5%); 10%-os kupon (−2 300 Ft nettó); szállítás 1 000 Ft nettó (27%).

A kupon szétosztása: a 27%-os csoport eladási értéke 20 000 Ft, az 5%-osé 3 000 Ft, így a 2 300 Ft kupon 2 000 Ft + 300 Ft nettó arányban oszlik meg (bruttóban 2 540 és 315 Ft).

Ellenőrzés: 27%: 19 000 Ft nettó + 5 130 Ft ÁFA = 24 130 Ft; 5%: 2 700 Ft nettó + 135 Ft ÁFA = 2 835 Ft. Végösszeg: 26 965 Ft – megegyezik az OpenCart rendelés végösszegével. (GROSS beállítással ugyanez a számla csak 21 700 Ft lenne – ezért kell a NET.)

6. Hibaelhárítás

6.1 Hol látom a hibákat?

• Kézi műveletnél: a gombsáv mellett piros szövegként, pl. „Nem sikerült létrehozni a számlát: ”.

• Automatikus műveletnél a rendelés előzményeiben megjelenik: „Billingo: az automatikus bizonylatkezelés hibára futott, részletek a hibanaplóban…”. Ilyenkor nézd meg a hibanaplót, javítsd a beállítást, majd pótold a bizonylatot a kézi gombbal.

• Hibanapló: System → Maintenance → Error Logs (Rendszer → Karbantartás → Hibanapló). A Billingo hibák „Billingo API Error”, „Partner creation error”, „Document creation error” stb. előtaggal szerepelnek, a Billingo részletes válaszával.

6.2 Gyakori hibák

7. Beállítási ellenőrzőlista

1. billingo.ocmod.zip feltöltése: Extensions → Installer → Upload, majd Install.

2. Extensions → Extensions → Modules → Billingo → Install, majd Edit.

3. Fő beállítások: API kulcs → Mentés → újra Edit → Számlatömb kiválasztása.

4. Számlák fül: ellenőrizd az alapértékeket – Számla típusa = Számla, Egységár és Szállítási költség típusa = NET (nettó áras boltnál), Fizetési határidő, Számla nyelve = Magyar. Korábbi verzióról frissítve a régi értékek megmaradnak, ezeket nézd át különösen!

5. Adószám: egyéni mező létrehozása (Customers → Custom Fields), majd kiválasztása a Számlák fülön.

6. E-mail küldés és „kifizetettként jelölés” igény szerint (4.2).

7. Automatikus számlázás és a kiváltó állapotok beállítása – nem a rendelés kezdő állapotára (4.1, 4.2).

8. Adófelülírás: csak ha szükséges (alanyi adómentesség, 0%-os termékek) – könyvelővel egyeztetve.

9. Fizetési módok: minden használt fizetési mód párosítása.

10. Mentés.

11. Jogosultság más admin csoportoknak: System → Users → User Groups → Access + Modify: extension/billingo/module/billingo.

12. Tesztrendelés → rendelés-adatlap → „Billingo számla generálása” → a Billingóban ellenőrizd a vevőt, a tételeket, az ÁFA-t és a végösszeget.