API pro službu Mobilem.cz, verze XML 5.01

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