API pro službu Mobilem.cz, verze XML 5.01 Tento dokument je určen pro partnery Mobilem.cz. Není dovoleno obsah použít pro jiný účel, než za jakým byl poskytnut. Všechna práva vyhrazena pro Crazy Tomato s.r.o. Publikováno: 16.05.2007 1. Obsah API pro službu Mobilem.cz, verze XML 5.01... 1 Publikováno: 16.05.2007... 1 1. Obsah... 1 2. Volání API a identifikace pro partnerské portály... 2 Obecné parametry... 2 3. Volání API a identifikace pro aplikace... 3 Identifikace partnera... 3 Autorizace uživatele v požadavku... 3 4. Formát požadavku... 4 Testovací parametry... 4 Příklad zaslání požadavku... 4 5. Formát odpovědí... 5 status= ok... 5 status= error... 5 Zaslání SMS... 6 6. Zaslání SMS... 6 Vzhled doručenky emailem... 7 Formát předání doručenky na HTTP:... 7 7. Zaslání libovolné binární a textové SMS... 8 8. Vyžádání informací o uživateli... 9 Odpověď... 9
2. Volání API a identifikace pro partnerské portály Pokud Vaše aplikace / portál vyžaduje dočasné přihlášení uživatele pro jeho práci, je třeba využít následující způsob volání, který se vyznačuje parametrem SID Session ID. Po přihlášení je uživateli vygenerován SID, který se následně musí předávat při každém dalším požadavku. Uživatel zůstává přihlášen 10 minut od posledního volání API. Obecné parametry Každý požadavek na API rozhraní obsahuje povinné parametry, které slouží k identifikaci partnera. Tyto parametry jsou: cust hash sid První čtyři písmena z přihlašovacího jména (pro Crazy Tomato login) partnera Přidělený 32 místný identifikátor. Tento identifikátor se nebude měnit. (pozn.: nejedná se o MD5 hesla) Session ID. Není přítomno při prvním požadavku systém jej vygeneruje a zašle zpět jako součást odpovědi. Klíč HASH je každému partnerovi přidělen individuelně a není možné jej libovolně vygenerovat mimo server Crazy Tomato. Jeho přidělení je možné až na základě registrace na Crazy Tomato portálu. Přihlášení se pak provádí příkazem login. Tento způsob identifikace uživatele se vylučuje s následující metodou.
3. Volání API a identifikace pro aplikace Toto volání je zjednodušené a nevyžaduje uchovávání údajů na straně aplikace. Díky tomu je však nutné se při každém požadavku autorizovat. Identifikace partnera Každý požadavek na API rozhraní může obsahovat parametry sloužící k identifikaci partnera. Pokud jsou uvedeny, je využívaná služba přičtená na účet partnera, který pak může získávat smluvní provizi ze služby. Tyto parametry jsou: cust hash První čtyři písmena z přihlašovacího jména (pro Crazy Tomato login) partnera Přidělený 32 místný identifikátor. Tento identifikátor se nebude měnit. (pozn.: nejedná se o MD5 hesla) Klíč HASH je každému partnerovi přidělen individuelně a není možné jej libovolně vygenerovat mimo server Crazy Tomato. Jeho přidělení je možné až na základě registrace na Crazy Tomato portálu. Autorizace uživatele v požadavku Pro některé požadavky API (placené a personifikované služby) je nutné se autorizovat systému: login auth Přihlašovací jméno uživatele Autorizační klíč. Jeho hodnota se spočítá jako MD5 hash následujících informací zapsaných za sebou bez mezer: MD5 hash hesla Přihlašovací jméno Akce Prvních 31 znaků zprávy, pokud je kratší, tak méně. Tedy: md5(md5(heslo)+login+action+substring(msg,0,31))
4. Formát požadavku Partnerská SMS brána Crazy Tomato je umístěna na adrese: http://api.mobilem.cz/xmlapi2.xp Na toto url se zasílají veškeré požadavky na API. Parametry lze zasílat v GET i POST požadavku. Testovací parametry Tyto testovací parametry použijte pouze pro účely vývoje a ladění vašeho portálu. Bez použití vlastních údajů nemůžete sledovat počty registrovaných uživatelů, počet zaslaných SMS a získávat provizi z využívání služeb. cust hash tros c4ca4238a0b923820d49b Příklad zaslání požadavku http://api.mobilem.cz/xmlapi2.xp?cust=tros&hash=c4ca4238&action=listgames &msg=1
5. Formát odpovědí Odpověď na požadavek je zaslána ve formátu XML zprávy. Příklady odpovědí: <?xml version="1.0" encoding="windows-1250"?> <mobilem_api status="ok"> <device> <id>0</id> <name>pro všechny telefony</name> </device> </mobilem_api> Základním tagem je mobilem_api který má povinný parametr status="xx", kde XX je odpověď OK nebo ERROR. status= ok V případě odpovědi OK, se další obsah řídí funkcí, která byl požadována. status= error Příklad chybové odpovědi: <?xml version="1.0" encoding="windows-1250"?> <mobilem_api status="error"> <error> <code>971</code> <message>není vybrána kategorie pro výpis</message> </error> </mobilem_api> Kódy chyb a jejich popis naleznete v následující tabulce: 901 Chyba při přihlášení uživatele (z bezpečnostních důvodů se nerozlišuje chyba jména, nebo hesla) 902 Nízký kredit 903 Služba není aktivovaná 904 Špatný parametr 905 Text SMS je prázdný 906 Číslo příjemce je špatné 907 Špatný AUTH kód 908 Špatný email 909 Tento účet již existuje, ale ještě nebyl aktivován 910 Tento účet již existuje 911 Tento účet již existuje, ale je zablokován 912 Špatný typ obsahu 913 Tento kód neobsahuje žádná data 971 Není vybrána kategorie pro výpis 972 Není vybrán typ pro výpis 995 Pro tuto akci musí být uživatel přihlášen 996 Neznámá akce 997 Chyba při identifikaci partnera 998 Služba není dostupná 999 Služba není dočasně dostupná
Zaslání SMS 6. Zaslání SMS SMS lze zaslat pouze pokud byl uživatel předem přihlášen případně s autorizačními údaji klienta služby mobilem.cz. Parametry pro zaslání SMS: action Hodnota send msisdn Telefonní číslo volajícího, kam bude SMS zaslána. Telefonní číslo může být v mezinárodním formátu (tedy +420xxxxxxxxx) nebo v národním formátu (xxxxxxxxx). Akceptovatelná je i stará nula na začátku. Pokud chcete zaslat na více telefonních čísel stejnou SMS zprávu, oddělte seznam čísel čárkou. msg Text SMS zprávy. Může být libovolně dlouhý, SMS je automaticky rozdělena. recack Doručenka. Pokud je zde nenulová hodnota, je SMS zaslána s doručenkou. Doručenka je zaslána na mail vyplněný v registraci, neníli uvedeno jinak. recackaddr Cíl doručenky. Pokud je vyžadována doručenka (hodnota recack musí být nenulová), je informace o ní zaslána na tuto adresu. Formát je v URI tvaru. Příklady: mailto:email@email.com http://www.doruceno.cz/ok.php delay Nepovinný parametr s časem kdy se má SMS odeslat. Čas je ve formátu: RRRR-MM-DD hh:mm:ss Lze obecně použít všechny formáty podporované příkazem GNU date. Kupříkladu: +1 hour next Monday +1 week 2 days 4 hours 10 September 2003 Uživatel musí mít na svém kontě dostatek prostředků pro odeslání SMS. Tyto prostředky jsou však odečteny až v čase odeslání SMS. Pokud je mezitím vyčerpal, není SMS doručena. Pokud je uvedena adresa pro doručenku, je zaslána informace o nedoručitelnosti. waitfordelivery Pokud chce uživatel přijmout i odpověď která nezačíná jeho přezdívkou, zvolte zde nenulovou hodnotu. Platnost SMS session je 24 hodin. nosave Nenulová hodnota znamená, že se odeslaná SMS neuloží do složky odeslané SMS. split Ovlivňuje způsob dělení SMS zprávy: concat SMS zpráva se rozdělí po 153 znacích a pošle se jako EMS zpráva (respektive NOKIA Smart Messaging) a pak se na telefonech podporujících EMS standard a na NOKIA telefonech spojí opět do jedné dlouhé SMS zprávy. nick Pokud chcete, aby SMS začínala přezdívkou uživatele, uveďte nenulovou hodnotu.
Příklad: http://api.mobilem.cz/xmlapi2.xp?action=send&login=xxxxx&auth=1883c53e0238d04b2504 5effc3322ff8&msisdn=%2B420775xxxxxx&msg=testovci+zprava&recack=1&recackaddr=mai lto%3apavel.mikulka%40crazytomato.com Odpověď má následující formát: <mobilem_api status="ok"> <smsid>8618164</smsid> <price>1.42</price> <credit>81.54</credit> <parts>1</parts> <recackaddr>mailto:</recackaddr> <gwref>-1</gwref> </mobilem_api> price credit parts recackaddr delay smsid Cena zaslaných SMS Zůstatek na účtě mobilem.cz Počet SMS na kolik byl TEXT rozdělen Cíl doručenky. Čas doručení SMS, pokud je zpožděná. Jedinečné ID SMS zprávy která byla odeslána. Pokud je SMS zpráva rozdělena na části, nebo zasíláte na více telefonních čísel, je název parametrů ukončen ještě pořadovým číslem zaslané zprávy (smsid_0, smsid_1, smsid_2, ) Vzhled doručenky emailem == MOBILEM.CZ * <PARTNER> * SMS brána == Vase sms byla dorucena na cislo <MSISDN>. Zpráva: <msg> Formát předání doručenky na HTTP: Po přijetí doručenky SMS bránou, je vyvoláno uložené URL s následujícími parametry: msisdn Telefonní číslo na které byla SMS doručena msg Text SMS zprávy queuetime Čas kdy byla SMS zařazena do fronty deliveredtime Čas kdy byla SMS doručena na mobilní telefon
7. Zaslání libovolné binární a textové SMS SMS lze zaslat pouze pokud byl uživatel předem přihlášen, nebo v případě app_api současně s autorizací. SMS je účtována jako TEXTová SMS pouze v případě, že neobsahuje UDH a je 7mi bitová. V tomto případě je dlouhý text automaticky rozdělen metodou CONCAT do více SMS, pokud je nutné (tyto SMS se na mobilním přístroji zase spojí dohromady). Parametry pro zaslání SMS: action Hodnota binsend msisdn Telefonní číslo volajícího, kam bude SMS zaslána. Telefonní číslo může být v mezinárodním formátu (tedy +420xxxxxxxxx) nebo v národním formátu (xxxxxxxxx). Akceptovatelná je i stará nula na začátku. msg (7bit, bez UDH) Text SMS zprávy. Může být libovolně dlouhý, SMS je automaticky rozdělena. (7bit, UDH) Text SMS zprávy do max velikosti 160 znaků (8bit, UDH) HEXA kódovaný obsah. Je nutné předat UDH. recack recackaddr udh Doručenka. Pokud je zde nenulová hodnota, je SMS zaslána s doručenkou. Doručenka je zaslána na mail vyplněný v registraci, není li uvedeno jinak. Cíl doručenky. Pokud je vyžadována doručenka (hodnota recack musí být nenulová), je informace o ní zaslána na tuto adresu. Formát je v URI tvaru. Příklady: mailto:email@email.com http://www.doruceno.cz/ok.php Hlavička SMS zprávy. Vždy je HEXA kódovaná. Př.: 050003FF0201 (toto je první část ze 2 pro dělené SMS) bits Počet bitů. Akceptovatelných je pouze 7 či 8 waitfordelivery Pokud chce uživatel přijmout i odpověď která nezačíná jeho přezdívkou, zvolte zde nenulovou hodnotu. Platnost SMS session je 24 hodin. Odpovědí jsou tyto hodnoty: <mobilem_api status="ok"> <sid>jyuynwtckqpmi4efav0</sid> <price>1.19</price> <credit>273</credit> <parts>1</parts> <recackaddr /> <smsid>27005</smsid> </mobilem_api> price credit parts recackaddr smsid Cena zaslaných SMS Zůstatek na účtě mobilem.cz Počet SMS na kolik byl TEXT rozdělen Cíl doručenky. Jedinečné ID SMS zprávy která byla odeslána. Pokud je SMS zpráva rozdělena na části, jsou jednotlivá ID oddělena čárkou.
8. Vyžádání informací o uživateli Informace lze získat pouze pokud byl uživatel předem přihlášen. Parametry jsou: action Hodnota info Odpověď Proměnné v odpovědi mají následující význam: login name surname email msisdn credit lastincome auth_phone auth_email Přihlašovací jméno uživatele systému. Křestní jméno uživatele (pokud vyplnil) Příjmení uživatele (pokud vyplnil) Jeho email. Email je ověřený při registraci. (pokud vyplnil) Telefonní číslo uživatele (pokud vyplnil) Stav jeho účtu v korunách. Oddělovačem desetinných míst je TEČKA Datum a čas posledního dobíjení kreditu. Je-li autorizovaný mobilní telefon. Je-li autorizovaný email. account_number 10ti místné číslo sloužící jako variabilní symbol pro platbu bank_number nick nick_active Číslo účtu pro složení zálohy na služby Jméno které si uživatel zvolil jako svojí přezdívku Nenulová hodnota, pokud je NICK aktivován