Xml Arayüzleri version 2.6 Son güncelleme Tarihi

Xml Arayüzleri version 2.6 Son güncelleme Tarihi

Xml Arayüzleri
version 2.6
Son güncelleme Tarihi : 26.01.2011
Eklenen Yenilikler :
- Şifre Değiştirme eklendi.
- Paket Bazında Ayrıntılı Rapor eklendi.
- Detay Rapor Eklendi.
Son güncelleme Tarihi : 13.01.2011
1.
Genel Bilgiler
2.
Uyarılar ve Öneriler
3.
Alan Açıklamaları
4.
Mesaj Tipleri
5.
SMS To Many (Aynı Mesajın Çok Numaraya Yollanması)
6.
Sms To Multisenders (Farklı Mesajların Farklı Numaralara Yollanması)
7.
Report By Id ( Belirli bir İşlemin İletim Raporu )
8.
GetCredit ( Originator ve Krediyi Aynı Anda Sorgulama )
9.
Cancel Job ( İleri Tarihli bir gönderimin iptal edilmesi )
10.
CheckDate ( Güncel Sistem Saatinin öğrenilmesi )
11.
Change Password (Kullanıcı şifresinin değiştirilmesi )
12.
Packet Based Report (Paket bazında rapor alınması)
13.
Detailed Report
1. Genel Bilgiler
Yazılım geliştiren firmaların kullanılabilecekleri iki çeşit sms gönderme yöntemi
sağlamaktadır.
•
Aynı mesajın çok numaraya yollanması,
•
Farklı mesajların farklı numaralara yollanması
İki yöntemde de mesajlar, ve diğer işlemler XML Envelop‟u olarak gönderilmektedir.
Oluşturulacak tüm İstekler aşağıdaki adrese Post edilmelidir.
http://processor.smsorigin.com/xml/process.aspx
yada secure bağlantı için
https://processor.smsorigin.com/xml/process.aspx
Genel Hata Kodları:
20 : Bilinmeyen hata
21 : Yanlış XML formatı
22 : Kullanıcı aktif değil
23 : Kullanıcı zaman aşımı
2. Uyarılar ve Öneriler
- Uzun(Concatenated) Mesaj göndermek isteyen kullanıcılar, Concat parametresini "1" olarak
ayarlamalıdır.
- Uzun Mesajların raporlarında, 1 numaraya ait mesajların herbiri için kayıt dönülür.
- & , < gibi XML‟in özel karakterlerini gönderebilmeniz için bu karakterleri aşağıdaki gibi
encode etmeniz gerekmektedir.
&lt; < less than
&gt; >greater than
&amp; & ampersand
&apos; ‟apostrophe
&quot; “ quotation mark
- Yurtdışına sms gönderiminde Tel numaralarının +49******** formatında olmasına dikkat
edilmelidir.Sms gönderilecek ülkedeki
ülke kodu + prefix + telno 12 karakterden küçük olması halinde de yine +35*********
şeklindeki bir format kullanılarak sms gönderimi yapılabilir.
- Hem SmsToMany, hem de SmsMultiSenders gönderimler sırasında numaralar
5421234567,05421234567 ya da 905421234567 şeklinde verilebilir.Ancak rapor alındığında
bütün numaralar 905421234567 şeklinde görünecektir. Yapılacak kodlamalarda bu durum
dikkate alınmalıdır.
3. Alan Açıklamaları
Xml İsteklerinde kullanılan Nodelara ait açıklamalar aşağıdaki gibidir.
PlatformID : Yetkili tarafından sağlanacak PlatformID. Yetkili tarafından aksi
söylenmedikçe 1 olarak girilmelidir.
ChannelCode : Yetkili tarafından sağlanacak Kanal Kodu.
UserName : Yetkili tarafından sağlanacak kullanıcı adı.
Password : Yetkili tarafından sağlanacak kullanıcı şifresi.
Command : Her işleme göre farklılık gösteren İşlem kodu. Alabileceği değerler aşağıdaki
gibidir.
Smstomany: 0
Smstomultisenders: 1
Reportbydate: 2
ReportbyId: 3
Canceljob: 4
Checkdate: 5
Getcredit: 6
Mesgbody : Type kısmında belirtilen formata göre oluşturulacak mesaj metni. MesajTipine
göre Mesgbody'nin oluşturulması ile ilgili açıklamaları Mesaj Tipleri kısmına
bulabilirsiniz.
Numbers : Smstomany, yani 1 mesaj metninin birden fazla numaraya gönderilmesinde
kullanılır. Numaralar 905422222222, 05423333333 veya 5444444444 şeklinde olabilir ve
numaralar arasında ayraç olarak virgül kullanılmalıdır.
Type : Mesajın formatını belirlemek için kullanılacaktır. Ayrıntılı açıklamaları Mesaj Tipleri
kısmına bulabilirsiniz.
Alacağı değerler.
Text SMS : 1
Wap-Push : 5
SDate : Mesajın gönderilmeye başlanacağı tarihi gösterir ddmmyyyyhhmm formatındadır. Bu
değer belirtilmemişse mesaj hemen yollanır.
Server tarihinden eski bir tarihe gönderilmeye çalışılırsa Mesajlar Hemen gidecektir.
EDate : Mesajın gönderim işleminin biteceği tarihi gösterir ddmmmyyyhhmm formatındadır..
Hiçbir değer girilmemişse mesaj 24 saat içerisinde gönderilmeye devam edilir. End Date min.
90 dakika olmalıdır. 90 dakikadan küçük EndDate'lerde otomatik olarak 90 dakika ayarlanır.
24 saatten büyük EndDate ayarlamasında ise otomatik olarak 24 saat olarak ayarlanır.
End Date her zaman Send Date „ ten büyük bir tarih olmalıdır. Bu durumda End Date ,
Send Date„ e 24 saat eklenerek uygulanır.
End Date, şu anki tarihten küçük bir tarih olmamalıdır. Bu durumda End Date , Send
Date„ e 24 saat eklenerek uygulanır.
Originator : Mesaj gönderilirken kullanılacak originator seçilebilir. Boş ise default olan
originator kullanır.
Concat : Gelen istekte, Mesaj Tipine ait 1 mesajda gönderilemeyecek İçerik var ise, bunu
otomatik olarak 1 den fazla mesaj olarak göndermesi için gerekli parametredir. Mesela 160
karakterlik Text Sms gönderilirken , Mesgbody alanına 160 tan fazla içerik yazılırsa ve
Concat parametresi 1 olarak ayarlanırsa Mesajlar aboneye tek bir mesaj olarak ulaşacak fakat
aslında birden fazla mesajın birleştirilerek gönderilmiş olacaktır.
Alacağı değerler.
0 : Mesajlar uzun olarak gönderilmesin.
1 : Mesajlar uzun olarak gönderilsin.
IsTCKimlikNoPacket : Msisdn yerine, Tc Kimlik No üzerinden gönderim yapmayı sağlar.
Parametre 1 olarak gönderilirse, Msisdn olarak yazılan değerler Tc Kimlik No olarak kabul
edilir. Bu gönderimler Concatenated Mesajları desteklemez.
4. Mesaj Tipleri
1.Text (ASCII 160 karakter):
Xml isteğinde Type Node u 1 olmalıdır.
Maximum uzunluk değerleri her mesaj için.
Normal : 160 karakter
Concat : 153 karakter
Mesgbody Node'una String değer olarak yazılır.
2. WapPush :
Xml isteğinde Type Node u 5 olmalıdır.
Mesgbody Node'unda ayrı bir Xml yapısı olarak girilir.Yapı aşağıdaki gibidir.
<Mesgbody>
<Indicator></Indicator>
<URL></URL>
</Mesgbody>
Indicator : Mesaj açıklaması olarak yazılacak kısım
URL : Adres bilgisi. Mutlaka aşağıdakilerden bir tanesi ile başlamalıdır.
http://
https://
http://www.
https://www.
5. SMS To Many (Aynı Mesajın Çok Numaraya Yollanması)
Bu yöntemde amaç tek bir mesaj metninin farklı numaralara yollanabilmesidir. Bu yöntemde
kullanılacak olan XML formatı aşağıdaki gibidir:
<MainmsgBody>
<Command>0</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<PassWord>password</PassWord>
<ChannelCode>channelcode</ChannelCode>
<Mesgbody> test mesajıdır </Mesgbody>
<Numbers>905329000000,905323333333</Numbers>
<Type>1</Type>
<Originator></Originator>
<SDate></SDate>
<EDate></EDate>
<Concat></Concat>
<IsTCKimlikNoPacket>1</IsTCKimlikNoPacket>
</MainmsgBody>
Bu XML POST edildiğinde “responsetext” olarak bir string dönülür. Bu string gönderilen
mesajlar için bir numara içerir.
Örnek: ”ID:123456”
Burada 123456 gönderilen mesajlarla ilgili server tarafından atanan işlem numarasını gösterir.
Bu numara daha sonra iletim raporları alma işleminde kullanılacaktır.
Başarılı Durum :
ID:123456 : SMS Gönderimi için dosya kabul edildi.
Hata Kodları :
01 : Username/PassWord yanlış girilmiş.
02 : Kredisi yeterli değil.
03 : Geçersiz içerik.
04 : Bilinmeyen SMS Tipi
05 : Yanlış Originator seçimi yapılmış.
06 : Mesaj metni yada numaralar boş girilmiş.
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 veya şu anda çalışmıyor.
09 : Yanlış Tarih formatı , Tarihler ddmmyyyyhhmm formatında olmalıdır.
11 : TCKimlikNo gönderimi yetkisi yok.
6. Sms To Multisenders (Farklı Mesajların Farklı Numaralara
Yollanması)
Bu yöntemde amaç farklı numalara farklı mesajların aynı anda yollanabilmesidir. Örneğin;
Herbir müşteriye farklı ödeme tutarlarının gönderilmesi gibi. Bu yöntemde kullanılacak XML
Envelopu aşağıdaki gibidir:
<MainmsgBody>
<Command>1</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode> channelcode </ChannelCode>
<PassWord> password</PassWord>
<Messages>
<Message>
<Mesgbody>SAYIN OZAN ÇETİN, BORCUNUZ 45 YTL DİR.</Mesgbody>
<Number>905320000000</Number>
</Message>
<Message>
<Mesgbody> SAYIN HAKAN GÖK, BORCUNUZ 67 YTL DİR.</Mesgbody>
<Number>905320000001</Number>
</Message>
</Messages>
<Type>1</Type>
<Originator></Originator>
<SDate>301220051229</SDate>
<EDate>311220051259</EDate>
<Concat></Concat>
</MainmsgBody>
Bu XML POST edildiğinde “responsetext” olarak bir string dönülür. Bu string gönderilen
mesajlar için bir numara içerir.
Örnek: ”ID:123456”
Burada 123456 gönderilen mesajlarla ilgili server tarafından atanan işlem numarasını gösterir.
Bu numara daha sonra iletim raporları alma işleminde kullanılacaktır.
Başarılı Durum :
ID:123456 : SMS Gönderimi için dosya kabul edildi.
Hata Kodları :
01 : Username/PassWord yanlış girilmiş.
02 : Kredisi yeterli değil.
03 : Geçersiz içerik.
04 : Bilinmeyen SMS Tipi
05 : Yanlış Originator seçimi yapılmış.
06 : Mesaj metni yada numaralar boş girilmiş.
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 veya şu anda çalışmıyor.
09 : Yanlış Tarih formatı , Tarihler ddmmyyyyhhmm formatında olmalıdır.
11 : TCKimlikNo gönderimi yetkisi yok.
7. Report By Id ( Belirli bir İşlemin İletim Raporu )
Mesaj gönderme işlemi başarıyla tamamlandıktan sonra gönderilen mesajların ulaşıp
ulaşmadığına ilişkin iletim raporu alabilme işlemi aşağıdaki XML Envelop‟u POST edilerek
gerçekleştirilebilir.
<MainReportRoot>
<Command>3</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode>channelcode</ChannelCode>
<PassWord>password</PassWord>
<MsgID>123456</MsgID>
</MainReportRoot>
Yukardaki XML Envelop‟u adresine POST edildiğinde XML responsetext aşağıdaki gibi
olacaktır.
GsmNo gönderimde 0543** veya 543** formatlarında gönderilse dahi raporlarda 90543**
şeklinde alınacaktır.
Başarılı Durum :
905321111111 5 1
905421111112 3 1
905551111113 6 1
1.Sütun : SMS gönderilen numara.
2.Sütun : SMS‟in iletim durumu.(status)
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ı
olamamış numaralar)
3.Sütun : Gönderilen SMS‟in Tipi.
Hata Kodları :
01 : Username/PassWord yanlış girilmiş.
02 : UserName'e ait, verilen ID numarali bir işlem bulunamadi.
03 : ID girilmemiş veya genel bir hata oluştu.
04 : İşlem başarısız olmuştur.(Multisenders gönderim ise mesaj metinleri yada numaralar
boştur)
05 : Verilen ID‟li işlem şuanda yazılıyor-filtreleniyor veya gönderiliyor. Bu işleme ait SMS
bulunamadı.
07 : Verilen ID‟li işlem‟a ait SMS bulunamadı. Yani boş bir işlem.
08 : İşlem kullanıcı tarafından iptal edilmiş.
8. Get Credit ( Originator ve Krediyi Aynı Anda Sorgulama )
Kullanıcı mevcut kredisini ve kullanabileceği Originator‟ları bir tek istekle sorgulayabilir.
<MainReportRoot>
<Command>6</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode>channelcode</ChannelCode>
<PassWord>password</PassWord>
</MainReportRoot>
Çıktısı aşağıdaki gibi olacaktır :
5123
ORIGINATOR1
ORIGINATOR2
Hata Kodları :
01 : Username/Password yanlış girilmiş.
9. Cancel Job ( İleri Tarihli bir gönderimin iptal edilmesi )
İleri tarihli bir gönderimi iptal etmek için aşağıdaki XML kullanılır.
<CancelJob>
<Command>4</Command>
<PlatformID>1</PlatformID>
<UserName>test</UserName>
<ChannelCode> channelcode</ChannelCode>
<PassWord>pwd</PassWord>
<MsgID>123456</MsgID>
</CancelJob>
Başarılı Durum :
OK : İşlem iptal edildi
Hata Kodları :
01 : Username/PassWord yanlış girilmiş ya da ID girilmemiş.
02 : İşlem iptal edilemedi ( işlem tamamlanmış ya da şu anda yapılıyor )
10. Check Date ( Güncel Sistem Saatinin öğrenilmesi )
Güncel Sistem Saati için XML aşağıdaki gibidir.
<CheckDate>
<Command>5</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode> channelcode</ChannelCode>
<PassWord>password</PassWord>
</CheckDate>
Başarılı Durum :
180520041203 : Güncel sistem saati ddMMyyyyHHmm formatında döner.
Hata Kodları :
01 : Username/PassWord yanlış girilmiş ya da ID girilmemiş.
07 : Genel hata.
11. ChangePassword (Kullanıcı şifresinin değiştirilmesi )
<ChangePassWord>
<Command>13</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode>channelcode</ChannelCode>
<PassWord>password</PassWord>
<NPassWord>npassword</NPassWord>
<ChangePassWord>
Başarılı Durum :
OK
Hata Kodları :
02 : Şifre Değiştirilemedi
03 : Geçersiz Şifre
12. Packet Based Report (Paket bazında rapor alınması)
2 Tarih arasında gönderilen Mesaj Paketlerine ait ayrıntıları verir. MessagePacketId
parametresi ile tek 1 paketin ayrıntısıda alınabilir.
<MainReportRoot>
<Command>30</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode>channelcode</ChannelCode>
<PassWord>password</PassWord>
<SDate>Start date</SDate>
<FDate>Finish date</FDate>
<MessagePacketId>packetId</MessagePacketId> //Optional
<Option>1</ Option> //Must
</MainReportRoot>
Başarılı Durum :
Paket Id||Content Gönderim türü||Mesaj Tipi||Gönderilme Zamanı||Başlangıç Tarihi||Bitiş
Tarihi||Originator||Durum||Durum Açıklaması||Concat||Toplam MSISDN Sayısı||Toplam
Mesaj Sayısı||Başarılı Mesaj Sayısı||İptal Mesaj Sayısı||Bekleyen Mesaj Sayısı||Zaman aşımı
mesaj sayısı||Mesaj Metni
Column Delimiter (Kolan Ayıracı) : “||”
Row Terminator (Satır Sonlandırıcı) : chr(30)
Alan Açıklamarı :
Content Gönderim türü :
0 : One To Many
1 : Many To Many
Concat :
0 : Uzunsa Birleştirilmesin
1 : Uzunsa birleştirilsin
Status Alanı :
0 : İşlemde
5 : Operatöre Gönderildi, Rapor Çekilebilir
7 : Kullanıcı tarafından İptal edildi
8 : Bir hata oluştu. (Acıklama alanına bakılsın)
Durum Açıklaması alanı :
51 : Fatura borcundan dolayı gitmemiş
Hata Kodları :
01 : Username/PassWord yanlış girilmiş.
07 : Verilen ID‟li işlem‟a ait SMS bulunamadı. Yani boş bir işlem.
09 : Geçersiz Tarih Formatı
13. Detailed Report
<Request>
<Command>36</Command>
<PlatformID>1</PlatformID>
<UserName>username</UserName>
<ChannelCode>channelcode</ChannelCode>
<PassWord>password</PassWord>
<MessagePacketId>MessagePacketId</MessagePacketId>
<Msisdn>Msisdn</Msisdn> //Optional
<Option>Option</Option>
</Request>
Alan Açıklamarı :
MessagePacketId : Gönderilen Mesaja ait Id no.
Msisdn : Gsm No
Option : Rapor Tipi 1 veya 2 değerini alır.
-
1 : “Msisdn, Durum, Ulaşma Zamanı, Durum Açıklaması” alanlarını döndürür.
2: “Msisdn, Durum, Ulaşma Zamanı, Durum Açıklaması, Mesaj Metni” alanlarını
döndürür.
Başarılı Durum :
OK|GsmNo0<TAB>Durum<TAB>UlaşmaTarihi<TAB>DurumAçıklaması<TAB>MesajMetni<CHR(30)>
1.Sütun : SMS gönderilen numara.
2.Sütun : SMS‟in iletim durumu.(status)
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ı
olamamış numaralar)
3.Sütun : Ulaşma Tarihi. Mesaj başarılı ise Ulaşma tarihi döner. Başarısız ise boştur.
Tarih formatı : yyyyMMddHHmmss
4. Sütun : Mesaj başarılı ise boştur. Başarısız ise durumuna ait açıklama var ise hata kodu
olarak döner.
5. Sütun : Option = 2 olarak set edilirse , Msisdn‟e ait Mesaj metnini döner.
Hata Kodları :
01 : Username/PassWord yanlış girilmiş.
02 : Verilen ID‟li işlem‟a ait Paket bulunamadı
04 : Paket başarısız olmuş.
05 : Paket gönderilmek üzere işleniyor.
06 : Geçersiz parametre
08 : Paket kullanıcı tarafından iptal edilmiş.
Status Description Değerleri :
000 Unknown subscriber ->Numara Turkcell Network‟ünde tanımlı değil -> Yeniden
denenmemeli
001 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
002 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
003 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
004 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
005 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
006 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
007 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
008 Service temporary not available ->Serviste geçiçi kesinti -> Yeniden denenebilir
009 Illegal error code
010 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
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
01 Checksum error
02 Syntax error
03 Operation not supported by system
04 Operation not allowed
05 Call barring active
06 AdC invalid
07 Authentication failure
09 GA not valid
19 New AC not valid
20 New legitimisation code not valid
21 Standard text not valid
22 Time period not valid
23 Message type not supported by system
24 Message too long
25 Requested standard text not valid
26 Message type not valid for the pager type
27 Message not found in SMSC
30 Subscriber hang-up
31 Fax group not supported
32 Fax message type not supported
33 Address already in list (60 series)
34 Address not in list (60 series)
35 List full, cannot add address to list (60 series)
36 RPID already in use
37 Delivery in progress
38 Message forwarded