Sistem Gereksinimleri Kullanılacak Karakterlere İlişkin Uyarılar Standart Dil Çevrimine İlişkin Uyarılar Toplu SMS Gönderiminde Kullanılacak Yönteme İlişkin Uyarılar Raporlamada Durum Bilgisi Kontrolüne İlişkin Uyarılar Hata Kodları

Kullanıcı Bilgilerinin Kontrolü GSM Numarası Formatına İlişkin Uyarılar Gönderen Bilgisi Kullanımına İlişkin Uyarılar Raporlamaya İlişkin Uyarılar KKTC XML Api Örnek Kodları

KKTC Toplu SMS XML API Kullanım Kılavuzunu indirmek için TIKLAYINIZ!

Genel

KKTC XML API, XML belgeleriyle çalışan yazılım geliştiricilerin, uygulamalarına SMS gönderimini XML üzerinden entegre etmelerini sağlamak amacıyla geliştirilmiştir.

Her işletim sistemi platformunun desteklediği bir araç olması ve her IDE ile kullanılabilir olması nedeniyle, yazılım geliştiricilerin tercih ettiği çözümümüzdür.

Yazılım geliştiriciler, bu belgede belirtilen şekilde hazırlamış oldukları XML ifadelerini, http://api.cyprus.mobildev.net/xmlapi.aspx (Bundan sonra Gateway olarak anılacaktır.) adresine, kendi çözümlerinde bir XMLHTTP isteği oluşturarak gönderirler. Gönderilen XML ifadesi Mobildev XML Parser tarafından işlenir. Eğer XML ifadesinde ya da XML ifadesi içinde bulunan parametre düğümlerinin herhangi birinde bir hata oluşmuşsa, yakalanan hata HTTP üzerinden önceden tanımlı bir kod olarak göndericiye iletilir. Eğer bir hata oluşmamışsa gönderilmiş olan XML ifadesinin işlevine uygun geri donuş ifadesi hazırlanıp HTTP üzerinden göndericiye iletilir. Önceden tanımlı hata kodları, belgenin ilgili ayrımında ayrıntılı olarak açıklanacaktır.

Sistem Gereksinimleri

Mobildev XML API çözümünü kullanabilmeniz için gereken minimum sistem gereksinimleri aşağıda belirtilmiştir.

• Windows 98 SE, ME, 2000, XP, UNIX, Linux ya da MacOS İşletim Sistemi

• Internet Explorer 6 SP1 (Windows Platformu için)

• cURL kütüphanesi (PHP kullanan geliştiriciler için)

Kullanıcı Bilgilerinin Kontrolü

SMS gönderimine başlamadan önce SMS kullanıcı bilgilerinin kontrolü sağlanmalıdır. Mevcut SMS hesabınız bulunmuyorsa test hesabı almak için TIKLAYINIZ.

Gateway'e yollanan kullanıcı bilgilerinin doğruluğu sistem tarafından kontrol edilerek kullanıcı hesabına ait kredi bilgisi ve orijinatör bilgisi sistem tarafından gönderilir. Kullanıcı bilgilerinin kontrolü sırasında Username, company_code, password ve action bilgileri kontrol edilir.

Username: Mobildev SMS hesabı üzerinde tanımlı kullanıcı adınızı ifade eder.
Company Code: SMS kullanıcı adınızın tanımlı olduğu kanal bilgisidir (client kodu olarak da adlandırılabilir).
Password: SMS kullanıcı adınıza ait şifreyi ifade eder.
Action: Gateway'e gönderilen XML ifadesinin hangi işlev için gönderildiğini rakamsal bazda ifade eden parametre düğümüdür.

Gateway'e gönderilen bilgilerin kontrolü gerçekleştirildiğinde; bilgiler hatalıysa 01 Hata Kodu döner. Hata Kodu 01, Hatalı Kullanıcı Adı – Şifre – Bayi Kodu bilgilerinden birinin ya da tamamının hatalı olduğu anlamına gelir. Bu durumda Mobildev Teknik Destek Ekibi ile iletişime geçip bilgilerinizi kontrol etmelisiniz.

Kullanıcı bilgilerinin kontrolünde olması gereken XML ifadesi aşağıdaki gibidir:

<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>4</Action>
</MainReportRoot>

