Tigrillo API User Guide

Size: px

Start display at page:

Download "Tigrillo API User Guide"

Elwin Parsons
6 years ago
Views:

1 Tigrillo API User Guide Document Reference: 8281 September 2016 Version: 9

2 Version Date Author Changes Number 1 Mar 2015 John Lindsay 2 Sep 2015 Sam Smith Branding updated Updated to be used with 8314 Postman User Guide 3 Apr 2016 Sam Smith Branding Updated 4 June 2016 Sam Smith UnsuspendSIMs description updated 5 Aug 2016 Sam Smith Added mappedmsisdn row to getsims 6 Aug 2016 Sam Smith Updated terminatesims request parameters 7 Sep 2016 Sam Smith Updated getsimlastactivity explanations 8 Sep 2016 Sam Smith Updated introductions to include reference to Postman app 9 Sep 2016 Sam Smith Added php curl example Page 1

3 Contents 1 Preparation Eseye Account Functions ping: getcookiename: login: changepassword: getsims: getsimstateoptions setsimstate: activatesims: suspendsims: unsuspendsims: terminatesims: getsimbilling: getsimlastactivity logout: Coding Examples PHP curl FAQ Versions of API SIM States General Page 2

4 1 Preparation 1.1 Eseye Account When setting up your API the support team at Eseye will give you your portfolioid. You will need this to login. To access the Production API you will also need to supply the static IP address you wish to access from. This document is designed to enable developers to interface with the Tigrillo API offered by Eseye. This document uses the Postman app only as an example, the API is app agnostic. The Postman User Guide can be found at Postman-User-Guide.pdf. 2 Functions 2.1 ping: This function tests whether the server running. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: Page 3

5 pong This indicates that the server is running Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that some JSON text has been entered, delete any content in the text box E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/ping section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" Page 4

6 This indicates that the ping section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - login" This indicates that some JSON text has been entered, delete any content in the text box Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.2 getcookiename: getcookiename returns the name of the HTTP cookie needed for sessions to be continued without the need to log in each time. It does not require a user to be logged in, and it also does not require any JSON formatted text. To test the interface in Postman app use the Page 5

7 details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Click the blue Send button Responses: Successful: In default view, pretty form: This will return "PHPSESSID" In Cookies: Click on the Cookies viewing option. If asked to download the Postman Interceptor follow the instructions in the Cookies section in the Postman User Guide (url: User-Guide.pdf ). Postman displays the Value of the cookie that matches the cookie value in the last successful login Errors: All of these errors are when viewed in the pretty form (default setting) E0001 Invalid input - Syntax error, malformed JSON: "status": Page 6

8 "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that some JSON text has been entered, delete any content in the text box E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/getCookieName section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the getcookiename section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - login" Page 7

9 This indicates that some JSON text has been entered, delete any content in the text box Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.3 login: This function logs the user on. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the three examples with the relevant information enclosed by speech marks. "username" : "exampleusername", Page 8

10 "password" : "examplepassword", "portfolioid" : "exampleportfolioid" Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: enter JSON formatted text. Note replace the three examples with the relevant information enclosed by speech marks. "username" : "exampleusername", "password" : "examplepassword", "portfolioid" : "exampleportfolioid" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status":, "errorcode": "", "errormessage": "", "status": "OK" "cookie": "88djk4qrg39m68lpdupkjiujo4", "permissions": "UAFE", "canactivate": "yes" This indicates a successful login. Page 9

11 "status": "OK" row: This indicates whether the attempt was successful: OK for success, ERR for unsuccessful cookie row: This is an example, yours will be different to "88djk4qrg39m68lpdupkjiujo4". The cookie stores your login details needed for the session to be continued without the need to log again. If you do not log out, but an attempt is made to log in, the previous user will be logged out, regardless of whether the new login attempt is successful. Note the system will only record an attempt to login if the function and JSON format text is entered correctly permissions row: This indicates the account type of the login, this dictates the amount of functions available. The permissions are as follows: Character F A U L T E Permission Finance Admin Standard user Logistics Technical Engineering All of the applicable permissions are indicated canactivate row: This indicates whether the account is permitted to activate SIMs. It will display either yes or no Errors: E0000, Unknown username or password: "status": "code": "E0000", "message": "Unknown username or password" This indicates that your password was entered incorrectly. Page 10

12 E0001, Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002, Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/login section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the login section of the Request URL was not entered. Page 11

13 E0100, Unknown username or password: "status": "code": "E0100", "message": "Unknown username or password" This indicates that one or both of your username, or portfolioid were entered incorrectly F0000, No response provided: "Status": "ERR", "Code": "F0000", "Message": "No response provided" This indicates that the Request URL is missing the s in https or that one or more of the fields were entered incorrectly. Note this is the typing of the field name, for example "password" might have been entered as "passwor" Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ Page 12

2.3.3.2.8 <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly.

