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). Where md5() 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). Where md5() 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
}