TOPLU SMS – HTTP API DOKÜMANI
Bu doküman, Verimor SMS API (kısaca smsapi) ile mesaj gönderimi ve gönderim raporu alımının nasıl yapılacağını anlatır.

Smsapi ile sms göndermek için iki bilgiye ihtiyaç vardır:
1- Verimor hesabınızın kullanıcı adı (12 haneli telefon numaranız, 908501234567 gibi)
2- API şifreniz

API şifrenizi https://oim.verimor.com.tr adresindeki Online İşlem Merkezinden SMS Hizmetleri altındaki SMS Ayarları bölümünden tanımlayabilirsiniz. Aynı zamanda bu menüden API erişiminizi sadece belirli IP adresine kısıtlayarak hesap güvenliğinizi de arttırabilirsiniz.

– – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – –

SMS GÖNDERİMİ
Smsapi gönderim için iki yöntemi destekler. Bunlar HTTP(S) GET (Plain de denir) ve HTTP(S) POST JSON’dır. İkisi de cevabını düz metin olarak döndürür.

HTTP GET ile SMS Gönderimi
Aşağıdaki örnekte olduğu gibi bir URL çağırılır.

Örnek:

  • username: Verimor hesabınızın kullanıcı adı. (zorunlu)
  • password: API şifreniz. (zorunlu)
  • source_addr: Gönderici kimliği (Başlık). Source_addr boş ise sistemde kayıtlı ilk başlığınız kullanılır.
  • msg: Gönderilecek mesaj. Türkçe harf içerebilir. Maksimum uzunluğu Türkçe harf içeriyorsa 1043, içermiyorsa 1071 karakter’dir. (zorunlu). Encoding her zaman UTF8 beklenir.
  • dest: Mesajın gönderileceği telefon numaraları. Birden fazla numara varsa virgül ile ayrılmalıdır. Telefon numaraları 90 ile başlayıp 12 hane olmalıdır. (zorunlu)
  • valid_for: Mesajın geçerlilik süresi. SS:DD (veya S:DD) formatında olmalı. (Varsayılan değer 24:00, Minumum değer 00:01, Maksimum değer 48:00)
  • datacoding: Mesaj metni için kullanılacak karakter kodlaması. 0, 1 ve 2 değerlerini alabilir. Mesajda kullanılabilecek harfleri ve mesajın boy limitlerini belirler. Boş ise mesaj metnine bakılır, türkçe harf varsa 1, yoksa 0 kaydedilir. Mesaj boyları tablosu için dokümanın sonuna bakınız.

 

Cevap:

Gönderim başarılıysa; cevap olarak “HTTP/1.1 200 OK” mesajı ve kampanya ID’si (Kampanya: Bir veya daha fazla mesajın paketlenmiş halidir.) döner. “HTTP/1.1 200 OK” mesajı HTTP response header kısmında olup cevap metninde (response body) geçmez.

Örnek:

Cevap (Başarılı):

Cevap (Başarısız):

Gönderim başarısızsa; cevap olarak “HTTP/1.1 400 Bad Request” mesajı ve kampanya ID’si yerine hata mesajı döner. “HTTP/1.1 400 Bad Request” mesajı HTTP response header kısmında olup cevap metninde (response body) geçmez.
HTTP POST JSON ile SMS Gönderimi

Aşağıdaki örnekte olduğu gibi bir JSON string POST edilir.

  • username: Verimor hesabınızın kullanıcı adı. (zorunlu)
  • password: API şifreniz. (zorunlu)
  • source_addr: Gönderici kimliği (Başlık). Source_addr boş ise sistemde kayıtlı ilk başlığınız kullanılır.
  • valid_for: Mesajın geçerlilik süresi. SS:DD (veya S:DD) formatında olmalı. (Varsayılan değer 24:00, Minumum değer 00:01, Maksimum değer 48:00)
  • send_at: Mesajın gönderilmesini istediğiniz tarih saat. ‘2015-02-20 16:06:00’ şeklinde veya ISO 8601 standardındaki formatlar kabul edilir (http://en.wikipedia.org/wiki/ISO_8601). Boş ise mesaj hemen gönderilir.
  • custom_id: Bu kampanyaya verebileceğiniz özel ID’dir. API’nin kampanyaya döndüreceği ID’yi kullanmayıp kendi vereceğiniz ID ile mesajların sonucu takip etmek isterseniz kullanılır. (Push veya GET ile Gönderim Raporu alırken bu ID’yi kullanabilirsiniz.)(zorunlu değil)
  • msg: Gönderilecek mesaj. Türkçe harf içerebilir. Maksimum uzunluğu Türkçe harf içeriyorsa 1043, içermiyorsa 1071 karakter’dir. (zorunlu). Encoding her zaman UTF8 beklenir.
  • dest: Mesajın gönderileceği telefon numaraları. Birden fazla numara varsa virgül ile ayrılmalıdır. Telefonların formatı: 905xxxxxxxxx şeklinde olmalıdır. (zorunlu)
  • datacoding: Mesaj metni için kullanılacak karakter kodlaması. 0, 1 ve 2 değerlerini alabilir. Mesajda kullanılabilecek harfleri ve mesajın boy limitlerini belirler. Boş ise mesaj metnine bakılır, türkçe harf varsa 1, yoksa 0 kaydedilir. Mesaj boyları tablosu için dokümanın sonuna bakınız.

 

Cevap:

– – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – –

GÖNDERİM RAPORU ALIMI
Smsapi gönderim raporlarını iki şekilde teslim eder. Bunlar PUSH ve GET ile alma yöntemleridir.

PUSH ile Gönderim Raporu Alımı
Push yönteminde mesajın durumu ile ilgili bilgi (teslim edildi, zaman aşımı, numara hatalı vb.) alınır alınmaz sizin belirlediğiniz bir URL tetiklenir. Aşağıdaki gibi bir JSON POST edilir:

  • campaign_id: Mesajın kampanya ID’si.
  • campaign_custom_id: Mesajın kampanyasına sizin tarafınızdan verilmiş özel ID.
  • message_id: Mesaja API tarafından verilmiş ID.
  • dest: Mesajın gönderildiği telefon numarası.
  • size: Mesajın boyu.
  • international_multiplier: Mesajın kredi çarpanı (bir boyunun kaç krediye denk geldiği). Uluslararası mesajlarda 1’den büyük olur. Ulusal mesajlarda daima 1 olur.
  • credits: Bu mesaj için hesabınızdan kaç kredi düşüldüğü.
  • status: Mesajın durumu (olabilecek durumlar ve anlamları için dokümanın sonundaki durum listesine bakınız).
  • gsm_error: Mesaj iletilemediyse operatörden dönen hata kodu.
  • sent_at: Mesajın iletildiği tarih (mesaj iletilemediyse null olur)
  • done_at: Mesajın son durumuna ulaştığı tarih (mesaj iletilemediyse de dolu olur)

 

Not : API, sisteminize PUSH bildirimi yaptığında “HTTP/1.1 200 OK” cevabı bekler. Bu cevabı alamadığı zaman 5’er dakika bekleyerek 3 kere daha dener. Hala cevap alamazsa bu mesajı tekrar bildirmez.
HTTP GET ile Gönderim Raporu Alımı
Kampanyaların durumunu Get ile sorarak da alabilirsiniz. Örnekler;

Örnek (API’nin ürettiği ID ile sorma):

Örnek (Custom ID ile sorma):

Örnek (Cep telefonuna göre sorma):

Örnek (message_id belirli değerden büyük olanları sorgulama):

  • id: Kampanya’ya API tarafından verilen ID’dir. id veya custom_id zorunludur.
  • custom_id: Kampanya’ya sizin tarafınızdan verilen ID’dir. id veya custom_id zorunludur.
  • dest: Zorunlu değil. Kampanya’da belirli telefon numaralarına gönderilmiş mesajları sorgular.
  • greater_than: Verilen message_id’den büyük mesajları sorgular. Bu parametre, içinde çok mesaj olan kampanyaların sorgulanması için zorunludur. Bu sorgu 100 mesaj döndürür, mesajların devamını almak için sonuçtaki son mesaj id’sini vererek ikinci bir sorgu yapmalısınız.

Cevap (Başarılı):

Cevap (Başarısız. Verdiğiniz ID’ye ait kampanya size ait değilse):

Cevap (Başarısız. Verdiğiniz ID’ye ait kampanya bulunamadıysa):

– – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – –

DURUM MESAJLARI
SMS gönderirken ve gönderim raporu alırken size dönen status sahalarında aşağıdaki tablodaki değerler olabilir:

Mesaj Gönderirken Dönebilecek Durumlar ve Açıklamaları

Web_Arayüzü_DurumlarıAPIAçıklama
-INVALID_SOURCE_ADDRESSBaşlık kabul edilmedi.
-MISSING_MESSAGEGönderilecek mesaj verilmemiş.
-MESSAGE_TOO_LONGMesaj çok uzun.
-INVALID_PERIODMesajın geçerlilik süresi (validity period) geçersiz. (1dk. ile 48 saat arasında değil).
-INVALID_DELIVERY_TIME"schedule_delivery_time" parametresi geçersiz veya geçmiş tarihe ait.
-INVALID_DATACODINGdatacoding parametresi hatalı verilmiş.
-MISSING_DESTINATION_ADDRESSMesaj için alıcı verilmemiş.
Hatalı NumaraINVALID_DESTINATION_ADDRESSAlıcı telefon numarasının formatı geçersiz. (905121234567 gibi olmalı)
Kredi YetersizINSUFFICIENT_CREDITSMesajı göndermek için yeterli bakiyeniz yok.

Mesaj Durumu Alınırken Dönebilecek Durumlar ve Açıklamaları

Web_Arayüzü_DurumlarıAPI_DurumlarıAçıklama
GönderiliyorSENDINGMesaj gönderiliyor.
BekliyorWAITINGMesaj gönderildi. Cevap bekleniyor.
İletildiDELIVEREDMesaj iletildi.
İletildiSENTMesaj iletildi. Fakat operatör gönderim raporunu desteklemediği için teyit edilemiyor. (Uluslararası bazı yönlerde oluşur.)
İletilemediNOT_DELIVEREDMesaj iletilemedi. (Genelde alıcı numaranın aktif olmamasından kaynaklanır.)
Zaman aşımıEXPIREDZaman aşımı. Mesajınız belirlediğiniz geçerlilik süresi içinde alıcısına teslim edilemedi.
Hatalı NumaraINVALID_DESTINATION_ADDRESSAlıcı telefon numarası geçersiz. (Hiçbir operatöre kayıtlı değil.)
ReddedildiREJECTEDMesajınızın gönderimi reddedildi. (Genelde gsm operatörü tarafından içerik kontrolü sonucu oluşur.)
Mükerrer GönderimDOUBLE_SEND_ERRORAynı içerik aynı gün aynı başlıkla aynı numaraya gönderilmiş. Mükerrer gönderim engellendi.
KaralistedeBLACKLISTED_DESTINATION_ADDRESSAlıcı kara listenizde.
Tarife BulunamadıMISSING_TARIFFAlıcının operatörü tarifelerimiz arasında bulunamamıştır. (Uluslararası yönlerde oluşur.)
Geçersiz ŞebekeROUTE_NOT_AVAILABLEHesabınız bu alıcıya mesaj gönderemez. (Uluslararası bazı yönlerde oluşur.)
Geçersiz ŞebekeNETWORK_NOTCOVEREDHesabınız bu alıcıya mesaj gönderemez. (Uluslararası bazı yönlerde oluşur.)
Gönderim HatasıSEND_ERRORMesajınız gönderilirken hata oluştu. (Sebebi çeşitli olabilir.)
Uluslararası Gönderim KapalıINTERNATIONAL_DENIEDOİM'de SMS ayarlarından 'uluslararası gönderim' ayarı kapalı olduğu için gönderilmedi.

SMS Boy Karakter Limitleri

Normal (datacoding=0)Türkçe (datacoding=1)Unicode (datacoding=2)
1 boy0-1600-1550-70
2 boy161-306156-29871-134
3 boy307-459299-447135-201
4 boy460-612448-596202-268
5 boy613-765597-745269-335
6 boy766-918746-894336-402
7 boy919-1071895-1043403-469

Not-1: datacoding=0 veya datacoding=1 gönderimlerde aşağıdaki karakterler 2 karakter sayılır.
^ { } \ [ ] ~ | €
Not-2: Sadece (Ş ş Ğ ğ ç ı İ) harfleri Türkçe olarak kabul edilir ve datacoding=1 olarak gönderilmelidir. Diğer Türkçe karakterleri (Ö ö U ü Ç) datacoding=0 olarak gönderebilirsiniz.
Not-3: HTTPS olarak API’mizi kullanırken SSL bağlanıtısı için kullandığınız kütüphane sisteminizde kök sertifikalar yüklü olmadığından sertifikamızı doğrulamayabilir. Bu sorunu çözmek için rapidssl.crt kök sertifika dosyasını buraya tıklayarak indirip sisteminize kurmalısınız.