NR Sam4s NR-330 nyugtakészítő szolgáltatás

Pénztárgép-kapcsolat fejlesztési teher nélkül

Nyugtát kell adnod? Ne a pénztárgéppel töltsd az időt.

Kész szolgáltatás szoftverfejlesztő cégeknek, akik gyorsan szeretnék összekötni saját rendszerüket Sam4s NR-330 pénztárgéppel. Egyszerű feladatleadás, lekérdezhető nyomtatási állapot, helyszíni Pénztárgép vezérlő és kevesebb egyedi hardveres hibakeresés.

Integráció áttekintése Feladattípusok Kapcsolat

Így készül el a nyugta

Tipikusan pár másodperc a leadástól a nyugtáig
Saját rendszered
Feladat leadása kulsoAzonosito: "WEB-10432"
  • Újraküldhető – ugyanarra a kulcsra nincs második nyugta
  • Visszavonható, amíg a vezérlő nem vette át
nyugtaszamlasztornovisszarupenzmozgasnapnyitasnapizarasstatuszmegszakitas
POST /nyugta 202 · feladatId
webhook aláírt végállapot
vagy GET lekérdezés
Nyugtaszerver
Feladat sorba áll
  • Ha a bolt nem elérhető, a feladat vár, majd magától lefut
  • 2 óra után lejár – utólag nem nyomtat
  • Több pénztárgép – AP szám szerint címezhető
átvétel a vezérlő húzza
2–5 mp-enként
eredmény nyugtaszám
vagy hibakód
Pénztárgép vezérlő · a boltban
Ellenőriz, majd nyomtat
  • Csak elérhető pénztárgéppel vesz át munkát
  • Küldés előtt validál: fizetési sorrend, tiltott karakter, hossz
  • Amit el sem kezdett, azt hibának jelenti – újraküldhető
PTG soros
9600 8N1
Sam4s NR-330adóügyi bizonylat

NYUGTA

0012/00034 2026.10.03. 14:32 Kávé 2×5001 000 Készpénz1 000 ÖSSZESEN1 000

A feladat életútja GET /api/v1/nyugta/{feladatId}

var atvette
kesz hiba bizonytalan
visszavonás átvétel előtt → visszavonva 2 óra után → lejart
Fájl alapú út Régi rendszer vagy RDP? JSON fájl a figyelt be mappába – a vezérlő csak a teljesen kiírt fájlt veszi át.
Pénztárgépeid állapota GET /api/v1/terminalok
  • rendben
  • akadály
  • nem jelentkezik
4 végpont ennyiből áll a teljes API — ennyit kell megtanulnod
9 bizonylattípus egy végponton: a tipus mező dönti el, mi készül
0 függőség sima HTTP és JSON, Bearer kulccsal — bármelyik nyelvből
1 mező a kulsoAzonosito megvéd a kettőzött nyugtától

Szolgáltatás

A pénztárgép-kapcsolatot mi tesszük integrálhatóvá

A fejlesztőcsapatodnak elég a feladatleadási és állapotlekérdezési szerződéshez igazodnia. A helyszíni Pénztárgép vezérlő kezeli a Sam4s NR-330 sajátosságait, a kapcsolat állapotát és a nyomtatási eredmény visszajelzését.

A Pénztárgép vezérlő alkalmazás áttekintő képernyője
A helyszíni Pénztárgép vezérlő áttekintő képernyője: pénztárgép állapot, nyugtaszolgáltatás kapcsolat, figyelt mappa és utolsó feldolgozott feladatok.
Webalkalmazásból

Nyugta leadása egyszerű API-n

A saját rendszerednek nem kell pénztárgép-protokollt, soros kapcsolatot vagy helyszíni hibakezelést fejlesztenie. Leadja a feladatot, eltárolja a feladatId-t, majd lekérdezi az eredményt.

Pénztárgép vezérlő

A helyszíni gép intézi a hardvert

A Pénztárgép vezérlő a boltban fut, figyeli az új feladatokat, ellenőrzi a pénztárgép állapotát, majd elvégzi a nyomtatást a Sam4s NR-330-on.

Fájl alapú út

RDP és régi rendszerek mellett is működik

Ha az API-hívás nem megoldható, a küldő program egy JSON fájlt tesz a figyelt mappába. A Pénztárgép vezérlő csak a teljesen kiírt fájlt veszi át, így nem dolgozik félig elkészült adatokból.

Előfizetés

Licenc pénztárgépenként

A bizonylatnyomtatás érvényes licenchez kötött. Ha a licenc nincs rendben, vagy a pénztárgép átmenetileg nem elérhető, a feladat várakozó állapotban marad, és a helyzet rendezése után magától lefut — de nem korlátlan ideig: a várakozó feladat alapértelmezés szerint két óra után lejárt állapotba kerül, és akkor sem nyomtatódik ki, ha a bolt később helyreáll.

Idempotens leadás

Ugyanarra a kulcsra nincs második nyugta

Add meg a saját rendelésszámodat kulsoAzonosito néven, és a szerver ugyanarra a kulcsra nem hoz létre második feladatot: a már meglévőt adja vissza. Így a hálózati hibára elszálló leadás bátran újraküldhető — enélkül a vak ismétlés második nyugtát nyomtathat.

Visszavonás

Amíg nem vette át, törölhető

Ha a vevő elállt vagy rossz terminálra adtad le, a még át nem vett feladat egyetlen hívással visszavonható — nem kell a lejáratot kivárni. A hívás idempotens: ha a válasz elveszett, megismételheted. Átvétel után már nincs visszaút, egy elkészült bizonylatot csak sztornó javít.

