Mehmet Giritli mehmet.giritli "at" kamu.ct.tr 18 Ocak 2021
KAMUNET Kısa Mesaj Portalı (KKMP), özellikle otomasyonların SMS gönderme ihtiyaçlarını karşılamak üzere geliştirilmiş bir altyapı sistemidir. K.K.T.C. sınırları içerisinde faaliyet gösteren iki cep telefonu operatörü firmasının sağlamış olduğu imkanlarla işlevini yerine getirmektedir. Bu hizmet sağlayıclar bugün itibarıyla KKTCELL ve TELSIM şirketleridir. Metnin geri kalanında kullanılan “sağlayıcılar” ve “operatörler” terimleri bu şirketleri belirtir.
KKMP, herhangi bir sayıda “operatör hesabı”nın tanımlanmasına imkan kılar. KKMP tanımlı hesapları (veya onların çeşitli kombinasyonlarını) kullanarak SMS mesajları sağlayıcılara yönlendirir.
Aynı zamanda KKMP gönderilmiş olan kısa mesajlar için mesaj durum kontrolü (alıcıya mesajın ulaşıp ulaşmadığı veya herhangi bir hata oluşup oluşmadığı gibi) ve istenildiği takdirde kayıt işlemlerini de gerçekleştirebilir. Özellikle test aşamalarında bu özellik kullanılarak entegrasyonların başarılı bir şekilde gerçekleştirilip gerçekleştirilmediğini anlamak kolaylaşmakta, istatistik bilgisi mümkün hale gelmektedir.
KKMP’nin getirdiği kazanımları kısaca özetleyebiliriz:
Bir operatör hesabı, herhangi bir sağlayıcı tarafından müşterilerine verilmiş olan bir kullanıcı adı ve şifre bilgisini kullanarak KKMP’na tanımlanır. Güvenlik bilgilerinin yanında, her tanımlanan hesap için bu hesap üzerinden gönderilen kısa mesajların kayıt yapılıp yapılmayacağı ve eğer yapılacaksa bunun ne kadar detaylı olarak gerçekleştirileceği belirtilmelidir. Ayrıca, her hesap için sanal veya gerçek hesap tiplerinden birisi seçilmelidir.
Sanal hesaplar, en az bir gerçek hesabı kullanarak tanımlanırlar. Gerçek hesaplar için kullanıcı adı ve şifreden oluşan güvenlik bilgileri zorunlu iken, sanal hesaplar tanımlarken herhangi bir güvenlik bilgisi kullanılmaz. Bunun nedeni, sanal hesapların, çalıştırıldıklarında aslında tanımlarında seçilmiş olan gerçek hesapları kullanıyor olmalarındandır. Güvenlik bilgisi gerçek hesaplarda tutulduğu için, sanal hesapların bu bilgiye ihtiyacı yoktur. Sanal hesapların tanımlarında belirtilmiş olan gerçek hesaplara, o sanal hesabın alt hesapları denir. Alt hesaplar sanal hesap için seçilirken kullanılan sıralama büyük öneme sahiptir. Sanal hesaplar, sanal mod seçimine bağlı olarak, alt hesaplarından hangisini, hangi biçimde kullanarak çalışacağına karar verir. Bu karar, hesabın kredi durumuna, tanımdaki sırasına vs. göre belirlenir.
Sanal hesap tanımında yer alan bir diğer bilgi de sanal mod türüdür. Şu an için (Ocak 2021), KKMP dört farklı modu desteklemektedir:
Gerçek hesaplar için bir sağlayıcı, kullanıcı adı ve şifre bilgileri yanında eğer istenirse, kredi uyarı sistemini de devreye almak için bazı bilgiler verilebilir. Kredi uyarı sistemi, belirtilecek bir epostaya, ilgili hesabın kredi miktarı yine hesap tanımında belirtilmiş bir seviyenin altına düştüğüne mesaj göndererek hizmet kesintilerinin önüne geçmeyi amaçlar.
Kredi uyarı sistemini devreye almak için, gerçek hesabın ayarlarında kredi uyarı seçimi işaretlenmeli ve uyarı seviyesi de rakamsal olarak belirtilmelidir. Ayrıca, uyarıların gönderileceği bir eposta adresi de sağlanmalıdır.
Operatör hesapları, kullanıcının yetkilerine göre listelenir. Süper kullanıcılar KKMP’de tanımlı tüm hesapları görebilirler. Eğer bir sistem yöneticisi tarafından müdahale edilip kaldırılmamışsa, her hesaba oluşturucusu için kullanım yetkisi otomatik olarak verilir. Yeni hesaplar yaratıldığı zaman, oluşturan kullanıcıya yetki verilme işlemi bir kaç saniye süreceğinden, operatör hesap listesinde hemen gösterilmeyebilir. Bu durumda bir kaç saniye içerisinde sayfayı tazelemek eklenen hesabın gösterilmesini sağlayacaktır.
KKMP’na yetkili herhangi bir kullanıcıya, kayıtlı herhangi bir hesap için yetki verilebilir. Bu işlem Kullanıcı Yönetim Sistemi üzerinden geçekleştirilebilir.
Operatör hesap listesinde gerçek hesaplar siyah renk ile gösterilirken, sanal hesaplar sönük bir renk ile gösterilirler.
Her hesap için listeleme ekranında ona ait id değeri gösterilmektedir. Herhangi bir servis kullanarak hesaplar tüketileceğinde, id değerinin de çağrı ile gönderilerek işlemin hangi hesap ile gerçekleştirileceği belirtilir. Daha fazlası için sunulan servisler bölümüne bakın.
Genel bakış bölümünde de anlatıldığı gibi, her operatör hesabı için zorunlu olan üç ayar mevcuttur. Birincisi hesap türü bilgisidir ve gerçek ya da sanal hesap seçimlerinden birisi olmalıdır. İkincisi ise mesaj kayıt tipidir. Bu ayar ile yaratılmakta olan hesabı kullanarak gönderilen mesajların kayıt edilip edilmeyecekleri ve eğer edileceklerse, bunun hangi düzeyde olacağı belirlenir. Üçüncü zorunlu ayar ise hesap isimi bilgisidir. Hesap isimleri tekil olmalı ve en az 3, en fazla 50 karakterden oluşmalıdır. İstenirse notlar bölümüne bazı açıklamalar girilebilir.
Geriye kalan ayarlar hesap türüne göre değişmektedir. Gerçek hesaplar için; sağlayıcı, kullanıcı adı ve şifre alanları üst paragraftaki ayarlarla birlikte zorunludur. Kullanıcı adı ve şifre en az 3 en fazla 20 karakterden oluşmalıdır. Kredi uyarı miktarı, kredi uyarı seçeneği seçili olduğunda zorunludur.
Sanal hesaplar için zorunlu ayarlar sanal mod ve alt hesap seçimlerinden oluşmaktadır. Genel bakış bölümünde de açıklandığı gibi, alt hesaplar sadece gerçek hesaplardan oluşur ve her sanal hesap için en az 1 hesap içeren bir alt hesap listesi tanımlanmalıdır. KKMP arayüzünde alt hesapları seçmek ve sıralamak için çeşitli araçlar sunulmuştur. Kayıtlı tüm gerçek hesaplar sağ tarafta listelenir ve herhangi birisinin üzerine çift tıklanarak alt hesaplar arasına eklenmesi sağlanabilir. Bir hesabı alt hesaplar listesinden çıkarmak için de yine üzerine çift tıklamak yeterlidir. Alt hesap sıralamasını değiştirmek için de yukarı ve aşağı düğmeleri kullanılabilir.
Yeni gerçek hesaplar yaratılırken, kullanılacak kullanıcı adı bilgisi söz konusu sağlayıcı için tekil olmalıdır. Bir diğer deyişle, aynı sağlayıcı için aynı kullanıcı adını kullanan iki farklı hesap yaratılamaz.
Bir gerçek hesap silinmek istendiği zaman, eğer o hesabı kullanmakta olan bir sanal hesap mevcutsa, buna izin verilmez. Bu durumda ilk önce gerçek hesabı alt hesabı olarak içeren tüm sanal hesaplar silinmelidir. Gerçek hesabı alt hesapları arasında bulunduran bir sanal hesap kalmadığı zaman, gerçek hesap silinebilir hale gelecektir.
TODO
TODO
KKMP webservisleri RESTful yöntemini kullanarak JSON biçiminde bir gövde (payload) içeren HTTP istek ve cevaplarıyla çalışan bir hizmettir. Yapılan tüm isteklerde aşağıdaki başlıklar (header) mevcut olmalıdır:
| Başlık (header) | Değer |
| Accept: | application/json |
| Content-Type: | application/json |
| Charset: | UTF-8 |
Servisleri tüketebilmek için OAUTH 2.0 standardı kullanarak güvenlik girişinin yapılması gerekmektedir. Bu çerçevede ilk önce OAUTH anahtar temini için aşağıdaki değerlerle birlikte ve POST methodunu kullanarak bir istek yapılmalıdır. Bu istek yapılırken kullanılması gereken değerler şöyledir:
| URL ve Anahtarlar | Değer | Açıklama |
| URL | https://sms.gov.ct.tr/oauth/token | |
| grant_type | client_credentials | x-www-form-urlencoded |
| client_id | KAMUNET’ten temin edilmeli | x-www-form-urlencoded |
| client_secret | KAMUNET’ten temin edilmeli | x-www-form-urlencoded |
| scope | com veya gov | Devlet içi sistemler için gov değeri, devlet dışı sistemler için com değeri kullanılmalıdır. Daha fazla bilgi için KAMUNET ile iletişime geçin. |
Başarılı OAUTH token alma işlemi sonucunda döndürülecek “access_token” anahtarının değeri ile servisler tüketilmeye başlanabilir.
Herhangi bir servisi tüketebilmek için uygun metod (aşağıda her servis için bu değer belirtilmiştir) kullanılmalı ve başlık içerisinde “authorization bearer access token” değeri yer almalıdır. Herhangi bir servisi tüketmek için çağrıya ait bir başlık şablonu şu şekilde verilebilir:
Accept: application/json
Content-Type: application/json
Charset: UTF-8
Authorization: Bearer <access token><access token> için yukarıda belirtilen https://sms.gov.ct.tr/oauth/token adresinden elde edilmiş access token değeri kullanılmalıdır.
Access token geçerlilik süresi 24 saattir.
endpoint: sms.gov.ct.tr/api/smsGonder
method: POST
payload: JSONoperatorHesabi | Kullanılacak hesaba ait id değeri. | KKMP arayüzünde operatör hesapları bölümünde id değerleri listelenmektedir. |
mesaj | Gönderilecek mesaj metni. | En fazla 500 karakter. |
aliciListesi | Mesaj alıcı listesi. | Her alıcı için bir JSON nesnesi içeren dizi. Detaylar için bir aşağıdaki satıra bakın. |
aliciListesi dizisinin JSON nesneleri | ulke ve numara anahtarlarına sahip iki elemanlı bir JSON nesnesi. ulke anahtarı değer olarak alıcının uluslararası telefon kodu (Ör., 90) veya ülke ISO 3166 çift karakterli kodu (Ör., TR) alır. numara anahtarı değer olarak alıcının ülke telefon kodunu içermeyen telefon numarasını alır (Ör. 533XXXXXXX). | Örneğin,{ ulke : 90,veya { ulke : "TR", |
Aşağıda iki farklı numaraya tek servis çağrısı ile gönderilmekte olan bir çağrıya ait JSON gövde örneği verilmektedir. Örneğimizde id değeri 1 olan operatör hesabı gönderim için kullanılacak. Mesaj üç alıcıya gönderilecek. Alıcılar Türkiye, Almanya ve İngiltere ülkelerindeki telefon numaralarından oluşuyor:
{
"operatorHesabi":1,
"mesaj":"Örnek mesajım",
"aliciListesi":[
{
"ulke":"90",
"numara":"1111111111"
},
{
"ulke":"DE",
"numara":"2222222222"
},
{
"ulke":"+44",
"numara":"3333333333"
}
]
}SMS servisi çağrıldığında, gönderme işleminin sonucun ne olduğuna dair bir sonuç döndürülmez. Bunun nedeni, mesajların bir kuyruğa alınıp gerçek zamanlı olarak gönderilmemesidir. Mesajın gerçek zamanlı durumu, operatöre gönderilme girişimi yapıldığı andan itibaren KKMP arayüzünü kullanarak takip edilebilir.
Başarılı bir servis çağrısının geri dönüşü aşağıdaki gibi bir JSON gövdeden oluşacaktır:
{
"hata":false,
"aciklama":"Kuyruğa alındı. Mesaj operatöre gönderildikten sonra KAMUNET Kısa Mesaj Portalı ile durumu canlı olarak sorgulanabilir."
}
Hata oluşması durumunda, eğer hata veri sağlama hatası ise HTTP 200 kodu ile birlikte, güvenlik girişi ile ilgili bir hata oluştuğu durumlarda ise HTTP 401 kodu ile birlikte, aşağıdaki örnekte belirtildiği şekilde JSON gövde içeren bir cevap döndürecektir:
{
"hata":true,
"gecerliOperatorHesabi":1,
"aciklama":[
"Dağıtım listesi geçersiz bir numara içeriyor: 16495338604364."
]
}gecerliOperatorHesabi anahtarı sadece veri sağlama hatası oluştuğu durumlarda döndürülür. hata ve aciklama anahtarları her durumda JSON cevap gövde içerisinde yerini alır:
hata | Boolean. Hata oluştuğu durumlarda true değerini alır, aksi hallerde false. |
aciklama | Hata olduğu durumlarda bir string dizisidir. Oluşan hatalarla ilgili açıklamaları string dizisi olarak içerir. |
gecerliOperatorHesabi | Veri doğrulama hatası oluştuğunda kullanılır. İşlemin yapılmakta olduğu hesabın id değeridir. |
endpoint: sms.gov.ct.tr/api/hesapBilgi
method: GET
payload: JSONServis çağrılırken kullanılması gereken JSON anahtarları şöyledir:
operatorHesabi | Kullanılacak gerçek hesaba ait id değeri. | KKMP arayüzünde operatör hesapları bölümünde id değerleri listelenmektedir. |
Bilgi servisini kullanarak gerçek hesaplar için kredi bilgisi ve gönderen bilgisi (originator) elde edilebilir. Sanal hesaplar için bu servis çağrıldığı zaman bir hata mesajı döndürülecektir. KKMP arayüzünü kullanarak hesap bilgisini bir sanal hesap için almaya çalışmak aynı hata mesajının üretilmesine neden olacaktır. Bu davranış normal olup herhangi bir soruna işaret etmez.
Başarılı bir servis çağrısının geri dönüşü aşağıdaki gibi bir JSON gövdeden oluşacaktır:
{
"hata":false,
"adi": <originator>,
"kredi": <kalan kredi>
}
Hata oluşması durumunda, gönderme servisinde belirtilen unsurlar, bu servis için de geçerlidir.
endpoint: sms.gov.ct.tr/api/smsDurum
method: POST
payload: JSONServis çağrılırken kullanılması gereken JSON anahtarları şöyledir:
operatorHesabi | Kullanılacak gerçek hesaba ait id değeri. | KKMP arayüzünde operatör hesapları bölümünde id değerleri listelenmektedir. |
smsID | Daha önce gönderilmiş bir SMS’e karşı döndürülmüş olan referens değeri. | Gönderme servisinde açıklandığı gibi, gönderme servisi bu referans değerini döndürmez. |
Başarılı bir servis çağrısının geri dönüşü aşağıdaki gibi bir JSON gövdeden oluşacaktır:
{
"hata":false,
"aciklama": <mesajın durumu>
}
Hata oluşması durumunda, gönderme servisinde belirtilen unsurlar, bu servis için de geçerlidir.