Számlagenerálás

Alapok

Egy normál számla generálásának teljes példáját a következő fájl szemlélteti:

./examples/document/invoice/create_invoice_with_custom_data.php

A számla generálásához a következő lépések szükségesek:

// 1. Papír számla létrehozása (átutalással fizetendő magyar nyelvű (Ft) számla 
// kiállítása mai keltezési és teljesítési dátummal, +8 nap fizetési határidővel).
$invoice = new Invoice(Invoice::INVOICE_TYPE_P_INVOICE);

// 2. Egyedi fejléc adatok hozzáadása a számlához (pl. számlakép sablon)
$invoice->getHeader()->setInvoiceTemplate(Invoice::INVOICE_TEMPLATE_8CM);

// 3. Eladói adatok hozzáadása a számlához
$invoice->setSeller(new Seller('OBER', '11111111-22222222-33333333'));

// 4. Vevő adatainak hozzáadása (kötelezően kitöltendő adatokkal)
$buyer = new Buyer('Kovacs Bt.', '2030', 'Érd', 'Tarnoki street 23.');

// a) Vevői adatok hozzáadása a számlához
$invoice->setBuyer($buyer);

// 5. Számla tétel összeállítása alapértelmezett adatokkal
// (1 db tétel 27%-os ÁFA tartalommal)
$item = new InvoiceItem('Eladó tétel 1', 10000.0);

// a) Tétel nettó értékének beállítása
$item->setNetPrice(10000.0);

// b) Tétel ÁFA értékének beállítása
$item->setVatAmount(2700.0);

// c) Tétel bruttó értékének beállítása
$item->setGrossAmount(12700.0);

// d) Tétel adatainak hozzáadása a számlához
$invoice->addItem($item);

// 6. Számla elkészítése (generálás)
$result = $agent->generateInvoice($invoice);

Elvárt és opcionális bemenetek

Számlafejléc adatok

Számlafejléc adatok	Mező	Típus	Kötelező	Alapérték
típus	invoiceType	int	igen	1
keltezés dátum	issueDate	date	igen	mai nap
teljesítés dátum	fulfillment	date	igen	mai nap
fizetési határidő	paymentDue	date	igen	keltezés +8 nap
fizetési mód	paymentMethod	string	igen	átutalás
pénznem	currency	string	igen	Ft
nyelv	language	string	igen	hu
megjegyzés	comment	string
bank név (árfolyam)	exchangeBank	string
banki árfolyam	exchangeRate	string
rendelésszám	orderNumber	string
díjbekérőszám	proformaNumber	string
helyesbített számlaszám	correctivedNumber	string
logo	extraLogo	string
előtag	prefix	string
fizetendő korrekció	correctionToPay	double
kifizetettség	paid	boolean		false
ÁFA árrés (kivezetés alatt)	profitVat	boolean		false
EU-s ÁFA	euVat	boolean		false
számla sablon	invoiceTemplate	string		SzlaMost
előnézeti PDF	previewPdf	boolean		false
előlegszámla számlaszám	prePaymentInvoiceNumber	string
egyszerűsített számlakép	simpleItems	boolean		false

Kivezetés alatt: profitVat és priceGapVatBase

Az egysoros árrés áfaalap megadás 2027. február 15-én kivezetésre kerül: a fejléc szintű profitVat és a tétel szintű priceGapVatBase mezőt új integrációban már ne használd, a meglévő integrációt a kivezetésig állítsd át. Különbözeti (árrés szerinti) áfás számlát két tételre bontva állíts ki: az első tétel az alap szolgáltatás/termék beszerzési ára K.AFA áfakulccsal, a második tétel az árrés összege 27%-os áfakulccsal. Részletek a Számla Agent Áfa értékek - K.AFA oldalán; utazásszervezőként lásd még az Egyszerűsített tételadatok utazásszervezőknek oldalt.

Egyszerűsített számlakép utazásszervezőknek (simpleItems)

A 2026. január 1-jén hatályba lépett Áfa tv. 210/A. §-a alapján az utazásszervezők főszabály szerint nem kötelesek feltüntetni a különbözeti áfa adóalapját és adóösszegét a számlaképen. Ezt a PHP API a 2.12.4-es verziótól az opcionális boolean simpleItems fejléc-mezővel támogatja: bekapcsolása esetén a számla egyszerűsített számlaképpel készül el, amely elrejti az ár- és áfaadatokat a vevő elől, miközben a NAV Online Számla adatszolgáltatás teljes marad.

