Ugrás a tartalomra
kassza

IPN webhook

Ha a Számlázz.hu-ban egy számla kifizetett összege megváltozik, például a banki egyeztetés rögzít egy átutalást, a Számlázz.hu HTTP POST kérést küld a megadott címre. Ebből tudod meg, hogy egy rendelés ki van fizetve. Az értesítés URL-jét a Számlázz.hu fiókban, a Fiók beállítások / Számlázás alapadatok oldal alján adod meg.

Az értesítést nem írja alá semmi, csak a feladó IP-címe azonosítja. Ezért a recept az értesítést csak jelzésnek veszi: a számla tényleges állapotát a kasszával kérdezi le, és azt menti.

A route handler#

A fizetesiAllapotMentese() a saját adatbázis-függvényed. Felülírja a rendelés fizetési állapotát, nem hozzáad.

app/api/szamlazz/ipn/route.ts
import { isSzamlazzError } from 'kassza'
import { type IpnNotification, ipnOkResponse, isSzamlazzIp, readIpnNotification } from 'kassza/ipn'
import { addMoney } from 'kassza/money'
import { kassza } from '@/lib/kassza'
import { fizetesiAllapotMentese } from '@/lib/rendelesek'

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

  let ertesites: IpnNotification
  try {
    ertesites = await readIpnNotification(request)
  } catch (error) {
    if (!isSzamlazzError(error)) throw error
    console.error('Értelmezhetetlen IPN értesítés', error.message)
    return new Response('Hibás értesítés', { status: 400 })
  }

  const szamla = await kassza.invoices.find(ertesites.invoiceNumber)
  if (!szamla) {
    console.error('IPN értesítés ismeretlen számláról', ertesites.invoiceNumber)
    return ipnOkResponse()
  }

  const kifizetett = addMoney(...szamla.payments.map((befizetes) => befizetes.amount))
  await fizetesiAllapotMentese({
    szamlaszam: szamla.header.number,
    rendelesszam: szamla.header.orderNumber,
    dijbekeroszam: ertesites.proformaNumber,
    kifizetett,
    teljesenFizetve: kifizetett >= szamla.totals.grossAmount,
  })

  return ipnOkResponse()
}

A válaszkódok a Számlázz.hu újraküldését irányítják. Csak a 200 számít sikernek, minden más válasz vagy időtúllépés után a Számlázz.hu 3 percenként újrapróbálja, legfeljebb tízszer.

HelyzetVálaszMi történik
Nem a Számlázz.hu címéről jött403Nincs feldolgozás.
Hiányzik egy kötelező mező400A Számlázz.hu újraküldi, de a hiba a naplóban látszik.
A számla nem található200Nincs mit menteni, az újraküldés sem segítene.
A lekérdezés vagy az adatbázis hibát dob500A Számlázz.hu 3 perc múlva újraküldi.
Sikeres mentés200Kész.

IPN fizetési értesítés

Webhook kérés feldolgozása és a Számlázz.hu IP-címének ellenőrzése.

Futtatás a sandboxban
ipn.ts
import { , ,  } from 'kassza/ipn'

const  = new ('https://webshop.example.hu/api/szamlazz/ipn', {
  : 'POST',
  : {
    'content-type': 'application/x-www-form-urlencoded',
    'x-forwarded-for': '3.73.214.98',
  },
  : new ({
    : 'WEB-2026-128',
    : 'WEB-58213',
    : '19 470',
    : '19 470',
    : 'átutalás',
    : '2026-09-17',
  }),
})

.(
  'A Számlázz.hu IP-címéről érkezett:',
  (..('x-forwarded-for') ?? ''),
)

const  = await ()
.()

if (.) .(`A(z) ${.} rendelés teljesen kifizetve.`)

const  = ()
.(., await .())

Az értesítés mezői#

A readIpnNotification() elfogad application/x-www-form-urlencoded és multipart/form-data törzset is, és az összegeket számmá alakítja.

MezőIPN paraméterLeírás
invoiceNumberszlahu_szamlaszamA kifizetett számla száma.
proformaNumberszlahu_dijbekero_szamaA díjbekérő száma, ha a számla díjbekérőből készült.
orderNumberszlahu_rendelesszamA rendelésszám, ha szerepelt a számlán.
grossTotalszlahu_bruttovegosszegA számla bruttó végösszege.
paidAmountszlahu_kifizetettbruttoA kifizetett bruttó összeg.
paymentMethodszlahu_fizetesmodA kifizetés módja.
paymentDateszlahu_kifizdatA kifizetés dátuma. Csak akkor érkezik, ha az ügyfélszolgálat bekapcsolta.
isFullyPaid–true, ha a kifizetett összeg eléri a végösszeget.

Buktatók#

A Számlázz.hu IP-címei#

Ha a végpontot tűzfalon is korlátozod, ezeket a címeket 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

Kapcsolódó#

IPN fizetési értesítés

Az IPN részletes leírása és a kassza/ipn modul.

Hálózat és biztonság

Bejövő és kimenő forgalom, IP-címek, proxyk.

Nevezés díjbekérővel

Díjbekérős folyamat, amelyben az értesítés díjbekérőszámot is hoz.

Cloudflare Workers

A kassza futtatása Workerben, KV munkamenettel.

Oldal szerkesztéseUtoljára frissítve: