Általános információk #
Az API célja, hogy lehetővé tegye az ION rendszer egyszerű, akár kétirányú összekapcsolását külső rendszerekkel. Lehetőség van adatok lekérdezésére, módosítására, új adatok rögzítésére illetve adatok törlésére.
Az API kapcsolat kialakításához fejlesztői ismeretek szükségesek.
Az API kapcsolat kialakításához fejlesztői ismeretek szükségesek. Az API kommunikáció HTTP alapú webszolgáltatásokon keresztül történik
(Használható GET és POST hívás is).
GET hívás #
Az eljárások bemenő paramétereit az URL után paraméterként kell átadni
https://URL/message?System=rendszernév&Client=kliens&Method=eljárásnév&Params[név1]=érték1&Params[név2]=érték2&...
POST hívás #
A Hívás fejébe a https://URL/message kerül és a response-ba pedig json formátumba a paraméterek:
{"System":"rendszernév",
"Client":"kliens",
"Method":"eljárásnév",
"Params": [
{"név1":"érétk1"},
{"név2":"érétk2"},
...
]
}
Teszt hívás #
Válasz:
{"result":"ok","products":[{"id":"c1","name":"Csokoládé"}]}
Paraméterek #
System: rendszernév #
Az a név, amin a felhasználók elérik a rendszert.
Például, ha a https://apps.relation.hu/dszamlazas1b címen elérhető rendszerhez szeretnénk API hívást intézni, akkor a system paraméterben a dszamlazas1b értéket kell átadni.
Client: kliens #
Az azonosítót az ION-t használó cégtől lehet beszerezni.
Az ION Beállítások / API ablakán található Kliens mező tartalmát (GUID) kell beleírni a hívásokban.
Method: eljárásnév #
A meghívni kívánt eljárás neve, például GetCustomer, GetProduct, GetPrice.
Params #
Az eljárások minden bejövő paraméterét külön meg kell adni Params[név]=érték formában.
Például:
…&Method=SetWebLink&Params[Product]=12&Params[Url]=12-022/398
API beállítása #
Az Beállítások / API ablakon létre kell hozni egy új kapcsolatot.
Ajánlott továbbá megadni a Távoli gép IP-jét, hogy az adott Client azonosítóval csak onnan engedjen hívást a rendszer; ezzel növelhető a rendszer biztonsága.
Be kell pipálni továbbá az adott kliensnek engedélyezett eljárásokat.
Ha megadunk egy Ügyfél kódot, akkor árlista lekérésnél a megadott ügyfél árait adja vissza a rendszer.
API Válaszok #
A válasz alapértelmezetten JSON formátumú. Ha egy eljárásban ettől eltérünk, akkor azt ott jelezzük. Ha az eljárás rendben lefutott, nem talált hibát, akkor a válasz mindig így kezdődik:
{"result":"ok",...
Hiba esetén a válasz az következő:
{"result":"error","message":"Hibaüzenet"}
Bemenő és kimenő paraméterek a leírásban #
Minta:
| KIMENŐ PARAMÉTEREK | |||
|---|---|---|---|
| id | * | Cikkszám | |
| price | * | Listaár (ha az ION-ban az Beállítások/API-nál meg van adva egy ügyfél a klienshez, akkor annak az ügyfélnek az ára) | |
| installerprice | Telepítői ár | ||
| action | Akció | ||
| price | ** | Akciós ár | |
| end_date | ** | Akció vége dátum (YYYY.MM.DD) | |
| end_time | Akció vége idő (HH. | ||
Az első oszlopban a paraméterek neve van. Ha több szintű a visszaadott paraméter, akkor az alparaméterek beljebb kezdődnek.
A második oszlopban a kötelezőség van. Ha üres, akkor nem kötelező, ha * jelet tartalmaz akkor kötelező, ha ** jelet tartalmaz, akkor kötelező, amennyiben meg van adva a szülő elem (például az end_date akkor kötelező, ha van action megadva.
Kimenő paramétereknél a kötelezőség azt jelenti, hogy mindenképpen szerepel az adott paraméter a válaszban.
A harmadik oszlopban a paraméter leírása szerepel.
A negyedik oszlopban a paraméter leírása szerepel.
Módosításnál, a kérésben nem szereplő paramétereket az ION nem módosítja.
Módosításnál, ha egy mező értéke null, akkor annak az értéket törli az ION.
A paraméterek alapértelmezetten szöveg típusúak. Eltérés esetén az adott paraméternél jelezve van a típusa.
Formátumok #
Az API UTF-8 karakter kódolást használ.
Számoknál a tizedest ponttal kell jelölni és nem használunk ezres osztályozást.
A dátumok (date) mindig YYYY.MM.DD (év.hónap.nap) formátumúak,
az idő (time) pedig HH:NN (óra.perc).
Időbélyeg (datetime) esetén a dátum és az óra:perc közé szóköz kerül:
(YYYY.MM.DD HH:NN).
Logikai paramétereknél (bool) true, false értéket fogad el. Minden más értéket figyelmen kívül hagy.
POST hívásnál a header CharSet = UTF-8 megadása kötelező!