WooCommerce OTP eBIZ Dokumentáció

Az alábbi bejegyzésben arról tudhatsz meg többet, hogy hogyan lehet az OTP eBiz számlázóprogramot a WooCommerce-el összekötni.

Mi szükséges hozzá?

eBiz rendszerében rendelkezned kell előfizetéssel. Az előfizetéshez javasolt legalább a standard csomag, ennek a havi nettó díja 1790 Ft. Az aktuális árakat itt találod: https://www.otpebiz.hu/arak

Az összeköttetéshez pedig szükséges lesz az ingyenes verzióban is elérhető, Integration for OTP eBiz & WooCommerce nevű bővítményre, amit innen tölthetsz le: 

A teljeskörű használathoz szükséged lesz a PRO verzióra. Mivel ez nem egy hivatalos bővítmény, így a vásárlással támogathatod a fejlesztést is, akkor is, ha esetleg a PRO verzióban elérhető funkciókra nincs is szükséged.

Rendszerkövetelmények

A bővítmény használatához szükséges a SOAP funkció. Ha nem tudod mi ez, kérd meg a tárhelyszolgáltatót, hogy kapcsolják be, de 99%, hogy már fut a tárhelyeden.

WooCommerce

Hogyan működik?

Amikor a vevőd felad egy rendelést az áruházadban, akkor a rendelést a WooCommerce adminisztrációs felületén látod és automatikusan egy státuszt fog hozzátársítani. Például átutalásos fizetésnél a “Fizetésre vár” státuszt, bankkártyásnál(amikor azonnal levonja a pénzt) pedig a “Feldolgozás alatt” nevű állapotot társítja. Amikor a rendelést teljesítetted(például feladtad a csomagot a vásárlónak), a rendelést a “Teljesítve” állapotra kell állítani. Általában ilyenkor célszerű a számlát is elkészíteni a vásárlónak. 

Ez a folyamat több ponton is változhat attól függően, milyen típusú terméket értékesítesz, milyen szállítási és fizetési módokat használsz. Szükséged lehet például díjbekérő vagy előlegszámlára átutalásos fizetés esetén, vagy sztornó számlára, ha a vásárlód nem fizette ki/vette át a rendelést.

Minden esetben érdemes elektronikus számlát készítened. Ez nem csak neked, de a vásárlódnak is tök jó: az ilyen típusú számlát a vásárlód elektronikusan, emailben kapja meg, PDF formátumban. Neked pedig nem kell a számlát kinyomtatni, aláírni, pecsételni és a csomagba rakni. A számlát automatikusan archiválja az eBiz rendszere, így bármikor visszakereshető. Minden elkészült számla a WooCommerce webáruházban is tárolásra kerül, így sosem vész el véglegesen. Az e-számla elektronikus aláírással és időbélyeggel van ellátva, ez garantálja a hitelességét és eredetiségét. Ebből adódik az, hogy kinyomtatva nem lesz hiteles(így nem olvasható a digitális aláírás), tehát az e-számla nyomtatott verziója maximum egy nem hiteles másolatként használható csak fel. Sajnos nagyon sok könyvelő ezzel nincs tisztában. Ha neked is ilyen problémád lenne, ezzel próbálhatsz érvelni a nyomtatás ellen.

Telepítés

A bővítmény telepítése úgy működik, mint minden más WordPress bővítményé. A Bővítmények / Új hozzáadása keress rá az OTP eBiz-re és telepítsd a bővítményt. A frissítéseket így a WordPress rendszerén automatikusan megkapod. A bővítmény aktiválása után aktiválhatod a PRO verziót. Ehhez menj a WooCommerce / Beállítások / Integráció menüpontra és add meg a vásárláshoz használd e-mail címed és a kapott licensz kulcsot a beállítások tetején:

Ha egy másik oldalon szeretnéd aktiválni a PRO verziót(pl csak tesztelted, de átváltanád az éles oldalra), ne felejtsd el deaktiválni, mert egyszerre csak egy oldalon lehet aktív a licensz kulcs.

Beállítások

A bővítmény rengeteg konfigurációs lehetőséget nyújt. A beállításokat 6 szekcióra bontva találod meg. Szinte minden opciónál találhatsz plusz leírást a kis kérdőjelre mutatva, de alább részletesen bemutatom, melyik opció mire való. A PRO verzióval jelölt funkciók csak a PRO verzió megvásárlása után érhetők el. 

Authentikáció

