1. Sandbox regisztráció
A webáruház létrehoz egy teszt szamla.hu fiókot, megadja a számlakibocsátó adatait, majd e-mailben aktiválja.
Webáruház integráció
szamla.hu API sandbox webáruházaknak
Regisztráljon tesztfiókot, kérjen sandbox hozzáférést, próbálja ki a számlagenerálást, majd ugyanazzal a folyamattal köthető rá később az éles szamla.hu rendszerre.
Javasolt megoldás
Egyszerű fejlesztői út webáruházaknak
A webáruház ne a teljes számlázó felületet tanulja meg, hanem egy tiszta integrációs útvonalon jusson el az első sikeres teszt számláig.
2. API hozzáférés
A fiókhoz sandbox token tartozik. A fejlesztő ezzel tud vevőt, tételt és számlát létrehozni.
3. Teszt számla
A webáruház egy rendelésből JSON kérést küld, a rendszer visszaadja a számla azonosítóját, PDF linkjét és NAV státuszát.
4. Élesítés
Sikeres sandbox tesztek után ugyanaz az integráció átkapcsolható az éles API URL-re és éles kulcsokra.
Endpoint terv
Minimális, webáruházbarát API
GET
/health
Sandbox elérhetőség és verzió ellenőrzése.
POST
/login
Fejlesztői token kérése tesztfiók e-mail és jelszó alapján.
GET
/snapshot
Számlatömbök, fizetési módok, ÁFA-kulcsok, partnerek és termékek lekérése.
POST
/customers
Vevő létrehozása vagy később upsert jellegű partnerkezelés.
POST
/invoices/preview
Számla validálása és összesítése mentés nélkül.
POST
/invoices
Számla végleges létrehozása, PDF és NAV státusz visszaadásával.
Integrációs elvek
Ami miatt kényelmes lesz
- Webáruház-rendelés azonosító tárolása a számla megjegyzésében vagy külön mezőben.
- Idempotens számlakészítés rendelésazonosító alapján, hogy dupla webhook ne duplázza a számlát.
- Előnézet endpoint, amely hibákat ad vissza sorszámfoglalás nélkül.
- Egységes hibakódok: validációs hiba, auth hiba, előfizetés, NAV feldolgozás.
- Élesítés előtt kötelező ellenőrzőlista: számlatömb, NAV kulcsok, fizetési módok, PDF, e-mail.
Sandbox próba
Számla JSON ellenőrzése a böngészőben
Ez a panel fejlesztői mintát ad: a beírt JSON-t validálja, összesítést számol, és megmutatja, milyen választ érdemes az API-nak adnia.
Kérés
POST
https://szamla.hu/api/mobile.php?route=/invoices/preview
Válasz
Nincs futtatva
A minta előnézetéhez kattintson az „Előnézet futtatása” gombra.
Következő fejlesztési lépés
Admin oldali API kezelés
Érdemes külön „API hozzáférések” menüpontot létrehozni a bejelentkezett fiókban, ahol a webáruház látja a sandbox és éles kulcsait, korlátozásait, webhook URL-jeit és naplóit.
KulcsokSandbox / éles token, újragenerálás
WebhookokSzámla elkészült, NAV sikeres, NAV hiba
NaplózásUtolsó 100 kérés, státusz, hibaüzenet
Kezdje tesztfiókkal
A sandbox a teszt.szamla.hu rendszerben fut, így a webáruház nyugodtan próbálhatja a rendelésből számlakészítést.
Sandbox regisztráció API hozzáférést kérek