MailMasterPlus API. fejlesztői dokumentáció

MailMasterPlus API fejlesztői dokumentáció

MailMaster Plus API dokumentáció v1.1

1. Bevezetés A MailMasterPlus API (továbbiakban API) célja, hogy lehetővé tegye a MailMasterPlus (továbbiakban MMP) rendszer integrációját, oda‐vissza történő adatcserét külső rendszerekkel.

2. REST interfész Az API REST szabvány szerint készült interfészt használ. Az adatcsere JSON formátumban történik. Az interfész HTTP GET, POST, PUT, DELETE metódusokat használja a különböző műveletekhez.

2.1 API elérhetősége Az API URL‐je: http://restapi.emesz.com

2.2 Authentikáció Minden API kérdéshez szükséges API kulcs és jelszó. Az authentikálás HTTP basic típusú.

2.3 Karakterkódolás Az MMP API minden adatcseréhez UTF‐8 karakterkódolást használ. UTF‐8‐ban fogadja és adja vissza az adatokat.

3. Használható erőforrások listája 3.1 Feliratkozó hozzáadása Ez a metódus az MMP‐ben korábban létrehozott e‐mail listában egy új feliratkozó hozzáadását teszi lehetővé. Az e‐mail listához létre kell hozni egy feliratkozó űrlapot – ha még nincs ‐, melynek a MMP API kulcsát használja az e‐mail lista beazonosításhoz. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/subscribe//form/<ns_id> Metódus POST Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak a listának az azonosítója, melyhez a feliratkozót hozzáadásra fog kerülni ns_id: annak a feliratkozó űrlapnak az azonosítója, amelyen keresztül a feliratkozót hozzáadja Kötelező paraméter A body‐ban átadott JSON formátumú asszociatív tömbben szerepelnie kell az emailkulcsó mezőnek, amely értéke a hozzáadandó feliratkozó e‐mail címe legyen. Opcionális paraméterek A kötelező email paraméter mellettátadhatóminden olyan mezőnek az értéke, melyet már szerepel az e‐ mail listába JSON formátumú asszociatív tömbként. A tömb kulcsa a mező neve legyen, értéke pedig a mező értéke UTF‐8 kódolással. 2. oldal


Válasz sikeres feliratkozás esetén Sikeres feliratkozás esetén a body értéke az újonnan hozzáadott feliratkozó azonosítója az e‐mail listában, amely egy nullánál nagyobb egész szám. Válasz hibás feliratkozás esetén Amennyiben csakis egyedi e‐mail cím rögzíthető a listában és a hozzáadandó e‐mail cím már szerepel abban, akkor a body értéke: ‐1. Szintaktikailag hibás e‐mail cím esetén a body értéke: ‐2. Egyéb rögzitési hiba esetén a body értéke: 0.

3.2 Feliratkozó adatainak módosítása Ez a metódus az MMP‐ben korábban létrehozott e‐mail listában rögzített feliratkozó adatainak megváltoztatását teszi lehetővé. Az e‐mail listához előzetesen létre kell hozni egy adatmódosító űrlapot, melynek MMP API kulcsát használjaaz adatmódosítás paramétereként. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/update//form/<ns_id> /record/ VAGY http://<username>:<password>@restapi.emesz.com/update//form/<ns_id>/field/ /value/ Metódus PUT Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak az e‐mail listának az azonosítója, amely a feliratkozót tartalmazza, akinek az adatait módosítja. ns_id: annak az adatmódosító űrlapnak az azonosítója, amelyen keresztül a feliratkozó adatait módosítja. id: annak a felhasználónak az azonosítója, akinek az adatait frissíti. field_name: annak a mezőnek a neve, amelynek értéke alapján beazonosítja a feliratkozót, akinek az adatait frissíti. field_value: a paraméterben meghatározott mező értéke. field_value: annak a mezőnek az értéke, amely alapján beazonosítja a feliratkozót. A paramétert urlencode‐olva kell átadni. Opcionális paraméterek A body‐ban átadott JSON formátumú adatok között szerepelhet minden olyan mező és annak értéke, melyet az URL‐ben meghatározott feliratkozónál frissíteni kívánunk. Válasz Sikeres adatmódosítás esetén a body értéke a módosított feliratkozók száma. Sikertelen adatmódosítás esetén a body értéke: üres. 3. oldal