Bilgi Kontrolü İçin Örnek XML İfadesi:
<MainReportRoot>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>4</Action>
</MainReportRoot>

Gateway'e gönderilen bilgilerin kontrolü gerçekleştirildiğinde; bilgiler doğruysa aşağıdaki geri dönüş değerini alırsınız:

Kontör sayısı<10>
Originator1<10>
Originator2<10>
OriginatorN

Kullanılacak Karakterlere İlişkin Uyarılar

Gönderim sırasında;

• Türkçe karakterler (ç,ş,ü,ö,ğ,Ç,Ü,Ş,Ğ,Ö,İ) .

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

• LineFeed, Enter, Tab komutları

kesinlikle kullanılmamalıdır.

Mesaj metni içerisinde sadece ( ), [ ], { }, =, *, ?, \, /, %, +, #, !, ", :, ;, _, | simgeleri kullanılabilir.

GSM Numarası Formatına İlişkin Uyarılar

GSM numaraları 05321234567, 5321234567, 905321234567 şeklinde ve Numbers parametre düğümü içerisinde yazılmalıdır. GSM numaraları uygun olmayan formatta yazılırsa 04 Hata Kodu alınır. Hata Kodu 04, GSM numarası formatının hatalı olduğu anlamına gelir. Bu durumda GSM Numarası Formatına İlişkin Uyarılar başlığı altındaki bilgileri kontrol etmelisiniz.

Kullanım Örnekleri:

<Numbers>05321234567</Numbers>
<Numbers>5321234567</Numbers>
<Numbers>905321234567</Numbers>

Unutmayın: +905321234567, 532 123 45 67, +05321234567 şeklinde ve -, ( ), [ ], { } vb. karakterlerle gönderim yapılamaz!

Standart Dil Çevrimine İlişkin Uyarılar

Mesaj metni oluşumunda ASCII (Bilgi Değişimi İçin Amerikan Standart Kodlama Sistemi) karakterleri dışında karakter kullanımı varsa Dil Çevirici kullanılması gerekmektedir.

Çevirici Kod Örneği:

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; }

Gönderen Bilgisi (Alfanumerik/Originator) Kullanımına İlişkin Uyarılar

Gönderen Bilgisi (Alfanumerik/Originator), mesaj gönderimlerinde gönderici kısmında yer alan; firmaya özel tanımlanmış 11 karakterden oluşan gönderici adıdır. Gönderim sırasında hesap aktivasyonunda aktivasyon biriminin tanımladığı Gönderen Bilgisi'nin aynısı Originator Parametre düğümü içerisinde yazılmalıdır. Gönderen Bilgisi tanımlı bilgiyle eşleşmezse 06 Hata Kodu alınır. Hata Kodu 06, Tanımsız Originator bilgisi anlamına gelir.

Büyük ve Küçük Harfli Örnek Kullanım:
<Originator>MOBILDEV</Originator>
<Originator>mobildev</Originator>

Unutmayın: Originator ifadesinde Türkçe karakterler ve &, <, >, -, ( ), [ ], / gibi simgeler kesinlikle kullanılmamalıdır!

Toplu SMS Gönderiminde Kullanılacak Yönteme İlişkin Uyarılar

Toplu olarak gönderilecek mesajlar tek tek paketler halinde değil toplu paketler halinde gönderilmelidir. Tek tek gönderilen paketler sistemde yoğunluk oluşturmakta ve bu yoğunluk mesajların gitmesinde gecikmeye neden olmaktadır.

Gönderilecek mesajlar mümkün olduğunca tek bir XML ifadesi hazırlanarak Gateway'e yollanmalıdır. İnternet bağlantısı ve sistem yoğunluğu nedenleriyle olası gecikmeleri önlemek için önerilen SMS paketi boyutu 30.000 adettir.

XML SMS API gönderimi için 2 çeşit XML ifadesi bulunmaktadır. Aynı mesaj metni ile yapılacak Toplu SMS gönderimlerinde SMS to Many; farklı mesajlar farklı GSM numaralarına gönderilecekse SMS MultiSenders yöntemi kullanılmalıdır.

SMS to Many:

SMS To Many ifadesi, aynı mesajı birden fazla GSM numarasına göndermek için kullanılır. Önerilen SMS paketi boyutu 30.000 adettir. Aşağıda SMS To Many XML ifadesi gösterilmektedir:

<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>

SMS To Many XML İfadesi Örneği
<MainmsgBody>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>0</Action>
<Mesgbody>dogum gununuz kutlu olsun</Mesgbody>
<Numbers>05421234567,05321234567</Numbers>
<Originator>MOBILDEV</Originator>
<SDate>010120121530</SDate>
</MainmsgBody>

SMS MultiSenders:

SMS MultiSenders ifadesi, farklı mesajları farklı GSM numaralarına göndermek için kullanılır. Önerilen SMS paketi boyutu 30.000 adettir. Aşağıda SMS MultiSenders XML ifadesi gösterilmektedir:

<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>

SMS MultiSenders XML İfadesi Örneği
<MainmsgBody>
<UserName>test-mb1000</UserName>
<PassWord>12345</PassWord>
<Action>1</Action>
<Messages>
<Message>
<Mesgbody>dogum gununuz kutlu olsun</Mesgbody>
<Number>05427654321</Number>
</Message>
<Message>
<Mesgbody>yeni yilinizi kutlariz.</Mesgbody>
<Number>05327654321</Number>
</Message>
</Messages>
<Originator>MOBILDEV</Originator>
<SDate></SDate>
</MainmsgBody>

Raporlamaya İlişkin Uyarılar

TimerID Bazında Raporlama: Yapılan her SMS paketi (XML ifadesi) gönderiminde sistem TimerID bilgisi verir. TimerID, gönderilen SMS paketine sistem tarafından otomatik olarak atanan numaradır.
TimerID (paket bazında) rapor almak için aşağıdaki XML ifadesi kullanılmalıdır ve Action parametresi 3 olmalıdır:

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

TimerId Bazında Rapor Alma Örneği:

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

Tarih Bazında Raporlama: Tarih Bazında Raporlama için Action parametresi 2 olmalıdır. Tarih aralığı belirtmek için Fdate, raporun başlangıç tarihi; Ldate, raporun bitiş tarihinin girilmesi gereken parametrelerdir.

Tarih bazında rapor almak için aşağıdaki XML ifadesi kullanılmalıdır:

<MainReportRoot>
<UserName>username-company_code</UserName>
<PassWord>password</PassWord>
<Action>2</Action>
<FDate>year-month-day</FDate>
<LDate>year-month-day</LDate>
</MainReportRoot>

Tarih Bazında Raporlama Örneği:

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

XML ifadesi Gateway'a ulaştığında iki çeşit geri dönüş değeri alınır:
1- İşlem Başarılı
2- Hatalı Geri Dönüş Değeri bknz: Hata Kodları

Unutmayın: Raporlar sadece geriye dönük 3 ay öncesine kadar sistemden çekilebilmektedir!

Raporlamada Durum Bilgisi Kontrolüne İlişkin Uyarılar

Raporlama sırasında gönderimi başarı olan paket için 4 farklı durum bilgisi döner:

• "1" mesajın beklemede olduğunu;

• "3" mesajın iletildiğini;

• "5" mesajın iletilemediğini

• "6" mesajın zaman aşımına uğradığını ifade eder.

Hata Kodları

Hata Kodu	Açıklama
01	Hatalı Kullanıcı Adı Hatalı Şifre Hatalı Bayi Kodu
02	Mesaj Gönderimi: Yetersiz kredi Geçersiz ID: Böyle bir mesaj (ID) kodu yok Raporlama: Paket işlenmemiş ya da Gateway tarafında beklemede
03	Tanımsız Action parametresi
04	Gelen XML yok
05	XML düğümü eksik ya da hatalı
06	Tanımsız Orijinatör bilgisi
07	Mesaj kodu (ID) yok
08	Verilen tarihler arasında SMS gönderimi yok
09	Tarih alanları boş - hatalı
10	SMS gönderilemedi
11	Tanımlanamayan hata
12	Admin yetkisiyle ulaşılabilecek bir alana Admin yetkisi olmayan biri ulaşmaya çalıştı.
13	Rapor istenen kullanıcı yok

KKTC XML Api Örnek Kodlar

	ASP Scripti		PHP Scripti
	VB Projesi		Delphi Projesi
	VB.net Projesi		C# Projesi
	Java Projesi		Phyton Projesi