Genel Bakış

Versiyon bilgisi

Versiyon : v1

URI şeması

Sunucu : stp.epias.com.tr
Kök Dizin : /stp-broadcaster-orchestrator/rest
Şemalar : HTTPS

Etiketler

  • endpoint

Döküman Hakkında

Bu dökümanda Yardımcı Servislerin tanımları ve bu servislerin nasıl çağrılacağı anlatılmaktadır.

Döküman her sürümde güncellendiğinden test ve gerçek ortam içerisindeki servisler farklılık gösterebilir. Sürüm notlarını takip ediniz.

Değişiklikler

1.0.0 Servis tanımları

Uygulama Hakkında

Bu uygulama REST servisleri üzerine kuruludur. JSON ve XML isteklerini kabul eder ve gelen isteğe göre JSON yada XML cevap döner.

Uygulamayı çağırabilmek için DGPYS 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 (gerçek ortam için https://cas.epias.com.tr test ortamı için https://testcas.epias.com.tr) etiket alınarak gönderilmelidir.

İstemci Oluşturmak

Servis dökümantasyonu Swagger ile hazırlanmıştır. Gerçek ortam için https://stp.epias.com.tr/stp-broadcaster-orchestrator/test/swagger.json gerçek ortam için https://teststp.epias.com.tr/stp-broadcaster-orchestrator/test/swagger.json dosyasını kullanarak https://generator.swagger.io adresinden kullandığınız dile uygun istemci kodlarını oluşturabilirsiniz.

Yardım ve Destek

Uygulama konusundaki istek ve görüşlerinizi Yardım Platformu ( https://yardim.epias.com.tr ) aracılığıyla iletebilirsiniz.

Uygulama 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 ile servisi çağırmanız mümkün değildir. Her servis çağrımında TGT üzerinden ST (Service Ticket) almanız gerekir. 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.

Ticket Granting Ticket (TGT) Oluşturma

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

parametre değer

xml

xml response döner

json

json response döner

text

text response döner

Gönderilen HTTP isteğinin header kısmında Content-Type ise aşağıdaki değerleri alabilir.

parametre değer

xml

application/xml

json

application/json

text

application/x-www-form-urlencoded

parametre değer

username

Kullanıcı Adı

password

Şifre

ö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=KULLANICI_ADIM&password=ŞİFREM

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

Service Ticket (ST) Oluşturma

ST oluşturmak için önce TGT alınmalıdır. TGT alındıktan sonra şu şekilde bir istek adresi oluşturulur. Gerçek ortam için https://cas.epias.com.tr/cas/v1/tickets/{TGT} test ortamı için https://testcas.epias.com.tr/cas/v1/tickets/{TGT} ST için xml veya JSON cevap alabilmeniz için url şu şekilde oluşturmalısınız.

örnek xml tipinde cevap için url formatı
https://cas.epias.com.tr/cas/v1/tickets/TGT-229-2hmcHafszagAAxtCh017nax1en3U9TouWeGvIrq9KbSbeKE9Zk-cas02.epias.com.tr?format=xml
cevap
<st>ST12312312312321</st>
örnek json tipinde cevap için url formatı
https://cas.epias.com.tr/cas/v1/tickets/TGT-229-2hmcHafszagAAxtCh017nax1en3U9TouWeGvIrq9KbSbeKE9Zk-cas02.epias.com.tr?format=json
cevap
{"st":"ST12312312312321"}
parametre değer

xml

xml response döner

json

json response döner

Bir servis için alınan ST başka bir servis için kullanılamaz.
ST nin geçerlilik süresi 30 saniyedir.
Uygulamanın servis adı gerçek ortam için https://stp.epias.com.tr test ortamı için app-preproduction
örnek
https://cas.epias.com.tr/cas/v1/tickets/TGT-229-2hmcHafszagAAxtCh017nax1en3U9TouWeGvIrq9KbSbeKE9Zk-cas02.epias.com.tr

Bu adrese aşağıdaki parametreler POST metodu ile gönderilir.

parametre değer

service

test ortamı için https://stp.epias.com.tr gerçek ortam için https://teststp.epias.com.tr

Sonuç olarak aşağıdaki cevap döner. Bu servisten HTTP 200 döndüğünde ST yi başarılı olarak almış olursunuz.

örnek
ST-29962-hSwyzWCP0xC0eRi0bmna-cas01.epias.com.tr

Uygulama Örnek Mesaj Yapısı

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

stp-service-ticket

Service Ticket (ST) Örneğin : ST-30247-uNWazHn52sKZU71v5Ar4-cas02.epias.com.tr

Accept

application/json veya application/xml

Content-Type

application/json veya application/xml

Accept-Language

tr-tr veya en-us (ingilizce henüz test aşamasındadır)

Servis mesajları iki bölümden oluşur.

Birinci bölüm header olarak kullanılan ve isteği, gönderdiğiniz servisten bağımsız olarak isteği tanımlayan mesaj alanıdır. header alanında aşağıdaki anahtarlar bulunmalıdır.

parametre değer açıklama

transactionId

isteği tanımlayan benzersiz anahtar (Universal Unique Identifier)

isteğiniz ile ilgili sorularınızda bu id değerini sizden isteyeceğiz

application

servisi çağırırken kullanmış olduğunuz uygulamanın adı

İkinci bölüm ise çağırdığınız 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.

header alanını anahtar (key) ve değer (value) şeklinde gönderilmelidir.
Servise gelen ve giden tüm mesajlardaki tarih alanları ISO-8601 formatındadır. Format yyyy-MM-dd’T’HH:mm:ss.SSSXXX ş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. O yüzden dökümanın içerisinde verilen örnek JSON dosyalarındaki tarih alanlarına dikkat ediniz. Örnek bir zaman değeri şu şekildedir. 2016-03-25T00:00:00.000+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:ss.SSSXXX");
        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:ss.SSSXXX");
        return sdf.format(v);
    }
}
Örnek HTTP Mesajı
POST /stp-organization-service/rest/organization/save HTTP/1.1
Host: testtysapi.epias.com.tr
Accept: application/json
Content-Type: application/json
stp-service-ticket: ST-31352-VjHOo5iDV4fDkOod3jZc-cas02.epias.com.tr
Cache-Control: no-cache