Csak utazásszervezőknek

A funkció kizárólag az Áfa tv. 210/A. §-a szerinti utazásszervezési szolgáltatást nyújtó adóalanyok (utazásszervezők) számára alkalmazható jogszerűen. Más tevékenységre használni nem megengedett.

A funkciót a számlafejlécen a setSimpleItems() metódussal tudod bekapcsolni:

$invoice = new Invoice(Invoice::INVOICE_TYPE_P_INVOICE);
$invoice->getHeader()->setSimpleItems(true);

• true: a generált XML fejlécébe bekerül a <simpleItems>true</simpleItems> mező, és a bizonylat egyszerűsített (utazásszervezői) számlaképpel készül el.
• false vagy nincs beállítva (alapértelmezés): a mező egyáltalán nem kerül be az XML-be, a rendszer az alapértelmezett (nem utazásszervezői) módban működik.

Teljes példát a ./examples/document/invoice/create_invoice_with_custom_data.php fájlban találsz.

A funkció szállítólevélnél (DeliveryNote) és helyesbítő számlánál (CorrectiveInvoice) nem használható: ezekben az esetekben az API még a kérés elküldése előtt SzamlaAgentException kivételt dob Egyszerűsített számlaképet szállítólevél és helyesbítő számla esetén nem lehet használni üzenettel. Sztornó számlánál a beállításnak nincs hatása, mert a sztornó XML nem tartalmazza ezt a mezőt; a sztornó a szerveroldalon az eredeti bizonylat állapotát örökli.

A bekapcsolt simpleItems-szel beküldött kérésekre a szerver további validációs szabályokat érvényesít: legfeljebb 2 tétel szerepelhet, kizárólag magyar áfakulcs használható, az OSS adózásnak kikapcsolva kell lennie és az eladó adószámának magyarnak kell lennie, a számlasablont pedig felülírja az egyszerűsített nézet. A hibás kéréseket a rendszer 551 és 556 közötti hibakóddal utasítja el. A teljes leírást, benne azzal, hogy mit lát a vevő a számlán és hogyan működik a funkció bizonylattípusonként, a Számla Agent Egyszerűsített tételadatok utazásszervezőknek (simpleItems) oldalán találod.

Az adatszolgáltatás mindig teljes

A simpleItems beállítástól függetlenül a NAV Online Számla adatszolgáltatás minden esetben a teljes tételadatokat tartalmazza, beleértve az adóalapot és az áthárított adó összegét. A számlakép és a NAV rendszerében látható adattartalom ezért eltérhet egymástól; ez a funkció működésének része.

Számla eladói adatok

Számla eladói adatok	Mező	Típus	Kötelező	Alapérték
bank	bank	string
bankszámlaszám	bankAccount	string
aláíró neve	signatoryName	string
e-mail válaszcím	emailReplyTo	string
e-mail tárgy	emailSubject	string
e-mail tartalma	emailContent	string

Számla vevői adatok

Számla vevői adatok	Mező	Típus	Kötelező	Alapérték
azonosító	id	string
név	name	string	igen
ország	country	string
irányítószám	zipCode	string	igen
város	city	string	igen
cím	address	string	igen
e-mail cím	email	string
küldünk-e e-mail	sendEmail	boolean		true
adószám	taxNumber	string
csoportazonosító	groupIdentifier	string
EU adószám	taxNumberEU	string
postázási név	postalName	string
postázási ország	postalCountry	string
postázási irsz.	postalZip	string
postázási város	postalCity	string
postázási cím	postalAddress	string
főkönyvi adatok	ledgerData	LedgerData
aláíró neve	signatoryName	string
telefonszám	phone	string
megjegyzés	comment	string

Új kata védelem

Ha a számlakibocsátó fiók adóneme az új kata, és a fiókszintű védelem be van kapcsolva, a vállalkozásnak (kifizetőnek) kiállított bizonylatot a rendszer 491-es hibakóddal utasítja el (jellemzően akkor, ha a vevőn be van állítva a taxNumber vagy a taxNumberEU). A beállítás: Adózási és pénzügyi adatok. Teljes leírás: Számla Agent Új kata védelem.