3.3 Feliratkozó adatainak lekérdezése Az MMP‐ben korábban létrehozott e‐mail listába már rögzített feliratkozó adatainak lekérdezését teszi lehetővé. A metódus egyszerre csak egy feliratkozó adatát adja vissza. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/list/ VAGY http://<username>:<password>@restapi.emesz.com/list//record/ VAGY http://<username>:<password>@restapi.emesz.com/list//field//value/ Metódus GET Kötelező paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak az e‐mail listának az azonosítója, amelyből a feliratkozó adatait lekérdezi. Opcionális paraméterek id: a feliratkozó azonosítója, akinek az adatait lekérdezi. field_name: annak a mezőnek a neve, amelynek értéke alapján beazonosítja a felhasználót, akinek az adatai lekérdezi. field_value: annak a mezőnek az értéke, amely alapján beazonosítja a felhasználót, akinek az adatai lekérdezi. Ha opcionális paraméterek nélkül kerül meghívásra a list metódus, akkor a listában lévő összes rekordot visszaadja. A paramétert urlencode‐olva kell átadni. Válasz Sikeres lekérdezés esetén a body értéke: a feliratkozó adatai asszociatív JSON tömbbe rendezve. Sikertelen lekérdezés esetén a body értéke: üres.

3.4 Leiratkozás A megadott feliratkozót leiratkozott állapotúvá teszi. Amíg a feliratkozónak ilyen a státusza nem történik a részére levélküldés. A leiratkozás metódust vagy a feliratkozó azonosítója (id) vagy az e‐mail címe (email) alapján lehet paraméterezni. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/unsubscribe//record/ http://<username>:<password>@restapi.emesz.com/unsubscribe//email /<email> Metódus GET 4. oldal


Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak az e‐mail listának az azonosítója, amelyről a feliratkozótleíratja. id: a feliratkozó azonosítója, akit leiratkoztat. email: a feliratkozó e‐mail címe, akit leiratkoztat. Válasz Sikeres leiratkoztatás esetén a body értéke: 1 Sikertelen leiratkoztatás esetén a body értéke: 0

3.5 Feliratkozó törlése A feliratkozót véglegesen és visszavonhatatlanul törli az e‐mail listából. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/delete//record/ Metódus DELETE Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak az e‐mail listának az azonosítója, amelyből a feliratkozót törli. id: a feliratkozó azonosítója, akinek a rekordját törli. Válasz Sikeres törlés esetén a body értéke: 1 Sikertelen törlés esetén a body értéke: 0

3.6 Megrendelések rögzítése A metódus lehetővé teszi megrendelések rögzítését egy már létező megrendelés listába. A megrendelés listához létre kell hozni egy megrendelés űrlapot, ezen keresztül működik az API híváson keresztüli megrendelés rögzítés. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/saveOrder//form/<ns_id> Metódus POST

5. oldal


Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. nl_id: annak a listának az azonosítója, melyhez a megrendelés hozzáadásra fog kerülni ns_id: annak a megrendelés űrlapnak az azonosítója, amelyen keresztül a rendelést leadják Kötelező paraméterek shipping_method :A JSON formátumú asszociatív tömbnek minden esetben tartalmaznia kell a shipping_method paramétert. Az értéke a választott szállítási mód azonosítója kell hogy legyen. Ezt az értéket a szoftver kezelőfelületén a bal oldali menü Beállítások / Megrendelés beállítások menüpontjából elérhető képernyőn találja az első oszlopban:

Csak olyan szállítási mód azonosítót adjon meg, amely az űrlaphoz be lett állítva. Megrendelt termékek: Attól függően, hogy milyen típusú megrendelés űrlapot hív meg az API erőforráson keresztül eltérő formátumban kell átadni a megrendelt termék azonosítóját prod_id és a megrendelt darabszámot qty.  