14 <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ <!DOCTYPE HTML PUBLIC -//IETF//BTB HTML 2.0//EN > This indicates that the IP Address that you are working from is not registered by Eseye. Contact Eseye Support team to add a static IP Address. 2.4 changepassword: This function changes the password for the account currently logged in. It requires the user to be logged in. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two examples with the relevant information enclosed by speech marks. All passwords must be: minimum of 6 and a maximum of 32 characters and contain one of each of the following: a digit, an uppercase letter, and a lower case letter. "currentpassword" : "examplepassword", "newpassword" : "newexamplepassword" Click the blue Send button. Page 13

15 2.4.2 Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two examples with the relevant information enclosed by speech marks. All passwords must be: minimum of 6 and a maximum of 32 characters and contain one of each of the following: a digit, an uppercase letter, and a lower case letter. "currentpassword" : "examplepassword", "newpassword" : "newexamplepassword" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" Your password has now been changed Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" Page 14

16 This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/changePassword section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the changepassword section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", Page 15

17 "message":"invalid parameter - currentpasswor" This indicates that the parameter being reported is invalid. Either currentpassword or newpassword are misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0116 Invalid password: "status": "code": "E0116", "message": "Invalid password" This indicates that the new password does not meet the criteria specified (All passwords must be: minimum of 6 and a maximum of 32 characters and contain one of each of the following: a digit, an uppercase letter, and a lower case letter) E0126 Passwords don t match: "status": Page 16

18 "code": "E0126", "message": "Passwords don t match" This indicates that the Request URL is missing the s in https or that the currentpassword field does not match your existing password Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.5 getsims: This function returns a list of SIM data. It requires the user to be logged in. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Page 17

19 Text box: Enter the following JSON formatted text. Note replace the nine null s in the JSON as required. For more information on the JSON fields see section JSON fields. "searchcriteria" : "state" : null, "group" : null, "tariff" : null, "matchstring" : null, "matchtype" : null, "matchfields" : null, "sortorder" : null, "startrec" : null, "numrecs" : null Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the nine null s in the JSON as required. For more information on the JSON fields see section JSON fields. "searchcriteria" : "state" : null, "group" : null, "tariff" : null, "matchstring" : null, "matchtype" : null, "matchfields" : null, "sortorder" : null, Page 18

20 "startrec" : null, "numrecs" : null Click the blue Send button JSON fields: The fields ( state, group, tariff, matchstring, matchtype, matchfields, sortorder, StartRec, and numrecs ) are all optional. If you do not wish to use any of these search criteria, enter null as the input (as shown in the examples, without speech marks). If you do wish to use any of the fields to narrow the search criteria then ensure that null is replaced by a value enclosed in speech marks. If null is entered as input for all parameters, all SIMs will be returned, in ascending order of ICCID number state : This field determines which state of SIM cards will be displayed. The available options are; suspended, terminated, and provisioned group : This field determines which Group Name of SIM cards will be displayed. Group names can be set for collections of SIMs when activating them using the activatesims function 2.8 or through the SIAM portal tariff : This field determines which tariff ID of SIM cards will be displayed. Tariff ID are usually four numerical digits in length (for example 2356) matchstring : This field determines which string of information you want to match (i.e. receive responses which match your string of information). This field needs the matchtype and matchfields to be filled matchtype : This field determines the type of match to be made, used in conjunction with the matchstring and matchfields. The options are: S, E, C, and M, these respectively stand for: starts with, ends with, contains, and matches. If this field is entered incorrectly then the entire estate of SIM cards will be returned matchfields : This field determines the field of information to match, used in conjunction with the matchstring and matchtype. Enter either the relevant Field or Indicator from the table below: Field Indicator FriendlyName F MSISDN M IMSI S ICCID I IMEI E IP Address A If this field is entered incorrectly then the entire estate of SIM cards will be returned. Page 19

21 sortorder : This determines what factor the SIM cards will be ordered by. Enter either the relevant Field or Indicator from the table below: Sort by Indicator FriendlyName F MSISDN M IMSI S ICCID I IMEI E IP Address A If this field is entered incorrectly then the SIM cards will not be sorted by an indicator startrec : This determines the number of the first SIM card to be returned (the records having been ordered as you specified in sortorder). The default is: null and 0, they both display all of the results, 1 doesn t display the first result, 2 doesn t display the first two results, and so on numrecs : This determines how many SIM cards will be displayed. null displays all SIM cards, 1 displays one and 2 displays two and so on Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "totrecs": 29, "sims": [ ], "status": "MSISDN": , "friendlyname": "SHIELD", "ICCID": " ", "ipaddress": " ", "group": null, "status": "provisioned", "alert": "", "controls": "SU" "status": "OK", Page 20

22 "errorcode": "", "errormessage": "" totalrecs row: This displays the number of records displayed MSISDN row: This displays the Mobile Station International ISDN Number (MSISDN) of the SIM card friendlyname row: This displays the name assigned to help identify the SIM card. This can be altered in the SIAM portal ICCID row: This displays the integrated circuit card identifier (ICCID) of the SIM card "ipaddress" row: This displays the Internet Protocol address, the unique string of numbers separated by full stops group row: This displays the name assigned to help identify a group of SIM cards. This can be altered in the SIAM portal status row: This displays the status of the SIM card. It will be either available, suspended, terminated, or provisioned alert row: This currently is not used to display any information controls row: This displays whether the SIM card can be sent a control message. This is displayed as an S for SMS, U for USSD, US for both USSD and SMS, and blank means neither are permitted "mappedmsisdn" row: This displays the any foreign number mapped on to the SIM card Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": Page 21

