api functions - tottoli gsm api functions your server should get our server requests only from...

Representative office in Russia:

+7 (499) 649-60-67 Representative office in Great Britain:

+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

API Functions

Your server should get our server requests only from whitelisted IP addresses. In

turn, our server will get requests only from preliminary provided list of your IP

addresses. Each day you comply files of (for example) csv format, containing detailed

information about all our charges for past 24 hours (each call, SMS, other chargeable

operations). We should have access to those files for example via FTP.

Rate sheets should be sent to FTP or to our e-mail.

Our URL for API: https://78.47.58.234/api.php

1. Authentication in operators’ network.

Your server sends a request to our server.

After subscriber’s attempt to connect to operator’s network (for example, MTS -

Russia), you send us the http (s) request GET or POST with information about

connection attempt. Depending on our response the handset can either connect to the

network or not. Table 1. Network authentication request from your server to ours.

Parameter Description Example

Request type Constant. request_type=lu_auth

identifier Unique network authentication

identifier in your system. lu_id=123456

msisdn of a

subscriber

The telephone number of a

subscriber who initiates the

request.

msisdn=79810002222

unique subscriber

identifiers imsi, iccid, etc.

imsi=2341000000000123 &iccid=8970101000000000001

profile SIM card profile. profile= profile1

Our identifier in

your system

Optional parameter.

For example, our login in your

system or any other key.

account=88888888

mcc, mnc, lac,

cellid

Optional parameter.

Information about base station and

operator.

mcc=250&mnc=01&lac=3333 &cellid=555

IMEI Optional parameter.

IMEI of the handset. imei=358301071214415

cost Optional parameter.

Request cost for us lu_cost=2.5

Variants of our server answers to requests in (for example) JSON format:

Variants 1. Allow to connect to operator.

{"allow":1}

Variants 2. Disallow to connect to operator.

{"allow":0}

https://78.47.58.234/api.php



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

2. Authentication in operators’ GRPS network.


After subscriber’s attempt to connect to DATA access point, you send us the http (s)

request GET or POST with information about connection attempt. Depending on our

response the handset can either connect to the network or not. Table 1. GPRS network authentication request from your server to ours.


Request type Constant. request_type=lu_gprs_auth

identifier Unique network authentication

identifier in your system. lu_gprs_id=123456

msisdn of a

subscriber


subscriber who initiates the

request.

msisdn=79810002222

unique subscriber

identifiers imsi, iccid, etc.

imsi=2341000000000123 &iccid=8970101000000000001


Our identifier in

your system

Optional parameter.



account=88888888

mcc, mnc, lac,

cellid

Optional parameter.


operator.



Request cost for us lu_cost=2.5


Variants 1. Allow to connect.

{"allow":1}

Variants 2. Disallow to connect.

{"allow":0}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

3. Outbound call authentication (camel, not callback).


Making a call attempt, the GET or POST http (s) request gets sent with information

about call attempt. Depending on our response call will either can be allowed or

disallowed.

Table 3. Outbound call authentication request from your server to our server.


Request type Constant. request_type=outbound_call_auth

call identifier Unique call identifier in your

system. call_id=123456

msisdn of a

subscriber


subscriber who initiates a call. msisdn=79810002222

destination

number

The telephone number ought to

receive a call. destination=79003335555

unique subscriber

identifiers imsi, iccid and etc.

imsi=2341000000000123 &iccid=8970101000000000001


Our identifier in

your system

Optional parameter.



account=88888888

mcc, mnc, lac,

cellid

Optional parameter.

Information about base station

and operator.



Request cost for us cost_ab=2.81&cost=2.5


Variant 1. Allow the call, we do the termination part (the SIP connection between our

servers is required). If necessary, we also specify the DID number to use for call redirect

– in this case we will have SIP connection not with you, but with DID number provider.

Subscriber sees msg message on the screen.

{"allow":1, "terminate":1, "did":"78120000001", "msg":"display message"}

Variant 2. Allow the call, you do the termination part:

{"allow":1, "terminate":2, "callerid":"79810002222", "msg":"display message"}

Variant 3. Disallow the call. Subscriber sees msg message on the screen.

{"allow":0, "msg":"display message"}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

4. Authentication of inbound call to MSISDN.


Making a call attempt, the GET or POST http (s) request gets sent with information

about call attempt. Depending on our response call will either can be allowed or

disallowed.

Table 4. Inbound call authentication request from your server to our server.


Request type Constant. request_type=inbound_call_auth

call identifier Unique call identifier in your

system. call_id=123456

msisdn of a

subscriber


subscriber who initiates a call. msisdn=79810002222

Call originator

number

The phone number that belongs to

a calling party. cli=79003335555

unique subscriber


imsi=2341000000000123 &iccid=8970101000000000001


Our identifier in

your system