Ha a megrendelő űrlap „Egy termékes megrendelő” vagy „Több termékes megrendelő, de csak egy választható” típusú akkor csak a kiválasztott termék prod_id‐jét kell átadni a prod_idparaméterben. Ha a megrendelő űrlap „Több termékes megrendelés, mindegyikből egy rendelhető” típusú akkor a products nevű tömbben kell átadni a megrendelt termékek prod_id‐jéta többikötelezőparamétermellett. Pl. $data = array('shipping_method' => 10,

'products' =>array( array('prod_id' => 23),

array('prod_id' => 24), array('prod_id' => 25),

array('prod_id' => 26)));

6. oldal


 Ha a megrendelő űrlap „Több termékes megrendelés, mindegyikből több rendelhető” típusú akkor a products nevű tömbben kell átadni a megrendelt termékek prod_id‐jét és a megrendelt mennyiséget qtya többikötelezőparamétermellett. Pl. $data = array('shipping_method' => 10, 'products' =>array( array('prod_id' => 23, qty=> 1),

array('prod_id' => 24, qty=> 2), array('prod_id' => 25, qty=> 3),

array('prod_id' => 26, qty=> 4)));

A példákban php tömböket használtunk a jobb áttekinthetőség végett ezért fontos, hogy a $data php tömböt JSON formátumúra alakítsuk. Ezt a következő utasítással tudjuk megtenni. $data = json_encode($data);

3.7 Adatátadás VCC rendszerből Az MMP‐ből korábban VCC rendszerbe átadott rekord adatainak visszaküldésének fogadása. A visszaküldött adatok alapján az MMP‐ben lévő rekord módosításra kerül. Az MMP eseménynaplóban rögzíti a visszaadott adatokat és a paramétereket. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/vccupdaterecord/<mmsyncid >/project/ <projectid>/record/ Metódus PUT Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. mmsyncid: az összekapcsolás azonosítója. Ezt a MMP adja fixen abban a linkben, amit be kell másolni a VCC kimenő API hívásában. projectid: VCC projekt azonosítója. Ezt az értéket változóként kell megadni a VCC felületén. recordid: VCC rekord azonosítója. Ezt az értéket változóként kell megadni a VCC felületén. Speciális paraméterek A body‐ban átadott JSON formátumú adatok között kell szerepeljen két speciális mező. Ezek segítségével történik a módosítandó rekord beazonosítása a MailMaster‐ben. Az adatok minden MMP által a VCC‐nek átadott rekordban szerepelnek. mssys_vccrecordid: az MMP által a VCC‐nek átadott rekord azonosító, amely a visszaadáskor azonosítja az MMP e‐mail listán belül a módosítandó rekordot. Ha a datatömbbön belül az mssys_vccrecordid értéke ürse, az MMP új rekordot szúr be az e‐mail listába az átadott adatokkal.

7. oldal


Válasz Sikeres adatmódosítás esetén a body értéke: 1 Sikertelen adatmódosítás esetén a body értéke: üres

