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), kde md5() 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.

ukázka 1: Základní požadavek (implementace v PHP)

$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). Kde md5() 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.

ukázka 2: Odpověď na správný požadavek

{
  "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.

ukázka 3: Odpověď na chybný požadavek

{
  "error":
  {
    "code":4,
    "message":"UNKNOWN_SERVICE"
  },
  "data":{
	},    
  "_time":0.27647018432617
}