TRNC Bulk SMS API | North Cyprus Bulk SMS API | The Turkish Republic of Northern Cyprus Bulk SMS API | North Cyprus XML API | The Turkish Republic of Northern Cyprus XML API | North Cyprus Bulk SMS XML API


	System Requirements
	Notice Regarding Characters To Be Used
	Notice Regarding Standard Language Translation
	Notice Regarding Method For Sending Bulk SMS
	Notice Regarding Status Information Control In Reporting
	Sample TRNC XML API Codes


	User Information Control
	Notice Regarding GSM Number Format
	Notice Regarding Sender Information Usage
	Notice Regarding Reporting
	Error Codes

General

TRNC XML API is developed for software developers who work with XML documents. With this API, software developers can integrate SMS sending into their applications over XML.

TRNC XML API is our solution that is preferred by software developers as it is a tool that each operating system platform supports and as it can be used with every IDE.

Software developers who can prepare an XML statement in their own solution using the information provided in this document will be able to submit XMLHTTP request to http://api.cyprus.mobildev.net/xmlapi.aspx (will be referred to as Gateway). 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; a predefined error code will be returned to the sender over HTTP. If there are no errors, an appropriate return statement will be prepared and sent back to the sender over HTTP. Predefined error codes will be explained in detail within the document.

System Requirements

Following is the minimum system requirements list in order to use Mobildev XML API solution:

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.

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: is your Mobildev SMS user name.

Company Code: is your channel information associated with your SMS user name –also known as client code-.
Password: is your SMS password.
Action: is the numerical parameter node stating the function for which the Gateway XML statement was sent.

After checking the information sent to Gateway, 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 – company code. In this case, please contact with Mobildev Technical Support Team and check your login details.

An XML statement must contain the following lines for user information control:
<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:

Credits remaining<10> Originator1<10> Originator2<10> OriginatorN

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 GSM Number Format

GSM numbers must be formatted as 05321234567, 5321234567, 905321234567 and written within Numbers parameter node. 04 Error Code will be returned should the GSM numbers are not in appropriate format. Error Code 04 means that the GSM number format is incorrect. In this case, please consider checking the information quoted under Notice Regarding GSM Number Format.

Sample Usage:

Notice: You cannot send should you format numbers as +905321234567, 532 123 45 67, +05321234567 and use - ( ) [ ] { } and etc. characters.

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:

public static string ConvertMessage(string message)
 {
 message = message.Replace("Ü", "U");
 message = message.Replace("ü", "u");
 message = message.Replace("Ğ", "G");
 message = message.Replace("ğ", "g");
 message = message.Replace("İ", "I");
 message = message.Replace("ı", "i");
 message = message.Replace("Ş", "S");
 message = message.Replace("ş", "s");
 message = message.Replace("Ç", "C");
 message = message.Replace("ç", "c");
 message = message.Replace("Ö", "O");
 message = message.Replace("ö", "o");
 message = message.Replace("é", "e");
 message = message.Replace("`", "'");
 message = message.Replace("^", "'");
 message = message.Replace("…", ".");
 message = message.Replace("ˆ", "'");
 message = message.Replace("‘", "'");
 message = message.Replace("’", "'");
 message = message.Replace("‘", "'");
 message = message.Replace("\r", "");
 message = message.Replace("\n", "");
 message = message.Replace("\r\n", "");
 message = message.Replace("?", "##S##");
 message = System.Text.Encoding.ASCII.GetString(System.Text.Encoding.ASCII.GetBytes(message));
 message = message.Replace("?", "");
 message = message.Replace("##S##", "?");
 message = message.Replace("&", "&");
 message = message.Replace("<", "<");
 message = message.Replace(">", ">");
 return message;
 }

Notice Regarding Sender Information Usage

Sender Information (Alphanumeric/Originator), is the sender name in the messages. This name is 11 characters long and is company dependant. 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 should 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: The Originator statement cannot contain Turkish characters and &, <, >, -, ( ), [ ], / signs.

Notice Regarding Method For Sending Bulk SMS

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.

There are 2 XML statements for sending XML SMS API; SMS to Many: where the messages are the same and SMS Multi Senders: where the messages are different.

SMS to Many:

SMS To Many statement is used to send the same message to different GSM numbers. We suggest using 30.000 SMS package. The following is the SMS to Many XML statement:
<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>0</Action> <Mesgbody>message</Mesgbody> <Numbers>GSM No1, GSM No2</Numbers> <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> <Numbers>05421234567,05321234567</Numbers> <Originator>MOBILDEV</Originator> <SDate>010120121530</SDate> </MainmsgBody>

SMS MultiSenders:

SMS MultiSenders is used to send different messages to different GSM numbers. We suggest using 30.000 SMS package. The following is the SMS MultiSenders XML statement:

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

Sample SMS MultiSenders XML Statement
<MainmsgBody> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>1</Action> <Messages> <Message> <Mesgbody>happy birthday to you</Mesgbody> <Number>05427654321</Number> </Message> <Message> <Mesgbody>happy new year.</Mesgbody> <Number>05327654321</Number> </Message> </Messages> <Originator>MOBILDEV</Originator> <SDate></SDate> </MainmsgBody>

Notice Regarding Reporting

Report Basing on TimerID: System will provide TimerID information on each of the SMS package (XML statement) sending. TimerID is the automatically assigned number by the system to each of the SMS packages.

In order to get a TimerID report (basing on package), the following XML statement should be used. The parameter for Action should be 3:

<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>3</Action> <MsgID>TimerID</MsgID> </MainReportRoot>

Sample TimerId Report:

<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>3</Action> <MsgID>65432</MsgID> </MainReportRoot>

Report Basing On Date: For this report, the Action parameter should be 2. For quoting a period use Fdate for starting date and Ldate for ending date.

In order to get a report basing on date, the following XML statement should 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 Report Basing On Date:

<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>2</Action> <FDate>2012-01-01</FDate> <LDate>2012-03-31</LDate> </MainReportRoot>

Once the XML statement makes its way to the gateway, there will be 2 values to return:
1- Successful
2- Error Return Value. Please refer to Error Codes

Notice: Reports may date back to 3 months, the most.

Notice Regarding Status Information Control In Reporting

4 different status values will be returned if the sending of SMS package is successful:

"1" means the message is awaiting;

"3" means the message was sent;

"5" means the message was not delivered;

"6" means the message has expired.

Error Codes

Error Codes	Description
01	Incorrect User Name Incorrect Password Incorrect company code
02	Sending Message: Insufficient credits Invalid ID: No such message (ID) code Reporting: Package was not processed or awaiting at Gateway
03	Undefined Action parameter
04	No Incoming XML
05	Incorrect or missing XML node
06	Undefined Originator Information
07	Missing message code (ID)
08	No SMS were sent for the given dates
09	Date fields are empty - incorrect
10	SMS was not sent
11	Unidentified error
12	Unauthorized access attempt
13	No user was specified for the report

Sample TRNC XML API Codes

	ASP Script		PHP Script
	VB Project		Delphi Project
	VB.net Project		C# Project
	Java Project		Phyton Project

Get A Test Account I Have a Project!

01

02

03

04

05

06

07

08

09

10

11

12

13