3.8 Globális változó létrehozása A metódus lehetővé teszi új globális változók létrehozását a MailMaster‐ben. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/createglobalvar Metódus POST Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. Kötelező paraméterek AJSON formátumú asszociatív tömbnek minden esetben tartalmaznia kell az alábbi paramétereket: name: a globális változó neve. Csak az angol ABC betűit és aláhúzást (_) tartalmazhat. html:a globális változó HTML levélben megjelenített értéke. Ez az érték kerül megjelenítésre a szöveges levélben is, ha nincs megadva a text opcionális paraméter. Opcionális paraméterek text:a globális változó szöveges levélben megjelenített értéke. Paraméterek átadása $data = array('name' =>valtozo_neve', 'html' => 'HTMLlevélben megjelenített érték', 'text' => 'Szöveges levélben megjelenített értéke '); A példa egy php tömböt mutat a jobb áttekinthetőség végett.Fontos, hogy az API híváskor a$data php tömb JSON formátumúra legyen alakítva. Ezt a következő utasítással lehet megtenni: $data = json_encode($data); Válasz Sikeres hozzáadás esetén a body értéke: 1

3.9 Globális változó módosítása A metódus lehetővé teszi a globális változók értékeinek módosítását. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/updateglobalvar

8. oldal


Metódus POST Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. Kötelező paraméterek A JSON formátumú asszociatív tömbnek minden esetben tartalmaznia kell az alábbi paramétereket: name: a módosítandó globális változó neve.

Opcionális paraméterek A html és a text paraméterek közül legalább egyiket kötelező megadni! html:a globális változó HTML levélben megjelenített értéke. Ez az érték kerül megjelenítésre a szöveges levélben is, ha nincs megadva a text opcionális paraméter. text:a globális változó szöveges levélben megjelenített értéke. Paraméterek átadása $data = array('name' => 'valtozo_neve', 'html' => ' HTMLlevélben megjelenített érték ', 'text' => ' Szöveges levélben megjelenített értéke '); A példa egy php tömböt mutat a jobb áttekinthetőség végett.Fontos, hogy az API híváskor a $data php tömb JSON formátumúra legyen alakítva. Ezt a következő utasítással lehet megtenni: $data = json_encode($data); Válasz Sikeres módosítás esetén a body értéke: 1

3.10 Globális változó adatainak lekérdezése A metódus lehetővé teszi a globális változó adatainak lekérdezését. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/getglobalvar/name/ Metódus GET 9. oldal


Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. name: a globális változó neve Válasz Sikeres lekérés esetén a visszatérési érték egy JSON formátumú asszociatív tömb, amely a globális változó értékeit tartalmazza. {"html":" HTML érték","text":"szöveges érték"} Amennyiben a lekérdezésnek nincs eredménye akkor a visszatérési érték 0 (nulla).

3.11 Termék hozzáadása a terméktörzshöz A metódus lehetővé teszi új termék hozzáadását a terméktörzshöz. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/createproduct Metódus POST Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. Kötelező paraméterek A JSON formátumú asszociatív tömbnek minden esetben tartalmaznia kell az alábbi paramétereket: prod_name: a termék neve prod_price: a termék ára prod_vat_percent: adókulcs prod_currency: valuta (HUF,EUR,USD) prod_sku: termék azonosítója prodcat_ids: azok a termék kategória id‐k tömb formájában, amelyekhez a termék tartozik Paraméterek átadása $data = array(‘prod_name’ =>’E‐book', ’prod_price’ =>’1000', ’prod_vat_percent’ =>’27 ', ’prod_currency’ =>’HUF', ’ prod_sku’ =>’termék azonosítója',

10. oldal


’prodcat_ids’ =>array(‘123’) ); A példa egy php tömböt mutat a jobb áttekinthetőség végett.Fontos, hogy az API híváskor a $data PHP tömb JSON formátumúra legyen alakítva. Ezt a következő utasítással lehet megtenni: $data = json_encode($data); Válasz Sikeres hozzáadás esetén a body értéke: 1

3.12 Termék módosítása A metódus lehetővé teszi egy adott termék adatainak módosítását. Erőforrás URL‐je http://<username>:<password>@restapi.emesz.com/modifyproduct/<prod_id> Metódus POST Paraméterek username: az MMP API felhasználónév. password: MMP API jelszó. Opcionális paraméterek prod_name: a termék neve prod_price: a termék ára prod_vat_percent: adókulcs prod_currency: valuta (HUF,EUR,USD) prod_sku: termék azonosítója prodcat_ids: azok a termék kategória id‐k tömb formájában, amelyekhez a termék tartozik Válasz Sikeres módosítás esetén a body értéke: 1

4. HTTP státuszkódok Az erőforrás kérések válaszának HTTP státusz kódja az alábbiak valamelyike lehet. 200 : Sikeresen végrehajtott művelet 401: authentikáció sikertelen, rossz felhasználónév vagy jelszó 404: ismeretlen erőforrás 405: érvénytelen metódus 11. oldal


406: hibás paraméterek

12. oldal

MailMasterPlus API. fejlesztői dokumentáció

Recommend Documents