# HHS ve YÖS API
HHS API, HHS’lerin detay bilgilerini sunan servistir. Bu servis ile aşağıdaki istek/yanıt yapıları ile ihtiyaç duyulabilecek ilgili bilgiler temin edilebilir. HHS API için “hhs_read” scope bilgisi kullanılır.
Production ortamında HHS / YOS API içerisinde sisteme dahil olmuş, sertifikasyonu başarı ile tamamlamış paydaşlar listelenecektir. HHS tarafından desteklenen API sürümleri listelenecektir.
YÖS’ler HHS API’sini sorgulayabilir ancak YÖS API’sini sorgulayamazlar.
Benzer şekilde HHS’ler YÖS API’sini sorgulayabilir, HHS API’sini sorgulayamazlar.
# HHS API
GET /hhs/{hhsKod}
İşlem Sorgu Örneği = /hhs ⇨ bu sorgu yöntemi ile tüm HHS’lerin dizi şeklinde verileri listelenir.
İşlem Sorgu Örneği = /hhs/2001 ⇨ bu sorgu yöntemi ile gönderilmiş olan hhsKodu’na ait bilgiler listelenir. Ya da “404 Not Found” hatası alır.
HHS ve YÖS API Tablo 20’deki istek parametrelerine göre sorgulanabilir.
İşlem Sorgu Örneği (Belirli Bir Hesap) = /hhs?srlmKrtr=kod&srlmYon=A
Tablo 20: HHS ve YÖS API Sorgulama İsteği Sorgu Parametreleri
| Alan Adı | Parametre Adı | Format | Zorunlu / Koşullu / İsteğe bağlı | Açıklama | HHS tarafından yapılması gereken kontrol ve işlemler |
|---|---|---|---|---|---|
| Sıralama Kriteri | srlmKrtr | AN3..50 | İ | Cevapta dönülecek işlemlerin sıralama kriterini belirtir. Alabileceği değerler: {“kod”, “unv”} | Bu veri gönderildiği durumda, HHS işlemler listesini bu kritere göre sıralayarak gönderir. Gönderilmediğinde, sıralama kriteri “unv” olarak belirlenmelidir. |
| Sıralama Yönü | srlmYon | AN1 | İ | Cevapta dönülecek işlemlerin sıralama yönünü belirtir. Alabileceği değerler: A: Azalan değerle sıralama Y: Artan değerle sıralama {“A”,”Y”} | Bu veri gönderildiği durumda, HHS işlemler listesini bu yöne göre sıralayarak gönderir. Gönderilmediğinde, HHS sıralama yönünü Azalan olarak belirler. |
Tablo 21: HHS Bilgileri Sorgulama Yanıtı “Hhs” nesnesi
| Alan Adı | Parametre Adı | Format | Zorunlu / Koşullu / İsteğe bağlı | Açıklama |
|---|---|---|---|---|
| hhs kodu | kod | AN4 | Z | HHS nin kod bilgisi |
| hhs unvanı | unv | AN3..140 | Z | HHS nin unvan bilgisi |
| hhs markası | marka | AN1..140 | Z | ÖHK'nın kolaylıkla algılayabileceği kısa unvan bilgisi. HHS tarafından belirlenecektir. |
| Açık anahtar | acikAnahtar | AN1..1024 | Z | HHS’nin mesaj imzalama için paylaştığı açık anahtar |
| HHS Api Bilgileri | apiBilgileri | Kompleks: HhsApiBilgi[Array][0..N] | Z | Desteklenen Api ve sürüm bilgileri dönülecektir. |
| > api | api | AN1..20 | Z | Api İsmi Örnek :obh, hbh,gkd |
| > surum | surum | AN1..10 | Z | Api Sürüm Kodu Örnek: s1.0, s2.0 s1.0 |
| Logo Bilgileri | logoBilgileri | Kompleks: LogoBilgisi [Array][1..N] | Z | HHS’ye ait logo bilgileri. Logotur = Original formatındaki logonun minimumda gönderimi zorunludur. |
| >logoTur | logoTur | AN3..50 | Z | Logonun türünü belirler. TR.OHVPS.DataCode.LogoTur alabileceği değerler ORIGINAL , WHITE_OVERLAY , BLACK_OVERLAY , GRAY_OVERLAY |
| > logoAdr | logoAdr | AN1..255 | Z | HHS tarafında tutulan ve YÖS’lerle paylaşılacak olan url adres bilgisidir. |
| Durum | durum | AN1 | Z | HHS'nin durum bilgisidir. TR.OHVPS.DataCode.HHSDurumu sıralı veri tipinde alabileceği değerler belirtilmiştir. |
HHS API'de; Açık, Yaygınlaştırma, Geçici Hizmet Veremiyor, Kapalı durumlarındaki HHS'ler listelenecektir.
Sertifikasyon onayı alan HHS'ler, üretim ortamına geçişte "Yaygınlaştırma" durumuna sahip olabilir. HHS'nin, hangi YÖS'ler ile "Yaygınlaştırma" kontrollerini yapacağı, HHS yönetiminde olacaktır. Böylece Üretim Ortamında HHS’nin kendisi tarafından tanımlanmış kısıtlı ÖHK’ya hizmet vermesi ve servislerini test etmesi sağlanabilir olacaktır. HHS'ler kendi kurum kontrollerini yapana kadar, "Yaygınlaştırma" durumunda kalabilirler. HHS'nin BKM'ye yapacağı talep ile, HHS "Yaygınlaştırma" durumundan "Açık" durumuna geçebilecektir.
HHS'de olası bir teknik sorun olması durumunda, BKM - HHS koordinasyonu ile HHS durumu "Geçici Hizmet Veremiyor" haline getirilecektir. Sorun giderildiğinde "Açık" durumuna geri dönecektir.
Hem YOS hem de HHS API için geçerli olacak; logo gönderiminde dikkat edilmesi gerekenler şu şekilde tariflenmiştir:
- Logoların ham dosya yerine kurumun yayınlayacağı bir URL üzerinden sunulması gerekmektedir. (Örn: logoURL = https://kurumadi.com.tr/logo.png) Logo BKM tarafında host edilmeyecektir.)
- PNG formatında (PNG-24) olmalıdır.
- 72 DPI çözünürlükte olmalıdır.
- 500 x 500 boyutlarında, yatayda veya dikeyde taşma paysız tam oturacak, sınır boyutlarını geçmeyecek ve ortalanmış yerleşime sahip olmalıdır.
- Logo arka planı renkli olmamalı, arka plan transparan olmalıdır.
- YÖS uygulamasında gösterim esnasında logoların hızlı yüklenmesi ve düşük veri tüketmesi açısından; logo boyutu 250 KB’ın altında olmalıdır.
- Dört adet logo türü belirlenmiştir. Bu 4 tür için de logo dönülmesi zorunludur.
- Logo url’in public erişilebilir url olması gereklidir.
YÖS API, YÖS statüsundeki kurumların detay bilgilerini sunan servistir. Bu servis ile aşağıdaki istek/yanıt yapıları ile ihtiyaç duyulabilecek ilgili bilgiler temin edilebilir. YÖS API için “yos_read” scope bilgisi kullanılır.
YÖS API yanıtında, listelenen yönlendirme ve bildirim adresleri bulunmaktadır. HHS, işlem anında iletilen yonAdr ya da bldrAdr alanlarında gönderilen adreslere yetKod değerini iletmelidir. YÖS API içerisinde yer alan adresleri, rıza isteğinde gönderilen adreslerin doğruluğunu kontrol etme amacıyla kullanılmalıdır. Bu nedenle YÖS API içerisinde listelenen adreslerin hostname seviyesinde yer alması yeterlidir.
# YOS API
YÖS API içerisinde yer alan YÖS rol bilgileri ve aktiflik/pasiflik durumları birbiriyle ilişkili değildir.
YÖS'ün sahip olduğu öbhs,hbhs rolleri için herhangi bir fraud ya da teknik sebeplerden ötürü geçici süreyle geri alınabilir.
YÖS aktifliğini korurken problem çözülene kadar geçici olarak alınan roller(öbhs,hbhs) tekrardan aktif hale getirilir.
GET /yos/{yosKod}
İşlem Sorgu Örneği = /yos bu sorgu yöntemi ile tüm yos lerin dizi şeklinde verileri listelenir.
İşlem Sorgu Örneği = /yos/2501 bu sorgu yöntemi ile gönderilmiş olan yosKodu’na ait bilgiler listelenir ya da “404 Not Found” hatası alır. YÖS API Tablo 20’deki istek parametrelerine göre sorgulanabilir. İşlem Sorgu Örneği (Belirli Bir Hesap)= /yos?srlmKrtr=kod&srlmYon=A
Tablo 22: YOS Bilgileri Sorgulama Yanıtı “Yos” nesnesi
| Alan Adı | Parametre Adı | Format | Zorunlu / Koşullu / İsteğe bağlı | Açıklama |
|---|---|---|---|---|
| Yös kodu | kod | AN4 | Z | YÖS'ün kod bilgisi |
| Yös unvanı | unv | AN3..140 | Z | YÖS unvan bilgisi |
| Yös markası | marka | AN1..140 | Z | ÖHK'nın kolaylıkla algılayabileceği kısa unvan bilgisi. YÖS tarafından belirlenecektir. |
| YÖS rolleri | roller | Array[AN4] | Z | YÖS’un rollerini belirten değer. Örnek: [ "obhs", "hbhs" ] - obhs - Ödeme Bilgisi Hizmet Sağlayıcı Rolü - hbhs - Hesap Bilgisi Hizmet Sağlayıcı Rolü |
| Adresler | adresler | Kompleks:Adres[Array] [1..N] | Z | --- |
| > Yetkilendirme Yöntemi | yetYntm | AN1 | Z | TR.OHVPS.DataCode.GkdTur sıralı veri türü değerlerlerinden birini alır. Adres detaylarının hangi GKD türüne ait olduğunu belirtir. |
| >Adres Detayları | adresDetaylari | adresDetaylari Kompleks: AdresDetayi[Array] [1..N] | Z | |
| >>Temel Adres | tmlAdr | AN1..1024 | Z | yetYntm değeri “Y” olarak iletildiğinde Yönlendirmeli GKD sürecinde HHS’nin YOS’e authorizasyon kodunu hangi url e göndereceği bilgisini tutar. yetYntm değeri “A” olarak iletildiğinde Ayrık GKD sürecinde HHS’nin YOS’e authorizasyon kodunu hangi url e göndereceği bilgisini tutar. Riza isteklerinde bu değer ile uyumluluğu kontrol edilmelidir. Örnek: https://example.com https://example2.com/path deepLink://example/test deepLink://example2/test |
| >>Açıklama | aciklama | AN1..1024 | İ | YÖS’ün gönderdiği adrese yönelik vermek istediği açıklama Örnek: WEB bireysel , WEB kurumsal , APP |
| Açık anahtar | acikAnahtar | AN1..1024 | Z | YÖS’ün mesaj imzalama için paylaştığı açık anahtar |
| Logo Bilgileri | logoBilgileri | Kompleks: LogoBilgisi [Array][1..N] | Z | YOS’e ait logo bilgileri. Logotur = Original formatındaki logonun minimumda gönderimi zorunludur. |
| >logoTur | logoTur | AN3..50 | Z | Logonun türünü belirler. TR.OHVPS.DataCode.LogoTur alabileceği değerler ORIGINAL , WHITE_OVERLAY , BLACK_OVERLAY , GRAY_OVERLAY |
| > logoAdr | logoAdr | AN1..255 | Z | YÖS tarafında tutulan ve HHS’lerle paylaşılacak olan url adres bilgisidir. Örnek: https://via.placeholder.com/150?text=0001 |
# Healthcheck API
GET /health
HHS ve YÖS API için health servisleri aşağıdaki servislerle kontrol edilebilir.
Başarılı yanıtta Http 200 kodu dönülecektir Başarılı Yanıt:
| Alan Adı | JSON Alan Adı | Format: Veri modeli İsmi | Zorunlu / Koşullu / İsteğe bağlı | Açıklama |
|---|---|---|---|---|
| status | status | AN2..20 | Z | “UP”, “DOWN” değerlerini alabilir |