Fontos tudnivalók

Bizonylat típusok

A következő bizonylattípusok állíthatók ki ezen az interfészen. A típust az XML kérés <fejlec> blokkjában adhatod meg:

• Számla – alapértelmezett típus, külön mező nem szükséges.
• Előlegszámla – <elolegszamla>true</elolegszamla> (részfizetéshez kapcsolódó előleg rögzítésekor).
• Végszámla – <vegszamla>true</vegszamla> (a maradék összeget rendező, előlegszámlához kapcsolódó záró számla).

fontos

A Számlázz.hu-ban egy előlegszámlához csak egy végszámla állítható ki. Nem lehetséges egy előlegszámlából több résszámlát készíteni, és több előlegszámlát sem lehet egy végszámlában összesíteni.

• Helyesbítő számla – <helyesbitoszamla>true</helyesbitoszamla> + <helyesbitettSzamlaszam> (a javítandó számla száma).
• Díjbekérő – <dijbekero>true</dijbekero> (előzetes fizetési felszólítás, jogilag nem számlának minősül).
• Szállítólevél – a <szamlaSablon>SzlaFuvarlevelesAlap</szamlaSablon> sablon használatával; a szállítási adatok a <fuvarlevel> blokkban adhatók meg.
• Sztornó számla – külön interfész kezeli, lásd a Sztornó számla oldalt.

E-számla vs papírszámla

A Számla Agent mind elektronikus, mind pedig hagyományos, papír alapú számla kiállítására képes. Az <eszamla> mező határozza meg a számla típusát: true esetén e-számla, false esetén hagyományos papír alapú számla készül. Az e-számlák kiállításához saját tanúsítványra van szükséged, vagy használhatod a Számlázz.hu által biztosított tanúsítványt (ez az alapértelmezett lehetőség).

Díjbekérőre hivatkozás

Számlát meglévő díjbekérőre hivatkozva is kiállíthatsz. Ehhez a számlakérés <fejlec> blokkjában add meg a díjbekérő számlaszámát a <dijbekeroSzamlaszam></dijbekeroSzamlaszam> mezőben.

Javasolt menet:

1. Ellenőrizd, hogy a hivatkozni kívánt díjbekérő számlaszáma pontosan megvan.
2. Készítsd elő a számlakiállítási XML-t.
3. A <fejlec> blokkban töltsd ki a <dijbekeroSzamlaszam> mezőt a díjbekérő számlaszámával.
4. Küldd be a számlakiállítási kérést a Számla létrehozás > Minta XML oldalon leírt minta alapján.
5. Az Agent a megadott számlaszám alapján a díjbekérőhöz kapcsolva készíti el a számlát.

Rendelésszám (rendelesSzam) és duplikáció-ellenőrzés

A rendelésszám a számlakérés <fejlec> blokkjának opcionális mezője (<rendelesSzam>). A számlát a saját rendszeredben lévő rendeléshez kapcsolja, és később rendelésszám alapján is lekérdezheted a számlát: Bizonylat lekérése XML-ben / Kérés, Bizonylat lekérése PDF-ben / Kérés.

Rendelésszám ismétlődés tiltása

Azt, hogy ugyanaz a rendelésszám szerepelhet-e több számlán, fiókbeállítás szabályozza: Beállítások → Fiók beállításai → Számlázás beállítások, a Számlaszerkesztő beállítások szekcióban a „Rendelésszám ismétlődés tiltása” kapcsoló. A nyugtákra külön, azonos nevű kapcsoló vonatkozik a Nyugtaszerkesztő beállítások szekcióban; lásd a Nyugta létrehozás / Fontos tudnivalók oldalt.

Ha a tiltás bekapcsolt:

• Egy bizonylattípuson belül ugyanaz a rendelésszám csak egyszer használható: a már használt rendelésszámmal beküldött új számlakérést a rendszer elutasítja a Már létező rendelésszám: XXX. Az ismétlődés engedélyezhető a Beállítások oldalon. hibával (hibakód: 71 vagy 152, lásd Alapok / Hibakezelés, hibakódok).
• Az ellenőrzés bizonylattípusonként történik: például egy számlán és egy nyugtán szerepelhet ugyanaz a rendelésszám.
• A sztornó és a helyesbítő számla kivétel az ellenőrzés alól. Egy számla sztornózása után a rendelésszáma újra felhasználhatóvá válik.