Optional parameter.



account=88888888

mcc, mnc, lac,

cellid

Optional parameter.


operator.


call cost

Optional parameter.

Cost of one minute of a

call/connection cost, etc.

cost_ab=2.81&cost=2.5


Variant 1. Allow the call, we do the termination part (the SIP connection between our

servers is required)

{"allow":1, "terminate":1}

Variant 2. Allow the call, you do the termination part:

{"allow":1, "terminate":2}

Variant 3. Disallow the call.

{"allow":0}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

1. SMS Received and SMS Sent authentication.


Making an attempt to dispatch / receive SMS, the GET or POST http (s) request gets

sent with information about the attempt. Depending on our response, SMS receiving/

dispatching can either be allowed or prohibited.

Table 5. SMS receiving/dispatching authentication request from your server to our server.


Request type

Constant. Receiving of

inbound SMS or

dispatch of outbound

SMS.

request_type=inbound_sms_auth or request_type=outbound_sms_auth

SMS identifier Unique SMS identifier in

your system. sms_id=123456

msisdn of a subscriber

The telephone number of

our party, which receives

/ sends sms.

msisdn=79810002222

Number of SMS

originator/receiver

The phone number that

belongs to a party that

either sent or received an

SMS

cli=79003335555 or destination=79003335555

text Text of the message text=hello

unique subscriber


imsi=2341000000000123 &iccid=8970101000000000001


Our identifier in your

system

Optional parameter.

For example, our login in

your system or any other

key.

account=88888888

mcc, mnc, lac, cellid

Optional parameter.

Information about base

station and operator.



Cost of SMS cost_ab=2.81&cost=2.5


Variant 1. Allow the receipt / dispatch of SMS.

{"allow":1}

Variant 2. Disallow the receipt / dispatch of SMS.

{"allow":0}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

2. Data authentication.


Making a data call attempt, the GET or POST http (s) request gets sent with information

about data network access attempt. Depending on our response data session will either

can be allowed or disallowed. This request should be sent after (for example) each 1

Mb of traffic used. Table 6. Data authentication request from your server to our server.


Request type Constant. request_type=data_auth

Data connect

attempt identifier

Unique identifier of current data

package authentication in your

system.

data_id=123456

msisdn of a

subscriber


subscriber who initiates a data

session.

msisdn=79810002222

unique subscriber


imsi=2341000000000123

&iccid=8970101000000000001


Our identifier in

your system

Optional parameter.



account=88888888

mcc, mnc, lac,

cellid

Optional parameter.


operator.

mcc=250&mnc=01&lac=3333

&cellid=555


Cost of the session for us cost_ab=2.81&cost=2.5


Variant 1. Allow 1 Mb.

{"allow":1, "byte_limit": 1048576}

Variant 2. Disallow.

{"allow":0}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

5. Dispatch of USSD message and initiation of USSD session. Subscriber is the

initiator.


Subscriber dials ussd command on the handset, you send it to us. Depending on our

answer:

- handset’s screen will show the text of message, ussd session will be closed;

- handset’s screen will show the text of message and session will be continued, so that

subscriber could answer within the session.

Table 7. Request from your server to ours informing about dialed USSD command.


Request type Constant. request_type=ussd

USSD session

identifier

Unique USSD session identifier in

your system. ussd_id=123456

Step number

Step index number within one ussd

session, i.e. first dialog window is

marked as 1, next request within

one USSD session gets index 2, the

next one 3, so on.

ussd_step=1

msisdn of a

subscriber


subscriber who initiates a USSD. msisdn=79810002222

ussd The dialed string itself. For

example, *100# ussd= %2A100%23

unique subscriber


imsi=2341000000000123

&iccid=8970101000000000001


Our identifier in

your system

Optional parameter.



account=88888888

mcc, mnc, lac,

cellid

Optional parameter.


operator.

mcc=250&mnc=01&lac=3333

&cellid=555

call cost Optional parameter.

USSD cost. cost=2.5


Variant 1. Handset’s screen will show the text of message, ussd session will be closed.

{"msg":"display message", "session":"close"}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

Variant 2. Handset’s screen will show the text of message and session will be

continued.

{"msg":"display message", "session":"continue"}

6. GET MSRN number of SIM card.

Our server sends a request to your server.

Table 8. Request from your server to ours for getting of SIM MSRN number.


Request type Constant. request_type=get_msrn

msisdn of a

subscriber

The telephone number of our

subscriber. msisdn=79810002222

login, password

Login and password of ours in your

system or any other way of

authentication.

login=88888888&pass=qwerty


Variant 1. MSRN has been successfully received. Also the answer should contain

information about BTS the subscriber is connected to, if the information is provided

for free.

{"msrn":"79810007799", "profile":"profile1", "mcc":"250", "mnc":"01",

"lac":"3333", "cellid":"555"}

