Piyango Çekiliş Servisleri Kılavuzu

Mehmet Giritli
mehmet.giritli "at" kamu.ct.tr

10 Mayıs 2020

Genel Bakış
Çekiliş Listesi Servisi
1. Genel Bakış
2. Cevap
  1. Örnek Cevap
Bilet Numara Kontrol Servisi
Hata Kodları
1. Örnek Hata Cevabı
Servis Demo

Genel Bakış

“Piyango çekiliş servisleri” Kamunet tarafından geliştirilen ve K.K.T.C. Başbakanlık Piyangolar Birimi devlet piyangosu çekiliş sonuçlarının web servis teknolojisi kullanarak aranmasına imkan veren bir hizmettir. Çekiliş sonuçları yönetim bilişim sistemi özel bir şirket tarafından Piyangolar Birimi için geliştirilmiştir. Piyango çekiliş servisleri, söz konusu bilişim sistemi veritabanı kayıtlarını kullanarak gerekli verilere ulaşmaktadır.

Piyango çekiliş servisi, iki mikro servisten oluşur. Bunlar “çekiliş listesi” ve “bilet numara kontrol” servisleridir.

Servisler herhangi bir güvenlik sistemi kullanmayan “açık servisler” olarak hizmet verirler. Fakat, sadece endpoint URL’ü kullanarak tüketilebilirler. IP adresi kullanarak servise ulaşmak mümkün değildir. Bu tür istekler HTTP 400 durum kodu ile cevaplanacak ve söz konusu isteklerin tekrar etmesi durumunda IP bloklaması gerçekleşecektir. İstek ile gelen “Accept” başlığından (“header”) bağımsız olarak, servisler her zaman JSON biçiminde bir gövde yapısı ile cevap vereceklerdir.

Çekiliş Listesi Servisi

GENEL BAKIŞ

Çekiliş listesi servisi, sisteme son 6 ay içerisinde girilmiş olan tüm çekilişlerin, tarihleri yeniden eskiye sıralı olacak şekilde, bir listesini döndürür. Her çekiliş tekil ve “integer” tipinde bir değer ile temsil edilir. Bu değer, servisin her çekiliş için döndürdüğü değerler arasında id anahtarı ile yer alır. Herhangi bir çekilişin sonuçları arasında arama yapmak için bilet numara kontrol servisini çağırırken bu değer kullanılır. Servisin geri döndürdüğü cevabın yapısı ve içerdiği anahtarlar Tablo 1‘de detaylandırılmıştır.

Servisi tüketmek için gerekli genel teknik bilgiler şöyledir:

endpoint: servis.piyangolar.gov.ct.tr/api/cekilisleriGetir
method: GET
payload: JSON

CEVAP

Çekiliş listesi servisi cevap olarak geriye her zaman bir JSON yapısı döndürecektir. Bu yapı içerisinde bulunabilecek anahtarlar ve anlamları şöyledir:

Anahtar	Kullanıldığı zaman	Açıklama
hata	Her zaman	Boolean. Herhangi bir hata oluştuğu durumlarda “true” değerini alır. Diğer zamanlarda “false” değerini alır. Hata durumları için Hata Kodları bölümüne göz gezdirin.
cekilisler	Hata oluşmayan her durumda.	Dizi. Tüm çekilişlerin bilgilerini içerir. Yapısı için Tablo 2‘ye bakın.
mesaj	Hata oluştuğu durumlarda.	String. Oluşan hatayla ilgili açıklama. Detaylar için Hata Kodları bölümüne göz gezdirin.

Tablo 1

Çekilişler, Tablo 1‘de bahsedildiği gibi bir dizi halinde döndürülür. Bu dizinin her bir elemanı, yapısı Tablo 2‘de verilen bir diziden ibarettir. Bir diğer deyişle, bu bir diziler dizisidir.

Anahtar	Açıklama
id	Integer. Her çekilişi tekil olarak temsil eden anahtar. Bilet numarası ile arama gerçekleştirmek için kullanılması zorunludur.
cekilisAdi	String. Her çekilişin sunumda gösterilebilecek tipte kısa adı, ör., “Yılbaşı Çekilişi”.
basamakSayisi	Integer. Çekiliş kapsamındaki bilet numaralarında kullanılan uzunluk / hane sayısı.
cekilisTarihi	String. dd/mm/yyyy biçimini kullanarak verilen çekilişin gerçekleştiği tarih.

Tablo 2

Örnek Cevap

{
     hata: false,
     cekilisler : [  {
                        id : 1,
                        cekilisAdi: "Yılbaşı özel çekilişi",
                        basamakSayisi: 6,
                        cekilisTarihi: "31/12/2019",
                      },

                     {
                        id : 2,
                        cekilisAdi: "Piyango Çekilişi",
                        basamakSayisi: 5,
                        cekilisTarihi: "18/02/2020",
                     },

                     ...

                  ]
}

Bilet Numara Kontrol Servisi

GENEL BAKIŞ

Bilet numara kontrol servisi, parametre olarak verilen bir bilet numarasını ve çekiliş anahtarını kullanarak, biletin belirtilen çekiliş için herhangi bir ikramiye kazanıp kazanmadığını ve eğer kazanmışsa, ikramiye miktarını cevap olarak döndüren bir servistir. Servisi tüketmek için gerekli genel teknik özellikler şöyledir:

endpoint: servis.piyangolar.gov.ct.tr/api/numaraKontrol
method: POST
payload: JSON

İstek

