Hálózat és biztonság

A kassza minden kérést HTTPS-en küld a https://www.szamlazz.hu/szamla/ címre. Ezen az oldalon azt találod, amire egy szigorúbban védett szerveren szükséged lehet: IP-címek a tűzfalhoz, időkorlát, újrapróbálás és naplózás.

Kimenő forgalom a Számlázz.hu felé#

A Számlázz.hu a Cloudflare hálózatán keresztül érhető el. Ha a szervered csak engedélyezett címekre indíthat kapcsolatot, a 443-as porton engedd a Cloudflare alábbi IPv4 tartományait. A lista 2025. augusztus 1-je óta érvényes.

IP-tartomány	IP-tartomány	IP-tartomány
`173.245.48.0/20`	`103.21.244.0/22`	`103.22.200.0/22`
`103.31.4.0/22`	`141.101.64.0/18`	`108.162.192.0/18`
`190.93.240.0/20`	`188.114.96.0/20`	`197.234.240.0/22`
`198.41.128.0/17`	`162.158.0.0/15`	`104.16.0.0/13`
`104.24.0.0/14`	`172.64.0.0/13`	`131.0.72.0/22`

Bejövő forgalom a Számlázz.hu felől#

A Számlázz.hu a fizetési értesítéseket (IPN) és a többi, általa indított hívást az alábbi címekről küldi. Ha a webhook végpontodat IP alapján korlátozod, ezeket engedélyezd:

Kimenő IP-cím	Mire használd
3.73.214.98	IPN értesítés és egyéb, a Számlázz.hu felől érkező hívás engedélyezése
3.76.149.232	IPN értesítés és egyéb, a Számlázz.hu felől érkező hívás engedélyezése
18.153.156.51	IPN értesítés és egyéb, a Számlázz.hu felől érkező hívás engedélyezése

A lista a kódban is elérhető, és az isSzamlazzIp() ellenőrzi, hogy egy cím a Számlázz.hu-é-e:

app/api/szamlazz/ipn/route.ts

import { ipnOkResponse, isSzamlazzIp, readIpnNotification } from 'kassza/ipn'

export async function POST(request: Request) {
  const ip = request.headers.get('x-forwarded-for')
  if (!isSzamlazzIp(ip)) return new Response('Tiltott', { status: 403 })

  const ertesites = await readIpnNotification(request)
  await rendelesFizetve(ertesites)
  return ipnOkResponse()
}

Időkorlát#

Egy kérés alapból 60 másodpercig várhat válaszra, ezt a timeoutMs opcióval módosíthatod. Egy hívásra saját AbortSignal-t is adhatsz, például ha a webhook szolgáltatód 10 másodpercen belül választ vár:

const szamla = await kassza.invoices.create(adatok, { signal: AbortSignal.timeout(8_000) })

Újrapróbálás és naplózás#

A biztonságosan ismételhető műveleteket a kassza hálózati hiba, 5xx válasz, időtúllépés és karbantartás esetén magától újrapróbálja, 1, majd 2 másodperc várakozással. A hookokkal minden próbálkozást naplózhatsz:

Hookok és újrapróbálás

Naplózás hookokkal, miközben a kassza egy hálózati hiba után újrapróbál.

Futtatás a sandboxban

hookok.ts

import {  } from 'kassza'
import {  } from 'kassza-sandbox'

const  = ({
  : 10_000,
  : 3,
  : 250,
  : {
    : ({ ,  }) => .(`→ ${}, ${}. próbálkozás`),
    : ({ , ,  }) =>
      .(`← ${}: HTTP ${}, ${} ms`),
    : ({ , ,  }) =>
      .(`✕ ${}: ${.}${ ? ', újrapróbálás' : ''}`),
  },
})

const  = await ..({
  : { : 'Vevő Kft.', : '1111', : 'Budapest', : 'Fő utca 1.' },
  : [{ : 'Szolgáltatás', : 10_000, : 27 }],
})

.failNext('getInvoicePdf', 'network')
const {  } = await ..(., { : .(5_000) })
.('A PDF a második próbálkozásra megérkezett:', )

1. Számla létrehozás · action-xmlagentxmlfile

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamla xmlns="http://www.szamlazz.hu/xmlszamla" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamla https://www.szamlazz.hu/szamla/docs/xsds/agent/xmlszamla.xsd">
  <beallitasok>
    <szamlaagentkulcs>••••••••</szamlaagentkulcs>
    <eszamla>false</eszamla>
    <szamlaLetoltes>true</szamlaLetoltes>
    <valaszVerzio>2</valaszVerzio>
  </beallitasok>
  <fejlec>
    <keltDatum>2026-09-19</keltDatum>
    <teljesitesDatum>2026-09-19</teljesitesDatum>
    <fizetesiHataridoDatum>2026-09-19</fizetesiHataridoDatum>
    <fizmod>Átutalás</fizmod>
    <penznem>HUF</penznem>
    <szamlaNyelve>hu</szamlaNyelve>
  </fejlec>
  <elado></elado>
  <vevo>
    <nev>Vevő Kft.</nev>
    <irsz>1111</irsz>
    <telepules>Budapest</telepules>
    <cim>Fő utca 1.</cim>
    <sendEmail>false</sendEmail>
  </vevo>
  <tetelek>
    <tetel>
      <megnevezes>Szolgáltatás</megnevezes>
      <mennyiseg>1</mennyiseg>
      <mennyisegiEgyseg>db</mennyisegiEgyseg>
      <nettoEgysegar>10000</nettoEgysegar>
      <afakulcs>27</afakulcs>
      <nettoErtek>10000</nettoErtek>
      <afaErtek>2700</afaErtek>
      <bruttoErtek>12700</bruttoErtek>
    </tetel>
  </tetelek>