Az első lépés az legyen, hogy megadod az eBiz-től kapott azonosítókat. Ezeket e-mailben tudod kérni tőlük a [email protected] e-mail címen. Válaszban kapni fogsz egy API kulcsot, egy Rel_ID-t(ez azonosítja az adott számlázási fiókodat, mert több is lehet) illetve egy technikai felhasználónevet és jelszót. A fiókod jelszavát megadhatod a wp-config.php fájlban is, így nem az adatbázisban kerül tárolásra a jelszó:

Áfakulcsok

Alapértelmezetten a számlára a nettó és bruttó értékekből számolt %-os érték kerül áfakulcsként(általában ez 27% lesz). Hogy külön számolja a nettó és bruttó árakat a rendszer, győződj meg róla, hogy megfelelően állítottad e be az adózás menüpont alatt a WooCommerce-et:

  • WooCommerce /  Beállítások / Általános / Adókulcsok és kalkulációk engedélyezése opció legyen bepipálva
  • WooCommerce / Beállítások / Adó oldalon nézd át a beállításokat, válaszd ki, hogy nettó vagy bruttó árakat adsz meg a termékeknek(bruttó javasolt, az okot lásd lejjebb)
  • WooCommerce / Beállítások / Adó / Normál árak oldalon hozz létre egy új adókulcsot, ahol az ország kódja lehet *(így minden országra érvényes), az adókulcs 27%, az adó neve pedig ÁFA.

A fenti példa természetesen a magyar áfakulcs beállítására szolgál. Ha áfakörön kívül vagy, vagy külföldre is értékesítesz, akkor kicsit bonyolultabb a beállítás és egyeztetned is kell a könyvelőddel.

Számlakibocsátó adatai

Ebben a szekcióban adhatod meg a vállalkozásod / céged címét. Ez fog szerepelni a számlán eladóként.

Számla beállítások

Számla sorszáma(PRO)
Itt megadhatsz egy egyedi számlasorszám formátumot. Üresen is hagyhatod, ilyenkor az eBiz generál egyet véletlenszerűen. A mezőben megadhatsz helyettesítő kódokat is, amiket a bővítmény automatikusan lecserél a megfelelő és aktuális értékre: {ev}, {honap}, {nap}, {rendelesszam}.

Számla típusa
Két lehetőség van, papír alapú és elektronikus számla. Fent már említettem, miért célszerű elektronikusra állítani, de konzultálj a könyvelőddel, hogy ő milyen megoldást ajánl. 

Számla típusa céges rendelésnél(PRO)
Sajnos nem minden cég van felkészülve arra, hogy elektronikus számlát fogadjon. Ha sok céges rendelésed van, érdemes ezt az opciót papíralapúra állítani. Ha a vásárlód kitöltötte a cégnév mezőt, akkor ilyen típusú számlát fog létrehozni.

Fizetési határidő(nap)
A számlán feltüntetett fizetési határidő. Ha csak bankkártyás fizetési módot használsz, akkor nem szükséges megadni, ilyenkor a számla kiállításának ideje lesz a fizetési határidő. Ha van átutalásos fizetési mód is, akkor érdemes 5 vagy 7 napot beállítani. Célszerű a könyvelőddel egyeztetni, mi a jó megoldás. Ha más és más határidőt szeretnél egyes fizetési módoknál, egyedi kóddal megoldható, erre mutatok példát később.

Megjegyzés
Az összes számla bal alsó sarkában jelenik meg ez a megjegyzés. Megköszönheted például a rendelést. Ha a {customer_email} helyettesítő kódot beleírod, akkor a bővítmény automatán lecseréli a vásárló email címére. Ha a megjegyzés tartalmát feltételekhez szeretnéd kötni, akkor filterrel módosítanod kell a számlaadatokat. Erre később mutatok példát.

Áfakulcs
A bővítmény alapértelmezetten nem veszi figyelembe a WooCommerce beállításaiban megadott áfakulcsot, hanem egyszerűen megpróbálja kiszámolni a bruttó és nettó árakból, hogy hány %. Ezért fordulhat elő az, hogy 0% áfakulcsot ír a számlára akkor, ha például alanyi adómentes vagy. Itt fixen felülírhatod az áfakulcsot, az összes terméknél ezt fogja beállítani. Lehetőségek: TAM, AAM, EU, EUK, MAA, F.AFA, ÁKK

Számla nyelve(PRO)
Itt beállíthatod, hogy milyen nyelven készüljön el a számla. Ezeket a nyelveket támogatja az eBiz: magyar, német, angol

WPML és Polylang kompatibilitás(PRO)
számlázz.hu bővítmény kompatibilis a WPML-el és a Polylang-al is. A rendelés nyelve szerint be tudja állítani automatán a számla nyelvét is. 