Ha a tiltás kikapcsolt, ugyanazzal a rendelésszámmal tetszőleges számú bizonylat készíthető.

Ismételt kérés ugyanazzal a rendelésszámmal

Bekapcsolt tiltás mellett a duplikáció-ellenőrzés a véletlen dupla beküldés ellen is véd (pl. a rendszered időtúllépés miatt nem kapta meg a választ, és újraküldte ugyanazt a kérést). Ilyenkor a Számla Agent nem készít második számlát, hanem sikeres válaszként a korábban kiállított számlát adja vissza, feltéve, hogy az alábbiak mindegyike megegyezik a korábbi számlával:

• vevő neve,
• bruttó végösszeg,
• kelt (keltDatum), fizetési határidő (fizetesiHataridoDatum) és teljesítés dátuma (teljesitesDatum),
• valamint a korábbi számla az elmúlt 2 napon belül készült.

Ha ezek bármelyike eltér, vagy a korábbi számla 2 napnál régebbi, a kérés a fenti már létező rendelésszám hibával kerül elutasításra.

tanács

Bekapcsolt duplikáció-ellenőrzés mellett a rendelésszám idempotencia-védelemként is használható: ugyanannak a számlakészítési kérésnek az újraküldése nem eredményez dupla számlát. Ha viszont a folyamatod szándékosan több számlát állít ki egy rendeléshez, kapcsold ki a tiltást.

Kedvezmény feltüntetése a számlán

A számlakészítési kérésben nincs külön kedvezmény mező. A kedvezményt külön, negatív összegű számlatételként tudod megjeleníteni:

• Vegyél fel egy új <tetel> elemet, és a <megnevezes> mezőben add meg a kedvezmény megnevezését vagy jogcímét.
• A nettó egységárat (<nettoEgysegar>) negatív előjellel add meg; a mennyiség (<mennyiseg>) maradjon pozitív. Így a tétel nettó, áfa és bruttó értéke is negatív lesz.
• Ugyanazt az áfakulcsot (<afakulcs>) használd, mint annál a tételnél, amelyre a kedvezmény vonatkozik.
• Ha a kedvezmény egy konkrét tételhez kapcsolódik, a kedvezmény tételt közvetlenül az érintett tétel után add meg, így a számlán egyértelmű, melyik termékhez vagy szolgáltatáshoz tartozik.

Példa kedvezmény tételre (2 000 Ft nettó kedvezmény egy 27%-os áfakulcsú tételre):

<tetel>
    <megnevezes>Kedvezmény: Minta termék</megnevezes>
    <mennyiseg>1.0</mennyiseg>
    <mennyisegiEgyseg>db</mennyisegiEgyseg>
    <nettoEgysegar>-2000</nettoEgysegar>
    <afakulcs>27</afakulcs>
    <nettoErtek>-2000.0</nettoErtek>
    <afaErtek>-540.0</afaErtek>
    <bruttoErtek>-2540.0</bruttoErtek>
</tetel>

Nincs százalékos és végösszegi kedvezmény

A Számlázz.hu-ban nincs százalékos és végösszegi kedvezmény funkció. A kedvezmény összegét a saját rendszeredben számítsd ki, és a fenti módon, negatív összegű tételként küldd be.

A szokásos tétel összeg-ellenőrzések a negatív tételekre is érvényesek: <nettoErtek> = <nettoEgysegar> × <mennyiseg>, <afaErtek> = <nettoErtek> × <afakulcs> / 100, <bruttoErtek> = <nettoErtek> + <afaErtek>. Lásd: Alapok / Hibakezelés, hibakódok (259–264 kódok).

Kapcsolódó tudástár bejegyzés: Hogyan tudok kedvezményt adni a számlán?

Számlaértesítő küldés

A Számla Agent elküldi az elkészült számlát a vevőnek e-mailben, ha a vevő <email> mezője ki van töltve, és a <sendEmail> értéke true (vagy a mező nincs megadva). Ha azt szeretnéd, hogy a számla elkészültéről ne kapjon a vevő értesítést, küldd <sendEmail>false</sendEmail> értékkel.

tanács

Több e-mail cím megadásához vesszővel (,) válaszd el őket az <email> mezőben.

E-mail tartalom testreszabása