Számlaértesítő

Ha a számla elkészültével számlaértesítő e-mailt is szeretnél küldeni, a vevőn állítsd be a cím(ek)et setEmail(...)-lel, és kapcsold be a küldést setSendEmail(true)-val.

Egyetlen email mezőbe (string) írd az összes címet. Ha több címzett van, válaszd el a címeket vesszővel, pontosvesszővel vagy szóközzel; egymás után több ilyen elválasztó is lehet. A Számlázz.hu ezek mentén bontja szét a szöveget, a címek elején és végén lévő szóközöket levágja, és minden így kapott résznek külön-külön érvényes e-mail címnek kell lennie.

$buyer->setEmail('[email protected], [email protected]');

Az eladó oldalán opcionálisan a emailReplyTo, emailSubject és emailContent mezőkkel szabhatod testre az értesítő levelet; lásd ./examples/document/invoice/create_invoice_with_custom_data.php.

Számla vevői főkönyvi adatok

Számla vevői főkönyvi adatok	Mező	Típus	Kötelező	Alapérték
vevő azonosító	buyerId	string
könyvelés dátum	bookingDate	date	igen
főkönyvi szám	buyerLedgerNumber	string
folyamatos teljesítés	continuedFulfillment	boolean	igen	false
elszámolási időszak kezdete	settlementPeriodStart	date
elszámolási időszak vége	settlementPeriodEnd	date

Számlatétel adatok

Számlatétel adatok	Mező	Típus	Kötelező	Alapérték
azonosító (termékazonosító, cikkszám; a számlaképen csak bekapcsolt megjelenítés mellett látszik, lásd lent)	id	string
megnevezés	name	string	igen
mennyiség	quantity	double	igen
mennyiségi egység	quantityUnit	string	igen
nettó egységár	netUnitPrice	double	igen
ÁFA kulcs	vat	string	igen
árrés ÁFA alap (kivezetés alatt)	priceGapVatBase	double
nettó érték	netPrice	double	igen
ÁFA érték	vatAmount	double	igen
bruttó érték	grossAmount	double	igen
megjegyzés	comment	comment
adattörlő kód darabszáma	dataDeletionCode	integer

A priceGapVatBase (árrés ÁFA alap) mező 2027. február 15-én kivezetésre kerül, új integrációban már ne használd. Különbözeti áfás számlához két tételt adj meg (K.AFA + 27%), lásd a fenti, profitVat mezőnél lévő figyelmeztetést és a Számla Agent Áfa értékek - K.AFA oldalát.

Tétel azonosító megjelenítése a számlaképen

A tétel id mezőjét ($item->setId(...)) a rendszer mindig eltárolja, de a számlaképen csak akkor jelenik meg (a tétel neve után zárójelben), ha a megjelenítés be van kapcsolva. Kérésenként a setInvoiceItemIdentifier() metódussal kapcsolhatod be:

$agent->setInvoiceItemIdentifier(true);

$item = new InvoiceItem('Item 1', 10000.0);
$item->setId('CIKK-001');

Ha nem hívod meg a metódust, az SDK nem küldi a mezőt, és a fiók „Termékazonosító megjelenítése a számlán” beállítása érvényes (alapból kikapcsolva). false értékkel akkor is elrejted az azonosítót, ha a fiókbeállítás be van kapcsolva. A hőnyomtatós sablon (Invoice::INVOICE_TEMPLATE_8CM) soha nem jeleníti meg az azonosítót, lásd a Számla Agent Számlasablon oldalát.

Számlatétel főkönyvi adatok

Számlatétel főkönyvi adatok	Mező	Típus	Kötelező	Alapérték
Árbevétel főkönyvi szám	revenueLedgerNumber	string
Árbevétel főkönyvi szám	vatLedgerNumber	string
Gazdasági esemény típus	economicEventType	string
ÁFA gazdasági esemény típus	vatEconomicEventType	string
Számla tétel elszámolási időszak kezdete	settlementPeriodStart	date
Számla tétel elszámolási időszak vége	settlementPeriodEnd	date