23 "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in 2.5 of this guide. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/getSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the getsims section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", Page 22

24 "code":"e0005", "message":"invalid parameter - sortorde" This indicates that the parameter being reported is invalid. Either a parameter is misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: Page 23

25 This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.6 getsimstateoptions This function returns a list of the possible states that a particular SIM card can be put into. It requires the user to be logged in, and the ICCID of the SIM (this can be found using the getsims function). To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the input with the relevant ICCID enclosed by speech marks. "ICCID" : "input" Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the input with the relevant ICCID enclosed by speech marks. "ICCID" : "input" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Page 24

26 Successful: If your request is successful a response will display as follows: "status":, "status": "OK", "errorcode": "", "errormessage": "" "stateoptions": [ ], "ID": "suspend", "title": "Suspend SIM" "ID": "terminate", "title": "Terminate the SIM" State Options suspend Suspend SIM This indicates that the SIM card can be suspended, if suspended the SIM will stop connecting to the network and continue to be billed for the service charge. This is instant and can be reversed. If suspend and terminate are returned together the SIM is active terminate Terminate the SIM This indicates that the SIM card can be terminated, if terminated the SIM will stop connecting to the network and will stop the service charge being billed (if the SIM is still in contract the customer is liable for the rest of the service charges up until the end date of the contract). This is not instant as it needs Eseye verification. If suspend and terminate are returned together the SIM is active. If active and terminate are returned together the SIM is suspended active Reactivate the SIM This indicates that the SIM card can be activated, if activated the SIM will start connecting to the network and could get billed for overage. This is instant and can be reversed. If active and terminate are returned together the SIM is suspended. Page 25

27 "reason": "English language reason for why there are no options" This indicates that the SIM card has no states that it can be altered into. It will state why the Sim is unable to change state. Errors: Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/getSIMStateOptions section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", Page 26

28 "message": "API version not recognized" This indicates that the getsimstateoptions section of the Request URL was not entered E0004 Missing Parameter: This error message will appear as below: "status": "code": "E0004", "message": "Missing parameter - ICCID" This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - CCID" This indicates that the parameter being reported is invalid. Either ICCID is misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: "status": "code": "E0006", Page 27

29 "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: "status": "code": "E0137", "message": "Invalid SIM no. provided" This indicates that the ICCID is not one associated with the account currently logged in Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: Page 28

30 This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.7 setsimstate: This function sets the state of a single SIM, allowing for suspension suspend, activation and reactivation active, and termination terminate. It does not allow for activation of a single SIM, for which the activatesims function 2.8 is required. If you wish the set a new state for multiple SIMs you should use one of suspendsims 2.9, unsuspendsims 2.10, or terminatesims It requires the user to be logged in 2.3 and the ICCID of the SIM card. It also requires the state the SIM card is to be changed into, to verify the possible states that a SIM can be altered to follow section 2.6 getsimstateoptions. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two input s with the relevant information enclosed by speech marks. The possible options for input are: suspend, active, and terminate. "ICCID" : "input", "state" : "input" Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two input s with the relevant information enclosed by speech marks. The possible options for input are: suspend, active, and terminate. Page 29

31 "ICCID" : "input", "state" : "input" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" The SIM is now in the state requested Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: Page 30

32 "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/getSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the setsimstate section of the Request URL was not entered E0004 Missing parameter: "status": "code": "E0004", "message": "Missing parameter - state" This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", Page 31

33 "code":"e0005", "message":"invalid parameter - CCID" This indicates that the parameter being reported is invalid. Either a parameter is misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: "status": "code": "E0137", "message": "Invalid SIM no. provided" This indicates that the ICCID number was entered incorrectly E0139 SIM cannot change state: SIM is pending termination: "status": Page 32

34 "code": "E0139", "message": "SIM cannot change state: SIM is pending termination" This indicates that the SIM card is awaiting termination, if this was requested accidently then contact the Eseye Support Team immediately E0140 Invalid state requested: "status": "code": "E0140", "message": "Invalid state requested" This indicates that the state requested was entered incorrectly. Either through a spelling error, or because the state requested is unavailable for the SIM. To verify if the state is available for the SIM use the getsimstateoptions function E0142 Cannot activate SIM via this route "status": "code": "E0142", "message": "Cannot activate SIM via this route" This indicates that the Sim card cannot be activated over the API, please contact Eseye Could not get any response: Page 33

35 This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ SIM is pending activation: This response means that a request has already been made for this SIM to be activated. If you are using the Staging server, this request will not be executed, so if you wish to 'reset' the SIM (in order that you can test the activation process again), contact Eseye. 2.8 activatesims: This function activates single or multiple SIMs. It requires the user to be logged in 2.3 and the ICCID of the SIM card. It also requires the Tariff ID that the SIM card will be on (should it not have been pre provisioned). It also requires the Friendly Name, Group Name, IMEI, and Device ID should you wish these to be assigned at activation. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Page 34

