Struktura API požadavků
API služby ProfiSMS (dále jen API) slouží ke komunikaci mezi aplikací a službami ProfiSMS. API je umístěné na adrese
https://api.profisms.cz
. Obecně API je veřejnou službou, a na základní funkcionalitu není potřeba žádné povolení.
Stačí se zaregistrovat pro používání služeb ProfiSMS. Některé služby ale musí mít uživatel API povolené od provozovatele.
Základní vlastnosti API
Jedná se o HTTP API, tedy o API používající standardizované metody pro přenos dat. API přijímá požadavky GET i POST bez rozdílu. Na způsobu předání nezáleží. Výsledek je vrácen jako JSON (česky). Všechny parametry API musí být v UTF-8 kódování. Výsledek je v UTF-8 kódování.
Logické hodnoty jsou reprezentovány čísly 1 pro true a 0 pro false.
Služby
Funkcionalita ProfiSMS se zkládá ze 4 služeb:
V následujícím popisu najdete název služby a následně její identifikátor pro použití v API.
- Základní rozhraní - general
-
Služba definující základní práci s objekty shodnými pro všechny ostatní služby. Např. uživatelské účty.
API této služby je dostupné pro všechny uživatele.
- SMS - sms
-
Služba pracující s běžnými SMS, wappushemi, apod. Zasílání a přijímání SMS, doručenek, apod.
API této služby je dostupné pro všechny uživatele.
- Prémiové SMS - prsms
-
Služba pracující s Prémiovými SMS (sms se zvýšeným tarifem).
API této služby není běžně dostupné pro uživatele.
- WAP platby - wappayment
-
Služba umožnující platbu pomocí mobilního telefonu.
API této služby není běžně dostupné pro uživatele.
Základní parametry požadavku
Každý požadavek musí obsahovat 5 základních parametrů:
- CTRL
- Definice akce. Tento parametr definuje, co se má provést. Hodnotou parametr je výčtový typ. Hodnoty jsou typu řetězce. Specifikaci hodnot naleznete v dalších částech, které se týkají už konkrétních akcí.
- _login
-
Přihlašovací jméno uživatele.
- _service
- Identifikátor služby. Každá funkcionalita API je přiřazená právě jedné službě, tento parametr musí odpovídat tomuto přiřazení.
- _call
- Identifikátor volání. Pro každé volání API od daného uživatele musí být tento parametr unikátní. Hodnotou je libovolný řetězec či číslo. Parametr slouží k zamezení duplicitních volání API a k podpisu odpovědi ze strany API (vizte níže).
- _password
-
Heslo pro dané volání API. Toto heslo je částečně vytvořeno z hesla uživatele a tím jej autorizuje a částečně z parametru _call, čímž zabraňuje jeho odposlechnutí (resp. v případě odposlechnutí je toto heslo nepoužitelné, jelikož je závislé na parametru, který musí být unikátní pro každý požadavek).
Způsob výpočtu:
_password = md5(md5(HESLO) + _call)
, kdemd5()
je funkce vypočítávající MD5 hash řetězce, HESLO je heslo uživatele pro přihlášení do ProfiSMS a _call je unikátní identifikátor volání (vizte výše). Operátor+
reprezentuje operátor pro spojení řetězců.Před dalším použitím, nebo předáním výsledku funkce
md5()
je nutné výsledek převést na malá písmena.
Na pořadí parametrů v požadavku nezáleží.
V případě přihlášeného uživatele lze místo parametrů _login a _password používat session.
$login = 'user'; // uživatelské jméno $call = microtime(true); // unikátní identifikátor $password = md5(md5("heslo").$call); // heslo pro autorizaci // Vytvoření URL pro volání API. $url = "https://api.profisms.cz?" . http_build_query(array( "CTRL" => "test", "_login" => $login, "_service" => "general", "_call" => $call, "_password" => $password, )); /* samotné URL bude vypadat: https://api.profisms.cz/index.php?CTRL=test&_login=user &_service=general &_password=2384d2267c2a783482aaea70c0ce1e1b &_call=1293487628.2969 */ // Volání API. $result bude obsahovat výsledek. $result = join("", file($url));
Ukázka jedna obsahuje existující volání (CTRL = test
). Jedná se o testovací volání, neprovádí žádnou akci.
Toto testovací volání, používejte při implementaci API. Výše uvedený kód je funkční tak, jak je zobrazen (pouze je nutné
nahradit přihlašovací jméno a heslo za Vaše).
Volání API může obsahovat další parametry, jejich název a hodnota záleží na konkrétní akci. Tyto parametry budou popsané u jednotlivých API.
Formát odpovědi
Odpověď je ve formátu JSON.
Odpověď na platný požadavek
- Popis chyby - error
- Jedná se o objekt s vlastnostmi code a message. Vzhledem k tomu, že se jedná o správnou odpověď, hodnoty těchto vlastností jsou vždy 0 a OK (vizte ukázku 2).
- Vlastní odpověď na požadavek - data
- Vlastnost obsahuje data závislá na požadavku. Typ této vlastnosti a možné hodnoty jsou popsané u jednotlivých požadavků.
- Doba zpracování - _time
- Čas potřebný pro zpracování požadavku v sekundách.
- Podpis ze strany API - _key
-
Jedná se o podpis ze strany API, slouží k validaci odpovědi, ověření toho, že odpověď skutečně pochází ze strany ProfiSMS.
Hodnota je vytvořena jako
md5(md5(HESLO) + _password)
. Kdemd5()
je funkce vypočítávající MD5 hash řetězce, HESLO je heslo uživatele pro přihlášení do ProfiSMS a _password je hodnota parametru _password, která byla předána v požadavku. Operátor+
reprezentuje operátor pro spojení řetězců.
Odpověď může obsahovat další parametry _POST, _GET, _WEBSOCKETSMS, které obsahují parametry požadavku.
{ "error": { "code":0, "message":"OK" }, "data": { "text":"n\u011bco", "number":55.78, "array":["a", "b", 1, 2], "object": { "name":"John", "surname":"Doe" } }, "_time":0.29474782943726, "_key":"64a63a8bcbbe770da3cf5c5772903a06" }
Ukázka 2 demonstruje odpověď na testovací volání (vizte ukázku 1). V případě testovacího volání jsou výsledná data (vlastnost data výsledného objektu) vždy shodná.
Formát odpovědi na chybný požadavek
Formát odpovědi je podobný, jako v případě platného požadavku.
- Popis chyby - error
- Jedná se o objekt s vlastnostmi code a message. Definice a významy možných chyb najdete v popisu chybových konstant
- Vlastní odpověď na požadavek - data
- Parametr může být prázdný, nemá význam.
- Podpis ze strany API - _key
- Parametr neexistuje.
Odpověď může obsahovat další parametry _POST, _GET, _WEBSOCKETSMS, které obsahují parametry požadavku.
{ "error": { "code":4, "message":"UNKNOWN_SERVICE" }, "data":{ }, "_time":0.27647018432617 }