szamla_api_felulet

szamla_api_felulet gépi interface:

r17109 (commitolt)

a kliens egy JSON formátumú adatot küld a szervernek.

A rendszer elvileg elfogadja

a Content-type: application/json illetve text/json érkező POST-olt adatot,
illetve a „json” névre hallgató form mező adatként is elfogadja,
- akár GET
- akár POST metódussal érkezik.

példa egy tartalmilag hiányos, de egyébként helyes json hívásra GET metódus esetén

http://....../cgi-bin/index.cgi?json={"token":".....","dok":"szamla_api_felvesz","muvelet":"0"}

Charset encoding: UTF-8

a JSON adat egy hash, melynek kulcsai az alábbi jelentésekkel bírnak

mező	tipus/érték	jelentés
		API hívás paraméterei
token	string	a klienst azonosító evir felhasználó tokenje (evir felhasználó jelszavának módosításakor kiíródik)
dok	„szamla_api_felvesz”	kötelező elem.
button	„b_felvesz”	kötelező elem.
		számlázás paraméterei
szamla_tipus	„előleg” vagy „gépi”	Normál végszámla esetén a „gépi” tipust kell választani
muvelet:	„0”, „M1”, „P1”, „M1P2”, „P1M2”, „P1M0”	hogyan jöjjön létre a számla (lásd lentebb)
email_cim	string(100)	email cím „valami@example.com” formátumban
		vevő partner adatai
partner_id	szám	partner_id
		Ha a partner_id ismert, akkor elegendő csak azt megadni. Ha új partnerről van szó, akkor a következő mezők adhatóak meg a partner létrehozásához
partner_tipus:	„cég” vagy „személy”
partner_nev:	string(90)	partner neve
partner_cim_orszag:	string(2)	ország kétbetűs kódja, (pontosan 2 karakter)
partner_cim_orszag_nev	string	ország megnevezése. Megegyezik az evir törzsadatai szerinti névvel (maximum 50 karakter)
partner_cim_varos	string(40)
partner_cim_cim	string(60)	közterület neve. nem bontott cím esetén házszám stb. egyben
partner_cim_irszam	string(10)	irányítószám
partner_adoszam	string(30)	adószám
		számla adatai következnek
arkat	string	árkategória (ha nincs megadva, akkor a partnerhez rendelt, vagy alapértelmezett árkategória lesz) ebből következik a számla pénzneme is
fizmod	string	fizetési mód, (beállítás szerinti hatással a teljdat, fizhat mezőkre) ha nincs megadva, alapértelmezett lesz)
teljdat	dátum	teljesítési dátum (ha nincs megadva, fizetési mód szerint lesz)
fizhat	dátum	fizetési határidő (ha nincs megadva, fizetési mód szerint lesz)
megjegyzes	string	Opcionális megjegyzés a számlára
nyelv	string	a bizonylat nyelve (ha nincs megadva, HU)
tetel_mezok	tomb
		A következő mezők a tetel_mezok tömbön belül többször is megadható hash adatszerkezete
tetel_tipusa	„termék” vagy „szolgáltatás” vagy „előlegszámla”	(kötelező)
tetel_bizonylatszam	string	A felhasználandó előlegszámla száma
		előlegszámla esetén a további mezőket nem kell megadni.
tetel_forrasraktar	string	annak a raktárnak a kódja, ahonnan a terméket eladja. szolgáltatás (és előlegszámla) esetén nem kell megadni
tetel_cikkszam	string	a termék vagy szolgáltatás cikkszáma
tetel_menny	szám	az eladott mennyiség (pozitív szám)
tetel_netto	szám	nettó eladási egységár
tetel_megj	string	tételhez kapcsolódó megjegyzés szöveg (opcionális)
		A következő adatokat akkor kell megadni, ha a szolgáltatás cikkszám még nem szerepel a cikktörzsben. termék esetén nem használható
tetel_cikk_rogzites	„” vagy „szolg_fix” vagy „szolg_gen”	Hogyan kell a cikkszámot rögzíteni
tetel_cikk_megnevezes	string	a cikk megnevezése
tetel_cikk_afa	string	az áfakulcsot azonosító szám vagy szöveg
tetel_cikk_megys	string	Mennyiségi egység
tetel_cikk_unit	szám	legkisebb mennyiség

token, dok, button, muvelet: mindig kötelező megadni
vagy meg kell adnia a partner_id adatot, de ekkor ne adja meg a többi partner adatot
vagy meg kell adni az összes többi partner adatot, de ekkor a partner_id adatot ne adja meg.
- Név és cím pontos egyezés esetén, a létező partnerrel dolgozik, ha nem találja, új partnert rögzít és azzal dolgozik.

tetel_mezok: legalább egy tételt meg kell adni.

email_cim: Akkor és csak akkor kell megadni, ha ki kell küldeni számlát/másolatot/értesítést emailben. azaz a muvelet tartalmaz egy 'M' betűt is.

muvelet: lehetséges értékei

„0” Az elkészült számla nem nyomtatódik ki. A nem nyomtatott számlák listájába kerül (sorszámát már megkapta) output: json
„P1” A számlat kinyomtatja, output: pdf
„M1” A számlát elküldi emailben, output: json
„M1P2” A számlát elküldi emailben, számlamásolatot kinyomtatja, output: pdf
„P1M2” A számlát kinyomtatja, a másolatot elküldi emailben, output: pdf
„P1M0” A számlát kinyomtatja, a számláról értesítőt küld emailben, output: pdf

Ezen értékek NEM MINDEN ESETBEN adhatóak meg. A megadható értékek a beállítások függvényében változnak, az alábbi táblázat szerint. Rosszul megadott esetben vagy hibaüzenet, vagy a beállítások szerinti működés történik.

muvelet	email_ertesito modul installálva van	Első példány emailben	PDF csatolmány
0	mindegy	mindegy	mindegy
P1	mindegy	mindegy	mindegy
M1,M1P2	igen	igen	igen
P1M2	igen	nem	igen
P1M0	igen	mindegy	nem

nyelv: opcionális. A bizonylat ezen a nyelven fog létrejönni (ha ez engedélyezve van a konfigurációban)

„HU” magyar (default)
„EN” angol
„HU,EN” magyar-angol kétnyelvű

arkat: opcionális. A „Törzsadatok/Cikkszámok/Árkategóriák/Árkategória-lista” menüből elérhető lista „Kategória” oszlopából választható érték, de csak ha a „Tipus”=„értékesítési”. Így lehet konkrétan a számla pénznemét is meghatározni. Az árkategóriának pénznemen felüli jelentősége akkor van, ha a tételeknél nem ad meg „tetel_netto” egységárat, hanem az árkézpzés szabályai szerint (pl. árkategóriához tartozó) áron fog számlázni.

fizmod: opcionális. A „Törzsadatok/Pénzügyi/Fizetési módok” menüben elérhető fizetési módok közül, a „Fizetési mód neve” oszlop értékei közül választhat azon feltételekkel, hogy: „Számlázáskor használható”. Az esetleges „Készpénzes” jelölésű fizetési módhoz ha kapcsolódik pénztárbizonylat készítés, az ezen az interface-en keresztül nem érhető el, ezért ilyen fizetési módok használata a rendszer jelen változatában kerülendő.

fizhat, teljdat: dátum mező formátuma „YYYY-MM-DD” (aka ÉÉÉV-HÓ-NP) értéküket befolyásolhatja a fizetési módnál lévő beállítások, de használható vagy létrehozható olyan fizetési mód ami nem befolyásolja.

pelda JSON adat

{
        "token":"gnfdkjgjnkjnfdshjfdk",
        "dok":"szamla_api_felvesz",
        "button":"b_felvesz",
        "szamla_tipus":"gépi",
        "nyelv":"HU",
        "muvelet":"0",

        "tetel_mezok":[
                {
                        "tetel_netto":2430,
                        "tetel_megj":"XXL kék",
                        "tetel_tipusa":"termék",
                        "tetel_cikkszam":"c2",
                        "tetel_menny":3,
                        "tetel_forrasraktar":"r1"
                }
        ],
        "partner_id":4,
        "megjegyzes":"Példa számla",
        "arkat":"ar1",
        "fizmod":"átutalás",
        
}

Visszatérési értékek:

Bizonyos esetekben egy JSON válaszüzenet készül. Sikeres számla rögzítés esetén, nyomtatás nélkül a lentihez hasonló.

Amire számítani lehet, hogy a lenti struktúrában a „message” listában ha az uzenethez tartozó „level” értéke „SysInfo” akkor ott a „message” üzenet „szamlaszam=SZ2015000110” formában az egyelőség jel után a létrehozott bizonylat (számla) számát fogja tartalmazni. Ha ilyen üzenet nincs, akkor feltételezhető, hogy nem jött létre a bizonylat.

[
   {
      "choice":{
        // nem dokumentált feature adatai
      },
      "framename":"main",
      "message":[
         {
            "level":"Info",
            "time":"2015.10.30 21:59:38.67",
            "message":"Számla rögzítve"
         },
         {
            "level":"SysInfo",
            "time":"2015.10.30 21:59:38.67",
            "message":"szamlaszam=SZ2015000110"
         },
      ],
      "szamlaszam":"2015000110",
      "status":"OK",
      "result":null
   }
]

Egy példa hibaüzenet formátuma:

A „message” struktúrája megegyezik a sikeres esettel. Azonban a „level” kulcs értékei sokfélék lehetnek.

Hibának tekintett üzenetek: Fatal, Error
Figyelmeztető üzenetek: Warning, Notice
Tájékoztató üzenetek: Info, SysInfo

Hibás esetekben:

a „result” kulcs alatt megjelenő adatszerkezetben a „name” kulcs alatt várható
az „error” vagy „Kernel error” hibaüzenetről tájékoztató bejegyzés.
A „result” … „info” … „errormessage” alatt pedig az a hibaüzenet, amit a rendszer visszaad.

[
   {
      "choice":{
        // nem dokumentált
      },
      "framename":"main",
      "message":[
         {
            "level":"Fatal",
            "time":"2020.02.30 22:11:52.31",
            "message":"Rendszerhiba: myexception (user): váratlan hibaüzenet  at ../include/dok/szamla/szamla_api_felulet.pm line 1 captured by kernel"
         }
      ],
      "result":[
         {
            "info":{
               "errormessage":null
            },
            "name":"error"
         }
      ]
   }
]

Egyéb eredmények lehetnek ezenkívül még:

nem 200 OK HTTP status: elég ritka, igyekezzük elkerülni.
Content-type: application/x-pdf: szándékos működés eredménye. amikor a 'muvelet' mező 'P' betűt tartalmaz
más Content-type: váratlan hibák esetén (pl: text/html)

Még nem létező szolgáltatás rögzítése az API-n keresztül

r14791 (commited; WIP)

Lehetőség van arra, hogy olyan szolgáltatás kerüljön az API-n keresztül kiszámlázásra, amelynek az adatai még nem szerepelnek a cikktörzsben. Ekkor a számlázandó tétel adatai között meg kell adni azokat a kötelező adatokat is, amelyek egyébként a cikktörzsből érkeznének. Az adatokat a tétel adatai között kell megadni.

  tetel_cikk_rogzites: "szolg_fix" vagy "szolg_gen" a rögzítés módja szerint
  tetel_cikk_megnevezes: A szolgáltatás megnevezése
  tetel_cikk_afa: A szolgáltatáshoz tartozó áfa
  tetel_cikk_megys: A szolgáltatás mennyiségi egysége (pl. darab, óra)
  tetel_cikk_unit: A legkisebb egység, aminek a többszöröse a mennyiség lehet. (általában pl 1)

A szolgáltatás rögzítéséhez ezenkívül felhasználja a tetel_cikkszam mezőt is, ami egyébként is kötelezően megadandó a számla készítéséhez.

A mezők értelmezése

tetel_cikk_rogzites:
- üres, vagy nincs megadva: Nem rögzít szolgáltatást.
- „szolg_fix”: Ha nem létezik a cikkszám, akkor ezzel a cikkszámmal rögzíteni fogja
- „szolg_gen”: Ha nem létezik a cikkszám, akkor levágja a végéről a számot, és egy új cikkszámot generál, aminek a végén lévő szám eggyel nagyobb a legutolsó ilyen kezdetű és számmal végződő cikkszámnál. Ez csak akkor működik, ha a beállításokban be van kapcsolva a „Következő cikkszám generálása”

tetel_cikk_megnevezes: Ez a szolgáltatás megnevezése, a szöveg rákerül a bizonylatra
tetel_cikk_afa: Az áfa mező lehetséges értékeinek illeszkedniük kell az ÁFA törzsadatban található értékekhez a következő módon
- Ha áfakulcs tartozik hozzá, akkor az ott található számot kell megadni. pl. 27% áfa esetén „27.00”
- Ha nem tartozik hozzá áfakulcs, akkor az „Adómentességi megjelölés” mező értékét kell pontosan megadni.
tetel_cikk_megys: Ez a mennyiségi egység, pl. darab, óra
tetel_cikk_unit: Ez a legkisebb mennyiségi egység. Ez leggyakrabban „1” szokott lenni.

Példa adat a tetel_mezok értékére.

        ...
        "tetel_mezok":[
                {
                        "tetel_netto":10000,
                        "tetel_megj":"Kiszállással együtt",
                        "tetel_tipusa":"szolgáltatás",
                        "tetel_cikkszam":"c5",
                        "tetel_menny":2,
                        "tetel_cikk_rogzites":"szolg_fix",
                        "tetel_cikk_megnevezes","Karbantartás
                        "tetel_cikk_afa":"27.00",
                        "tetel_cikk_megys":"óra",
                        "tetel_cikk_unit":1,
                }
        ],
        ...

PLANS:

megjegyzes_template kezelés