36 Text box: Enter the following JSON formatted text. Note replace the nine null s in the JSON as required. For more information on the JSON fields see section JSON fields and the IMEI field row does not end in a comma. "sims" : [,, "ICCID" : "exampleiccid", "friendlyname" : null, "IMEI" : null "ICCID" : "exampleiccid2", "friendlyname" : null, "IMEI" : null "ICCID" : "exampleiccid3", "friendlyname" : null, "IMEI" : null ], "tariffid" : null, "group" : null, "device" : null In the above example three SIM cards have been activated. More or fewer can be entered as desired according to the following pattern: "ICCID" : "exampleiccid", "friendlyname" : null, "IMEI" : null Click the blue Send button Staging: Production: Request URL: Page 35

37 Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the nine null s in the JSON as required. For more information on the JSON fields see section JSON fields and the IMEI field row does not end in a comma. "sims" : [,, "ICCID" : "exampleiccid", "friendlyname" : null, "IMEI" : null "ICCID" : "exampleiccid2", "friendlyname" : null, "IMEI" : null "ICCID" : "exampleiccid3", "friendlyname" : null, "IMEI" : null ], "tariffid" : null, "group" : null, "device" : null In the above example three SIM cards have been activated. More or fewer can be entered as desired according to the following pattern: "ICCID" : "exampleiccid", "friendlyname" : null, "IMEI" : null Click the blue Send button. Page 36

38 2.8.3 JSON fields: The fields ( friendlyname, IMEI, tariffid, group, and device ) are all optional. If you do not wish to alter any of these during activation, enter null as the input (as shown in the examples, without speech marks). If you do wish to enter any of the fields to improve the ability to identify the SIM card, ensure that null is replaced by the correct value enclosed in speech marks ICCID mandatory: This field defines the SIM cards to be activated, it can be found by getsims 2.5. The ICCID is a numerical value.it must be enclosed by speech marks friendlyname optional: This field defines the name assigned to the each SIM, it is used to help identify the SIM later. Friendly Names must be less than 128 characters long and not include commas. It must be enclosed by speech marks. Should you not wish to change a friendly name from what it is already set as or not use one enter null, as seen in the example above. Should you wish to remove an existing Friendly Name, enter an empty string, or two speech marks: IMEI optional: This field defines the code of the device that the SIM card is being put into to help identify the SIM later. This can be changed on the SIAM portal. It must be enclosed by speech marks. Should you not wish to change an IMEI already set or not use one enter null, as seen in the example above. Should you wish to remove an existing IMEI, enter an empty string, or two speech marks: tariffid optional: This field defines the four digit code of the payment details of the SIM. It must be enclosed by speech marks. If every SIM already has a package assigned through preprovisioning, null can be entered, as seen in the example above. You are notified of your tariff ID during contract signing. contact Eseye if you are unable to remember it group optional: This field defines the name assigned to a number of SIMs, it is used to help identify the SIMs later. It must be enclosed by speech marks. Should you not wish to change a group name already set or not use one enter null, as seen in the example above. Should you wish to remove an existing group name, enter an empty string, or two speech marks: device optional: This field defines the identifying code of the hardware model provided by Eseye, to help identify the SIM later. This can be changed on the SIAM portal. It must be enclosed by speech marks. Page 37

39 Should you wish to not change a device ID already set or not use one enter null, as seen in the example above. Should you wish to remove an existing IMEI, enter an empty string, or two speech marks: Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status":, "status": "OK", "errorcode": "", "errormessage": "" "simstatuses": " ":, "ICCID": " ", "status": "OK" " ": "ICCID": " ", "status": "AUTO" status" row: "OK": This indicates that the request has been sent to the provisioning team, as displayed with exampleiccid "AUTO": This indicates that the SIM has been scheduled for activation and should be on the network within five minutes, as displayed with exampleiccid Errors: Please note that if an error message is received none of SIMs have been activated. Even if the error code refers to one or only some of the SIMs. Page 38

40 E0001 Invalid input ExampleICCID cannot be activated: "status":, "errorcode": "See simerrors for details", "errormessage": "" "simerrors": " ": "E0001:Invalid input cannot be activated" This indicates that the SIM cannot be activated. To verify that the SIM can be activated follow section 2.6 getsimstateoptions. Note is an example E0001 Invalid input ExampleICCID is not a valid SIM number: "status":, "errorcode": "See simerrors for details", "errormessage": "" "simerrors": " ": "E0001:Invalid input is not a valid SIM number" This indicates that the ICCID was entered incorrectly. Note is an example E0001 Invalid input ExampleICCID is not an available SIM: "status": Page 39

41 "errorcode": "See simerrors for details", "errormessage": "", "simerrors": " ": "E0001:Invalid input is not an available SIM" This indicates that the SIM is not available to be activated. To verify that the SIM can be activated follow section 2.6 getsimstateoptions. Note is an example E0001: Invalid input ExampleICCID requires Tariff: "status":, "errorcode": "See simerrors for details", "errormessage": "" "simerrors": " ": "E0001:Invalid input requires a tariff" This indicates that a tariff ID needs to be assigned. Enter the correct tariff ID or if the Tariff ID appears correct, or you have forgotten your tariff ID, contact Eseye E0001 Invalid input Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" Page 40

