Yük Tevzi Bilgi Sistemi

Web Servis İşlemleri Kılavuzu

Saatlik Ölçüm Verileri Servisleri

Enerji Teknolojileri
Güç Sistemleri Araştırma Grubu

05.01.2024
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

İçindekiler

1. YTBS Web Servis Uygulaması ................................................................................................................ 3

Genel Kurallar .................................................................................................................................... 3
Yetkilendirme Servisleri ..................................................................................................................... 5
1.2.1. Login Servisi................................................................................................................................. 5

1.2.2. Logout Servisi .............................................................................................................................. 5

Saatlik Ölçüm Verileri Servisleri ......................................................................................................... 6

1.3.1. Sorgulama Servisi ........................................................................................................................ 6

1.3.2. Ekleme Servisi ............................................................................................................................. 7

1.3.3. Silme Servisi ................................................................................................................................ 8

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 2/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

1. YTBS Web Servis Uygulaması

YTBS Web Servis Uygulaması RESTFULL mimarisi ile API’ler üzerinden sistem kullanımını sağlayan bir web
uygulamasıdır. Bu başlıkta uygulamanın kullanım kuralları ve API bilgileri yer almaktadır.

Genel Kurallar
Web servisler Post request kullanılacaktır. Her web servisin genel URL’si aşağıda belirtilmiştir. Servislere
özel URL uzantıları kılavuzun ilgili bölümlerinde verilecektir. Web servis request datalarında veri formatı
JSON olmalıdır. Aşağıda detaylıca bahsedilen servis anahtarı ve jeton request datasının header kısmında
yer almalıdır.

Genel URL: https://ytbsws.teias.gov.tr/ytbs-webservis/rest/

Servis Anahtarı: Servis anahtarı web servis yetkilendirmesi için tanımlanan Public anahtardır. Servis
anahtarı kimseyle paylaşılmamalıdır. Bütün request datasının header kısmına eklenmelidir. Servis anahtarı
YTBS Web Uygulaması → Yardım İşlemleri → Sistem Yönetimi → Sistem Parametresi sayfasındaki YTBS
Web Servis seçeneği altında yer alan Service Key parametresinin değerinde sunulmaktadır.

Jeton: Login servisi hariç diğer servislerin kullanılması için YTBS Web Servisi tarafından üretilen
yetkilendirme araçlarından biridir. Sonraki bölümlerde detaylıca bahsedilecek olan Login web Servisi
kullanılarak elde edilir. Servisler kullanıldıktan sonra Logout servisi ile jetonun geçerliliği sonlandırılmalıdır.
Login servisi ile temin edilen jetonun maksimum geçerlilik süresi 1 saattir. 1 saat sonunda yeni bir jeton
alınmalıdır.

JSON request datasının body kısmında alan adları lower camel case formatında olmalıdır. JSON
formatındaki response içeriğindeki alan adları da aynı formatta olacaktır. Boolean türündeki alanlar true
ya da false olacaktır. “basarili”, “gecerli” ve “mesaj” alanları dosya talep edilen servisler (şebeke modeli
webservisleri v.b.) hariç ortak olacaktır. Dosya talep edilen servislerde dosyanın oluşturmanın başarısız
olduğu durumlarda veri formatı repsonse genel yapısına uygun olacaktır. Dosyanın başarılı bir şekilde
oluşturulması durumunda dosya APPLICATION_OCTET_STREAM formatındaki response içerisinde yer
alacaktır.

Request Genel Yapısı

Type Params Values Info

HEADER Content-Type string 'application/json'

HEADER SERVICE_KEY string Sistem Parametresi sayfasından temin edilecektir.

HEADER AUTH_TOKEN string Login servisi kullanılarak temin edilir. Geçerlilik süresi 1 saat.

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 3/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

Response Genel Yapısı

Field Values Info

basarili boolean İlgili web servisin başarı ile response oluşturması durumunda true olacaktır.

gecerli boolean Request datasının ve isteğin geçerlilik durumunu belirtir.

mesaj string Web servisin yanıtı ile ilgili bilgilendirme ve hata mesajlarının yer aldığı alandır

veri JSON Data Beklenen web servislerde bulunan bir alandır.

Hata Kodları

Status Response

200 Request’in başarılı şekilde yanıtlandığı durumları belirtir.

400 Verinin geçerli olduğu ancak web servisin response oluşturmada bir sorun ile karşılaşılması
durumu belirtir.

401 Yetkinin geçersiz olduğu durumları belirtir. Servis anahtarı veya jetonun geçersiz olduğunu
veya web servisin kullanımı için yetkinin olmadığı durumlarda karşılaşılır.

412 Veri formatının hatalı olması ya da ilgili web servisi kullanmak için gerekli alanların
doldurulmaması gibi durumları belirtir.

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 4/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

Yetkilendirme Servisleri

1.2.1. Login Servisi

Login servisi kullanıcı adı ve şifre ile Jeton alma işlemi gerçekleştirilir. Başarılı bir şekilde alınan Jeton, diğer
tüm servislerde Header kısmında belirtilir.

URL

Method URL

POST yetkilendirme/login

Request

Params Values Info

kullaniciAdi string YTBS kullanıcı adı

sifre string YTBS kullanıcı şifresi

Response Body

Field Values Info