Az e-mail tárgyát (<emailTargy>) és szövegtörzsét (<emailSzoveg>) az <elado> blokkban adhatod meg. A szövegben az alábbi BB kódok használhatók formázáshoz:

BB kód	Hatás
[b]…[/b]	félkövér
[i]…[/i]	dőlt
[u]…[/u]	aláhúzott
[h1]…[/h1] – [h6]…[/h6]	fejléc
[center]…[/center]	középre igazítás

Sortöréshez egyszerűen használj kézi sortörést az <emailSzoveg> mezőn belül, BB kód erre nem szükséges:

<emailSzoveg>első sor
második sor
</emailSzoveg>

További dinamikus mezőkről (pl. számlaszám beillesztése az e-mail szövegbe) a tudástárban olvashatsz részletesen.

Csatolmányok

Az értesítő e-mailhez legfeljebb 5 fájlt csatolhatsz. A fájlokat a HTTP POST kérésben, a fő XML mellé kell küldeni attachfile1 … attachfile5 mezőneveken.

• Fájlonkénti méretkorlát: 2 MB
• Ha egy csatolmány hibás, a rendszer figyelmeztető e-mailt küld a beküldőnek, de az értesítő a többi megfelelő csatolmánnyal együtt kiküldésre kerül.
• Ha az XML-ben nem kérsz e-mail küldést (<sendEmail>false</sendEmail>), a csatolmányok nem kerülnek feldolgozásra.

Tesztkörnyezet

Tesztfiók esetén az értesítő nem a vevő XML-ben megadott e-mail címére érkezik, hanem a fiókbeállításokban megadott e-mail címre.

Számlasablon (szamlaSablon)

A <fejlec> blokkban az opcionális <szamlaSablon> mezővel adhatod meg a kívánt számlasablont. Ha üresen hagyod, az alapértelmezett sablon lesz használva. Vizuális példák itt tekinthetők meg.

Kód	Felületen megjelenő név
SzlaMost	Számlázz.hu ajánlott számlakép
SzlaTomb	Retró kéziszámla
SzlaNoEnv	Borítékbarát számlakép
SzlaAlap	Tradicionális számlakép
Szla8cm	Hőnyomtatós számlakép (8 cm széles)
SzlaFuvarlevelesAlap	Fuvarleveles alap számlakép

Nyugtasablonhoz lásd a pdfSablon mezőt a nyugta kiállítás oldalon.

Nyelvek

Jelenleg 15 nyelven lehet bizonylatot kiállítani. A megadott nyelv nemcsak a bizonylat szövegét határozza meg, hanem az automatikus számlaértesítő e-mail szövegét és a vevői fiókoldal megjelenítési nyelvét is.

A nyelvet a <fejlec> blokkon belüli <szamlaNyelve> mezőben add meg:

Kód	Nyelv
hu	magyar
en	angol
de	német
it	olasz
ro	román
sk	szlovák
hr	horvát
fr	francia
es	spanyol
cz	cseh
pl	lengyel
bg	bolgár
nl	holland
ru	orosz
si	szlovén

Adattörlőkód (torloKod)

A számlakészítési kérésben minden tételhez opcionálisan megadható egy adattörlőkód a <torloKod> mezőben. A mező a <tetelek> blokkon belül, minden egyes <tetel> elemben helyezhető el. Típusa egész szám (int), értéke 0 vagy annál nagyobb.

További információ

Az adattörlőkód API-n keresztüli használatáról és tömeges számlageneráláskor való alkalmazásáról a tudástárban olvashatsz.

Példa egy tételre:

<tetel>
    <megnevezes>Minta termék</megnevezes>
    <mennyiseg>2.0</mennyiseg>
    <mennyisegiEgyseg>db</mennyisegiEgyseg>
    <nettoEgysegar>10000</nettoEgysegar>
    <afakulcs>27</afakulcs>
    <nettoErtek>20000.0</nettoErtek>
    <afaErtek>5400.0</afaErtek>
    <bruttoErtek>25400.0</bruttoErtek>
    <torloKod>123</torloKod>
</tetel>

fontos

A Számlázz.hu fiókban a Beállítások menüben be kell kapcsolni az adattörlőkód használatát. Ha ki van kapcsolva, 539 hibakódot kapsz. Tételenként legfeljebb 400 adattörlőkód adható; ha túlléped, 537 hibakódot kapsz. A hibakódok részlete: Hibakezelés, hibakódok.