42 This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/activateSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the activatesims section of the Request URL was not entered E0004 Missing parameter: "status": "code": "E0004", "message": "Missing parameter - sims" Page 41

43 This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - ICCI" This indicates that the parameter being reported is invalid. Either tariffid, group or device are misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0132 Tariff ID is not valid: "status": "code": "E0132", "message": "Invalid tariff selected" Page 42

44 This indicates that the Tariff ID was entered incorrectly. Check that the tariff ID entered is the one agreed in your contract with Eseye. If the Tariff ID appears correct, or you have forgotten your tariff ID, contact Eseye E0133 Device type is not valid: "status": "code": "E0133", "message": "Invalid device type selected" This indicates that the Device ID was entered incorrectly. Contact Eseye if the Device ID appears to be valid and you are still receiving this response E9998 System not available at this moment: "status": "code": "E9998", "message": "System not available at this moment" This indicates that the system is not currently running. Wait and then try again later Could not get any response: Page 43

45 This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ SIM is pending activation: This response means that a request has already been made for this SIM to be activated. If you are using the Staging server, this request will not be executed, so if you wish to 'reset' the SIM (in order that you can test the activation process again), contact Eseye Status : PAY "exampleiccid": "ICCID": "exampleiccid", "status": "PAY" "price" : "1.00" "ccy" : "examplecurrency" This indicates that payment is required before the SIM can be activated, as displayed with exampleiccid3. With this response two rows will appear; price indicates the amount needed to pay, ccy indicates the currency requested. Page 44

46 To pay the outstanding amount log in to SIAM and use the Finance > Transactions > Make Ad-hoc Payment By Credit Card. 2.9 suspendsims: This function suspends multiple SIMs. It requires the user to be logged in 2.3 and the ICCIDs of the SIM cards. It also requires the SIM cards to be able to be suspended, to verify this use section 2.6 getsimstateoptions. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ ] "exampleiccid", "exampleiccid", "exampleiccid", "exampleiccid" Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ "exampleiccid", "exampleiccid", Page 45

47 "exampleiccid", "exampleiccid" ] Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" This indicates that all the listed SIMs have been suspended. If the list of SIMs include some that are unsuccessful the response with display as follows: "status":, "status": "OK", "errorcode": "", "errormessage": "" "simstatuses": " ": "E0137:Invalid SIM no. provided" Use the Errors below to verify the reasons for the errors Errors: E0001 Invalid input - Syntax error, malformed JSON: Page 46

48 "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/suspendSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the suspendsimss section of the Request URL was not entered E0004 Missing parameter: Page 47

49 "status": "code": "E0004", "message": "Missing parameter - sims" This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - ICCID" This indicates that the parameter being reported is invalid. Ensure that sims is the only parameter in the JSON text E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: Page 48

50 "status": "status": "OK", "errorcode": "", "errormessage": "", "simstatuses": " ": "E0137:Invalid SIM no. provided" This indicates that the relevant ICCID was entered incorrectly E0143: SIM cannot be suspended: "status":, "status": "OK", "errorcode": "", "errormessage": "" "simstatuses": " ": "E0143:SIM cannot be suspended" This indicates that the SIM cannot be suspended, to verify that the SIM can be suspended follow section 2.6 getsimstateoptions. Note is an example Could not get any response: Page 49

51 This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.10 unsuspendsims: This function unsuspends multiple SIMs. It can only be achieved after the SIM card has been suspended for two hours. It requires the user to be logged in 2.3 and the ICCIDs of the SIM cards. It also requires the SIM cards to be able to be unsuspended, to verify this use section 2.6 getsimstateoptions. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ "exampleiccid", "exampleiccid", Page 50

52 "exampleiccid", "exampleiccid" ] Click the blue Send button Staging: Request URL: tigrillostaging.eseye.com/japi/tigrillo/unsuspendsims Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ ] "exampleiccid", "exampleiccid", "exampleiccid", "exampleiccid" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" This indicates that all the listed SIMs have been unsuspended. Page 51

53 If the list of SIMs include some that are unsuccessful the response with display as follows: "status":, "status": "OK", "errorcode": "", "errormessage": "" "simstatuses": " ": "E0144:SIM cannot be unsuspended", " ": "E0137:Invalid SIM no. provided" Use the errors codes below to verify the reasoning for the errors Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" Page 52

54 This indicates that the Tigrillo/unsuspendSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the unsuspendsims section of the Request URL was not entered E0004 Missing parameter: "status": "status":"err", "code":"e0004", "message":"missing parameter - sims" This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - ICCID" Page 53

55 This indicates that the parameter being reported is invalid. Ensure that sims is the only parameter in the JSON text E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: "status":, "status": "OK", "errorcode": "", "errormessage": "" "simstatuses": " ": "E0137:Invalid SIM no. provided" This indicates that either the relevant ICCID was entered incorrectly. Note is an example E0144 SIM cannot be unsuspended: "status": Page 54