Bilet numara kontrol servisi iki zorunlu parametreyi göndererek tüketilebilir. Parametreler JSON biçiminde gövdeye sahip bir istek oluşturularak gönderilmelidir. JSON yapının her parametre için özel bir anahtarı olmalıdır. Parametrelerin eksik olması veya belirtilen özelliklerin dışına çıkması durumunda cevap olarak uygun bir hata döndürülür. Daha fazla bilgi için Hata Kodları bölümüne göz gezdirin. Parametreler ve sahip olması gereken özellikleri şöyledir:

Anahtar / parametre	Kullanıldığı zaman	Açıklama
numara	Her zaman	Integer. Kontrol edilecek bilet numarası. Numara uzunluğu/hane sayısı çekilişin “basamak sayısı”na eşit olmalıdır. Daha fazla bilgi için Tablo 2‘ye bakın.
cekilis	Her zaman	Integer. Çekiliş listesi servisi ile elde edilmiş olan çekiliş anahtarı. Daha fazla bilgi için Tablo 2‘de “id anahtarı” kısmına göz gezdirin.

Tablo 3

Cevap

Servis JSON biçiminde gövdeye sahip bir cevap döndürecektir. JSON yapıya ait anahtarlar ve açıklamaları Tablo 4‘de verilmiştir.

Anahtar	Kullanıldığı zaman	Açıklama
hata	Her zaman	Boolean. Hata oluştuğu durumlarda “true” değerini alır aksi halde “false” değerini alır. Detaylar için Hata Kodları bölümüne göz gezdirin.
mesaj	Hata oluştuğu durumlarda	String/Dizi. Hata oluştuğu durumlarda hatayla ilgili açıklamayı içerir. Daha fazla bilgi için Hata Kodları bölümüne göz gezdirin.
kazandi	Hata oluşmayan durumlarda	Boolean. Eğer bilet numarası herhangi bir ikramiye kazanmışsa “true” değerini alır.
miktar	Hata oluşmayan durumlarda	Integer. Eğer bilet numarası bir ikramiye kazanmışsa, ikramiye miktarı. Herhangi parasal biçimlendirme içermez.

Tablo 4

ÖRNEK CEVAP

2000 TL kazanan bir bilet numarası ile sorgu yapıldığı varsayılırsa, servis şu şekilde bir JSON cevap gönderir:

{
     hata: false,
     kazandi: true,
     miktar: 2000
}

Hata Kodları

Çekiliş listesi servisi ve numara kontrol servisi belirli durumlarda ve beklenmeyen durumlarda farklı hata kodları ve mesajları döndürür. Hata oluşması durumunda, uygun bir HTTP durum kodu ve beraberinde JSON biçiminde gövdeye sahip bir cevap döndürülür. Söz konusu JSON gövde yapısının anahtarları şöyledir:

Anahtar	Kullanıldığı zaman	Açıklama
hata	Her zaman	Boolean. Hata oluştuğu durumlarda “true” değerini alır.
mesaj	Sadece hata oluştuğu durumlarda	Hata oluştuğu durumlarda hata ile ilgili bilgi verir. 5XX kodlu hata mesajlarında string, 4XX kodlu hata mesajlarında dizi tipinde olur.

Tablo 5

HTTP 5XX sınıfı hata kodları daha ciddi bir durumu işaret ederler ve normalde bu kodların döndürülmesi beklenmez. Tablo 6 bu kodların kullanımı hakkında bilgi verir.

HTTP kodu	Açıklama
503	Veritabanı ile ilgili tüm hatalar için: bağlantı problemi, yapısal bozukluk vs.
500	Öngörülmemiş tüm diğer hata durumlarında

Tablo 6

HTTP 400 durum kodu genellikle parametreler ile sağlanan verilerin beklenen özelliklerin dışında kalması durumunda döndürülür. HTTP 400 durum kodu aşağıdaki durumlarda döndürülür:

cekilis parametresi eksik olduğunda
cekilis parametresi “integer” tipinde olmadığında
cekilis parametresi veri tabanında bulunamadığında
numara parametresi eksik olduğunda
numara parametresi “integer” tipinde olmadığında
numara parametresi basamak sayısı çekiliş basamak sayısına eşit olmadığında. Çekiliş basamak sayısı hakkında çekiliş listesi servisi ve Tablo 2‘ye göz gezdirin.

HTTP 400 durum kodu döndürüldüğü durumlarda Tablo 5‘de verilen cevap JSON gövdesi içerisinde yer alan “mesaj” anahtarının değeri bir dizi olacaktır. Bu dizinin yapısı Tablo 7’de verilmektedir.

Anahtar	Kullanıldığı zaman	Açıklama
numara	`numara` parametresi ile ilgili hata oluştuğu durumlarda	Dizi. `numara` parametresi ile ilgili hata oluştuğu zamanlarda mevcut olur. String elemanları olan bir dizidir. Her bir string eleman farklı bir hata mesajıdır.
cekilis	`cekilis` parametresi ile ilgili hata oluştuğu durumlarda	Dizi. `cekilis` parametresi ile ilgili hata oluştuğu zamanlarda mevcut olur. String elemanları olan bir dizidir. Her bir string eleman farklı bir hata mesajıdır.

Tablo 7

ÖRNEK HATA CEVABI

{
     hata: true,
     mesaj : {
                  numara : [
                              "Bilet numarası sadece rakamlardan oluşabilir."
                           ],

                  cekilis : [
                              "Çekiliş tanımlayıcısı eksik veya hatalı."
                            ]
             }
}

Servis Demo

http://servis.piyangolar.gov.ct.tr adresinde servis tüketimi ve test işlemleri demo programı ile gerçekleştirilebilir.

K A M U N E T

Dokümantasyon Merkezi