API request structure
API for ProfiSMS (API) is used for communications between customer's application
and ProfiSMS.
API is located at https://api.profisms.cz
.
API is generally public, next to registration in ProfiSMS, no other permissions are required.
Limited number of functionality must be allowed by administrators.
Basic API properties
API is HTTP based. API accepts GET and POST requests, there are no differences. Response is in JSON format. All request parameters must be in UTF-8 encoding. Response is in UTF-8 encoding.
Logical values are represented by numbers 1 for true and 0 for false.
Services
ProfiSMS functionality contains 4 services:
The list below contains service name and service identifier which is used in API.
- Basic interface - general
-
This service defines basic functionality with objects common for all other services. For example user account.
Service API is available for all users.
- SMS - sms
-
Service for SMS, wappushes and similar messages. Sending and receiving messages, delivery reports, etc.
Service API is available for all users.
- Prémiové SMS - prsms
-
Service working with Premium SMS (SMS with higher tariff).
Service API is not usually available for all users.
- WAP platby - wappayment
-
Service for micropayments using cell phones.
Service API is not usually available for all users.
API request common parameters
Every request must contain 5 general parameters:
- CTRL
- Action definition, what should be done. Parameter type is enumeration of strings. Each particular action described in this documentation defines its action value.
- _login
-
User's login name
- _service
- Service identifier. Each API action belongs to certain service. This relation must be valid.
- _call
- Request identifier. This identifier must be unique for each user's call. Parameter can be string or number. Parameter is used to prevent duplicated requests and to sign response from system (see below)
- _password
-
Password for request. This parameter is created from user's password and parameter _call. This allows system to authorize user and prevents man-in-the-middle attack (if anyone can track/see the request, the request and password is useless, since _call must be unique) .
How to create parameter:
_password = md5(md5(PASSWD) + _call)
. Wheremd5()
is function to compute MD5 hash from string, PASSWD is user's password and _call is unique identifier (see above).+
operator represents operator/function for joining string.Before any additional usage or passing of
md5()
function result, this must be converted to lowercase.
In case of already logged user one can use session instead of _login a _password parameters.
$login = 'user'; // user's name $call = microtime(true); // unique identifier $password = md5(md5("heslo").$call); // password // request URL. $url = "https://api.profisms.cz?" . http_build_query(array( "CTRL" => "test", "_login" => $login, "_service" => "general", "_call" => $call, "_password" => $password, )); /* URL: https://api.profisms.cz/index.php?CTRL=test&_login=user &_service=general &_password=2384d2267c2a783482aaea70c0ce1e1b &_call=1293487628.2969 */ // API call. $result will contain response. $result = join("", file($url));
The first example contain existing action (CTRL = test
).
It is testing action with no functionality.
You should use this testing action while implementing API.
API request can contain additional parameters, their names and values depend on action. Such parameters will be described in each action.
Response format
Response is in JSON format.
Response to valid request
- Error - error
- Object with parameters code and message. In case of correct/valid request, those parameters have always those values: 0 and OK (see example 2).
- Response data - data
- Parameter value is based on request.
- Processing time - _time
- Time used to processed requests (in seconds).
- API response signature - _key
-
Response signature, can be used for request validation (that response is from ProfiSMS).
How is parameter created (and can be validated):
_key = md5(md5(PASSWD) + _password)
. Wheremd5()
is function to compute MD5 hash from string, PASSWD is user's password and _password is parameter from request.+
operator represents operator/function for joining string.
Response can contain additional parameters _POST, _GET, _WEBSOCKETSMS containing request parameters.
{ "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" }
Example 2 shows response to request from example 1 (parameter data is still the same in case of testing request).
Response to invalid request
Response is similar as for valid request.
- Error - error
- Object with parameters code and message. See error constants
- Response data - data
- Parameter can be empty, has no meaning.
- API response signature - _key
- Parameter does not exists
Response can contain additional parameters _POST, _GET, _WEBSOCKETSMS containing request parameters.
{ "error": { "code":4, "message":"UNKNOWN_SERVICE" }, "data":{ }, "_time":0.27647018432617 }