56 "status": "OK", "errorcode": "", "errormessage": "", "simstatuses": " ": "E0144:SIM cannot be unsuspended" This indicates that either: the SIM cannot be suspended, (to verify that the SIM can be suspended follow section 2.6 getsimstateoptions) or that either cookies are not being stored correctly (to verify that the cookies are not causing the error follow section 2.2 getcookiename) or you are not logged in (to verify that you are successfully logged in follow section 2.3 login). Note is an example Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ Page 55

57 2.11 terminatesims: This function terminates multiple SIMs. It requires the user to be logged in 2.3 and the ICCIDs of the SIM cards. It also requires the SIM cards to be able to be terminated, to verify this use section 2.6 getsimstateoptions. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ ] "exampleiccid", "exampleiccid", "exampleiccid" Click the blue Send button Staging: Request URL: tigrillostaging.eseye.com/japi/tigrillo/terminatesims Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the exampleiccid s with the relevant ICCIDs enclosed by speech marks and ensure that all rows end in a comma except the last ICCID. "sims" : [ ] "exampleiccid", "exampleiccid", "exampleiccid" Page 56

58 Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" This indicates that all the listed SIMs have been terminated. If the list of SIMs include some that are unsuccessful the response with display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "", "simstatuses": " ": "E0144:SIM cannot be terminated", " ": "E0137:Invalid SIM no. provided" Use the errors codes below to verify the reasoning for the errors Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": Page 57

59 "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/terminateSIMs section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the terminatesims section of the Request URL was not entered E0004 Missing Parameter: This error message will appear as below: Page 58

60 "status": "code": "E0004", "message": "Missing parameter - sims" This indicates that the parameter being reported is absent or entered incorrectly, or that the s in the https section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - newpassword" This indicates that the parameter being reported is invalid. Ensure that sims is the only parameter in the JSON text E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E9998 System not available at this moment Page 59

61 "status": "code": "E9998", "message": "System not available at this moment" This indicates that the system is not currently running. Wait and then try again later Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.12 getsimbilling: This function returns billing data for one SIM. It requires the user to be logged in 2.3, the ICCIDs of the SIM cards. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Page 60

62 Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the input with the ICCID enclosed in speech marks and the six null s in the JSON as required. For more information on the JSON fields see section JSON fields. "ICCID" : "input", "startdate" : null, "enddate" : null, "sortorder" : null, "startrec" : null, "numrecs" : null, "filter" : null Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the input with the ICCID enclosed in speech marks and the six null s in the JSON as required. For more information on the JSON fields see section JSON fields. "ICCID" : "input", "startdate" : null, "enddate" : null, "sortorder" : null, "startrec" : null, "numrecs" : null, "filter" : null Click the blue Send button. Page 61

63 JSON fields: The fields ( startdate, enddate, sortorder, startrec, numrecs, and filter ) are all optional. If you do not wish to use any of these search criteria, enter null as the input (as shown in the examples, without speech marks). If you do wish to use any of the fields to narrow the search criteria then ensure that null is replaced by a value enclosed in speech marks ICCID mandatory: This field defines the SIM card for which the billing will be returned, it can be found by getsims 2.5. The input should be a number and enclosed by speech marks startdate optional: This field defines the beginning of the period to be searched for bills. The input should in the format yyyy-mm-dd hh:mm:ss (year-month-date hour:minute:second, if no time is entered then is set as default) and enclosed in speech marks. Should you wish to leave the search period as the most recent number of records (as defined by numrecs ) enter null, as seen in the example above enddate optional: This field defines the end of the period to be searched for bills. The input should in the format yyyy-mm-dd hh:mm:ss (year-month-date hour:minute:second, if no time is entered then is set as default) and enclosed in speech marks. Should you wish to leave the search period as the most recent number of records (as defined by numrecs ) enter null, as seen in the example above sortorder optional: This field defines the order that the results will be counted and presented in. The input is two characters long, with no spaces and enclosed in speech marks. For results ordered by activity the first character is an A, the second character is either A (for ascending, alphabetical order) or D (for descending, reverse alphabetical order). For results ordered by event the first character is an E, the second character is either A (for ascending, oldest result first) or D (for descending, newest result first). Note if no date range has been specified the results will be ordered in descending order only, regardless of the second character. Should you not wish to alter from the default ordering (event, descending) enter null, as seen in the example above startrec optional: This field defines the first record to return, having been sorted by the sortorder function. If you wish the first record to be returned enter 0, with the second enter 1, all enclosed in speech marks. Should you not wish to alter from the default setting (returning the first record) enter null, as seen in the example above numrecs optional: This field defines the amount of results listed. Enter the numerical value desired enclosed in speech marks. If the number entered is more than the total amount of results available (after the results have been sorted by the other parameters) then the maximum available will be displayed. Page 62