Variant 2. MSRN has been successfully received.

{"msrn":"79810007799", "profile":"profile1", "mcc":"250", "mnc":"01"}

Variant 3. Subscriber is offline. The particular time the subscriber was online.

{"msrn":"offline", "last_time_online":"2016-12-31 23:59:59"}


+7 (499) 649-60-67

Representative office in Great Britain:

+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

7. Receiving of SIM card info.


Using one SIM identifier, we get all other SIM identifiers, list of profiles, current

profile, subscriber’s online status. Example: Table 9. Request from our server to yours for SIM current MSRN number.


Request type Constant. request_type=get_sim_info

One of identifiers Unique SIM identifier: msisdn or

imsi or iccid and others msisdn=79810002222

login, password

Login and password of ours in your

system or any other way of

authentication.

login=88888888&pass=qwerty

Answer:

{

"msisdn":"79810002222",

"imsi":"2341000000000123",

"iccid":"8970101000000000001",

"profiles":[

"profile1", "profile2"

],

"current profile":"profile1"

}

8. Request for all SIMs information.


Request from our server to yours: https://api.yourdomain.com/?request_type=get_allsim_info&login=88888888&pass=qwerqw

Your answer (for example, if there are only 2 SIM cards): { "1":{

"id":1, "msisdn":"79810002222", "imsi":"2341000000000123", "iccid":"8970101000000000001", "profiles":[

"profile1", "profile2"

],



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

"current profile":"profile1" }, "2":{ "id":2, "msisdn":"79810002222", "imsi":"2341000000000124", "iccid":"8970101000000000002", "profiles":[ "profile1", "profile2", "profile3" ], "current profile":"profile3" } }

9. Get subscriber location.


This request is needed in a case the receiving of BTS info is chargeable (otherwise it

is enough to perform the provision of BTS info within point 8 – GET MSRN with

BTS info).

Your answer should contain information about current BTS used by our subscriber

(mcc, mnc, lac, cellid).

Request from our server to yours: https://api.yourdomain.com/?request_type=get_current_location&iccid=8970101000000000001&login=88888888&pass=qwerqw

Your answer: {"iccid":"8970101000000000001", "mcc":250, "mnc":1, "lac":3333, "cid":555}

10. Dispatch of USSD and SMS to our subscriber. Our server is the initiator.


We send USSD or SMS message to our subscriber.

USSD can be:

- a session (show text on screen with opportunity to send an answer by USSD);

- single USSD, show text on screen with no opportunity to answer.

11. Get list of available msisdn.

12. Allocate and untie msisdn to iccid.

13. Account balance request.


In your reply we get an answer to our request.

Our server sends a request to yours: https://api.yourdomain.com/?request_type=get_current_balance&login=88888888&pass=qwerqw

Your answer: {"current balance":"1000.05"}



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

14. Get our account top up history.

15. Get our account deduction history.

16. OTA-server or SMS of 0-class.

17. Request for data session closure.

18. Get API status.


In your response you provide us with current API status, whether it works or not. If it

doesn’t, there should be stated the reason why.

Request from our server to yours: https://api.yourdomain.com/?request_type=get_api_status&login=88888888&pass=qwerqw

Your answer when API works: {"api status":1}

Your answer when API doesn’t work: {"api status":0, "reason":"no balance"}

19. CDR for outbound/inbound calls, outbound/inbound SMS, used data

traffic, USSD sessions.


After each action described in articles 1,2,3,4,5,6,7,12 you send the https request GET

or POST with information about cost, duration, amount of data traffic used, etc. Each

request should have conjunction to unique request identifier. In our response we send

you the confirmation about successful receiving of CDR or not. In a case you don’t

receive our confirmation, it is required to repeat the dispatch of CRD with period (for

example) once in 10 minutes.

Example, CDR after the call is finished: Table 10. CDR information from our server to yours after the call is done.


Request type Constant. request_type=cdr_

outbound_call

call identifier Unique call identifier related to the

particular CDR information. id=123456

msisdn of a

subscriber


subscriber who initiated the call. msisdn=79810002222

unique subscriber


imsi=2341000000000123

&iccid=8970101000000000001

profile SIM card profile at the moment

customer was making the call profile= profile1



+44 (79) 782-409-73

[email protected]

www.tottoli-gsm.com

cost

Total call cost (if it gets calculated

according to several parameters, all

parameters are required).

cost1=0.5&cost2=0.6

Call duration

Call duration (if the call consists of

2 legs (A-leg, B-leg), then the

duration of each leg).

dur1=50&dur2=30

Our identifier in

your system

Optional parameter.



account=88888888

Requests that do not have description are optional (articles 11, 12, 14, 15, 16, 17).

api functions - tottoli gsm api functions your server should get our server requests only from...

Documents