04_Kısa Mesaj Servisleri Entegrasyon Dokümanı v3

Transkript

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
TURATEL Mobil Medya | Kısa Mesaj Servisleri Entegrasyon Dokümanı
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 :
<?xml version=“1.0” encoding=“utf-8” ?>
<MainmsgBody>
<Command>0</Command>
<PlatformID>1</PlatformID>
<ChannelCode>Kanal Kodu</ChannelCode>
<UserName>Kullanıcı Adı</UserName>
<PassWord>Şifre</PassWord>
<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
İstek :
<MainReportRoot>
<MsgID>61273486</MsgID>
</MainReportRoot>
Cevap :
9053XXXXXXXXchr(32)3chr(32)1
Mesaj Toplama
Metod : HTTP POST
İstek :
<MainReportRoot>
<Status>0</Status>
<ApplicationID>Uygulama Id</ApplicationID>
</MainReportRoot>
Cevap :
<Messages>
<Message>
<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:
http://processor.smsorigin.com/xml/process.aspx
veya
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
Kodu
Açıklama
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
√
Açıklama
Check Date metodunun komut numarası.
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
İstek :
<CheckDate>
</CheckDate>
8
Hata Kodları
Hata
Kodu
Açıklama
01
Kullanıcı Adı ve/veya Şifre Hatalı
07
Genel Hata
Cevap :
260120131123
Şifre Değiştirme (Change Password)
Kullanıcı şifre değişikliği için kullanılır.
XML NODE
Zorunlu
Command
√
Açıklama
Change Password metodunun komut numarası
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
NPassWord
√
Yeni Şifre
İstek :
<ChangePassWord>
<NPassWord>Yeni Şifre</NPassWord>
</ChangePassWord>
Hata Kodları
Hata
Kodu
01
02
03
Açıklama
Kullanıcı adı veya şifre hatalı
Şifre değiştirilemedi
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
√
Açıklama
Get Credit metodunun komut numarası
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
İstek :
<MainReportRoot>
</MainReportRoot>
Hata Kodları
Hata
Kodu
01
Açıklama
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
√
Açıklama
Cancel Job metodunun komut numarası
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
MsgID
√
Gönderim takip numarası
İstek :
<CancelJob>
<MsgID>Takip No</MsgID>
</CancelJob>
Hata Kodları
Hata
Kodu
Açıklama
01
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ıç
1
153
306
459
Bitiş
160
306
459
612
Mesaj Sayısı
1 Mesaj
2 Mesaj
3 Mesaj
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ıç
1
153
Bitiş
160
268
Mesaj Sayısı
1 Mesaj
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 Kodu
(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
√
Açıklama
SMS to Many metodunun komut numarası
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
Mesgbody
√
Numbers
√
Gönderilecek mesaj içeriği
Gönderilecek alıcı listesi. Her alıcı “;” veya “,” karakterleri ile
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.
Type
√
Originator
√
SDate
EDate
Concat
IsTCKimlikNoPacket
Option
Standart
:1
Flash
:4
Standart Türkçe : 2
Flash Türkçe
:7
Binary
:3
Wap-Push
:5
Gönderen ismi.
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.
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.
GSM yerine TC Kimlik No’ya gönderim yapılmasını sağlar. Alıcı
tipinin TC Kimlik No olarak algılanması için “1” olarak
ayarlanması gerekmektedir.
OTP ( One Time Password / Single Shot ) gönderimlerde “1”
olarak verilmelidir.
15
GSM Numarası alıcılarına:
İstek :
<MainmsgBody>
<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
Kodu
Açıklama
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:61273487
16
TC Kimlik Numarası alıcılarına:
İstek :
<MainmsgBody>
<Type>1</Type>
<Concat>0</Concat>
<IsTCKimlikNoPacket>1</IsTCKimlikNoPacket>
<Mesgbody>SMS To Many TCKN - TEST SMS</Mesgbody>
<Numbers>26497188029,29674966209</Numbers>
<SDate>280120131325</SDate>
<EDate>280120131525</EDate>
</MainmsgBody>
Hata
Kodu
Açıklama
01
02
03
Geçersiz içerik
04
Bilinmeyen SMS tipi
05
06
Mesaj metni ya da Alıcı bilgisi girilmemiş.
07
08
09
11
TC Kimlik No gönderim yetkisi bulunmamaktadır
Cevap :
ID:61273488
17
GSM Numarası Alıcılarına Single Shot (OTP - One Time
Password):
İstek :
<MainmsgBody>
<Type>1</Type>
<Concat>0</Concat>
<Option>1</Option>
<Mesgbody>SMS To Many OTP - TEST SMS</Mesgbody>
<Numbers>905321111111,905331111111</Numbers>
<SDate>280120131425</SDate>
</MainmsgBody>
Cevap :
ID:61273489
Hata Kodları
Hata
Kodu
Açıklama
01
Kullanıcı adı yada şifre hatalı
02
03
Geçersiz içerik
04
Bilinmeyen SMS tipi
05
06
07
08
09
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
√
Açıklama
SMS to Multisenders metodunun komut numarası
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
Mesages / Message / Mesgbody
√
Gönderilecek mesaj içeriği
Mesages / Message / Number
√
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.
Type
√
Standart
Flash
Standart Türkçe
Flash Türkçe
Originator
√
Gönderen ismi.
:
:
:
:
1
4
2
7
SDate
Mesajın gönderime başlanacağı tarih. Boş
bırakıldığında gönderim hemen gerçekleşir.
Giriş Formatı
: ddMMyyyyHHmm
EDate
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
Concat
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.
Option
Single Shot (OTP - One Time Password)
gönderimlerde “1” olarak ayarlanmalıdır.
19
GSM Numarası alıcılarına:
İstek :
<MainmsgBody>
<Type>1</Type>
<Concat>0</Concat>
<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>
</Message>
</Messages>
<SDate>280120131330</SDate>
<EDate>280120131530</EDate>
</MainmsgBody>
Hata Kodları
Hata
Kodu
Açıklama
01
02
03
Geçersiz içerik
04
Bilinmeyen SMS tipi
05
06
07
08
09
Cevap :
ID:61273490
20
GSM Numarası Alıcılarına Single Shot (OTP):
İstek :
<MainmsgBody>
<Option>1</Option>
<Type>1</Type>
<Concat>0</Concat>
<Messages>
<Message>
<Mesgbody>SMS To Multisender 1 - TEST SMS</Mesgbody>
</Message>
<Message>
<Mesgbody>SMS To Multisender 2 - TEST SMS </Mesgbody>
</Message>
</Messages>
<SDate>280120131325</SDate>
</MainmsgBody>
Hata Kodları
Hata
Kodu
Açıklama
01
02
03
Geçersiz içerik
04
Bilinmeyen SMS tipi
05
06
07
08
09
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
√
Açıklama
Report By Id metodunun komut numarası.
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
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>
<MsgID>Takip No</MsgID>
<Status></Status>
<AddDeliveryTime></AddDeliveryTime>
</MainReportRoot>
Hata Kodları
Hata
Kodu
Açıklama
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
Kodu
3
Açıklama
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 Açıklama||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 Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
SDate
√
Sorgulama başlangıç tarihi.
Giriş Formatı
: ddMMyyyyHHmm
FDate
√
Sorgulama bitiş tarihi.
Giriş Formatı
: ddMMyyyyHHmm
MessagePacketId
Açıklama
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.
İstek :
<MainReportRoot>
<SDate>28012013000000</SDate>
<FDate>28012013235959</FDate>
</MainReportRoot>
Hata Kodları
Hata
Kodu
Açıklama
01
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
Kodu
0
Açıklama
İş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
Açıklama
0
One To Many
1
Many To Many
Mesaj
Tipi
1
Açıklama
Standart
2
Standart (Türkçe)
3
Binary
4
Flash
5
Wap-Push
7
Flash (Türkçe)
Uzun
Mesaj
Açıklama
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 Açıklamasıchr(9)Mesaj
İçeriğichr(30)
XML NODE
Zorunlu
Command
√
Açıklama
Detailed Report metodunun komut numarası.
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
MessagePacketId
√
Gönderim takip numarası.
Takip numarası belirtilen gönderim içerisinde durumu
sorgulanmak istenen alıcı bilgisi.
Msisdn
Option
√
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>
<MessagePacketId>Takip No</MessagePacketId>
<Option>1</Option>
</Request>
Hata Kodları
Hata
Kodu
Açıklama
01
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>
<MessagePacketId>Takip No</MessagePacketId>
<Option>2</Option>
</Request>
Cevap :
OK|905339351565chr(9)3chr(9)20130114142500chr(9) chr(9)Standart SMS –
Testchr(30)
Durum
Kodu
3
Açıklama
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
Açıklama
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
3
4
5
6
7
8
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 Kodu
UserName
√
Kullanıcı Adı
PassWord
√
Şifre
ApplicationID
Açıklama
Mesaj toplama servisine ait ID bilgisi. Bu alana bilgi girişi yapıldığında
sadece belirtilen uygulamaya ait detaylar listelenecektir.
İstek :
<MainReportRoot>
<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
Açıklama
IApplication / ID
Mesaj toplama servisinin komut numarası
IApplication / GSMOperator
Mesaj toplama servisinin tanımlı olduğu Operatör bilgisi
IApplication / MSISDN
Mesaj toplama servisinin tanımlı olduğu Kısa Numara bilgisi
IApplication / Prefix
Mesaj toplama servisinin bağlı olduğu anahtar kelime
IApplication / CreditsToCharge
Alınan mesajlar için kullanıcıdan alınacak kredi miktarı.
IApplication / SDate
Mesaj toplama servisinin başlayacağı tarih
IApplication / FDate
Mesaj toplama servisinin sonlanacağı tarih
IApplication / PushStatus
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
IApplication / PushServiceURL
Mesajların gönderildiği, firma tarafından belirlenen URL bilgisi
IApplication / Status
Mesaj toplama servisinin durumu. “0” ise pasif, “1” ise aktif
anlamındadır.
Hata Kodları
Hata
Kodu
Açıklama
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
Açıklama
Command
√
Get Messages metodunun komut numarası.
PlatformID
√
Platform Numarası
ChannelCode
√
Kanal Kodu
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
Mesajların sorgulama başlangıç zamanı
Giriş Formatı
: ddMMyyyyHHmmss
FDate
Mesajların sorgulama bitiş zamanı
Giriş Formatı
: ddMMyyyyHHmmss
İstek :
<MainReportRoot>
<Status>0</Status>
<ApplicationID>Uygulama ID</ApplicationID>
<SDate>01012013000000</SDate>
<FDate>28012013235959</FDate>
</MainReportRoot>
Cevap :
<Messages>
<ApplicationID>1234</ApplicationID>
<Message>
<Date>xxx</Date>
<Number>9053XXXXXXXX</Number>
<Text>TEST1</Text>
</Message>
<Message>
<Date>xxx</Date>
<Number>9053XXXXXXXX</Number>
<Text>TEST2</Text>
</Message>
</Messages>
31
XML NODE
Açıklama
Message / MsgID
Listelenen mesajın sistemde tanımlı olan komut numarası
Message / Date
Listelenen mesajın sisteme gönderildiği tarih
Message / Number
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
Message / Text
Listelenen mesaja ait içerik bilgisi
Hata Kodları
Hata
Kodu
Açıklama
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
[email protected]
[email protected]
34

04_Kısa Mesaj Servisleri Entegrasyon Dokümanı v3

Transkript

Benzer belgeler

Giden Parametreler

XML API - smsmax.net

XML API İndir

İçindekiler

erkekler-icin-arkadaslik-siteleri

XML ile Mesaj İşlemleri

TürkiyeSMS Toplu Sms Gateway API

Üniversite Öğrencilerinin Mobil Reklâmcılığa Karşı Tutumları

BTP208 – İnternet Programcılığı II XML ve XML Uygulamaları (2

Degerli Turkish Virtual Pilotlari. Son zamanlarda Turkish Virtual pilot

Global Haberleşme API Kullanıcı Notları SMS Gönderimi hakkında

DAP-06 Alarm Paneli

Google Apps - Googleusercontent.com

FineELEC

Bayi Alış Net Fiyat Listesi

Şubat 2012 tarihli Birtaş kablo fiyat listesi

Kullanım Kılavuzu - Dikey iletişim elektronik

LunaMetrics, Google Analytics`in özelliklerini ihtiyaçlara göre

dbWiz: Akademik Kütüphaneler İçin Açık Kaynak ve Birleşik Tarama

Sosyalleşmenin Yeni Yüzü: Sosyal Paylaşım Ağları

Undergraduate Course Plan - Çalışma Ekonomisi ve Endüstri İlişkileri

ı ı ı - Dikey iletişim elektronik