64 Should you not wish to alter from the default setting (10 results) enter null, as seen in the example above filter optional: This field defines the type of records that will be returned. Enter as many of the following characters as desired: Character Returns D Data S SMS V Voice Enter the characters without spaces and enclosed in speech marks. Should you not wish to alter from the default setting (all type of records returned) enter null, as seen in the example above Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "totalrecs": 1, "recs": [ ], "activity": "Data", "start": " :26:06", "stop": " :33:39", "description": "Zone 1 Data", "quantity": 2236, "price": "0.00", "mcc": "208", "mnc": "01" "packageid": 1179 "status": "status": "OK", "errorcode": "", "errormessage": "" Page 63

65 totalrecs row: This displays the number of records displayed activity row: This displays the type of activity in the event. It will be either Data, SMS, Voice or Other start row: This displays the beginning time of the event. This is displayed in the format yyyy-mm-dd hh:mm:ss (year-month-date hour:minute:second) stop row: This displays the end time of the event, or if the event is instant like an SMS this will display null. This is displayed in the format yyyy-mm-dd hh:mm:ss (year-month-date hour:minute:second) description row: This displays a text description of the activity. This is how the activity will be described in your SIM contract quantity row: This displays the amount of usage in the event. Data is measured in bytes, SMS by number of messages, and voice is measured in seconds price row: This displays the amount billed for the event. This is rounded to two decimal points and will be in the currency specified in your SIM contract mcc row: This displays the Mobile Country Code, this indicates the country that the device was in when the event occurred. For more information: mnc row: This displays the Mobile Network Code, this indicates the network that the device was using when the event occurred. For more information: packageid row: This displays the reference number of the package that the SIM was on when the event occurred Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": Page 64

66 "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/ section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the getsimbilling section of the Request URL was not entered E0005 Invalid parameter: This error message will indicate the parameter which is invalid. E.g.: "status": "status":"err", Page 65

67 "code":"e0005", "message":"invalid parameter - startdat" This indicates that the parameter being reported is invalid. Either a parameter is misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: This error message will appear as below: "status": "code": "E0006", "message": "Permission denied" This indicates you do not have permission to view the SIMBilling data. This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: "status": "code": "E0137", "message": "Invalid SIM no. provided" This indicates that either the ICCID is not one associated with the account currently logged in or that the s in the https section of the Request URL was not entered Could not get any response: Page 66

68 This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.13 getsimlastactivity This function returns the details of the last activity of the SIM card. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two input s with the relevant information enclosed by speech marks. The possible options for input are: suspend, active, and terminate. "ICCID" : "input" Click the blue Send button. Page 67

69 Staging: Request URL: Command: Post Parameters: Leave blank Options: Body, Raw, and JSON (application/json) Text box: Enter the following JSON formatted text. Note replace the two input s with the relevant information enclosed by speech marks. The possible options for input are: suspend, active, and terminate. "ICCID" : "input" Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "info": "LastLat": " ", "LastLon": " ", "LastRadiusBytes": 13619, "LastUsername": "user", "LastSMS": null, "LastVoice": null, "LastMCC": "234", "LastMNC": "33", "LastLAI": "638", "LastCI": "17153", "LastMCCMNCDate": " :47:04", "LastLAICIDate": " :47:04", "LastRadiusStart": " :48:44", "LastRadiusStop": " :13:22", "MonthsRadiusBytes": 0, Page 68

70 "LastSMSMO": null, "LastSMSMT": " :29:43", "LastVoiceMO": null, "LastVoiceMT": null, "LastUSSDMO": null, "LastUSSDMT": null, "LastIMEI": " ", "LastIMEIDate": " :38:24", "LastIMSI": null, "LastIMSIDate": null, "MonthsDataTotal": , "MonthsDataDate": " :35:14", "MonthsSMSTotal": 0, "MonthsSMSDate": " :35:14", "MonthsUSSDTotal": 0, "MonthsUSSDDate": " :35:14", "MonthsVoiceTotal": 0, "MonthsVoiceDate": " :35:14", "LastSMSMT_DR": null, "LastNetworkName": "GB - EE", "status": "status": "OK", "errorcode": "", "errormessage": "" "LastLat" row: This displays an estimate of the latitude of the SIM card last time it was active "LastLon" row: This displays an estimate of the longitude of the SIM card last time it was active. Page 69

71 "LastRadiusBytes" row: This displays the radius of the area that the last location is found within "LastUsername" row: This is the last username used by the customer to recognise the device, not the SIAM/Tigrillo login of the SIM card "LastSMS" row: This should be ignored "LastVoice" row: This should be ignored "LastMCC" row: This displays the Mobile Country Code of the last mast used by the SIM card "LastMNC" row: This displays the Mobile Network Code of the last mast used by the SIM card "LastLAI" row: This displays the Local Area Identifier of the last mast used by the SIM card "LastCI" row: This displays the cell identifier of the last mast used by the SIM card "LastMCCMNCDate" row: This displays the date of the last Mobile Country Code and Mobile Network Code were calculated "LastLAICIDate" row: This displays the date of the last Local Area Identifier and Cell Identifier were calculated "LastRadiusStart" row: This displays the start date and time of the last data session "LastRadiusStop" row: This displays the end date and time of the last data session "MonthsRadiusBytes" row: This displays the amount of bytes used by the SIM card in the last month (prior to rounding for billing) "LastSMSMO" row: This displays the date and time of the last SMS sent from the SIM card "LastSMSMT" row: This displays the data and time of the last SMS sent to the SIM card "LastVoiceMO" row: This displays the data and time of the last Voice call made from the SIM card. Page 70