Mennyiségi egység(PRO)
Ha szeretnél mennyiségi egységet is feltüntetni a számlán, akkor itt adhatod meg, hogy mi legyen az alapértelmezett érték. Utána minden egyes terméknél felülírhatod ezt.

Két új mezőt fogsz találni a termék szerkesztésekor a Haladó fülön: Mennyiségi egység és tétel megjegyzés. Ha nincs megadva, akkor az alapértelmezett értéket fogja használni. A megjegyzést a tétel alá írja az eBiz a számlán. Az extra mezők az egyes variációknál is megjelennek külön-külön, nem csak az egyszerű terméktípusnál.

Cégnév + név(PRO)
Ha a pénztár oldalon nincs megoldva az, hogy cégnév mező opcionális(például egy jelölődoboz kijelölése után látszódik csak), sokszor megadják a vásárlók azt cégnévnek, hogy Nincs, N/A stb… Ilyenkor ez az érték kerül a számlára, a tényleges név pedig nem. Ezzel az opcióval mindkettőt ráírja a számlára. 

Szállítási adatok(PRO)
Ha be van kapcsolva, akkor a számlán feltünteti a vásárló szállítási címét is, nem csak a számlázásit.

Számla fejléc és lábléc(PRO)
A fejlécben és a láblécben megadható egyedi szöveges tartalom. Az előnézet gombbal megnézheted, kb hogyan fog kinézni(a végleges számlán nem biztos, hogy pontosan ez a formátum lesz!)

Automatizálás

Értelem szerűen ezekkel a beállításokkal tudod elérni azt, hogy a számlákat, díjbekérőket automatikusan létrehozza a rendszer.

Automata számlakészítés(PRO)
Ha ez az opció be van kapcsolva, akkor a rendelés lezárásakor(teljesített státuszba kerüléskor) automatikusan létrejön a számla. 

Számlakészítés státusznál
Ha nem a teljesített státusznál szeretnéd automatán létrehozni a számlát, akkor itt beállíthatsz egy másikat. Azok a státuszok is megjelennek itt, amit más bővítményekkel hoztál esetleg létre.

Számlaértesítő
Az eBiz emailben elküldi a vásárlónak a számlát. A PRO verzióban lehetőség van arra, hogy a számlát a meglévő WooCommerce emailekhez csatolja, így célszerű ezt kikapcsolni, ne kapjon egyel több emailt a vásárló a kelleténél.

Fizetési módok
Ennél a táblázatos nézetnél láthatod az összes bekapcsolt fizetési módot. Mindegyikhez külön-külön beállíthatod, hogy hány nap legyen a fizetési határidő, hozzon e létre díjbekérőt és kiválaszthatod az eBiz rendszerében lévő fizetési módok közül, hogy melyik passzol a WooCommerce-es fizetési módhoz.

  • Díjbekérő(PRO): célszerű akkor, ha átutalásos fizetési módot használsz

Adószám

Adószám mező vásárláskor
A WooCommerce-ben alapértelmezetten nincs adószám mező. Ezzel az opcióval bekapcsolható, hogy a számlázási adatok között megjelenjen. Az adószámot a rendszer eltárolja, a vásárlónak küldött emailben és a rendelés adatai között is megjelenik. 

Csak 100.000 Ft áfa felett
Ezzel az opcióval csak akkor fog megjelenni az adószám mező, ha a rendelés áfatartalma több, mint 100.000 Ft: 2017. január 1-jétől hatályba lépett az általános forgalmi adóról szóló 2007. évi CXXVII. törvény (Áfa tv.) 169. § d) pont dc) alpontja, amely értelmében a számlán kötelezően fel kell tüntetni a vevő adószámát vagy csoportos adóalanyiság esetén a csoportos adószámot, ha a számla áfa értéke meghaladja a 100.000 forintot.

Adószám figyelmeztetés
Itt megadható az az üzenet, amit a vásárló lát a pénztár oldalon a 100.000 Ft feletti áfatartalom miatt. Az alapértelmezett érték: “A vásárlás áfatartalma több, mint 100.000 Ft, ezért amennyiben rendelkezik adószámmal, azt kötelező megadni a számlázási adatoknál.”

Egyéb beállítások

Számlák a profilban
Ha a vásárló belép az oldalra, akkor a rendelések között látni fogja a számlát is és le is töltheti azt. 

Számla és nyugta csatolása rendelés emailekhez(PRO)
Ha be van pipálva, akkor a számlát csatolja a WooCommerce emailekhez. Érdemes ilyenkor a számlaértesítőt kikapcsolni. A Rendelés feldolgozása/Megrendelés fizetésre vár emailhez csatolja a díjbekérőt(ha van), a Teljesített rendelés/Vásárlói számla/Rendelési adatok emailhez az elkészült számlát, a Visszamondott/Visszatérített emailekhez pedig a sztornó számlát.