</xmlszamla>

2. PDF lekérés · action-szamla_agent_pdf

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlapdf xmlns="http://www.szamlazz.hu/xmlszamlapdf" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlapdf https://www.szamlazz.hu/szamla/docs/xsds/agentpdf/xmlszamlapdf.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <szamlaszam>KASSZA-2026-1</szamlaszam>
  <valaszVerzio>2</valaszVerzio>
</xmlszamlapdf>

3. PDF lekérés · action-szamla_agent_pdf

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlapdf xmlns="http://www.szamlazz.hu/xmlszamlapdf" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlapdf https://www.szamlazz.hu/szamla/docs/xsds/agentpdf/xmlszamlapdf.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <szamlaszam>KASSZA-2026-1</szamlaszam>
  <valaszVerzio>2</valaszVerzio>
</xmlszamlapdf>

1. Számla létrehozás · válasz, HTTP 200

content-type: application/xml; charset=UTF-8
szlahu_szamlaszam: KASSZA-2026-1
szlahu_nettovegosszeg: 10000
szlahu_bruttovegosszeg: 12700
szlahu_kintlevoseg: 12700
set-cookie: JSESSIONID=1F6A8C5CBDD71887899A4D24; Path=/szamla; Secure; HttpOnly

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlavalasz xmlns="http://www.szamlazz.hu/xmlszamlavalasz">
  <sikeres>true</sikeres>
  <szamlaszam>KASSZA-2026-1</szamlaszam>
  <szamlanetto>10000</szamlanetto>
  <szamlabrutto>12700</szamlabrutto>
  <kintlevoseg>12700</kintlevoseg>
  <pdf>JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5k… (base64 PDF, rövidítve)</pdf>
</xmlszamlavalasz>

2. PDF lekérés · válasz, HTTP network-error

3. PDF lekérés · válasz, HTTP 200

content-type: application/xml; charset=UTF-8
szlahu_szamlaszam: KASSZA-2026-1
szlahu_nettovegosszeg: 10000
szlahu_bruttovegosszeg: 12700
szlahu_kintlevoseg: 12700

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlavalasz xmlns="http://www.szamlazz.hu/xmlszamlavalasz">
  <sikeres>true</sikeres>
  <szamlaszam>KASSZA-2026-1</szamlaszam>
  <szamlanetto>10000</szamlanetto>
  <szamlabrutto>12700</szamlabrutto>
  <kintlevoseg>12700</kintlevoseg>
  <pdf>JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5k… (base64 PDF, rövidítve)</pdf>
</xmlszamlavalasz>

Konzol

→ createInvoice, 1. próbálkozás
← createInvoice: HTTP 200, 1 ms
→ getInvoicePdf, 1. próbálkozás
✕ getInvoicePdf: network, újrapróbálás
→ getInvoicePdf, 2. próbálkozás
← getInvoicePdf: HTTP 200, 1 ms
A PDF a második próbálkozásra megérkezett: Uint8Array(2657) [PDF]

A hookok a műveletet, a próbálkozás sorszámát, a HTTP státuszt, az időtartamot és a hibát kapják meg. Az Agent kulcsot és a kérés XML-jét soha, így a naplóba nem kerülhet titok vagy vevőadat.

Proxy és egyedi fetch#

A kassza a globális fetch-et használja, így vállalati proxy mögött elég a Node.js globális HTTP kliensét beállítani, például az undici csomaggal:

instrumentation.ts

import { ProxyAgent, setGlobalDispatcher } from 'undici'

const proxy = process.env.HTTPS_PROXY
if (proxy) setGlobalDispatcher(new ProxyAgent(proxy))

Ha csak a Számlázz.hu felé menő forgalmat akarod mérni vagy módosítani, add meg a saját fetch függvényedet:

export const kassza = createKassza({
  fetch: async (url, init) => {
    const valasz = await fetch(url, init)
    metrika.novel('szamlazz_http_valasz', { status: valasz.status })
    return valasz
  },
})

Az Agent kulcs védelme#

A kulcsot csak szerveroldali kód olvassa, soha ne kerüljön böngészőbe vagy mobilalkalmazásba.
Titokkezelőben vagy környezeti változóban tárold, ne a forráskódban.
Webshoponként és integrációnként használj külön kulcsot, így egy kiszivárgott kulcs a többit nem érinti.
A kulcsot a Számlázz.hu felületén bármikor visszavonhatod. Visszavonás után a kassza auth kategóriájú hibát ad, a verifyCredentials() pedig false-t.