Áttekintés és előfeltételek
A Billingo Integráció (4.2.1) a Magento rendelésekből Billingo számlát, díjbekérőt, piszkozatot és sztornó számlát készít. Ez történhet automatikusan egy rendelésállapotnál, vagy kézzel az adminból. A vevő, a termékek, a szállítás, a kedvezmények és az ÁFA a rendelésből kerül át, így a bizonylat mindig egyezik a rendeléssel.
Ami a használathoz kell:
Billingo fiók API hozzáféréssel.
Billingo API kulcs, amivel partner (vevő) és bizonylat is létrehozható. Teljes jogosítványú Billingo felhasználóval kell generálni. Korlátozott kulccsal minden bizonylat „You do not have permission for this operation” hibával áll le.
Legalább egy számlatömb a Billingóban, és ha a számlán bankszámla is szerepeljen, egy rögzített bankszámla.
Magento Open Source / Adobe Commerce 2.4.x, PHP 8.1 vagy újabb.
Telepítés
A modul composerrel, egy helyi „path” repositoryból települ. Így a függőségei (guzzle, valitron, twig, carbon) automatikusan bekerülnek a vendor mappába.
cd /var/www/html && mkdir -p packages/billingo && composer config repositories.billingo path packages/billingo/integration && composer require billingo/integration:^4.0 && bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
A modul fájljai a packages/billingo/integration/ mappába kerülnek, a composer ide mutató hivatkozást tesz a vendor/billingo/integration alá.
Frissítés
Töltsd fel az új fájlokat a packages/billingo/integration/ mappába.
Ha a composer.json függőségei változtak, futtasd: composer update billingo/integration.
Futtasd: bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.
Ha az OPcache nem figyeli a fájlváltozást, indítsd újra a PHP-FPM-et.
A modul egyszerre csak egy helyen lehet: vagy a packages/… alatt composerrel, vagy az app/code/Billingo/Integration alatt. Az app/code alatti másolás 4.2.1 óta a projekt composer.json módosítása nélkül is működik, de ott a függőségeket kézzel kell telepíteni:
composer require vlucas/valitron:^1.4 twig/twig:^3.10 "nesbot/carbon:^2.62 || ^3.0"
Beállítás
A beállítások a Stores > Configuration > Billingo menüben vannak, négy részre bontva. Elsőként az API kulcsot mentsd el: a számlatömb, bankszámla és fizetési mód listákat a modul ezzel a kulccsal tölti le a Billingóból.
Általános
Beállítás | Jelentés |
Használat | Az automatikus bizonylatkezelés be- és kikapcsolása. |
API Key | A Billingo API kulcs. |
Számlatömb | A Billingo számlatömb, amibe a bizonylatok kerülnek. Kötelező. |
Bankszámla kiválasztása (HUF / EUR) | A HUF és EUR bizonylatokon szereplő bankszámla. Üres EUR esetén a HUF számla kerül rá. |
Proforma figyelmen kívül hagyása | Nem: ha van díjbekérő, abból készül a számla. Igen: mindig a rendelés adataiból. |
Megjegyzés | Állandó megjegyzés minden bizonylaton. |
Megrendelés azonosító hozzáadása a megjegyzéshez | A rendelésszám a megjegyzésbe kerül. |
Cikkszám hozzáadása a tételek megjegyzéseihez | Minden tételsorhoz kiírja a cikkszámot. |
Elektronikus számla | E-számla készítése. |
Pénzügyi teljesítést nem igényel jelölés | A bizonylat ilyen jelölést kap. |
Manuális számlakészítés típus | A kézi műveletek (gomb, tömeges művelet, Billingo oldal) bizonylattípusa: számla, díjbekérő vagy piszkozat. |
Automata számlakészítés | Nem, Igen, rendes számla vagy Igen, de csak piszkozat. |
Számlakészítés rendelés állapot | Az állapot, aminél az automatikus számla elkészül. |
Automata sztornózás | A rendelésállapot, aminél a számla sztornózásra kerül. |
Automata proforma készítés | Nem, Igen, a rendelés leadásakor, vagy egy rendelésállapot. |
Alapértelmezett fizetési mód | Ezt használja, ha a rendelés fizetési módja nincs hozzárendelve (pl. kuponnal fizetett 0 Ft-os rendelés). |
Számla nyelve | A bizonylatok nyelve. Kötelező. |
Kerekítés | A bizonylat kerekítési szabálya. |
Mennyiségi egység | A tételsorok egysége, alapértelmezetten „db”. |
Keresztnév és vezetéknév felcserélése | A vevő neve magyar sorrendben (vezetéknév elöl). |
Képviselő nevének feltüntetése a cégnév után | Céges vevőnél „Cég Kft. (Kapcsolattartó)” formátum. |
Adattörlő kód | A termékattribútum, ami adattörlő kódot igénylő terméket jelöl (is_generate_erase_code). |
Adó
Az Adó oldal első blokkja az Adószám Beállítások. Az Adószám mező megjelenítése vásárláskor egy adószám mezőt tesz a pénztár számlázási adataihoz, ami a számlára is rákerül. Az Adószám figyelmeztetés szövege a fizetés oldal tetején jelenik meg, ha a mező be van kapcsolva.
Beállítás | Jelentés |
ÁFA felülírás | A rendelés ÁFA kulcsai helyett az itt megadott érték kerül a bizonylatra. |
Felülírás típusa | Áfa felülírás (rögzített kulcs) vagy 0%. |
ÁFA érték és jogcím | A rögzített felülírás kulcsa és jogcíme. |
0% ÁFA jogcíme | A 0%-os felülírás jogcíme. |
ÁFA felülírás szállítóknál is | A szállítási sorra is vonatkozik. |
Szállító mindig látszódjon | Ingyenes szállításnál is kerül szállítási sor a bizonylatra. |
Felülírás nélkül minden tétel ÁFA kulcsa a Magento rendelésből jön. A Billingo által nem ismert kulcs Unsupported VAT rate hibát ad.
Díjbekérőre, számlára és sztornóra külön:
Küldés: ki küldi a bizonylatot a vevőnek – Nem, Billingo, Magento vagy Mindkettő.
Gomb szövege és a gomb feletti szöveg a Magento e-mailben.
Fizetési beállítások
Minden Magento fizetési módnak saját csoportja van, a kikapcsolt módok a lista végén.
Beállítás | Jelentés |
Billingo megfelelője | A bizonylaton szereplő Billingo fizetési mód. Minden aktív módot rendelj hozzá, különben az alapértelmezett kerül rá, ha az is üres, nem készül bizonylat. |
Fizetési határidő (nap) | A fizetési határidő a készítés napjától. |
Fizetettnek jelölés (Díjbekérő / Éles számla esetén) | Az ilyen fizetésű bizonylat fizetettként készül (pl. bankkártya). |
Díjbekérő kiállítása | Csak Igen esetén készül automatikus díjbekérő ehhez a fizetési módhoz. |
Automatikus bizonylatok
Az automatikus kezelés minden rendelésmentéskor lefut (leadás, számlázás, szállítás, állapotváltás), ha a Használat be van kapcsolva. Egy rendeléshez soha nem készít két azonos típusú bizonylatot. Billingo hiba esetén a rendelés mentése megtörténik, a hiba a var/log/Billingo.log fájlba kerül.
Számla rendelésállapotra
Az Automata számlakészítés legyen Igen, rendes számla (vagy piszkozat), a Számlakészítés rendelés állapot pedig pl. Teljesítve vagy Feldolgozás alatt. Amikor a rendelés ebbe az állapotba lép, elkészül a számla. Ha van díjbekérő és a Proforma figyelmen kívül hagyása értéke Nem, a számla a díjbekérőből készül.
Díjbekérő
Az Automata proforma készítés adja meg, mikor készül díjbekérő. A fizetési mód Díjbekérő kiállítása beállítása adja meg, melyik rendeléshez.
Automata proforma készítés | Mikor készül |
Nem | Soha |
Igen, a rendelés leadásakor | Amint a vevő leadja a rendelést |
Állapotba váltáskor: … | Amikor a rendelés a kiválasztott állapotba lép |
Csak Igen értékű Díjbekérő kiállítása mellett készül díjbekérő. Nem és soha el nem mentett fizetési mód esetén nem készül, akkor sem, ha az automata proforma be van kapcsolva. Számlázott rendeléshez nem készül díjbekérő.
Tipikus beállítás, ha átutalásnál azonnal kell díjbekérő, kártyás fizetésnél soha:
Általános > Automata proforma készítés = Igen, a rendelés leadásakor
Fizetési beállítások > Átutalás > Díjbekérő kiállítása = Igen
Fizetési beállítások > Bankkártya > Díjbekérő kiállítása = Nem
Email > Proforma Beállítások > Küldés = Billingo (vagy Mindkettő), hogy a vevő megkapja
Automata sztornó
Ha az Automata sztornózás egy rendelésállapotra (pl. Törölve) van állítva, az ebbe az állapotba lépő rendelés számlája sztornózásra kerül a Billingóban, és a sztornó számla a rendeléshez mentődik.
Munka a rendelésekkel
Billingo blokk a rendelés oldalán
Nyisd meg a rendelést (Sales > Orders > View, Information fül). Alul a Billingo blokk a rendelés összes bizonylatát mutatja.
Oszlop | Tartalom |
Bizonylat | Számla, Díjbekérő, Sztornó számla vagy Piszkozat |
Szám | A Billingo bizonylatszám |
Létrehozva | A készítés dátuma |
Állapot | Érvényes vagy Sztornózva |
Megnyitás | Megnyitás a Billingóban: a bizonylat nyilvános oldala új lapon |
Kézi küldés. Amíg a rendelésnek nincs érvényes, a manuális típusnak megfelelő bizonylata, a blokkban egy … küldése a Billingóba gomb látszik (pl. Számla küldése a Billingóba). Kattints rá és erősítsd meg. Az oldal újratöltődik a sikeres üzenettel és az új bizonylattal, vagy a hiba okával. A További lehetőségek link a rendelés Billingo oldalát nyitja meg.
A rendelés Billingo oldala
A rendelés eszköztárának Billingo gombjával vagy a blokk További lehetőségek linkjével nyitható meg.
Az oldal a rendelés bizonylataihoz igazodik:
Nincs még bizonylat: a + jelre kattintva megjegyzés, fizetési határidő (nap), teljesítési dátum és bizonylattípus adható meg, majd Számla készítése.
Van díjbekérő: Díjbekérő Megtekintése és Számla készítés Díjbekérő-ból.
Van számla: Számla Megtekintése és Sztornózás (a számla sztornózása a Billingóban).
Több rendelés küldése a rendeléslistából
Nyisd meg a Sales > Orders listát.
Jelöld ki a rendeléseket.
Actions > Számla küldése a Billingóba, majd erősítsd meg.
Az eredményüzenet felsorolja az elkészült bizonylatszámokat, a kihagyott (már bizonylattal rendelkező) rendelések számát és minden sikertelen rendelés hibaokát. Egy rendelés több Billingo API hívás, ezért egyszerre legfeljebb néhány tucat rendelést küldj.
Jogosultságok
A jogosultságokat a System > Permissions > User Roles menüben lehet beállítani. Az első nélkül a felhasználó nem látja a Billingo blokkot a rendelés oldalán.
ACL erőforrás | Mit enged |
Billingo számlázás (Billingo_Integration::documents), Sales > Operations > Orders alatt | Billingo blokk és gombok, Billingo oldal, tömeges művelet |
Billingo beállítások (Billingo_Integration::config), Stores > Settings > Configuration alatt | A Billingo beállítási oldalak |
Hibaelhárítás
Minden Billingo művelet a Magento gyökerében lévő var/log/Billingo.log fájlba kerül, a rendelés azonosítójával.
Üzenet | Ok és teendő |
A vevőt (partnert) nem sikerült létrehozni … „You do not have permission for this operation” | Az API kulcs nem hozhat létre partnert, más cégé, vagy az előfizetésben nincs API. Új kulcsot kell generálni teljes jogú felhasználóval. |
A vevőt (partnert) nem sikerült létrehozni … hiányos számlázási adatok | Hiányos a számlázási cím vagy ismeretlen az ország. Javítsd a címet és küldd újra. |
Nincs beállítva a számlatömb | Válassz számlatömböt: Általános > Számlatömb. |
A rendelés fizetési módja (…) nincs Billingo fizetési módhoz rendelve | Rendeld hozzá a Fizetési beállításokban, vagy adj meg alapértelmezett fizetési módot. |
Nincs beállítva a számla nyelve | Állítsd be: Általános > Számla nyelve. |
A rendelés pénzneme (…) nem támogatott | A Billingo nem támogatja a rendelés pénznemét. |
Unsupported VAT rate: … | A Billingo nem ismeri a tétel ÁFA kulcsát. Javítsd az adószabályt, vagy használj ÁFA felülírást. |
Ehhez a rendeléshez már készült bizonylat a Billingóban | Nincs teendő. Új bizonylathoz előbb sztornózd a régit a Billingo oldalon. |
Nincs elérhető link | A Billingo nem adott nyilvános linket. Nyisd meg a bizonylatot a száma alapján a Billingóban. |
Nem készül díjbekérő az új rendelésekhez | Az Automata proforma készítés ne legyen Nem, és a fizetési mód Díjbekérő kiállítása legyen Igen. A naplóban a „no proforma for payment method” sor erre utal. |
Az API kulcs ellenőrzése a szerverről (a KULCS helyére a saját kulcs kerül):
curl -s -H "X-API-KEY: KULCS" https://api.billingo.hu/v3/organization
curl -s -H "X-API-KEY: KULCS" "https://api.billingo.hu/v3/document-blocks?per_page=10"
Az első megmutatja, melyik céghez tartozik a kulcs. A második a kulccsal elérhető számlatömböket listázza: a beállításokban kiválasztottnak ezek között kell lennie.