COM API v.1.1

www.smsmakinesi.com
[email protected]
COM API v.1.1
BELGE SÜRÜMÜ
: 1.1
1
www.smsmakinesi.com
1. İÇİNDEKİLER
1. İçindekiler…………………………………………………………………………………………………………2
2. Bu Belgenin Amacı………………………………………………………………………………………………3
3. Kullanım Şekli…………………………………………………………………………………………………….3
4. Uyarılar…………………………………………………………………………………………………………….4
5. Hata Kodları……………………………………………………………………………………………………….4
6. Kullanıcı Bilgileri Kontrolü……………………………………………………………………………………..5
7. Mesaj (SMS) Gönderimi…………………………………………………………………………………………6
7.1. Addtosmsbasket Yöntemi…………………………………………..……………………………….6
7.2. Sendsms Yöntemi…………………………………………..…………………………………….......7
7.3. Clearsmsbasket Yöntemi……………………………….…………………………………………...7
8. Raporlama……………………………………………………………………………………………………..….8
8.1. Tarih Bazında Raporlama (Getmsgstatustodate Yöntemi)…………………………………....8
8.2. Gönderilen Mesaj Bazında Raporlama (Getmsgstatus Yöntemi)…………………………….9
2
www.smsmakinesi.com
2. Bu belgenin amacı
Bu belge, toplu mesaj (SMS) gönderim hizmetimizi kullanmak isteyen yazılım geliştiricilerin,
kullanmakta oldukları yazılım geliştirme ortamlarıyla Hermes SMS Hizmetlerini entegre edebilmelerini
sağlayan COM API çözümümüzün nasıl kullanılacağını açıklamak için hazırlanmıştır.
3. Kullanım Şekli
Hermes COM API, uygulama geliştiricilerin çözümlerini SMS teknolojisiyle bütünleştirmelerini
sağlamak amacıyla IDE bağımsız olarak geliştirilmiş bir COM çözümüdür.
Yazılım geliştiriciler, COM API tarafından sunulan yöntemleri, bu belgede belirtilen şekilde
kullanarak çağırırlar. Çağrılan yöntemler http://gateway.smsmakinesi.com/ (Bundan sonra Gateway olarak
anılacaktır.) adresine, taşımış oldukları parametreleri aktarırlar. Aktarılan parametreler Gateway tarafından
işlenir. Eğer parametre bilgilerinde ya da gönderilen SMS paketinde hata oluşmuşsa, yakalanan hata HTTP
üzerinden önceden tanımlı bir kod olarak göndericiye iletilir. Eğer bir hata oluşmamışsa gönderilmiş olan
parametre ya da SMS paketine uygun dönüş ifadesi hazırlanıp HTTP üzerinden göndericiye iletilir.
Önceden tanımlı hata kodları, belgenin ilgili ayrımında ayrıntılı olarak açıklanacaktır.
Not:
Hermes Com_Api yi işletim sistemine tanıtabilmek için command ekranında
regsvr32 “c:\smsmakinesi.dll”
komutunu çalıştırmak gereklidir. (dll dosya yolunu kendiniz belirleyebilirsiniz)
Daha sonra SMSMakinesi.Gateway sınıfından bir nesne yaratılıp desteklenen fonksiyonlar kullanılabilir.
Örnek olarak ;
Visual Basic
Set objSms = Server.CreateObject("SMSMakinesi.Gateway")
objSms.getinfo(parameters)
.Net c#
SMSMakinesi.Gateway objSms = new SMSMakinesi.Gateway();
objSms.getinfo();
3
www.smsmakinesi.com
4. Uyarılar:
Hermes COM API çözümü aşağıdaki uyarılar göz önünde bulundurularak kullanılmalıdır.
•
•
GSM numaraları 53XXXXXXXX şeklinde olmalıdır.
Mesaj içeriğinde Türkçe karakter veya aşağıdaki işaretler bulunmamalıdır.
|
^
€
{
}
[
~
]
\
5. Hata Kodları :
Hata Kodu
-1
-2
Açıklama
Hermes sunucusuna erişimde sorun var. Lütfen internet bağlantınızı kontrol
ediniz.
Sms sepeti Boş.
01
Hatalı kullanıcı adı – şifre – bayi kodu
02
04
Böyle bir Mesaj id kayıtlı değil.
05
XML düğümü eksik ya da hatalı
06
Tanımsız Originator Bilgisi
08
Verilen tarihler arasında SMS gönderimi yok ya da Gönderim Raporu hazır değil
09
Tarih alanları boş veya hatalı
11
Tanımlanamayan hata
14
Gönderimde Hatalı Numaralar var.
15
Mesaj gönderiminde hatalı içerik var.
Tablo-1
Gelen XML yok
4
www.smsmakinesi.com
6. Kullanıcı Bilgileri Kontrolü
Hermes COM API, kullanıcı bilgileri kontrolü için getinfo adıyla bir yöntem sunar.
Söz dizimi:
getinfo(“username”, “password”, “vendor_id”) şeklindedir.
Bu yöntemde:
UserName parametresi, Hermes’de tanımlı kullanıcı adınızı,
PassWord parametresi, Hermes’de tanımlı olan kullanıcı adınıza ait şifreyi ifade etmektedir.
Vendor_id parametresi, Kulanıcının Hermes’ de tanımlı bayi kodu.
Getinfo yöntemini örnekte belirtildiği gibi çağırıp Gateway’a gönderdiğinizde aşağıdaki geri dönüş
değerlerini alırsınız:
2. İşlem başarılıysa:
Originator1<10>
Originator2<10>
Originator3<10>
Not: <10> LineFeed karakterini temsil eder.
2. Hata oluşmuşsa: Bknz. Tablo 1
5
www.smsmakinesi.com
7. Mesaj (SMS) Gönderimi
Hermes COM API, SMS gönderimi için, birbirlerine bağlı çalışan ve belirli bir sırayla kullanıması
gereken üç adet yöntem sunmaktadır. Bunlar:
1. addtosmsbasket
2. sendsms
3. clearsmsbasket
Hermes COM API’nın mesaj gönderim paketlerinin önerilen boyutu 35.000 adettir.
7.1. addtosmsbasket yöntemi
addtosmsbasket yöntemi, gönderilmek istenen SMS paketinin hazırlanmasında kullanılır. Bu yöntemi her
çağırışınızda parametre olarak belirtmiş olduğunuz GSM numarası ve mesaj içeriğini mevcut SMS paketi
içerisine ekler.
Söz dizimi:
addtosmsbasket ( "Mesaj","GsmNo") şeklindedir.
Bu yöntemde:
Mesaj parametresi, SMS mesajı olarak gönderilmek istenen 160 karakterlik String değerini,
Gsmno parametresi, mesajın gönderileceği 10 haneli (53XXXXXXXX)cep telefonu numarasını ifade
etmektedir.
Not: Türkçe karakterlere ve yasaklı karakterlere dikkat edilmelidir.
6
www.smsmakinesi.com
7.2. sendsms yöntemi
Sendsms yöntemi, addtosmsbasket yöntemiyle oluşturulmuş SMS paketini parametre olarak
belirtilen kullanıcı bilgileri ile Gateway’a göndermek için kullanılır.
Söz dizimi:
sendsms("username","password","originator","senddate","vendor_id") şeklindedir.
Bu yöntemde:
UserName parametresi, Hermes’ de tanımlı kullanıcı adınızı,
PassWord parametresi, Hermes’ de tanımlı olan kullanıcı adınıza ait şifreyi,
Originator parametresi, mesajın gönderildiği GSM numarasında gönderen kısmında çıkacak ifadeyi,
SendDate parametresi, ggaayyyyssdd (GünAyYılSaatDakika) şeklinde gönderim zamanını,
Vendor_id parametresi, Kullanıcının Hermes’ de tanımlı bayi kodunu ifade eder.
Eğer SendDate parametresine bir değer girmezseniz mesaj gönderim işlemi hemen başlar. Bir
değer belirtirseniz mesaj gönderim işlemi o tarihte yapılır.
Not: Originator bilgisi mutlaka bulunmalıdır.
Sendsms yöntemiyle gönderilen SMS paketi Gateway’a ulaştığında iki çeşit geri dönüş değeri alınır:
1. İşlem başarılıysa: “Paket_ID:2007XXXXXX0101 ” şeklinde SMS paketine ait TimerID bilgisi döner.
2. Hata oluşmuşsa: Bknz. Tablo 1
7.3. clearsmsbasket yöntemi
clearsmsbasket yöntemi, addtosmsbasket yöntemiyle hazırlanmış olan paketi sendsms yöntemiyle
gönderdikten sonra paket içeriğini temizlemek için kullanılır.
UYARI: Hermes COM API’yı kullanarak Gateway’a ulaşan yazılım geliştiriciler, bir GSM numarasına aynı
mesajın birden fazla gittiğini, aynı SMS paketinin Gateway tarafından işlendiğini ve dolayısıyla kullanıcıların
faturalarına da yansıdığı sıklıkla karşılaşılan bir durumdur.
Eğer clearsmsbasket yöntemini sendsms yönteminden hemen sonra çağırmazsanız SMS paket
içeriği silinmeyecek ve bir sonraki sendsms yöntemi çağrıldığında aynı mesaj(lar) aynı GSM numaralarına
tekrar yollanacaktır. Çok kritik bir önemi olan clearsmsbasket yöntemini sendsms yöntemini çağırdıktan
hemen sonra çağırmanızı tavsiye ediyoruz. SMS gönderiminde kullanılan yöntemlerin hepsinin kullanım
şekilleri ve sıraları gösterilmektedir.
addtobasket( "Mesaj","53XXXXXXXX")
sendsms("username", "password","orjinator", "senddate","vendor_id")
clearbasket()
7
www.smsmakinesi.com
8. Raporlama
Hermes COM API, gönderilen SMS’lerin raporlanması için iki çeşit raporlama yöntemi sunmaktadır:
1. Tarih bazında raporlama için getmsgstatustodate yöntemi
2. Gönderilen mesaj bazında raporlama için getmsgstatus yöntemi
8.1. Tarih bazında raporlama (getmsgstatustodate yöntemi)
Tarih bazında raporlama, belirtilen iki tarih arasında yapılan SMS gönderim hareketlerinin toplu
halde raporlanmasında kullanılır.
Söz dizimi:
getmsgstatustodate("username","password","date1","date2","vendor_id")
Bu yöntemde:
UserName parametresi , Hermes’de tanımlı olan kullanıcı adınızı,
PassWord parametresi, Hermes’de tanımlı olan kullanıcı adınıza ait şifreyi,
Date1 parametresi, raporun başlangıç tarihini ggaayyyy (“Gün-Ay-Yıl” şeklinde),
Date2 parametresi, raporun bitiş tarihini ggaayyyy (“Gün-Ay-Yıl” şeklinde)
Vendor_id parametresi, Kullanıcının Hermes’ de tanımlı bayi kodunu ifade etmektedir.
Bilgiler Gateway’a ulaştığında iki çeşit geri dönüş değeri alınır:
1. İşlem başarılıysa:
Gelen cevap bilgisinde “gsmno”;”durum”; bilgisi geri dönecektir. GsmNo ve durum bilgisi noktalı virgül ile
birbirlerinden ayrılırlar ve gsmno ve durum bilgisi ayrı satırda fonksiyondan geri döner.
Örnek olarak :
5320000000;-1;<10>
5320000001;0;<10>
5320000002;1;<10>
5320000003;2;<10>
5320000004;3;<10>
5320000005;4;<10>
8
www.smsmakinesi.com
Durum bilgisinde:
-1 : Sunucuyla iletişim kurulamaması nedeniyle Beklemede.
0 : Sms mesajı iletildi.
1 : Sms mesajı iletilemedi.
2 : Sms mesajı gönderilmeyi bekliyor.
3 : Bu mesaj raporu henüz hazır değil.
4 : Mesaj sistem hatası nedeni ile iletilemedi.
2. Hata oluşmuşsa: Bknz. Tablo 1
8.2. Gönderilen mesaj bazında raporlama (getmsgstatus yöntemi)
Gönderilen mesaj bazında raporlama,diğer adıyla TimerID bazında raporlama, bir SMS paketine ait
mesaj gönderim hareketlerini raporlamada kullanılır.
Söz dizimi:
getmsgstatus("username","password","packet_id","vendor_id")
Bu yöntemde:
UserName parametresi, Hermes’de tanımlı olan kullanıcı adınızı,
PassWord parametresi, Hermes’de tanımlı olan kullanıcı adınıza ait şifreyi,
Paket_id parametresi, rapor almak istenilen SMS paketine ait Paket_Id bilgisini ifade etmektedir.
Vendor_id parametresi, Kullanıcının Hermes’ de tanımlı bayi kodu.
Bilgiler Gateway’a ulaştığında iki çeşit geri dönüş değeri alınır:
1. İşlem başarılıysa:
Gelen cevap bilgisinde “gsmno”,”durum” bilgisi geri dönecektir.
Örnek olarak :
5320000000;-1;<10>
5320000001;0;<10>
5320000002;1;<10>
5320000003;2;<10>
5320000004;3;<10>
5320000005;4;<10>
Durum bilgisinde:
-1 : Sunucuyla iletişim kurulamaması nedeniyle Beklemede.
0 : Sms mesajı iletildi.
1 : Sms mesajı iletilemedi.
2 : Sms mesajı gönderilmeyi bekliyor.
3 : Bu mesaj raporu henüz hazır değil.
4 : Mesaj sistem hatası nedeni ile iletilemedi.
2. Hata oluşmuşsa: Bknz. Tablo 1
9