Webhook

Nem kell pollozni minden rendelésért

A végállapotokról a szerver értesítést küld a saját https végpontodra, aláírva és a kulsoAzonosito-val együtt, így nem kell háttérfeladatot építeni minden rendeléshez. Egy ritka egyeztető lekérdezés azért kell: a kiszállítást a szerver egy óra után feladja.

Egyszerűsített számla

Engedélyhez kötött, két helyen

A számla ugyanazon a végponton megy, mint a nyugta, de két engedély kell hozzá: az előfizetésben a Számla kapcsoló, és magán a pénztárgépen is be kell kapcsolni a funkciót. Ha az első hiányzik, a vezérlő nincs_engedely hibával áll meg; ha a második, a bizonylatot a gép utasítja el.

Feladattípusok

Nem csak nyugta

Ugyanaz az endpoint kezeli a nyugtát, sztornót, visszárut, egyszerűsített számlát, pénzmozgást, napnyitást, napi zárást, állapotot és megszakítást.

Kiválasztott típus

nyugta

Alap bizonylat tétellel, fizetéssel, opcionális nyomtatott azonosítóval.

Végpont
POST /api/v1/nyugta
API példa
{"tipus":"nyugta","kulsoAzonosito":"WEB-10432","tetelek":[{"arunev":"Kave","ar":500,"mennyiseg":2}],"fizetesek":[{"fizetoeszkoz":1,"ertek":1000}]}

Fejlesztői integráció

Négy végpont és egy webhook, világos felelősségekkel

A leadás nem egyszerű mellékhatásként kezelendő, hanem állapotváltásként a saját rendszeredben. A feladatId lesz a horgony a rendelés és a későbbi nyugtaszám között, a kulsoAzonosito pedig azt biztosítja, hogy egy megismételt leadásból ne legyen második nyugta. 

curl -X POST "https://pelda.hu/nyugtaszerver/api/v1/nyugta" \
  -H "Authorization: Bearer nyk_..." \
  -H "Content-Type: application/json" \
  -d '{"tipus":"nyugta","kulsoAzonosito":"WEB-10432","tetelek":[{"arunev":"Kave","ar":500,"mennyiseg":2}],"fizetesek":[{"fizetoeszkoz":1,"ertek":1000}]}'

# 202 Accepted
{ "feladatId": "6c1f0c8e-...-9b2a", "allapot": "var", "terminal": "A31500001" }

# ugyanaz a kulcs masodszor: 200, es UGYANAZ a feladatId
{ "feladatId": "6c1f0c8e-...-9b2a", "allapot": "var", "ismetelt": true }

Megbízhatóság

A rendszer a duplázás ellen van hangolva

Adóügyi bizonylatnál a kimaradt nyugta pótolható, a véletlenül duplán kinyomtatott viszont nem vonható vissza. A nehezét ezért megépítettük — a te oldaladon nem kell újra megoldani.

  1. Idempotens leadás

    Add meg a saját rendelésszámodat, és ugyanarra a kulcsra nem keletkezik második nyugta. A hálózati hiba utáni újrapróbálkozás így biztonságos — nem kell körülötte védelmi kódot írnod.

  2. Ami kétséges, annak kétséges a neve is

    A rendszer nem mond „kész”-t olyasmire, amiről nem tud: külön állapot szól arról, ha a kimenetel bizonytalan, és arról is, ha a szerver zárta le. A te kódodnak nem kell találgatnia.

  3. Az elfelejtett feladat lejár

    A pénteken leadott nyugta nem jön ki hétfőn a nyomtatóból. Ha a bolti gép nem veszi át időben, a szerver lezárja a feladatot — bizonylat nem készül utólag, a hátad mögött.

  4. Visszavonható, amíg nem késő

    Amíg a vezérlő nem vette át, egy hívással törölheted a feladatot. Utána a válasz megnevezi, miért nem lehet — nem egy általános hibakódot kapsz, amiből neked kell kitalálnod a teendőt.

A mezőszintű részletek — fizetési sorrend, tiltott karakterek, hosszkorlátok, hibakódok — a fejlesztői dokumentációban vannak, példákkal és döntési táblákkal.

01

Feladat leadása

A webalkalmazás vagy fájlküldő létrehozza a nyugta, számla vagy állapot feladatot, a saját rendelésszámával mint kulsoAzonosito.

02

Sorba állítás

A nyugtaszerver eltárolja, a fájl alapú út pedig a be mappában várakoztatja. A webes feladat innen még visszavonható.

03

Átvétel

A Pénztárgép vezérlő csak akkor vesz át munkát, ha elérhető a pénztárgép és rendben van a licenc.

04

Nyomtatás vagy hiba

A PTG lánc validál, küld, választ értelmez, majd visszaírja a nyugtaszámot vagy a hibát.

05

Visszajelzés

A végállapotról webhook értesítés megy a te végpontodra; lekérdezéssel is megtudható. Ha a vezérlő a határidőig nem vette át, a feladat lejárt lesz, és bizonylat nem készül.

Kapcsolat

Árakért és további információért

Írj vagy hívj, ha szoftverfejlesztőként Sam4s NR-330 pénztárgép-kapcsolatot szeretnél beépíteni kevesebb saját fejlesztési munkával.

Trillion Studio Aradvári György e.v. +36 70 3633 445 aradgyuri@gmail.com