Ugrás a tartalomra
kassza

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ányIP-tartományIP-tartomány
173.245.48.0/20103.21.244.0/22103.22.200.0/22
103.31.4.0/22141.101.64.0/18108.162.192.0/18
190.93.240.0/20188.114.96.0/20197.234.240.0/22
198.41.128.0/17162.158.0.0/15104.16.0.0/13
104.24.0.0/14172.64.0.0/13131.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ímMire használd
3.73.214.98IPN értesítés és egyéb, a Számlázz.hu felől érkező hívás engedélyezése
3.76.149.232IPN értesítés és egyéb, a Számlázz.hu felől érkező hívás engedélyezése
18.153.156.51IPN é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 : string[] = []

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')
await ..(., { : .(5_000) })

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.
Oldal szerkesztéseUtoljára frissítve: