====== 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) | település neve (maximum 40 karakter)
| 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 | tételsorokat tartalmazza. egy tételsor egy hash
| | | //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