EPYS - Dengeden Sorumlu Grup Servisleri

Genel Bakış

Versiyon bilgisi

Versiyon : 1.0.0

URI şeması

Sunucu : epys-prp.epias.com.tr
Kök Dizin : /balancing-group
Şemalar : HTTPS

Etiketler

balanceResponsibleGroup

Doküman Hakkında

Bu dokümanda Dengeden Sorumlu Grup servislerinin tanımları ve bu servislerin nasıl çağrılacağı anlatılmaktadır.

1. EPYS Dengeden Sorumlu Grup Servisleri Hakkında

EPYS Dengeden Sorumlu Grup uygulaması REST servisler üzerine kuruludur. JSON ve XML isteklerini kabul eder ve gelen isteğe göre JSON yada XML cevap döner.

Uygulamanın kullanıcı arayüzünde görmüş olduğunuz bilgilerin tamamı dışarıya açık olan bu servislerden alınmaktadır. Bu arayüzü kullanmadan da sahip olduğunuz uygulamalar ile sistemi kullanmanız mümkündür.

Uygulamayı çağırabilmek için EKYS de kayıtlı bir kullanıcınız olmalı ve bu kullanıcının ilgili servisleri çağırabilmek için yeterli yetkisi olmalıdır. Uygulamaya gelen tüm istekler Merkezi Yetkilendirme Sunucusu’ndan (https://cas.epias.com.tr) TGT alınarak gönderilmelidir.

2. İstemci Oluşturmak

Servis dokümantasyonu Swagger ile hazırlanmıştır. Test ortamı için https://epys-prp.epias.com.tr/balancing-group/technical/swagger.json gerçek ortam için https://epys.epias.com.tr/balancing-group/technical/swagger.json dosyasını kullanarak https://generator.swagger.io adresinden kullandığınız dile uygun istemci kodlarını oluşturabilirsiniz.

3. EPYS Dengeden Sorumlu Grup Uygulaması Servis Çağrımı

TGT (Ticket Granting Ticket) kullanıcının oturumunu kontrol eder. TGT Servisinden alacağınız değer 45 dakika boyunca kullanmasanız bile aktiftir. TGT değerini her kullanışınızda 45 dakikalık süre tekrar başlar.

TGT tekrar kullanılabilen bir değerdir. Her istek için TGT almanıza gerek yoktur. Her istek için TGT almanız halinde CAS (Merkezi Yetkilendirme Sunucusu) tarafından bloke edilebilirsiniz.

3.1. Ticket Granting Ticket (TGT) Oluşturma

TGT oluşturmak için https://cas.epias.com.tr/cas/v1/tickets?format=text (test ortamı için https://testcas.epias.com.tr/cas/v1/tickets?format=text) adresine aşağıdaki değerleri POST metodu ile göndermeniz gerekmektedir.

Gönderilen HTTP isteğinin header kısmında Content-Type karşılığında ise application/x-www-form-urlencoded yazmalıdır.

parametre	değer
username	EKYS Kullanıcı Adı
password	EKYS Şifresi

parametre

değer

username

EKYS Kullanıcı Adı

password

EKYS Şifresi

örnek http isteği

POST /cas/v1/tickets HTTP/1.1
Host: cas.epias.com.tr
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

username=DGPYSUSER&password=DGPYSSIFRE

Servisten HTTP 200 cevabını beklemelisiniz. Sonuç olarak aşağıdaki gibi bir örnek dönecektir.

örnek cevap

TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr

3.2. Service Ticket (ST) Oluşturma

ST oluşturabilmeniz için öncelikle geçerli TGT bilgisi almış olmanız gerekmektedir. Alınan TGT bilgisi ile https://cas.epias.com.tr/cas/v1/tickets/TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr adresine aşağıdaki değerleri *POST metodu ile göndermeniz gerekmektedir. ST oluşturabilmeniz için kullanıcak service bilgisi aşağıdaki gibidir. Service ticket bilgisi tek kullanımlık olup 15 saniye içinde kullanılmaz ise geçerliliğini kaybetmektedir.

ortam	service
PROD	https://epys.epias.com.tr
TEST	https://epys-prp.epias.com.tr

ortam

service

PROD

https://epys.epias.com.tr

TEST

https://epys-prp.epias.com.tr

Gönderilen HTTP isteğinin header kısmında Content-Type karşılığında ise application/x-www-form-urlencoded yazmalıdır.

parametre	değer
service	https://epys.epias.com.tr

parametre

değer

service

https://epys.epias.com.tr

örnek http isteği

POST /cas/v1/tickets/TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr HTTP/1.1
Host: cas.epias.com.tr
Content-Type: application/x-www-form-urlencoded
Content-Length: 39

service=https%3A%2F%2Fepys.epias.com.tr

Servisten HTTP 200 cevabını beklemelisiniz. Sonuç olarak aşağıdaki gibi bir örnek dönecektir.

örnek cevap

ST-30853663-c3OsaqpG16IDVGIA3cbs-cashazel-n201

3.3. EPYS Dengeden Sorumlu Grup Uygulaması Örnek Mesaj Yapısı

EPYS servislerinin standart bir mesaj yapısı bulunmaktadır. Gönderdiğiniz tüm isteklerde bu formata uygun veri göndermelisiniz.

Öncelikle her isteğin HTTP header alanına aşağıdaki değerleri eklemelisiniz.

parametre	değer
TGT	(Ticket Granting Ticket) (TGT) Örneğin : TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr
ST	(Service Ticket) (ST) Örneğin : ST-30853663-c3OsaqpG16IDVGIA3cbs-cashazel-n201
Accept	application/json veya application/xml
Content-Type	application/json veya application/xml

parametre

değer

TGT

(Ticket Granting Ticket) (TGT) Örneğin : TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr

(Service Ticket) (ST) Örneğin : ST-30853663-c3OsaqpG16IDVGIA3cbs-cashazel-n201

application/json veya application/xml

Content-Type

application/json veya application/xml

servise has parametreleri içeren body alanıdır. Tüm servisler için farklılık gösterebilir.

Aşağıdaki örnekte teslim gününün doğru olup olmadığını kontrol eden bir mesaj bulunmaktadır.

Servise gelen ve giden tüm mesajlardaki tarih alanları ISO-8601 formatındadır. Format yyyy-MM-dd’T’HH:mm:ssXXX şeklinde olmalıdır. Timezone değeri Yaz Saati Uygulamasında için +03:00 Kış Saatin Uygulamasında +02:00 olarak değişmektedir. Örnek bir zaman değeri şu şekildedir. 2016-03-25T00:00:00+03:00

Örnek ISO8601 Parser Java 8

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

public class DateUtil
{

    public static Date fromISO8601Date(String v)
    {
        if (null == v) return null;
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssXXX");
        try
        {
            return sdf.parse(v);
        } catch (ParseException e)
        {
            throw new RuntimeException(e);
        }
    }

    public static String toISO8601Date(Date v)
    {
        if (null == v) return null;
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssXXX");
        return sdf.format(v);
    }
}

Örnek HTTP Mesajı

POST /reconciliation-res/servis/v1/luy-invoice/invoice/list HTTP/1.1
Host: epys.epias.com.tr
Accept: application/json
Content-Type: application/json
TGT: TGT-237-U0TU0jUHLyOEIrdoDBEEf3AdRFAXGLifK2ITn4LoY3HfhstGtx-cas02.epias.com.tr
Cache-Control: no-cache
{
  "effectiveDate": "2019-04-01T00:00:00+03:00"
}

Örnek JSON Mesajı

{
   "status":"200 OK",
   "correlationId":"(NotUsingGateway)b09d8806-46b9-4703-b185-2167bf74e55e",
   "spanIds":"14826",
   "hostName":"10.199.199.67",
   "clientIp":"127.0.0.1",
   "userName":"NA",
   "successMessage":null,
   "errors":null,
   "body":{
      "content":{
          "completed": true
      }
   }
}

Gönderilen tüm isteklere dönen cevaplar da iki bölümden oluşur. Birinci bölüm isteğin başarılı olup olmadığını dönen status değeri. İkinci bölüm ise body alanında sonucu dönen kısım.

Her sonuç mesajında aşağıdaki alanlar sabit olarak bulunur.

parametre	tip	değer	açıklama
status	string	"200 OK" başarılı diğer hallerde hatakodu içerir	Aldığınız hatanın HTTP status kodunu dönmektedir.
error	list	başarılı durumda liste null dönmektedir	Hata almanız durumunda liste içinde aldığınız hatanın hata kodu ve hata mesajlarını dönmektedir. Hatalar ile ilgili detaylı bilgi almak isterseniz bu değerleri göndermeniz gerekmektedir.
correlationId	string	yapmış olduğunuz isteği tekilleştirmeye yarar spanIds ile birlikte	hata almanız durumunad bu bilgi ile birlikte spanIds göndermeniz zorunludur.
spanIds	string	yapmış olduğunuz isteği tekilleştirmeye yarar correlationId ile birlikte	hata almanız durumunad bu bilgi ile birlikte correlationId göndermeniz zorunludur.

parametre

tip

değer

açıklama

status

string

"200 OK" başarılı diğer hallerde hatakodu içerir

Aldığınız hatanın HTTP status kodunu dönmektedir.

error

list

başarılı durumda liste null dönmektedir

Hata almanız durumunda liste içinde aldığınız hatanın hata kodu ve hata mesajlarını dönmektedir. Hatalar ile ilgili detaylı bilgi almak isterseniz bu değerleri göndermeniz gerekmektedir.

correlationId

string

yapmış olduğunuz isteği tekilleştirmeye yarar spanIds ile birlikte

hata almanız durumunad bu bilgi ile birlikte spanIds göndermeniz zorunludur.

spanIds

string

yapmış olduğunuz isteği tekilleştirmeye yarar correlationId ile birlikte

hata almanız durumunad bu bilgi ile birlikte correlationId göndermeniz zorunludur.

VAL- hata kodu ile başlayan hata mesajlarının olduğunuz istek ile ilgili bir sorun olduğunu belirtir. İsteğinizi gözden geçirmelisiniz veya iş kurallarını kontrol etmelisiniz. APP- hata kodu ile başlayan hata mesajları sistemde bir hata olduğunu belirtir.Bizimle irtibata geçmelisiniz.

Örnek Başarılı JSON Cevap Mesajı

{
   "status":"200 OK",
   "correlationId":"b09d8806-46b9-4703-b185-2167bf74e55e",
   "spanIds":"14826",
   "hostName":"1.1.1.1",
   "clientIp":"127.0.0.1",
   "userName":"TESTUSER",
   "successMessage":null,
   "errors":null,
   "body":{
      "content":{
          "completed": true
      }
   }
}

Örnek Hatalı JSON Cevap Mesajı

{
  "status": "400 BAD_REQUEST",
  "correlationId": "b09d8806-46b9-4703-b185-2167bf74e55e!",
  "spanIds": "38048",
  "hostName":"1.1.1.1",
  "clientIp":"127.0.0.1",
  "userName": "TESTUSER",
  "successMessage": null,
  "errors": [
    {
      "errorCode": "VAL-PER-1002",
      "errorMessage": "2020-01-01T00:00:00+03:00[GMT+03:00] tarihi için faturalama dönemi bulunamamıştır. "
    }
  ],
  "body": {}
}

4. Servis Detayları

Bu bölümden kategorilerine göre Servis çağırım detayları ile ilgili bilgilere ulaşabilirsiniz.

4.1. DSG Talep Onaylama Servisi

Bu servis sadece piyasa katılımcısı kurumlar tarafından kullanılmaktadır. Servis parametre detaylarına buradan erişebilirsiniz.