Vezetéknév / keresztnév csere
Ha a számlán rossz sorrendben jelenik meg a keresztnév és a vezetéknév, akkor ezzel az opcióval megcserélhető. Téma, fordítás és WooCommerce verzió függő, hogy éppen hogyan jelenik meg a First name / Last name mező, ezért van rá egy külön opció, hogy cseréni lehessen.

Fejlesztői mód
Az eBiz részére egy XML fájlt kell küldeni, ezt csinálja meg a bővítmény a háttérben. Ha be van kapcsolva, akkor az XML fájlt nem fogja letörölni a rendszer, hanem eltárolja a wp-content/uploads/wc_ebiz mappában. Fontos, hogy fejlesztői módban a teszt eBiz szerverrel kommunikál, tehát ilyenkor az teszt authentikációs adatokat kell használnod.

E-mail cím hibajelzéshez(PRO)
Az itt megadott e-mail címre küld egy üzenetet a rendszer, ha volt egy sikertelen automata számlakészítési kísérlet. Az Agent hibákról a számlázz.hu is szokott küldeni, de ezzel az opcióval lehet egy másik címre is kérni értesítést.

Számlák kezelése a rendeléseknél

Lehetőség van arra is, hogy számlákat manuálisan ugyan, de egy kattintással lehessen létrehozni. A rendelés részletei oldalon lévő számlázz.hu számla nevű dobozban található ez a megoldás. Az opciók gombra kattintva lehetőség nyílik arra, hogy díjbekérőt vagy szállítólevelet csináljon számla helyett a rendszer, illetve megadható a teljesítés dátuma, a fizetési határidő és a megjegyzés(ebben a mezőben a beállításoknál megadott megjegyzés az alapértelmezett érték). A számlakészítés kikapcsolása gombbal kikapcsolható a rendelésnél az automata számlakészítés, így a rendelés teljesítésekor sem készül számla hozzá.

Ebben a dobozban találhatók a létrejött számlák, illetve a sztornózás opció is. Ha esetleg a vásárló visszamondta a rendelést, vagy visszaküldte a terméket, akkor létrehozható a sztornó számla. A teljesítettnek jelölés opcióval pedig manuálisan megjelölhető a számlázz.hu rendszerében a teljesítés. 

Ha a rendeléshez nem készül számla, csak nyugta, akkor az alábbi formátumot fogod látni:

A számlákat a rendelések táblázatos nézetében az utolsó oszlopban lévő gombok segítségével is le lehet tölteni:

Újabban a WooCommerce a műveletek oszlopot nem mutatja alapból, viszont ezt egyszerűen be lehet kapcsolni a jobb felső Mit lássunk gombra kattinva:

Programozóknak

Számla és nyugtakészítés előtt a WordPress rendszerből ismert filterekkel lehet módosítani a számla adatait, amit az eBiz rendszerébe küld a bővítmény. Ezek a filterek érhetők el:

  • wc_ebiz_xml – Végszámla, díjbekérő módosítására

A fent említett filterek mindegyike két paraméterrel rendelkezik, $xml és $order. Előbbi az eBiz felé küldendő XML fájl, utóbbi az éppen aktuális rendelés adatai.

Van néhány action is:

  • wc_ebiz_after_invoice_error – hibás számlakészítés esetén fut le, 3 paraméterrel: $order, $response, $error_object
  • wc_ebiz_after_invoice_success – sikeres számlakészítés után, 3 paraméterrel: $order, $response, $pdf_url

Hibaelhárítás

Valamiért nem készül el a számla

Ha látsz egy olyan üzenetet, hogy az automata számlakészítés sikertelen volt, próbáld meg manuálisan létrehozni a számlát, ilyenkor pontosan látni fogod a hiba okát. Több minden előfordulhat, ha így sem tiszta, nyugodtan írj egy emailt.

Agent hibakód: 164

A számlázz.hu dokumentációjából idézve:

A Számla Agent csak olyan felhasználói azonosítóval hívható, aki csak egyetlen számlakibocsátó fiókhoz fér hozzá. Ha az xml-ben megadott bejelentkezési névnek több számlakibocsátó fiókhoz is hozzáférése van, a művelet nem végezhető el, mert a cél-számlakibocsátó fiók nem beazonosítható. Javaslat: a Számla Agent használathoz létre kell hozni egy Számlázó jogosultságú hozzáférést (bejelentkezési nevet).