jeton string Login web servisi tarafından oluşturulan jeton

1.2.2. Logout Servisi

Logout servisi için oluşturulacak request datasında body kısmı yoktur. Request’in headers alanında servis
anahtarı ve jeton bilgisinin bulunması yeterlidir.

URL

Method URL

POST yetkilendirme/logout

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 5/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

Saatlik Ölçüm Verileri Servisleri

Saatlik ölçüm verileri servisleri ile verilerin sorgulanması, veri tabanına veri eklenmesi ya da veri
tabanından silinmesi işlemleri yapılmaktadır. Servislerde request datada veya response datalarında
bulunan ölçüm birimleri ve ölçüm yerleri aşağıdaki tablolarda belirtilmiştir.

Merkez Türü ID Merkez Türü Adı

0 Santral
1 Trafo Merkezi

Veri girişi veya sorgulaması yapılan merkezlerin ID bilgisi ve merkezde bulunan teçhizatların ID bilgisi YTBS
Veri Toplama İşlemleri altında bulunan Analog Ölçüm Şablonu Sayfasından elde edilebilir. Sayfadaki
merkez seçeneklerinde [XXX] değeri merkez ID’yi göstermektedir. Merkez adının sonunda (*) simgesi var
ise merkezin türü Santraldir, aksi durumda merkez türü trafo merkezidir. Her bir teçhizatta toplanan
analog ölçümlerin listesi sayfada belirtilmektedir.

1.3.1. Sorgulama Servisi

Saatlik ölçüm verileri sorgulama servisinde tabloda verilen request datasında ‘*’ ile belirtilen parametreler
request datasında mutlaka bulunması gerekmektedir. Bu servis ile ilgili merkez için belirtilen tarih veya
tarih-saat’e ait tüm saatlik ölçüm verileri sorgulanabilecektir. Response JSON Array formatında olup
array’in elemanlarına ait parametre adları response tablosunda verilmiştir.

URL

Method URL

POST veritoplama/saatlikolcum/sorgula

Request

Params Values Info

merkezId* string Merkezin ID’sini belirtir.

merkezTuru* integer Santral ise 0, trafo merkezi ise 1

tarih* string “yyyy-aa-gg” formatında olmalıdır.

saat string “ss:dd” formatında olmalıdır.

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 6/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

Response Body

Field Values Info

tanimId integer Techizat ID

tanimAdi string Techizat Adi

analogOlcumId integer Analog ölçüm ID

olcumYeriId string Ölçüm yeri ID.

olcumYeriAdi string Ölçüm Yeri Adı

olcumBirimiId integer Ölçüm birimi ID

olcumBirimiAdi string Ölçüm birimi adı

veriDeger double Ölçülen değer

zaman string “gg-aa-yyyy ss:dd” formatındadır.

guncelleyenKullaniciAdi string Veri kayıt eden kullanıcının adı

guncellemeZamani string “gg-aa-yyyy ss:dd” formatındadır.

1.3.2. Ekleme Servisi

Ölçüm verisi ekleme servisi request datasında merkez, merkez türü ve veri alanları bulunmaktadır.

URL

Method URL

POST veritoplama/saatlikolcum/ekle

Request

Params Values Info

merkezId* string Merkezin ID’sini belirtir.

merkezTuru* integer Santral ise 0, trafo merkezi ise 1

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 7/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

veri* JSON array Eklenecek veri listesi

Request datasında veri JSON array formatında olup array elemanlarının JSON yapısı aşağıdaki tabloda
verilmiştir.

Params Values Info

tarih* string “yyyy-aa-gg” formatında olmalıdır.

saat* string “ss:dd” formatında olmalıdır.

analogOlcumId* integer Analog Ölçüm ID

veriDeger* double Ölçüm değeri

1.1 Genel Kurallar bölümünde verilen yapıya uygun response dönmektedir.

1.3.3. Silme Servisi

Saatlik ölçüm verisi silme servisi belirtilen tarih veya tarih-saatteki verilerin ya da liste halinde sunulan
ölçüm verilerinin silinmesine olanak sağlar. Tarih veya tarih saat bilgisi ile silme işlemi yapılacaksa “veri”
alanının doldurulması gerekli değildir. Tarih ile işlem yapılmayacaksa “veri ” alanının mutlaka dolu olması
gerekir.

URL

Method URL

POST veritoplama/saatlikolcum/sil

Request

Params Values Info

merkezId* string Merkezin ID’sini belirtir.

merkezTuru* integer Santral ise 0, trafo merkezi ise 1

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 8/9
Yük Tevzi Bilgi Sistemi Web Servis İşlemleri Kılavuzu

tarih string “yyyy-aa-gg” formatında olmalıdır.

saat string “ss:dd” formatında olmalıdır.

veri JSON array Silinecek veri listesi

Request datasında veri JSON array formatında olup array elemanlarının JSON yapısı aşağıdaki tabloda
verilmiştir.

Params Values Info

tarih* string “yyyy-aa-gg” formatında olmalıdır.

saat* string “ss:dd” formatında olmalıdır.

analogOlcumId* integer Analog Ölçüm ID

1.1 Genel Kurallar bölümünde verilen yapıya uygun response dönmektedir.

TÜBİTAK MAM Enerji Teknolojileri, ANKARA

05.01.2024 9/9