{
   "header":[
      {
         "key":"transactionId",
         "value":"6d553b3c-1ffc-44cc-bed6-1dce4d5b48ac"
      },
      {
         "key":"application",
         "value":"UYGULAMA_ADI"
      }
   ],
   "body":{
      "settlementPeriod":"2016-06-01T00:00:00.000+0300",
      "requestStatuses":["WAITING","INVALID_DISTRIBUTION_METER_CODE","INSUFFICENT_LIMIT","APPROVED"]
   }
}
Örnek JSON Mesajı
{
   "resultCode":"0",
   "resultDescription":"OK",
   "resultType":"SUCCESS",
   "body":{
      "queryInformation":{
         "begin":1,
         "end":10000,
         "count":3
      },
      "unregisteredMeteringPoints":[
         {
            "requestId":1,
            "requestDate":"2016-10-03T13:34:43.000+0300",
            "reportingDate":null,
            "distributionMeterCode":"  M328",
            "eic":"40Z000007531577H",
            "requestStatus":"APPROVED",
            "requestedCompany":{
               "organizationId":9327,
               "eic":"40X000000009327Q",
               "name":"ERZURUM 1.ORGANİZE SANAYİ BÖLGE MÜDÜRLÜĞÜ",
               "shortname":"ERZ.1-OSB"
            },
            "requestingCompany":{
               "organizationId":195,
               "eic":"40X000000000195P",
               "name":"ELEKTRİK ÜRETİM A.Ş.",
               "shortname":"EÜAŞ"
            },
            "recordingUser":"PK195",
            "reportingUser":null
         }
      ]
   }
}

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 result ile başlayan değerler. İ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

resultCode

string

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

aldığınız hatalar ile ilgili bilgi almak isterseniz bu alanı sizden isteyeceğiz.

resultDescription

string

başarılı durumda "OK" diğer hallerde hatanın açıklamasını içerir

aldığınız hatalar ile ilgili bilgi almak isterseniz bu alanı sizden isteyeceğiz. SUCCESS, BUSINESSERROR, SYSTEMERROR, SECURITYERROR

resultType

string

başarılı isteklerde SUCCESS , bir iş kuralına takıldıysanız BUSINESSERROR , bir sistem hatası ile karşılaşırsanız SYSTEMERROR, yetkilendirme ile ilgili hata alırsanız SECURITYERROR

BUSINESSERROR : Göndermiş olduğunuz istek ile ilgili bir sorun olduğunu belirtir. İsteğinizi gözden geçirmelisiniz. SYSTEMERROR : Sistemde bir hata olduğunu belirtir. Bizimle irtibata geçmelisiniz.
Örnek Başarılı JSON Cevap Mesajı
{"resultCode":"0","resultDescription":"OK","body":true,"resultType":"SUCCESS"}

Servis Detayları

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

1. Gerçek Zamanlı Yayın Servisi

1.1. Gerçek zamanlı yayın servisi nasıl çağrılır?

