MailMasterPlus API fejlesztői dokumentáció
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. http://<username>:<password>@restapi.emesz.com/subscribe/<nl_id>/form/<ns_id> POST 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
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. 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. http://<username>:<password>@restapi.emesz.com/update/<nl_id>/form/<ns_id> /record/<id> VAGY http://<username>:<password>@restapi.emesz.com/update/<nl_id>/form/<ns_id>/field/ <field_name>/value/<field_value> PUT 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 <field_name> 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. 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. http://<username>:<password>@restapi.emesz.com/list/<nl_id> VAGY http://<username>:<password>@restapi.emesz.com/list/<nl_id>/record/<id> VAGY http://<username>:<password>@restapi.emesz.com/list/<nl_id>/field/<field_name>/value/<field_value> GET Kötelező paraméterek 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. 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. http://<username>:<password>@restapi.emesz.com/unsubscribe/<nl_id>/record/<id> http://<username>:<password>@restapi.emesz.com/unsubscribe/<nl_id>/email /<email> GET 4. oldal
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. 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. http://<username>:<password>@restapi.emesz.com/delete/<nl_id>/record/<id> DELETE 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. 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. http://<username>:<password>@restapi.emesz.com/saveorder/<nl_id>/form/<ns_id> POST 5. oldal
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. http://<username>:<password>@restapi.emesz.com/vccupdaterecord/<mmsyncid >/project/ <projectid>/record/<recordid> PUT 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
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. http://<username>:<password>@restapi.emesz.com/createglobalvar POST 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. á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); 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. http://<username>:<password>@restapi.emesz.com/updateglobalvar 8. oldal
POST 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. á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); 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. http://<username>:<password>@restapi.emesz.com/getglobalvar/name/<name> GET 9. oldal
name: a globális változó neve 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. http://<username>:<password>@restapi.emesz.com/createproduct POST 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 á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); 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. http://<username>:<password>@restapi.emesz.com/modifyproduct/<prod_id> POST 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 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
