Kısa Mesaj Servisleri Entegrasyon Dökümanı Sürüm: 3.3 2013
İÇİNDEKİLER HIZLI BAŞLANGIÇ... 3 SMS Gönderimi... 3 SMS Sorgulama... 4 Mesaj Toplama... 4 GENEL BAKIŞ... 5 PLATFORM İŞLEMLERİ... 8 Genel Tanımlar... 8 Sistem Saati Sorgulama (Check Date)... 8 Şifre Değiştirme (Change Password)... 9 Gönderen ve Kredi Sorgulama (Get Credit)... 10 Gönderim İptal (Cancel Job)... 11 MESAJ GÖNDERİM İŞLEMLERİ... 12 Mesaj Metni hazırlanırken dikkat edilmesi gereken kurallar... 12 Aynı Mesajı Farklı Alıcıya / Alıcılara Gönderme (One to Many)... 15 Farklı Mesajları Farklı Alıcılara Gönderme (Many to Many)... 19 SORGULAMA İŞLEMLERİ... 22 Takip No ile Sorgulama (Report By Id)... 22 İki Tarih Arası Sorgulama (Packet Based Report)... 24 Detaylı Rapor (Detailed Report)... 26 MESAJ TOPLAMA İŞLEMLERİ... 29 Mesaj Toplama Uygulamaları Listesi (Get Interactive Applications)... 29 Gelen Mesajların Listelenmesi (Get Messages)... 31 TANIMLAR... 33 2
HIZLI BAŞLANGIÇ Kısa Mesaj Servislerimizden SMS göndermek, yapılan gönderimleri sorgulamak ve mesaj toplamak için aşağıdaki yöntemleri kullanarak ilk çalışmanıza başlayabilirsiniz. Windows işletim sistemlerinde dilerseniz rar dosyası içinde verilmiş olan aynı isimdeki VBS dosyalarını da TURATEL kullanıcı bilgileriniz ile güncelledikten sonraçalıştırabilirsiniz. Hızlı bir başlangıç için verilen bu komut ve gönderim örneklerinin detaylı açıklamaları devam eden sayfalarda yer almaktadır. SMS Gönderimi Metod : HTTP POST URL : http://processor.smsorigin.com/xml/process.aspx İstek : <MainmsgBody> <Command>0</Command> <ChannelCode>Kanal </ChannelCode> <Mesgbody>Mesaj İçeriği</Mesgbody> <Numbers>9053XXXXXXXX</Numbers> <Type>1</Type> <Originator>Gönderen</Originator> </MainmsgBody> Cevap : ID:61273486 3
SMS Sorgulama Metod : HTTP POST URL : http://processor.smsorigin.com/xml/process.aspx İstek : <MainReportRoot> <Command>3</Command> <ChannelCode>Kanal </ChannelCode> <MsgID>61273486</MsgID> </MainReportRoot> Cevap : 9053XXXXXXXXchr(32)3chr(32)1 Mesaj Toplama Metod : HTTP POST URL : http://processor.smsorigin.com/xml/process.aspx İstek : <MainReportRoot> <Command>25</Command> <ChannelCode>Kanal </ChannelCode> <Status>0</Status> <ApplicationID>Uygulama Id</ApplicationID> </MainReportRoot> Cevap : <Messages> <Message> <MsgID>11749628</MsgID> <Date>25012013153425</Date> <Number>905XXXXXXXXX</Number> <Text>TEST SMS</Text> </Message> </Messages> 4
GENEL BAKIŞ TURATEL Kısa Mesaj Servisleri 7/24 esasında hizmet vermektedir. Operatör e kayıt işlemleriniz tamamlandıktan sonra TURATEL den alacağınız kullanıcı bilgileri ile gönderim/sorgulama ve mesaj toplama servislerini kullanmaya başlayabilirsiniz. Servislerimizin üzerinde çalıştığı sunucular güvenlik standartlarına uygun ortamlarda yer almaktadır. Servislerimiz, network girişindeki IPS ve sunucu tarafını kontrol eden başka bir güvenlik duvarı (firewall) arkasında hizmet vermektedir. GSM operatörleri tarafından test gönderimine imkan verilmediğinden bir test platformu sağlanamamaktadır. Bir mesajın gönderimi ilk olarak Turatel e teslim edilmesi ile başlar. Teslim edilen mesaj Turatel sunucusunda mesaj teslim saatine kadar bekletilir ve gönderim zamanı geldiğinde operatöre teslimine başlanır. İptal işlemi ise bu süre içinde yapılabilir. Hemen gönderilmesi istenen mesajlar ise teslim alındıktan sonra beklemeden operatöre iletilir. Operatöre iletilen mesajlar veritabanına kayıt edildikten sonra SMSC adı verilen tüm baz istasyonlarını kontrol eden sunucuya aktarılır ve herhangi bir baz istasyonuna bağlı olan alıcıya mesaj iletilir. İletilen mesajların iletim durumu SMSC tarafından kontrol edilir. Alıcı cihaz tarafından alınan mesajın alındı durumu SMSC tarafından operatör veritabanına aktarılır ve alındı bilgisi ile birlikte alım tarihi Turatel sunucusunda güncellenir. MESAJ GÖNDERİM TALEBİ Gönderimlerde, talebiniz sunucumuza geldikten sonra sıraya alınarak mesajın teslimi yapılmaktadır. Bu süreler servislerin yoğunluğuna göre değişkenlik gösterir. Yoğunluk Yılbaşı, Kandil, Bayram vb özel günlerde artış gösterebilir. 5
MESAJIN ALICIYA TESLİM İŞLEMLERİ Gönderim zamanı gelen mesajlar operatöre iletilir. Operatör mesaj içeriğini kontrol ettikten sonra SMSC platformuna mesajı iletir. Mesaj metni veya alıcılarla ilgili sorun meydana geldiğinde bu bilgi hata kodu ile birlikte mesaj durum sorgulama servisinden numara bazında alınabilir. MESAJ DURUM SORGULAMA Alıcıya iletilen mesajların durumu en erken 15 dakika sonra güncellenmektedir. Bu durum SingleShot (OTP) gönderimlerinde daha kısadır. Mesaj gönderim alanında edindiğimiz tecrübelere göre; gönderimlerde yaşanan sorunların bir çoğu network ve operatör kaynaklı olabilmektedir. Operatörlere ait sistemler çok yoğun olduğundan, bazen gün içerisinde özelliklede yoğunluğun yaşandığı saatlerde tekrarlayan sorunlarla karşılaşılabilmektedir. Turatel olarak bu konuda operatörler ile kurduğumuz koordinasyon sonucu operatör tarafında yapılacak çalışmalarla ilgili önceden bilgi alıp, gerektiğinde bu bilgileri sizinle paylaşmaktayız. 6
POST İŞLEMİ Servislerimize taleplerinizi tüm dünyada geçerli ve en bilinen yöntem olan HTTP POST ile yapabilirsiniz. POST için kullanılacak web adresimiz: veya http://processor.smsorigin.com/xml/process.aspx https://processor.smsorigin.com/xml/process.aspx POST edilecek komut XML formatında olmalıdır. XML komutlarının detaylı açıklamaları devam eden sayfalarda mevcuttur. XML standartlarına uymayan bir talep hata olarak değerlendirilir ve işlem yapılamaz. XML komutlarınızın başında aşağıdaki gibi encoding bilgisi bulunmalıdır. Bu sayede farklı sistemlerden gelen taleplerde, özellikle de İngilizce karakterler haricinde içeriği olan verilerde UTF-8 encoding in belirtilmesi muhtemel bölgesel ayar sorunlarının önüne geçecektir. Hazırlanan XML komutlarında \n tarzı carriage return / newline karakterlerini gönderimden önce temizlemeniz gereklidir. Özellikle <![CDATA[... ]]> alanları içinde gönderilen NewLine komutları malformed xml hatalarına neden olabilmektedir. XML format hatası almanız durumunda önce XML komutu içerisindeki zorunlu alanların doğru bir şekilde doldurulduğunu daha sonra da hatalara neden olabilecek karakterlerin temizlendiğinden mutlaka emin olunuz. Talep doğru bir şekilde gönderildiğinde, gönderilen her talep karşılığında servislerimizden metin (text) olarak bir cevap geri dönecektir. 7
PLATFORM İŞLEMLERİ TURATEL kullanıcı bilgileriniz ile TURATEL servislerinden yapacağınız kullanıcı bilginiz, alfanumerik tanımlarınız, kalan kredi miktarınız (Ön ödemeli müşterilerimiz için) hakkında sorgulamaları içermektedir. Genel Tanımlar Oluşturulan tüm XML komutlar aşağıdaki URL e HTTP POST metoduyla iletilmelidir. Normal Bağlantı için URL : http://processor.smsorigin.com/xml/process.aspx Güvenli Bağlantı için URL : https://processor.smsorigin.com/xml/process.aspx Tüm taleplerde ilk olarak aşağıda listelenen hata kodları kontrol edilmelidir. Hata 00 Sistem Hatası 20 Tanımsız Hata (XML formatını kontrol ediniz veya TURATEL den destek alınız) 21 Hatalı XML Formatı (\n - carriage return newline vb içeriyor olabilir) 22 Kullanıcı Aktif Değil 23 Kullanıcı Zaman Aşımında Sistem Saati Sorgulama (Check Date) Gönderimi yapan sunucudaki saati sorgulamak için kullanılır. Turatel Sunucu sistem saati ile servisinizi senkronize etmek için kullanabilirsiniz. XML NODE Zorunlu Command Check Date metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre İstek : <CheckDate> <Command>5</Command> <ChannelCode>Kanal </ChannelCode> </CheckDate> 8
Hata Kodları Hata Cevap : 01 Kullanıcı Adı ve/veya Şifre Hatalı 07 Genel Hata 260120131123 Şifre Değiştirme (Change Password) Kullanıcı şifre değişikliği için kullanılır. XML NODE Zorunlu Command Change Password metodunun komut numarası PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre NPassWord Yeni Şifre İstek : <ChangePassWord> <Command>13</Command> <ChannelCode>Kanal </ChannelCode> <NPassWord>Yeni Şifre</NPassWord> </ChangePassWord> Hata Kodları Hata 01 Kullanıcı adı veya şifre hatalı 02 Şifre değiştirilemedi 03 Geçersiz şifre Cevap : OK 9
Gönderen ve Kredi Sorgulama (Get Credit) Gönderen : Alıcı tarafında, gönderen numara yerinde görüntülenecek bilgi. Alfanumerik veya Originator olarak da anılır. Gönderim için kullanılabilecek gönderen tanımları ve kredili müşterilerimiz için mevcut kredi miktarı aynı anda sorgulanabilir. İlk satır kredi miktarı, sonraki satırlar sistemde tanımlanmış gönderen isimleridir. Faturalı müşteriler için kredi miktarı varsayılan 10000 olarak görüntülenecektir. Bu nedenle; faturalı bir hesap tanımınız var ve kredi miktarınız 10,000 görünüyorsa lütfen dikkate almayınız. XML NODE Zorunlu Command Get Credit metodunun komut numarası PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre İstek : <MainReportRoot> <Command>6</Command> <ChannelCode>Kanal </ChannelCode> </MainReportRoot> Hata Kodları Hata 01 Kullanıcı adı veya şifre hatalı Cevap : 10000 TURATEL 3172 10
Gönderim İptal (Cancel Job) İleri tarihli gönderilmek üzere ayarlanmış ve henüz sistem tarafından operatöre teslim edilmemiş mesajı iptal eder. XML NODE Zorunlu Command Cancel Job metodunun komut numarası PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre MsgID Gönderim takip numarası İstek : <CancelJob> <Command>4</Command> <ChannelCode>Kanal </ChannelCode> <MsgID>Takip No</MsgID> </CancelJob> Hata Kodları Hata 01 Kullanıcı adı veya şifre hatalı 02 Gönderim iptal edilemedi. Gönderim tamamlandı veya devam ediyor Cevap : OK 11
MESAJ GÖNDERİM İŞLEMLERİ Gönderilen mesajlardan çeşitli nedenlerle başarısız olanlar için operatör tarafından ücret alınmamaktadır. Turatel sunucularında hiç bir mesaj, gönderim sırasında hata alındığı takdirde tekrar işleme alınmaz. Mesaj Metni hazırlanırken dikkat edilmesi gereken kurallar GSM 7 Bit Karakter Kümesi: Mesaj gönderimleri GSM 7 Bit karakter kümesini desteklemektedir. Karakter tablosu aşağıdaki gibidir. 0 5 :? + & @ D I N S X c h m R w 1 6 ;. * % $ E J O T Y d ı n S x 2 7 < / ( # A F K P U Z e j o T y 3 8 = - ) B G L Q V a f k p U z 4 9 >, '! C H M R W b g l q V Ü Ö Ç ü ö ç Gönderim sırasında type node u 1 olarak verildiğinde; bu karakter kümesi haricinde bir sembol metinde yer aldığında hata alınacak ve gönderim başarısız olacaktır. Bu durumda GSM 7 Bit dışındaki karakterleri desteklemeye izin veren type node u 2 olarak ayarlanabilir. Type = 2 gönderimlerde ise mesaj metni maximum 268 karaktere düşecek ve bu tablo haricindeki karakterlerden en az 1 tanesinin metinde olması istenecektir. XML formatını bozan karakterler: XML yapısına özel <,>, & vb özel karakterleri mesaj metni içinde kullandığınızda mutlaka HTML Encode işleminden geçirilmelidir: < < less than > > greater than & & ampersand " quotation mark ' ' apostrophe Mesaj içerik uzunluğu: Standart veya Flash tipindeki bir SMS içerik uzunluğu 160 karakterdir. 160 karakter uzunluğunu geçen içeriklerin faturalandırılması aşağıdaki gibi olmaktadır. 160 karakteri geçen metinlerde 2. SMS in başlangıç uzunluğu 153. karakterden başlayarak hesaplanacaktır. Başlangıç Bitiş Mesaj Sayısı 1 160 1 Mesaj 153 306 2 Mesaj 306 459 3 Mesaj 459 612 4 Mesaj 12
Türkçe veya Türkçe Flash tipindeki bir içerik 160 karaktere kadar yine 1 SMS olarak faturalandırılır. Maximum uzunluk 268 karakterdir. 160 karakter uzunluğunu geçen Türkçe SMS içeriklerinizin faturalandırması ise aşağıdaki gibi olacaktır. Başlangıç Bitiş Mesaj Sayısı 1 160 1 Mesaj 153 268 2 Mesaj Türkçe Gönderim (GSM 7 Bit): GSM 7 Bit Karakter Kümesi haricinde gönderim için type node u 2 olarak verilmelidir. Bu aynı zamanda Türkçe karakterleri de içeren bir durumdur. Type = 2 olarak verilen mesajların içinde mutlaka GSM 7 Bit Karakter Kümesi haricinde (İ,Ğ,Ş,ı,ğ,ş) bir karakter bulunmak zorundadır. Olmadığı takdirde operatör tarafından gönderim yapılmayacak ve - 467 hatası verilecektir. 2 karakter olarak hesaplanan semboller: Aşağıdaki karakterler operatör tarafından 2 karakter olarak hesaplanmaktadır. ^ { } [ ~ ] \ ENTER TC Kimlik No ya Mesaj Gönderimi: Servislerimizden TC Kimlik No ile Mesaj gönderimi yapabilirsiniz (TC Kimlik No gönderimi parametrik gönderim türünü desteklememektedir). TC Kimlik No ya Mesaj gönderimlerinde, TC Kimlik No ya karşılık gelen GSM numarasına Mesaj gönderimi gerçekleştirilir. TC Kimlik No GSM Numara eşleştirmesi ile ilgili detaylar aşağıda belirtilmiştir. - TC Kimlik No ya karşılık gelen GSM Numara sayısı 1 den fazla ise; o TC Kimlik No ya gönderilen Mesaj başarısız olacaktır. o Operatör den TC Kimlik No ya karşılık gelen tüm GSM numaralarına Mesaj gönderimi için yetki alındığında, Mesaj gönderimi başarılı sonuçlanacaktır. - Operatör tarafından belirlenen kurallar çerçevesinde TC Kimlik No ya karşılık gelen GSM numarasının yasal sahibi ve kullanıcısı aynı kişi olmak durumundadır. GSM numarasının yasal sahibi ile kullanıcısı farklı kişiler ise; o TC Kimlik No ya karşılık gelen hattın yasal sahibi ve kullanıcısı olarak kayıtlı olan GSM numaralarına Mesaj gönderimi yapılabilir. Hattın yasal sahibi olmayan kullanıcılarına Mesaj gönderimi gerçekleştirilmez. o TC Kimlik No ya karşılık gelen GSM numaraları içerisinde, hem yasal sahibi hem de kullanıcısı farklı GSM numaralarına Mesaj gönderimi için Operatör den yetki alınması gerekmektedir. Hattın yasal sahibi veya kullanıcısı; kurumsal anlamda kayıtlı hatlar ve hattın yasal sahibi olmadığı halde hattı kullanmak üzere kendisine tahsis edilmiş kurum çalışanları olarak düşünülebilir. 13
Yurtdışı Mesaj Gönderimleri: Servislerimizden Yurtdışı GSM numaralarına mesaj gönderimi yapabilmek için GSM operatöründen özel yetki alınması zorunludur. Yurtdışı GSM gönderimlerinde numara girişi aşağıdaki şekilde yapılmalıdır. Ülke (2 Karakter) Telefon Numarası (10 Karakter) 86 1069445464 33 687712345 44 7700954321 Bazı yurt dışı operatörleri gönderen ismi olarak sadece numerik isimleri desteklemektedir. Alfanumerik isimler ile yapılan SMS gönderimleri alıcılara ulaşmamaktadır. Numerik gönderen ismi kullanılarak SMS gönderimi yapmak için Turatel ile irtibata geçip, gerekli operatör yetkilerinin oluşturulması için destek alabilirsiniz. 14
Aynı Mesajı Farklı Alıcıya / Alıcılara Gönderme (One to Many) Aynı mesaj içeriğinin bir yada birden fazla alıcıya gönderilmesidir. Önerilen alıcı sayısı üst limiti 50.000 dir. Daha fazla alıcı içeren XML komutları, boyutu nedeniyle farklı nedenlerden dolayı servislerimize ulaşamayabilir ve gönderiminiz başarısız olabilir. 50.000 adet alıcıdan fazla gönderimlerinizde birden fazla XML komutu oluşturarak gönderiminizi gerçekleştirebilirsiniz. XML NODE Zorunlu Command SMS to Many metodunun komut numarası PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre Mesgbody Gönderilecek mesaj içeriği Gönderilecek alıcı listesi. Her alıcı ; veya, karakterleri ile Numbers ayrılmalıdır. Örnek : 9053XXXXXXXX;9054XXXXXXXX Gönderilen mesajın formatını belirlemek için kullanılır. Alabileceği değerler aşağıdaki gibidir. Standart : 1 Type Flash : 4 Standart Türkçe : 2 Flash Türkçe : 7 Binary : 3 Wap-Push : 5 Originator Gönderen ismi. Mesajın gönderime başlanacağı tarih. Boş bırakıldığında SDate gönderim hemen gerçekleşir. Giriş Formatı : ddmmyyyyhhmm Mesajın gönderiminin sonlandırılacağı tarih. Başlangıç tarihinden en az 45dk sonrasına ayarlanmalıdır. EDate Hatalı giriş yapıldığında ya da boş bırakıldığında gönderim 21 saat sonra sonlandırılacak şekilde ayarlanır. Tarih Formatı : ddmmyyyyhhmm Standart ve Flash SMS tiplerinde 160 karakter uzunluğuna kadar gönderilecek içerikler için 0, 160 karakter uzunluğunu geçen içerikleri için 1 olarak ayarlanmalıdır. Standart Türkçe ve Flash Türkçe SMS tiplerinde 70 karakter Concat uzunluğuna kadar gönderilecek içerikler için 0, 70 karakter uzunluğunu geçen içerikleri için 1 olarak ayarlanmalıdır. 1 olarak ayarlanan gönderimlerde, içeriğin 160 karakterden kısa olması durumunda herhangi bir hata cevabı dönülmeyecek, servis tarafından bu parametre 0 olarak güncellenecektir. GSM yerine TC Kimlik No ya gönderim yapılmasını sağlar. Alıcı IsTCKimlikNoPacket tipinin TC Kimlik No olarak algılanması için 1 olarak ayarlanması gerekmektedir. Option OTP ( One Time Password / Single Shot ) gönderimlerde 1 olarak verilmelidir. 15
GSM Numarası alıcılarına: İstek : <MainmsgBody> <Command>0</Command> <ChannelCode>Kanal </ChannelCode> <Type>1</Type> <Concat>0</Concat> <Originator>TURATEL</Originator> <Mesgbody>Mesaj İçeriği</Mesgbody> <Numbers>905321111111,905331111111</Numbers> <SDate>280120131325</SDate> <EDate>280120131525</EDate> </MainmsgBody> Hata Cevap : 01 Kullanıcı adı ya da şifre hatalı 02 Kredisi yeterli değil 03 Geçersiz içerik 04 Bilinmeyen SMS tipi 05 Hatalı gönderen ismi 06 Mesaj metni ya da Alıcı bilgisi girilmemiş 07 İçerik uzun fakat Concat özelliği ayarlanmadığından mesaj birleştirilemiyor 08 Kullanıcının mesaj göndereceği gateway tanımlı değil ya da şu anda çalışmıyor 09 Yanlış tarih formatı.tarih ddmmyyyyhhmm formatında olmalıdır ID:61273487 16
TC Kimlik Numarası alıcılarına: İstek : <MainmsgBody> <Command>0</Command> <ChannelCode>Kanal </ChannelCode> <Type>1</Type> <Concat>0</Concat> <IsTCKimlikNoPacket>1</IsTCKimlikNoPacket> <Originator>TURATEL</Originator> <Mesgbody>SMS To Many TCKN - TEST SMS</Mesgbody> <Numbers>26497188029,29674966209</Numbers> <SDate>280120131325</SDate> <EDate>280120131525</EDate> </MainmsgBody> Hata Cevap : 01 Kullanıcı adı ya da şifre hatalı 02 Kredisi yeterli değil 03 Geçersiz içerik 04 Bilinmeyen SMS tipi 05 Hatalı gönderen ismi 06 Mesaj metni ya da Alıcı bilgisi girilmemiş. 07 İçerik uzun fakat Concat özelliği ayarlanmadığından mesaj birleştirilemiyor 08 Kullanıcının mesaj göndereceği gateway tanımlı değil ya da şu anda çalışmıyor 09 Yanlış tarih formatı.tarih ddmmyyyyhhmm formatında olmalıdır 11 TC Kimlik No gönderim yetkisi bulunmamaktadır ID:61273488 17
GSM Numarası Alıcılarına Single Shot (OTP - One Time Password): İstek : <MainmsgBody> <Command>0</Command> <ChannelCode>Kanal </ChannelCode> <Type>1</Type> <Concat>0</Concat> <Option>1</Option> <Originator>TURATEL</Originator> <Mesgbody>SMS To Many OTP - TEST SMS</Mesgbody> <Numbers>905321111111,905331111111</Numbers> <SDate>280120131425</SDate> </MainmsgBody> Cevap : ID:61273489 Hata Kodları Hata 01 Kullanıcı adı yada şifre hatalı 02 Kredisi yeterli değil 03 Geçersiz içerik 04 Bilinmeyen SMS tipi 05 Hatalı gönderen ismi 06 Mesaj metni ya da Alıcı bilgisi girilmemiş 07 İçerik uzun fakat Concat özelliği ayarlanmadığından mesaj birleştirilemiyor 08 Kullanıcının mesaj göndereceği gateway tanımlı değil ya da şu anda çalışmıyor 09 Yanlış tarih formatı.tarih ddmmyyyyhhmm formatında olmalıdır 11 TC Kimlik No gönderim yetkisi bulunmamaktadır 18
Farklı Mesajları Farklı Alıcılara Gönderme (Many to Many) Farklı mesaj içeriğinin birden fazla farklı alıcıya gönderilmesidir. Önerilen alıcı sayısı üst limiti 5.000 dir. Daha fazla alıcı içeren XML komutları, boyutu nedeniyle farklı nedenlerden dolayı servislerimize ulaşamayabilir ve gönderiminiz başarısız olabilir. 5.000 adet alıcıdan fazla gönderimlerinizde birden fazla XML komutu oluşturarak gönderiminizi gerçekleştirebilirsiniz. XML NODE Zorunlu Command SMS to Multisenders metodunun komut numarası PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre Mesages / Message / Mesgbody Gönderilecek mesaj içeriği Mesages / Message / Number Type Gönderilecek alıcı. Örnek : 9053XXXXXXXX Gönderilen mesajın formatını belirlemek için kullanılır. Alabileceği değerler aşağıdaki gibidir. Standart : 1 Flash : 4 Standart Türkçe : 2 Flash Türkçe : 7 Originator Gönderen ismi. SDate EDate Concat Option Mesajın gönderime başlanacağı tarih. Boş bırakıldığında gönderim hemen gerçekleşir. Giriş Formatı : ddmmyyyyhhmm Mesajın gönderiminin sonlandırılacağı tarih. Başlangıç tarihinden en az 45dk sonrasına ayarlanmalıdır. Hatalı giriş yapıldığında ya da boş bırakıldığında gönderim 21 saat sonra sonlandırılacak şekilde ayarlanır. OTP ( One Time Password / Single Shot ) gönderimlerde maximum geçerlilik süresi gönderimden itibaren +5dk olduğu için Zaman Aşımı tarihini vermeye gerek yoktur. Bununla birlikte verilmesi gereken durumlarda; 5dk dan uzun bitişi tarihi ayarlandığında, servis tarafından Takip No cevabı alınsa bile gönderiminiz başarısız olacaktır. Tarih Formatı : ddmmyyyyhhmm Standart ve Flash SMS tiplerinde 160 karakter uzunluğuna kadar gönderilecek içerikler için 0, 160 karakter uzunluğunu geçen içerikleri için 1 olarak ayarlanmalıdır. Standart Türkçe ve Flash Türkçe SMS tiplerinde 70 karakter uzunluğuna kadar gönderilecek içerikler için 0, 70 karakter uzunluğunu geçen içerikleri için 1 olarak ayarlanmalıdır. 1 olarak ayarlanan gönderimlerde, içeriğin 160 karakterden kısa olması durumunda herhangi bir hata cevabı dönülmeyecek, servis tarafından bu parametre 0 olarak güncellenecektir. Single Shot (OTP - One Time Password) gönderimlerde 1 olarak ayarlanmalıdır. 19
GSM Numarası alıcılarına: İstek : <MainmsgBody> <Command>1</Command> <ChannelCode>Kanal </ChannelCode> <Type>1</Type> <Concat>0</Concat> <Originator>TURATEL</Originator> <Messages> <Message> <Mesgbody>Sayın Ali Can, borcunuz 50 Liradır</Mesgbody> <Number>905321111111</Number> </Message> <Message> <Mesgbody>Sayın Veli Kara, borcunuz 100 Liradır</Mesgbody> <Number>905331111111</Number> </Message> </Messages> <SDate>280120131330</SDate> <EDate>280120131530</EDate> </MainmsgBody> Hata Kodları Hata 01 Kullanıcı adı ya da şifre hatalı 02 Kredisi yeterli değil 03 Geçersiz içerik 04 Bilinmeyen SMS tipi 05 Hatalı gönderen ismi 06 Mesaj metni ya da Alıcı bilgisi girilmemiş 07 İçerik uzun fakat Concat özelliği ayarlanmadığından mesaj birleştirilemiyor 08 Kullanıcının mesaj göndereceği gateway tanımlı değil ya da şu anda çalışmıyor 09 Yanlış tarih formatı.tarih ddmmyyyyhhmm formatında olmalıdır Cevap : ID:61273490 20
GSM Numarası Alıcılarına Single Shot (OTP): İstek : <MainmsgBody> <Command>1</Command> <ChannelCode>Kanal </ChannelCode> <Option>1</Option> <Type>1</Type> <Concat>0</Concat> <Originator>TURATEL</Originator> <Messages> <Message> <Mesgbody>SMS To Multisender 1 - TEST SMS</Mesgbody> <Number>905321111111</Number> </Message> <Message> <Mesgbody>SMS To Multisender 2 - TEST SMS </Mesgbody> <Number>905331111111</Number> </Message> </Messages> <SDate>280120131325</SDate> </MainmsgBody> Hata Kodları Hata 01 Kullanıcı adı ya da şifre hatalı 02 Kredisi yeterli değil 03 Geçersiz içerik 04 Bilinmeyen SMS tipi 05 Hatalı gönderen ismi 06 Mesaj metni ya da Alıcı bilgisi girilmemiş 07 İçerik uzun fakat Concat özelliği ayarlanmadığından mesaj birleştirilemiyor 08 Kullanıcının mesaj göndereceği gateway tanımlı değil ya da şu anda çalışmıyor 09 Yanlış tarih formatı.tarih ddmmyyyyhhmm formatında olmalıdır Cevap : ID:61273491 21
SORGULAMA İŞLEMLERİ Mesaj gönderiminden sonra alınan takip numarası veya iki tarih arası gönderimlerinizin genel ve detaylı durumlarını sorgulayabilirsiniz. Mesaj durum sorgulamalarında kullanılan genel tanımları aşağıdadır. Sorgulamalarda GSM formatı 9053XXXXXXXX olarak görüntülenecektir. Takip No ile Sorgulama (Report By Id) Mesaj gönderiminden sonra alınan takip numarası ile gönderimlerinizin durumlarını sorgulamanıza olanak sağlar. Dönecek cevap formatı aşağıdaki gibidir: GSMchr(32)Durumchr(32)Teslim Tarihi XML NODE Zorunlu Command Report By Id metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre MsgID Gönderim takip numarası Boş bırakılırsa teslim durumuna bakılmadan tüm gönderimler listelenir. Aşağıdaki durum değerlerinden biri veya birden fazlası, ile ayırılarak verildiğinde ise sadece istenen durumdaki alıcılar listelenir. Status AddDeliveryTime 3 : Delivered (Başarı ile iletilmiş) 5 : Rejected (İptal olan veya Gsm No formatına uygun olmayan numaralar) 6 : Pending (İşlemde olan ve gönderilmeye çalışılan numaralar) 9 : Expired (Geçerlilik Süresi bitene kadar gönderilmeye çalışılmış fakat başarılı olmayan numaralar) 1 olarak verildiğinde alıcı cihaza mesajın teslim edildiği tarihi de listeye ekler. Listeleme formatı: yyyymmddhhmmss Not: Bu komutun eski sürümü <Command>3</Command> tür ve sadece geriye dönük olarak desteklenmektedir. 22
İstek : <MainReportRoot> <Command>15</Command> <ChannelCode>Kanal </ChannelCode> <MsgID>Takip No</MsgID> <Status></Status> <AddDeliveryTime></AddDeliveryTime> </MainReportRoot> Hata Kodları Hata 01 Kullanıcı Adı veya Şifre Hatalı 02 Takip no hatalı 03 Takip no boş 04 Gönderim başarısız (Parametrik gönderim ise mesaj metinleri yada numaralar boştur) 05 Takip no ya ait gönderim bulunamadı ya da şu anda gönderiliyor 07 Takip no ya ait gönderim bulunamadı 08 Gönderim kullanıcı tarafından iptal edilmiş Cevap : 9053XXXXXXXXchr(32)3chr(32)20090901180000 9054XXXXXXXXchr(32)5chr(32)20090901180000 9055XXXXXXXXchr(32)6chr(32)20090901180000 9050XXXXXXXXchr(32)9chr(32)20090901180000 Durum 3 Başarılı (Alıcıya başarılı olarak iletilmiş) 5 Başarısız (GSM numarası hatalı ya da gönderim iptal edilmiş) 6 Beklemede (İşlemde veya gönderilmeye çalışılıyor) 9 Zaman Aşımı (Geçerlilik süresi bitene kadar gönderilmeye çalışılmış fakat başarısız olmuş) 23
İki Tarih Arası Sorgulama (Packet Based Report) Belirtilen iki tarih arasındaki gönderimlerin, gönderim bazında bilgilerini sorgulamanıza olanak sağlar. Cevap yapısı ve bazı alanlara ait açıklamalar şu şekildedir; Takip No Gönderim Tipi Mesaj Tipi Gönderim Zamanı Başlangıç Zamanı Bitiş Zamanı Gönderici İsmi Durum Durum Uzun Mesaj Toplam Alıcı Toplam Mesaj Toplam Başarılı Toplam Başarısız Toplam Bekleyen Toplam Zaman Aşımı Mesaj İçeriğichr(30) XML NODE Zorunlu Command Packet Based Report metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre SDate FDate MessagePacketId İstek : Sorgulama başlangıç tarihi. Giriş Formatı : ddmmyyyyhhmm Sorgulama bitiş tarihi. Giriş Formatı : ddmmyyyyhhmm Gönderim takip numarası. Bu alana bilgi girişi yapıldığında, belirtilen tarihler arasında sadece bu mesaja ait sorgu sonucu görüntülenecektir. <MainReportRoot> <Command>30</Command> <ChannelCode>Kanal </ChannelCode> <SDate>28012013000000</SDate> <FDate>28012013235959</FDate> </MainReportRoot> Hata Kodları Hata 01 Kullanıcı adı veya şifre hatalı 02 Takip no hatalı 09 Geçersiz tarih formatı Cevap : OK 61273487 1 1 20120509102140 20120509102140 20120510072140 TUR ATEL 5 True 2 2 2 0 0 0 SMS To Many - TEST SMSchr(32) 24
Durum 0 İşlemde 5 Operatöre iletildi. Sorgulama işlemi başlatılabilir. 7 Kullanıcı tarafından iptal edildi. 8 Bir hata oluştu. Durum detay alanından, hata detayı öğrenilebilir. 51 Fatura borcundan dolayı SMS gönderimi operatör tarafından sonlandırılmıştır. Gönderim Tipi 0 One To Many 1 Many To Many Mesaj Tipi 1 Standart 2 Standart (Türkçe) 3 Binary 4 Flash 5 Wap-Push 7 Flash (Türkçe) Uzun Mesaj 0 160 karakterden az 1 160 karakterden fazla 25
Detaylı Rapor (Detailed Report) Alınan takip numarasına ait gönderimin detaylı durumunu listeler. Tüm alıcıların durumunu sorgulamakla birlikte, tek bir alıcının da durum sorgulaması yapılabilir. Cevap yapısı aşağıdaki şekildedir; OK GSMchr(9)Durumchr(9)İletim Zamanıchr(9)Durum sıchr(9)mesaj İçeriğichr(30) XML NODE Zorunlu Command Detailed Report metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre MessagePacketId Gönderim takip numarası. Msisdn Option Takip numarası belirtilen gönderim içerisinde durumu sorgulanmak istenen alıcı bilgisi. Sorgu sonucu formatı. Alabileceği değerler aşağıdaki gibidir. İçerik görüntülenmesin : 1 İçerik görüntülensin : 2 İstek : <Request> <Command>36</Command> <ChannelCode>Kanal </ChannelCode> <MessagePacketId>Takip No</MessagePacketId> <Option>1</Option> </Request> Hata Kodları Hata 01 Kullanıcı adı veya şifre hatalı 02 Takip no hatalı 04 Gönderim başarısız oldu 05 Gönderim devam ediyor 06 Geçersiz parametre 08 Gönderim kullanıcı tarafından iptal edilmiş 26
Cevap : OK 905339351565chr(9)3chr(9)20130114142500chr(9) chr(30) İstek : <Request> <Command>36</Command> <ChannelCode>Kanal </ChannelCode> <MessagePacketId>Takip No</MessagePacketId> <Option>2</Option> </Request> Cevap : OK 905339351565chr(9)3chr(9)20130114142500chr(9) chr(9)standart SMS Testchr(30) Durum 3 Başarılı (Alıcıya başarılı olarak iletildi) 5 Başarısız (GSM numarası hatalı ya da gönderim iptal edildi) 6 Beklemede (İşlemde veya gönderilmeye çalışılıyor) 9 Zaman Aşımı (Geçerlilik süresi bitene kadar gönderilmeye çalışılmış fakat başarısız olmuş) Durum Detay 0 Unknown subscriber ->Numara Turkcell Network ünde tanımlı değil -> Yeniden denenmemeli 1 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 2 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 3 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 4 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 5 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 6 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 7 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 8 Service temporary not available ->Serviste geçici kesinti -> Yeniden denenebilir 9 Illegal error code 10 Network time-out 100 Facility not supported 101 Unknown subscriber ->Numara Turkcell Network ünde tanımlı değil -> Yeniden denenmemeli 102 Facility not provided 103 Call barred ->SMS servis kullanımı kısıtlanmış -> Yeniden denenmemeli 104 Operation barred ->Yeniden denenmemeli 27
105 SC congestion 106 Facility not supported 107 Absent subscriber ->Mobil istasyon kapalı, yakın zamanda açılmayacağı düşünülerek denenmemeli. 108 Delivery fail ->Mesaj başarısız -> uygulama deneyip denemeyeceğine karar vermelidir. 109 Sc congestion ->Yeniden denenmemeli 110 Protocol error ->Yeniden denenmemeli 111 MS not equipped ->Yeniden denenmemeli 112 Unknown SC ->Yeniden denenmemeli 113 SC congestion ->Yeniden denenmemeli 114 Illegal MS ->Mobil istasyonda sorun var, hemen düzelmeyeceği düşünülerek -> Yeniden denenmemeli 115 MS not a subscriber ->Yeniden denenmemeli 116 Error in MS ->Yeniden denenmemeli 117 SMS lower layer not provisioned ->Yeniden denenmemeli 118 System fail ->Sistem hatası, uygulama deneyip denemeyeceğine karar verebilir 119 PLMN system failure ->Yeniden denenmemeli 120 HLR system failure ->Yeniden denenmemeli 121 VLR system failure ->Yeniden denenmemeli 122 Previous VLR system failure ->Yeniden denenmemeli 123 Controlling MSC system failure ->Yeniden denenmemeli 124 VMSC system failure ->Yeniden denenmemeli 125 EIR system failure ->Yeniden denenmemeli 126 System failure ->Sistem hatası, uygulama deneyip denemeyeceğine karar verebilir 127 Unexpected data value ->Yeniden denenmemeli 200 Error in address service centre ->Yeniden denenmemeli 201 Invalid absolute Validity Period 202 Short message exceeds maximum 203 Unable to Unpack GSM message 204 Unable to convert to IRA ALPHABET ->Yeniden denenmemeli 205 Invalid validity period format 206 Invalid destination address 207 Duplicate message submit 208 Invalid message type indicator -444 Mesaj filtreleme nedeniyle reddedildi. (Abone istemiyor) -426 Kullanıcının mesaj göndermeye izni yok -466 Geçersiz Validity Period -467 TYPE = 2 verilmesine rağmen GSM 7 Bit Karakter içermeyen UZUN (concat) mesaj -470 TCKN'e bir MSISDN bağlı değil / Geçersiz TCKN / Rehberde kayıtlı değil 28
MESAJ TOPLAMA İŞLEMLERİ Mesaj toplama servisi, firmalara TURATEL tarafından tanımlanan anahtar kelimeler (prefix) ile birlikte gönderilen mesajların sorgulanmasını sağlar. Tanımlanan her anahtar kelimenin sistemde bir ApplicationID bilgisi oluşmaktadır. Kullanıcılar tarafından gönderilen mesajlar bu ApplicationID ile sorgulanmalıdır. Sorgulanan mesajlar otomatik olarak okundu durumu ile işaretlenir ve bir sonraki talepte tekrar listelenmez. Mesajlar status = 0 parametresi ile alınırsa bu durum geçerlidir. Mesaj Toplama Uygulamaları Listesi (Get Interactive Applications) Kullanıcı tanımınıza ait uygulamaları listeler. Bu listeden alınacak ID bilgisini sorgulamalarınızda kullanmanız gerekmektedir. XML NODE Zorunlu Command Get Interactive Application metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre ApplicationID Mesaj toplama servisine ait ID bilgisi. Bu alana bilgi girişi yapıldığında sadece belirtilen uygulamaya ait detaylar listelenecektir. İstek : <MainReportRoot> <Command>24</Command> <ChannelCode>Kanal </ChannelCode> <ApplicationID>Uygulama ID</ApplicationID> </MainReportRoot> 29
Cevap : OK <IApplications> <IApplication> <ID>2894</ID> <GSMOperator>TurkCell</GSMOperator> <MSISDN>3172</MSISDN> <Prefix>TEST</Prefix> <CreditsToCharge>0</CreditsToCharge> <SDate>01012013000000</SDate> <FDate>01012014000000</FDate> <PushStatus>0</PushStatus> <PushServiceURL></PushServiceURL> <Status>1</Status> </IApplication> </IApplications> XML NODE IApplication / ID IApplication / GSMOperator IApplication / MSISDN IApplication / Prefix IApplication / CreditsToCharge IApplication / SDate IApplication / FDate IApplication / PushStatus IApplication / PushServiceURL IApplication / Status Mesaj toplama servisinin komut numarası Mesaj toplama servisinin tanımlı olduğu Operatör bilgisi Mesaj toplama servisinin tanımlı olduğu Kısa Numara bilgisi Mesaj toplama servisinin bağlı olduğu anahtar kelime Alınan mesajlar için kullanıcıdan alınacak kredi miktarı. Mesaj toplama servisinin başlayacağı tarih Mesaj toplama servisinin sonlanacağı tarih Mesajların firma tarafından belirlenen URL e gönderilip, gönderilmediğinin bilgisi. 0 ise gönderilmiyor, 1 ise gönderiliyor anlamındadır Mesajların gönderildiği, firma tarafından belirlenen URL bilgisi Mesaj toplama servisinin durumu. 0 ise pasif, 1 ise aktif anlamındadır. Hata Kodları Hata 04 Hatalı mesaj toplama ID bilgisi 06 Kullanıcıya ait mesaj toplama uygulaması bulunamadı 30
Gelen Mesajların Listelenmesi (Get Messages) Verilen Uygulama Numarasına (ApplicationID) ait gönderilen mesajların listeler. Status = 0 verilirse sadece daha önce listelenmemiş (yeni) mesajlar listelenir. Aynı komut tekrar gönderildiğinde bir önceki sorgu sonucundaki mesajlar listelenmez. Bu şekilde sadece yeni gelen mesajları başka parametre vermeden toplamanız mümkündür. XML NODE Zorunlu Command Get Messages metodunun komut numarası. PlatformID Platform Numarası ChannelCode Kanal UserName Kullanıcı Adı PassWord Şifre Status Listelenmek istenen mesajların durumu. Alabileceği değerler aşağıdaki gibidir. Okunmamış : 0 Okunmuş : 1 Tümü : 2 ApplicationID Mesaj toplama servisine ait ID bilgisi. SDate FDate İstek : Mesajların sorgulama başlangıç zamanı Giriş Formatı : ddmmyyyyhhmmss Mesajların sorgulama bitiş zamanı Giriş Formatı : ddmmyyyyhhmmss <MainReportRoot> <Command>25</Command> <ChannelCode>Kanal </ChannelCode> <Status>0</Status> <ApplicationID>Uygulama ID</ApplicationID> <SDate>01012013000000</SDate> <FDate>28012013235959</FDate> </MainReportRoot> Cevap : <Messages> <ApplicationID>1234</ApplicationID> <Message> <MsgID>1234567</MsgID> <Date>xxx</Date> <Number>9053XXXXXXXX</Number> <Text>TEST1</Text> </Message> <Message> <MsgID>1234568</MsgID> <Date>xxx</Date> <Number>9053XXXXXXXX</Number> <Text>TEST2</Text> </Message> </Messages> 31
XML NODE Message / MsgID Message / Date Message / Number Message / Text Listelenen mesajın sistemde tanımlı olan komut numarası Listelenen mesajın sisteme gönderildiği tarih Listelenen mesaja ait GSM numara bilgisi. Gönderen Numarası operatöre göre aşağıdaki şekilde olmaktadır: Turkcell: 05551112233 Vodafone: 5551112233 Avea: 905551112233 Listelenen mesaja ait içerik bilgisi Hata Kodları Hata 02 Hatalı mesaj toplama ID bilgisi 04 Hatalı durum bilgisi 06 Mesaj toplama uygulamasında listelenecek kayıt bulunamadı 09 Hatalı tarih formatı 32
TANIMLAR ONE TO MANY Bir mesajın birden fazla alıcıya aynı anda iletilmesidir. Duyurularınız için bu tip gönderimi tercih edebilirsiniz. MANY TO MANY Farklı Mesajların Farklı Alıcılara bir defada iletilmesidir. Fatura borcu gibi gün sonunda veya belirli aralıklar çalışan uygulamalarınızın müşterilerinize ait borcunu liste halinde hazırlayabilirsiniz. CONCAT (CONCATENATED) Birleştirilmiş/Uzun mesaj anlamında kullanılır. SMS mesajları 160 karaktere kadar 1 mesaj olarak faturalandırılır. 160 karakterden uzun mesajlar CONCAT olarak adlandırılır ve 612 karaktere kadar tek bir mesaj gönderilebilir. 612 karakterlik bir mesaj 4 SMS olarak faturalandırılacaktır. INTERACTİVE (ETKİLEŞİMLİ) MESAJ Telefonlardan size gönderilen mesajlardır. TURATEL de sizin için tanımlanacak bir Interaktif hesaba mesaj gönderilmesini isteyebilirsiniz. Hesap tanımı yapılıp size bir ön ek (prefix) verildikten sonra 3172 e bu prefix ile başlayan mesajlar gönderilebilir ve sorgulama yaparak bu mesajları alabilirsiniz. 33
Turatel Mobil Medya İletişim F.Kerim Gökay Caddesi Erdem Sokak Necdet Kalkavan Plaza No:4 Kat:1-2 Altunizade / İSTANBUL Tel: +90 (216) 474 8888 Faks: +90 (216) 474 3172 info@turatel.com.tr destek@turatel.com.tr 34