System Requirements Notice Regarding Characters To Be Used Notice Regarding Standard Language Translation Notice Regarding Method For Sending Message To TR ID No Notice Regarding Reporting XML API Error Codes

User Information Control Notice Regarding TR ID No Format Notice Regarding Sender Information Usage Notice Regarding Character Control For Over 160 Character Message Sending Notice Regarding Status Information Control in Reporting SOAP API Error Codes

General

Mobildev XML API is developed for enabling client end requests to be sent to Mobildev SMS Gateway -which has a physical three layer architecture- according to certain standards. These requests utilize XML technology and HTTP protocol.

Using the information provided in this document, software developers can prepare and send XML statements in their own solutions as XMLHTTP request to http://apitc.mobildev.net/xmlapi.aspx , to the gateway, in short. Once the XML statement is sent, it will be processed by XML Parser. If any error is found within the XML statement or within the parameter nodes in the XML statement; a predefined error code will be returned to the sender over HTTP. If there are no errors, an appropriate return statement -that is suitable for the XML - will be prepared and sent back to the sender over HTTP. 

Mobildev SOAP API is developed for enabling client end requests to be sent to Mobildev TR ID SMS Gateway -which has a physical three layer architecture that is developed using SOAP technology- according to certain standards. Software developers can access this service at http://apitc.mobildev.net/api.asmx address (hereinafter will be referred to as gateway)

System Requirements

Following is the minimum system requirements list in order to use Mobildev XML API and SOAP API solutions:

• Windows 98 SE, ME, 2000, XP, UNIX, Linux or MacOS

• Internet Explorer 6 SP1 (for Windows Platform)

• cURL library (for developers using PHP)

User Information Control

Before starting with sending SMS, SMS user information control must be carried out. If you don't have a current SMS account please click HERE to obtain a test account from Mobildev Customer Services.

XML API
When Gateway receives the user information, the system verifies it and sends credit and originator information associated with it. During verification of the user information, username, company_code, password and action information is checked. 

Username: refers to your Mobildev SMS user name.
Company Code: refers to your channel information associated with your SMS user name –also known as client code-
Password: refers to your SMS password associated with your SMS user name. 
Action: it is the parameter node in numerical basis defining for which function the XML statement is sent to the Gateway.

<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>4</Action>
</MainReportRoot>
The below XML statement must be included in the user information control process:
<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>4</Action>
</MainReportRoot>
Sample XML Statement For Information Control:
<MainReportRoot>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>4</Action>
</MainReportRoot>
After the information sent to Gateway is checked, the below values will be returned if the information is correct:
Balance credit<10>
Originator1<10>
Originator2<10>
OriginatorN
After the information sent to Gateway is checked, the below 01 Error Code will be returned if the information is not correct. Error Code 01 means that one or all of the following is incorrect: User Name – Password – Dealer Code. In this case, you must contact with Mobildev Technical Support Team and check your account information.


SOAP API
public string GetInfo(string username, string companycode, string password)
String Username: refers to your Mobildev SMS user name. 
String Company Code: refers to your channel information associated with your SMS user name –also known as client code-. 
String Password: refers to your SMS password associated with your SMS user name.


Sample SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> <GetInfo xmlns="http://www.mobildev.net/"> 
<username>string</username> 
<companycode>string</companycode> 
<password>string</password> 
</GetInfo> 
</soap:Body> 
</soap:Envelope>

Sample Return SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<GetInfoResponse xmlns="http://www.mobildev.net/"> 
<GetInfoResult>string</GetInfoResult> 
</GetInfoResponse> 
</soap:Body> 
</soap:Envelope>
<10> in the return value refers to the LineFeed character. Originator information represents the information that will be displayed as the "Sender" on the target GSM number. This information can be a numeric or alphanumeric statement, consisting of 11 characters, excluding Turkish and special characters like &, <, and, >.

Notice Regarding Characters To Be Used

During sending, the below is not allowed:

• Turkish characters (ç,ş,ü,ö,ğ,Ç,Ü,Ş,Ğ,Ö,İ) .

• ~, ^^, &, <, >, €, £, ã, Ã, ‰, €, ©, ®, ∞, ° signs

• LineFeed, Enter, Tab commands

Within a message, only the following characters are allowed: ( ), [ ], { }, =, *, ?, \, /, %, +, #, !, ", :, ;, _, |

Notice Regarding TR ID No Format

TR ID numbers must be formatted as 11111111111and must be written within TcKimlik parameter node.

Sample Usage:
<TcKimlik>11111111111</TcKimlik>

Notice Regarding Standard Language Translation

If non-ASCII (American Standard Code for Information Interchange) characters were used within the text, use of a language translator will be necessary.

Sample Translator Code:

Notice Regarding Sender Information Usage

Sender Information (Alphanumeric/Originator) is the sender name in the messages. It is 11 characters long and is company specific.  While sending, the exact sender information –provided by the activation unit during account activation- must be quoted within the Originator Parameter node. 06 Error Code will be returned if Sender Information does not match. Error Code 06 means that the Originator information is not defined.

Sample Usage with Upper and Lower Case:

<Originator>MOBILDEV</Originator> 
<Originator>mobildev</Originator>

Notice Regarding Method For Sending Message To TR ID No

Bulk Messages should be sent as bulk packages rather than individual packages. Individual packages cause the system to become busy, consequently, cause the messages to be sent in a delay. Messages should be sent to the Gateway using a single XML statement where possible. 30.000 SMS packages should be preferred In order to avoid possible delays due to internet connection and system overload, recommended SMS package size is 30000.

Mobildev offers 2 types of XML statements for sending XML API SMS:

• SMS To Many

• SMS MultiSenders

SMS to Many XML
SMS To Many statement is used to send the same message to different TR ID numbers. Recommended SMS package size is 30.000. The following is the SMS to Many XML statement:

<MainmsgBody>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>0</Action>
<Mesgbody>message</Mesgbody>
<TcKimlik>TR ID No1, TR ID No2</TcKimlik>
<Originator>originator</Originator>
<SDate></SDate>
</MainmsgBody>

Sample SMS To Many XML Statement
<MainmsgBody>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>0</Action>
<Mesgbody>happy birthday</Mesgbody>
<TcKimlik>11111111111</TcKimlik>
<Originator>MOBILDEV</Originator>
<SDate>010120121530</SDate>
</MainmsgBody>

Username: refers to your Mobildev SMS user name.
Company Code: refers to your channel information associated with your SMS user name –also known as client code-
Password: refers to your SMS password associated with your SMS user name. 
Action: it is the parameter node in numerical basis defining for which function the XML statement is sent to the Gateway.
Mesgbody: refers to the message text to send.
TcKimlik: refers to the target TR ID number.
Originator: refers to the statement which will be displayed as the sender on the GSM number of the recipient TR ID number.
SDate: refers to the time of sending in ddmmyyyyhhmm (DateMonthYearHourMinute) format. 

SOAP
SMSToMany is the function which is used to send the same message to different TR ID numbers. Recipient TR ID numbers must be written with commas to the tcKimlikList which is one of the function parameters.

[WebMetot] 

public string SMSToMany(string username, string companycode, string password, string tcKimlikList, string message, string sdate, string originator)

String Username: refers to your Mobildev SMS user name. 
String Company Code: refers to your channel information associated with your SMS user name –also known as client code-. 
String Password: refers to your SMS password associated with your SMS user name.
String tcKimlikList: refers to the target TR ID number or the target number list that will receive SMS.
String message: refers to the message text to send. This text can be longer than 160 characters.
String sdate: refers to the date of sending. If the field is left blank, sending of message starts immediately. Valid date format 311220120859 (DateMonthYearHourMinute).
String originator: refers to the user name which will be displayed as the sender on the GSM number of the recipient TR ID number.

Sample SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<SMSToMany xmlns="http://www.mobildev.net/"> 
<username>string</username> 
<companycode>string</companycode> 
<password>string</password> 
<tcKimlikList>string</tcKimlikList> 
<message>string</message> 
<sdate>string</sdate> 
<originator>string</originator> 
</SMSToMany> 
</soap:Body> 
</soap:Envelope>

Sample Return SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<GetInfoResponse xmlns="http://www.mobildev.net/"> 
<GetInfoResult>string</GetInfoResult> 
</GetInfoResponse> 
</soap:Body> 
</soap:Envelope>
If you do not input any value to the Originator parameter node, then the initial Originator information which is defined for the user will be used. If you do input any value to the SDate parameter node, then the sending of the messages will start immediately. And if you input a value, then sending of the messages will be performed on that date.Once the XML statement makes its way to the gateway, there will be 2 return values:

• If the operation is successful: TimerID information belonging to the message sending package as "ID: 1234567" will be returned.

• If an error occurred: Please refer to Error Codes

Notice Regarding Character Control For Over 160 Character (Concat SMS) Message Sending

Number of the message depends on the characters used when you type the message text:

SMS MultiSender XML
SMS MultiSenders statement is used to send different messages to different GSM numbers. Recommended SMS package size is 30.000. The below is an example for SMS MultiSenders XML statement:

<MainmsgBody>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>1</Action>
<Messages>
<Message>
<Mesgbody>message1</Mesgbody>
<TcKimlik>TR ID No1</TcKimlik>
</Message>
<Message>
<Mesgbody>message2</Mesgbody>
<TcKimlik>TR ID No2</TcKimlik>
</Message>
</Messages>
<Originator>originator</Originator>
<SDate></SDate>
</MainmsgBody>

Sample MS MultiSenders XML Statement
<MainmsgBody>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>1</Action>
<Messages>
<Message>
<Mesgbody>happy birthday</Mesgbody>
<TcKimlik>1111111111</TcKimlik>
</Message>
<Message>
<Mesgbody>happy new year</Mesgbody>
<TcKimlik>22222222222</TcKimlik>
</Message>
</Messages>
<Originator>MOBILDEV</Originator>
<SDate></SDate>
</MainmsgBody>

SOAP
SMS MultiSenders statement is used to send different messages to different TR ID numbers.

[WebMetot] 
public string MultiSender(string username, string companycode, string password, SMSInfo[] smsInfoArray, string sDate, string originator)

String Username: refers to your Mobildev SMS user name. 
String Company Code: refers to your channel information associated with your SMS user name –also known as client code-. 
String Password: refers to your SMS password associated with your SMS user name.
StringSMSInfo[] smsInfoArray: refers to the array object belonging to the SMSInfo object that contains message text and TR ID number information details. This object consists of 2 fields: 
• String TcKimlikNo 
• String Message
String message: refers to the message text to send. This text can be longer than 160 characters.
String sdate: refers to the date of sending. If the field is left blank, sending of message starts immediately. Valid date format 311220120859 (DateMonthYearHourMinute).
String originator: refers to the user name which will be displayed as the sender on the GSM number of the recipient TR ID number.

Sample SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> 
<MultiSender xmlns="http://www.mobildev.net/"> <username>string</username> 
<companycode>string</companycode> <password>string</password> 
<smsInfoArray> <SMSInfo> 
<TcKimlikNo>string</TcKimlikNo> <Message>string</Message> 
</SMSInfo> <SMSInfo> 
<TcKimlikNo>string</TcKimlikNo> <Message>string</Message> 
</SMSInfo> 
</smsInfoArray> 
<sDate>string</sDate> 
<originator>string</originator> 
</MultiSender> 
</soap:Body> 
</soap:Envelope>
Once the XML statement makes its way to the gateway, there will be 2 return values:
1. If the operation is successful: TimerID information belonging to the message sending package as "ID: 3152005" will be returned.
2. If an error occurred: Please refer to Error Codes

Sample Return SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<MultiSenderResponse xmlns="http://www.mobildev.net/"> 
<MultiSenderResult>string</MultiSenderResult> 
</MultiSenderResponse> 
</soap:Body> 
</soap:Envelope>

Notice Regarding Reporting

Mobildev XML API and SOAP API offer 2 types of reporting options for the SMS messages sent:
• Reporting Basing On Message Sent (TimerID)
• Date Based Reporting


XML
Reporting Basing On Message Sent (TimerID):
The system gives TimerID information for each performed SMS package (XML statement) sending. TimerID is the number that is automatically assigned to the SMS package by the system.

In order to get TimerID (package based) report, the following XML statement must be used and the Action parameter must be 3:
<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>3</Action>
<MsgID>TimerID</MsgID>
</MainReportRoot>

Sample For Getting TimerId Based Report: 
<MainReportRoot>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>3</Action>
<MsgID>65432</MsgID>
</MainReportRoot>

Date Based Reporting:
For reporting basing on date, the Action parameter must be 2.In order to specify date period, Fdate –starting date- and Ldate –ending date- parameters must be input. 

In order to get a report basing on date, the following XML statement must be used:
<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>2</Action>
<FDate>year-month-day</FDate>
<LDate>year-month-day</LDate>
</MainReportRoot>

Sample Date Based Reporting:
<MainReportRoot>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>2</Action>
<FDate>2012-01-01</FDate>
<LDate>2012-03-31</LDate>
</MainReportRoot>

Once XML statement makes its way to Gateway, there will be 2 return values:

1- If the operation successful:"TimerID<32>TR ID No<32>Status<10>"

Example Return Value
65432<32>11111111111<32>2<10> 
65432<32>22222222222<32>3<10>
2- Erroneous Return Value please refer to Error Codes.


SOAP
Reporting Basing On Message Sent (ReportByID):
TimerID (Message Code) based reporting is used for reporting sending actions of a SMS package.

[WebMetot] 

public string ReportByID(string username, string companycode, string password, string packetid)

Sample SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<ReportByID xmlns="http://www.mobildev.net/"> <username>string</username>
<companycode>string</companycode> 
<password>string</password> 
<packetid>string</packetid> 
</ReportByID> 
</soap:Body> 
</soap:Envelope>
1. If the operation is successful:
TimerID<32>TR ID No<32>Status<10>
Sample TimerID Based Reporting Return Value
1234<32>11111111111<32>2<10> 
1234<32>22222222222<32>3<10>
2. If an error occurred: please refer to Error codes

Sample Return SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<ReportByIDResponse xmlns="http://www.mobildev.net/"> 
<ReportByIDResult>string</ReportByIDResult> 
</ReportByIDResponse> 
</soap:Body> 
</soap:Envelope>

Date Based Reporting (ReportbyDate):
Date Based Reporting is used for reporting the SMS sending performed between 2 dates as a whole .

[WebMetot] 

public string ReportByDate(string username, string companycode, string password, string FDate, string LDate)

Sample SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<ReportByDate xmlns="http://www.mobildev.net/"> 
<username>string</username> 
<companycode>string</companycode> 
<password>string</password> 
<FDate>string</FDate> 
<LDate>string</LDate> 
</ReportByDate> 
</soap:Body> 
</soap:Envelope>

1. If the operation is successful:

TimerID<32>TR ID No<32>Status<10>

2. If an error occurred: please refer to Error codes

Sample Return SOAP Data
<?xml version="1.0" encoding="utf-8"?> 
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<ReportByDateResponse xmlns="http://www.mobildev.net/"> 
<ReportByDateResult>string</ReportByDateResult> 
</ReportByDateResponse> 
</soap:Body> 
</soap:Envelope>

Notice Regarding Status Information Control in Reporting

During reporting, for the successfully performed package sending, 3 different status information will be returned:

• "1" means that the message is awaiting,

• "2" means the message is sent,

• "3" means that the message is not delivered.

XML API Error Codes

SOAP API Error Codes