api functions - tottoli gsm api functions your server should get our server requests only from...
TRANSCRIPT
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
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}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
2. Authentication in operators’ GRPS network.
Your server sends a request to our server.
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.
Parameter Description Example
Request type Constant. request_type=lu_gprs_auth
identifier Unique network authentication
identifier in your system. lu_gprs_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
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.
{"allow":1}
Variants 2. Disallow to connect.
{"allow":0}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
3. Outbound call authentication (camel, not callback).
Your server sends a request to our server.
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.
Parameter Description Example
Request type Constant. request_type=outbound_call_auth
call identifier Unique call identifier in your
system. call_id=123456
msisdn of a
subscriber
The telephone number of a
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
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
cost Optional parameter.
Request cost for us cost_ab=2.81&cost=2.5
Variants of our server answers to requests in (for example) JSON format:
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"}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
4. Authentication of inbound call to MSISDN.
Your server sends a request to our server.
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.
Parameter Description Example
Request type Constant. request_type=inbound_call_auth
call identifier Unique call identifier in your
system. call_id=123456
msisdn of a
subscriber
The telephone number of a
subscriber who initiates a call. msisdn=79810002222
Call originator
number
The phone number that belongs to
a calling party. cli=79003335555
unique subscriber
identifiers imsi, iccid and 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
call cost
Optional parameter.
Cost of one minute of a
call/connection cost, etc.
cost_ab=2.81&cost=2.5
Variants of our server answers to requests in (for example) JSON format:
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}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
1. SMS Received and SMS Sent authentication.
Your server sends a request to our server.
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.
Parameter Description Example
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
identifiers imsi, iccid and 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
cost Optional parameter.
Cost of SMS cost_ab=2.81&cost=2.5
Variants of our server answers to requests in (for example) JSON format:
Variant 1. Allow the receipt / dispatch of SMS.
{"allow":1}
Variant 2. Disallow the receipt / dispatch of SMS.
{"allow":0}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
2. Data authentication.
Your server sends a request to our server.
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.
Parameter Description Example
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
The telephone number of a
subscriber who initiates a data
session.
msisdn=79810002222
unique subscriber
identifiers imsi, iccid and 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
cost Optional parameter.
Cost of the session for us cost_ab=2.81&cost=2.5
Variants of our server answers to requests in (for example) JSON format:
Variant 1. Allow 1 Mb.
{"allow":1, "byte_limit": 1048576}
Variant 2. Disallow.
{"allow":0}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
5. Dispatch of USSD message and initiation of USSD session. Subscriber is the
initiator.
Your server sends a request to our server.
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.
Parameter Description Example
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
The telephone number of a
subscriber who initiates a USSD. msisdn=79810002222
ussd The dialed string itself. For
example, *100# ussd= %2A100%23
unique subscriber
identifiers imsi, iccid and 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
call cost Optional parameter.
USSD cost. cost=2.5
Variants of our server answers to requests in (for example) JSON format:
Variant 1. Handset’s screen will show the text of message, ussd session will be closed.
{"msg":"display message", "session":"close"}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
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.
Parameter Description Example
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
Variants of our server answers to requests in (for example) JSON format:
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"}
Representative office in Russia:
+7 (499) 649-60-67
Representative office in Great Britain:
+44 (79) 782-409-73
www.tottoli-gsm.com
7. Receiving of SIM card info.
Your server sends a request to our server.
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.
Parameter Description Example
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.
Our server sends a request to your server.
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"
],
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
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.
Our server sends a request to your server.
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.
Our server sends a request to your server.
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.
Our server sends a request to your server.
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"}
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
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.
Our server sends a request to your server.
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.
Your server sends a request to our server.
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.
Parameter Description Example
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
The telephone number of a
subscriber who initiated the call. msisdn=79810002222
unique subscriber
identifiers imsi, iccid and etc.
imsi=2341000000000123
&iccid=8970101000000000001
profile SIM card profile at the moment
customer was making the call profile= profile1
Representative office in Russia:
+7 (499) 649-60-67 Representative office in Great Britain:
+44 (79) 782-409-73
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.
For example, our login in your
system or any other key.
account=88888888
Requests that do not have description are optional (articles 11, 12, 14, 15, 16, 17).