Servis parametrelerinde dönen adres alanı oturum açacağınız alandır. Diğer servislerden farklı olarak yayın servisine oturum açmadan önce bu servisin dönmüş olduğu http header bilgileri oturum açılan adrese gönderilmelidir. Servise oturum açtıktan sonra bağlantınızın kopması halinde tekrar oturum parametrelerini alarak oturum açmalısınız. Servis parametre detaylarına buradan erişebilirsiniz.

Örnek XML İsteği
<?xml version="1.0" encoding="UTF-8"?>
<endpointGetRequest>
        <headers>
                <key>transactionId</key>
                <value>6d553b3c-1ffc-44cc-bed6-1dce4d5b48ac</value>
        </headers>
        <body>
        </body>
</endpointGetRequest>
Örnek XML Cevabı
<?xml version="1.0" encoding="UTF-8"?>
<endpointGetServiceResponse>
        <resultCode>0</resultCode>
        <resultDescription>OK</resultDescription>
        <resultType>SUCCESS, BUSINESSERROR, SYSTEMERROR, SECURITYERROR</resultType>
        <transactionId>Transaction id.</transactionId>
        <body>
                <parameters>
                        <name>string</name>
                        <value>string</value>
                </parameters>
                <broadcastAddress>string</broadcastAddress>
                <broadcastBase>string</broadcastBase>
        </body>
</endpointGetServiceResponse>
Örnek Json İsteği
{
  "headers": [
    {
      "key": "transactionId",
      "value": "6d553b3c-1ffc-44cc-bed6-1dce4d5b48ac"
    }
  ],
  "body": {}
}
Örnek Json Cevabı
{
  "resultCode": "0",
  "resultDescription": "OK",
  "resultType": "SUCCESS, BUSINESSERROR, SYSTEMERROR, SECURITYERROR",
  "transactionId": "Transaction id.",
  "body": {
    "parameters": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "broadcastAddress": "string",
    "broadcastBase": "string"
  }
}

2. Dizinler

2.1. Realtime Notification Service Configuration

POST /endpoint/get

2.1.1. Açıklama

Returns connection parameters and url of notification endpoint.

2.1.2. Parametreler

Tip İsim Açıklama Şema Varsayılan

Header

stp-service-ticket
gerekli

STP Service ST Header

string

Body

body
opsiyonel

endpointGetRequest

2.1.3. Cevaplar

HTTP Kodu Açıklama Şema

200

successful operation

endpointGetServiceResponse

2.1.4. Kullanılanlar

  • application/json

  • application/xml

2.1.5. Üretilenler

  • application/json

  • application/xml

2.1.6. Etiketler

  • endpoint

3. Tanımlar

3.1. Header

Header information.

İsim Açıklama Şema

key
opsiyonel

Header key.
Örnek : "transactionId"

string

value
opsiyonel

HTTP Parameter Value
Örnek : "6d553b3c-1ffc-44cc-bed6-1dce4d5b48ac"

string

3.2. HttpParameter

Http Parameter

İsim Açıklama Şema

name
gerekli

HTTP Parameter Name

string

value
gerekli

HTTP Parameter Value

string

3.3. RequestBody

Tip : object

3.4. endpointGetRequest

Realtime Notification Service Request

İsim Açıklama Şema

body
opsiyonel

RequestBody

headers
opsiyonel

Header information.

< Header > array

3.5. endpointGetServiceResponse

Realtime Notification Configuration Response

İsim Açıklama Şema

body
opsiyonel

endpointResponse

resultCode
gerekli

0 for successful requests. For unsuccessful requests, this value contains the error code.
Örnek : "0"

string

resultDescription
gerekli

Returns OK if successful or error description otherwise.
Örnek : "OK"

string

resultType
gerekli

SUCCESS for successful requests BUSINESSERROR if a business is blocked by the rule. SECURITYERROR if it is attached to security or authorization control, SYSTEMERROR if there is a system error.
Örnek : "SUCCESS, BUSINESSERROR, SYSTEMERROR, SECURITYERROR"

enum (SUCCESS, BUSINESSERROR, SYSTEMERROR, SECURITYERROR)

transactionId
opsiyonel

SUCCESS for successful requests BUSINESSERROR if a business is blocked by the rule. SECURITYERROR if it is attached to security or authorization control, SYSTEMERROR if there is a system error.
Örnek : "Transaction id."

string

3.6. endpointResponse

Realtime Notification Configuration Response

İsim Açıklama Şema

broadcastAddress
opsiyonel

string

broadcastBase
opsiyonel

string

parameters
opsiyonel

< HttpParameter > array