72 "LastVoiceMT" row: This displays the date and time of the last Voice call received by the SIM card "LastUSSDMO" row: This displays the date and time of the last USSD message sent from the SIM card "LastUSSDMT" row: This displays the date and time of the last USSD message sent to the SIM card "LastIMEI" row: This displays the last IMEI of a modem used by the SIM card "LastIMEIDate" row: This displays the date and time of the last IMEI reported by the SIM card "LastIMSI" row: This displays the last IMSI used by the SIM card "LastIMSIDate" row: This displays the date and time of the last IMSI reported by the SIM card "MonthsDataTotal" row: This displays the total of the data used over the last month (after rounding for billing) "MonthsDataDate" row: This displays the end date of the last month, used to calculate the data used "MonthsSMSTotal" row: This displays the total SMSs used over the last month "MonthsSMSDate" row: This displays the end date of the last month, used to calculate the SMSs used "MonthsUSSDTotal" row: This displays the total USSDs used over the last month "MonthsUSSDDate" row: This displays the end date of the last month, used to calculate the USSDs used "MonthsVoiceTotal" row: This displays the total amount of voice calls used in the last month "MonthsVoiceDate" row: This displays the end date of the last month, used to calculate the amount of voice calls used "LastSMSMT_DR" row: This displays the date and time of the last delivery receipt. Page 71

73 "LastNetworkName" row: This displays a written description of the last network used by the SIM card Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that the JSON text was structured incorrectly. Check that your JSON text follows the format described in. Note this error can be received due to Microsoft Word style text being entered, as some characters are slightly different between Microsoft Word and ASCII. To avoid this, either type the text in directly, or configure Microsoft Word so that basic ASCII text is entered. To do this, consult section E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" This indicates that the Tigrillo/terminateSIMs section of the Request URL was entered incorrectly E0005 Invalid parameter: This error message will indicate the parameter which is invalid. E.g.: "status": "status":"err", "code":"e0005", Page 72

74 "message":"invalid parameter - iccd" This indicates that the parameter being reported is invalid. Either a parameter is misspelt or an additional parameter has been added. Correct the spelling or delete the additional parameter in the JSON E0006 Permission denied: This error message will appear as below: "status": "code": "E0006", "message": "Permission denied" This indicates you do not have permission to view the SIMBilling data. This indicates that either cookies are not being stored correctly or you are not logged in. To verify that the cookies are not causing the error follow section 2.2 of this document. To verify that you are logged in follow section 2.3 of this document E0137 Invalid SIM no. provided: "status": "code": "E0137", "message": "Invalid SIM no. provided" This indicates that either the ICCID is not one associated with the account currently logged in or that the s in the https section of the Request URL was not entered Could not get any response: Page 73

75 This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ 2.14 logout: This function logs the user off. To test the interface in Postman app use the details shown below, to download a code example of this request use the Generate Code button: Production: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Click the blue Send button Staging: Request URL: Command: Post Parameters: Leave blank Options: Leave as default Text box: Leave blank Page 74

76 Click the blue Send button Responses: All of these responses are when viewed in the pretty form (default setting) Successful: If your request is successful a response will display as follows: "status": "status": "OK", "errorcode": "", "errormessage": "" This indicates a successful logout. To use any functions except ping 2.1 and getcookiename 2.2 a successful login will be needed, follow login Errors: E0001 Invalid input - Syntax error, malformed JSON: "status": "code": "E0001", "message": "Invalid input - Syntax error, malformed JSON" This indicates that some JSON text has been entered, delete any content in the text box E0002 Function not recognised: "status": "code": "E0002", "message": "Function not recognized" Page 75

77 This indicates that the Tigrillo/logout section of the Request URL was entered incorrectly E0003 API Version not recognised: "status": "code": "E0003", "message": "API version not recognized" This indicates that the logout section of the Request URL was not entered E0005 Invalid parameter: "status": "status":"err", "code":"e0005", "message":"invalid parameter - login" This indicates that some JSON text has been entered, delete any content in the text box E0006 Permission denied: "status": "code": "E0006", "message": "Permission denied" Page 76

78 This indicates you are already logged out. If you were expecting to be logged in still this indicates that the cookies are not being stored. To verify that the cookies are causing the error follow section 2.2 of this document Could not get any response: This indicates that either you are not connected to the internet or one or more of the following sections of the Request URL were entered incorrectly. http ://.eseye.com/ <!DOCTYPE html>: This error message will begin as follows: This indicates that one or more of the following sections of the Request URL were entered incorrectly. siam tigrillostaging Japi/ Page 77

SIAM R3.0 USER GUIDE

SIAM R3.0 USER GUIDE Document Reference: 8295 September 2016 Revision: 3 Version Date Author Changes Number 1 Mar 2015 John Lindsay 2 Jun Sam Unsuspending a SIM card description updated. 2016 Smith 3 Sep