1. Obsah. Publikováno:

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

technical support: Pavel Mikulka [email protected]

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í: <mobilem_api status="ok"> <device> 0 pro všechny telefony

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: <mobilem_api status="error"> <error> 971 <message>Není vybrána kategorie pro výpis

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 msisdn

msg recack recackaddr

delay

Hodnota „send“ 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. Text SMS zprávy. Může být libovolně dlouhý, SMS je automaticky rozdělena. 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 protected] http://www.doruceno.cz/ok.php 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 <price>1.42 81.54 <parts>1 mailto:[email protected] -1

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

*

*

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 msg queuetime deliveredtime

Telefonní číslo na které byla SMS doručena Text SMS zprávy Čas kdy byla SMS zařazena do fronty Č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 msisdn msg

Hodnota „binsend“ 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. • (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

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 protected] http://www.doruceno.cz/ok.php udh 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 <price>1.19 273 <parts>1 <smsid>27005

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. technical support: Pavel Mikulka [email protected]

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

Přihlašovací jméno uživatele systému.

name

Křestní jméno uživatele (pokud vyplnil)

surname email msisdn credit

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

lastincome

Datum a čas posledního dobíjení kreditu.

auth_phone

Je-li autorizovaný mobilní telefon.

auth_email

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


1. Obsah. Publikováno:

Recommend Documents