Etkinlik Bileti Entegrasyonu

Servis test çağrıları için https://ebiletservicetest.isim360.com/apidocs/ adresindeki arayüz kullanılabileceği gibi Postman tool’u da kullanılabilir. Dokümanda yer alan servis test ekran görüntüleri için Postman tool’u kullanılmıştır.

Buradaki adreste anlatıldığı şekilde access token alındıktan sonra e-bilet servislerine erişim sağlanabilir.

Servislere erişim için service request header’ın authorization alanı ‘bearer(boşluk)access_token’ şeklinde set edilmelidir.

Örnek Postman ekran görüntüsü;

SaveTicket

Service Endpoint : https://ebiletservicetest.isim360.com/v1/eventtickets

e-Bilet kayıt servisidir. Servis ile her seferinde tek e-bilet kaydı yapılabilir.

Örnek Postman request’i ekran görüntüsü ve ekran görüntüsündeki alanların açıklamaları aşağıda verilmiştir;

Servis input parametreleri 1- Bilet bilgileri

Tüm bilet tipleri için ortak kabul edilen alanlar ve açıklamaları şu şekildedir;

ExecutionDate

Bilet düzenleme tarihi. Zorunlu alandır.

PaymentType

Ödeme tipini ifade eder. Zorunlu alandır. Aşağıdaki değerleri alabilir;

BankaKarti = 0

Bedelsiz = 1

KrediKartı = 2

Puan = 3

Mahsup = 4

MahsupPuan = 5

Nakit = 6

Pass = 7

Promosyon = 8

Mil = 9 Coklu = 10

UlasimKarti = 11

Diger = 12

TotalAmount

Kdv hariç toplam bedelini ifade eder. Zorunlu alandır.

PayableAmount

Toplam bilet bedelini ifade eder. Zorunlu alandır.

TaxPayer

Bilet bedelini gider gösterecek veya indirime konu edecek mükellef.

TaxPayerTcknVkn

Bilet bedelini gider gösterecek veya indirime konu edecek mükellefe ait vkn/tckn bilgisi yazılacaktır.

NameSurname

Bilet’i satın alan kişi/kurum isim bilgisini ifade eder.

VknTckn

Bilet’i satın alan kişi/kurum tckn/vkn bilgisini ifade eder.

KdvAmount

Toplam Kdv tutarını ifade eder. Zorunlu alandır.

UseManuelTicketNumber

e-Bilet entegrasyon sürecinde her bilet’in unique bir bilet numarası olmak zorundadır. Bu bilet numarası GİB’in belirttiği standartlarda 16 haneli (3 haneli birim kodu ve 13 haneli sıra numarası) olarak oluşturulur. UseManuelTicketNumber alanı false olarak geçilirse bilet numarası Turkcell e-Şirket tarafından, true geçilmesi halinde ise istemci tarafından belirlenecek demektir. UseManuelTicketNumber alanı true geçilirse, istemci 16 haneli bilet numarasını request içerisinde belirtmek zorundadır. Bu alan TicketNumber alanıdır.

Prefix

Prefix alanmı zorunlu bir alan değildir. 16 haneli bilet numarasındaki 3 haneli birim koduna karşılık gelir. Birim kodu istemci tarafından set edilmek istenirse bu alan kullanılmalıdır. Prefix alanı set edilirse, bilet numarasında bu prefix kullanılır. Set edilmezse sistemde istemci için tanımlanmış olan, varsayılan birim kodu (prefix) kullanılır.

Not: İstemci’nin Prefix alanında belirteceği 3 haneli değerin Turkcell e-Şirket sisteminde tanımlı olma zorunluluğu vardır. Turkcell e-Şirket sisteminde tanımlı olmayan bir prefix kullanılamaz.

Servis input parametreleri 2- Etkinlik bilgileri (EventTicket);

Etkinlik bileti tipindeki biletlere özgü oaln EventTicket tipindeki alanlardır. EventTicket tipinin sahip olduğu alanlar şu şekildedir;

Eventticket: EventDate

Etkinlik tarihini ifade eder. Zorunlu alandır.

EventTicket: LocationCityCode

Etkinliğin yapılacağı şehrin kodu (plakası)’nu ifade eder.

EventTicket: LocationMunicipality

Etkinliğin tertip eden bir belediyeyse, belediye adını ifade eder.

EventTicket: LocationDecription

Varsa etkinliğin açıklaması için kullanılır.

EventTicket: EventOrganizer

Etkiniği düzenleyenin tckn/vkn bilgisini ifade eder.

Servis input parametreleri 3- Diğer vergiler (Tax[ ]);

KDV dışındaki vergileri belirtmek için kullanılan Tax tipindeki listedir. Bu liste zorunlu alan değildir. Tax tipinin alanları şu şekildedir;

TaxCode

Vergi kodunu ifade eder. Zorunlu alandır. (Diğer vergiler listesine kayıt eklendiği takdirde.)

TaxName

Vergi adını ifade eder. Zorunlu alandır. (Diğer vergiler listesine kayıt eklendiği takdirde.)

TaxAmount

Vergi tutarını ifade eder. Zorunlu alandır. (Diğer vergiler listesine kayıt eklendiği takdirde.)

TaxRate

Vergi oranını ifade eder. Zorunlu alandır. (Diğer vergiler listesine kayıt eklendiği takdirde.)

Servis output parametreleri

Servis http tabanlı bir rest servisidir. Tüm servis çağrılarının neticesinde bir HttpStatusCode response olarak döner.

Muhtemel HttpStatusCode’ları ve anlamları şu şekiledir;

200 - Başarılı. (Oluşan biletin tüm bilgileri döner)

400 - İşlem sırasında bir hata meydana geldi. (Hata detayı açıklama olarak döner)

Örnek postman response’u ekran görüntüsü

SaveTicket Servisi Request Model;

 public class TicketModel
 {
    public long Id { get; set; }

    public string TicketNumber { get; set; }

    public string NameSurname { get; set; }

    public string VknTckn { get; set; }

    public string TaxPayer { get; set; }

    public string TaxPayerVknTckn { get; set; }

    public DateTime ExecutionDate { get; set; }

    public int? PaymentType { get; set; }

    public decimal? TotalAmount { get; set; }

    public decimal? PayableAmount { get; set; }

    public decimal? KdvAmount { get; set; }

    public bool UseManuelTicketNumber { get; set; }

    public string LocalReferenceId { get; set; }

    public bool CheckLocalReferenceId { get; set; }

    public string Prefix { get; set; }

    public List<TaxModel> Tax { get; set; }

    public EventTicketModel EventTicket { get; set; }
 }

public class EventTicketModel
{
    public DateTime EventDate { get; set; }

    public string LocationCityCode { get; set; }

    public string EventOrganizer { get; set; }

    public string LocationMunicipality { get; set; }

    public string LocationDecription { get; set; }
}

public class TaxModel
{
    public long TicketId { get; set; }

    public string TaxCode { get; set; }

    public string TaxName { get; set; }

    public decimal TaxAmount { get; set; }

    public decimal TaxRate { get; set; }
}

CancelTicket

Service Endpoint : https://ebiletservicetest.isim360.com/v1/tickets/cancelticket

Bilet iptali için kullanılacak servistir. Servis ile her seferinde tek e-bilet iptali yapılabilir.

Örnek Postman request’, ekran görüntüsü ve ekran görüntüsündeki alanların açıklamaları aşağıda verilmiştir;

Servis input parametreleri

CancelDate

Biletin iptal edilme tarihidir. Zorunlu alandır.

TicketId

Biletin Turkcell e-Şirket tarafındaki Unique Id’sini ifade eder. SaveTicket servisinin response’unda bu ticket id değeri istemciye dönülmektedir. Bilet kayıt işlemi sonrasında dönen bu değer, istemci tarafından saklanmalı ve bilet iptali için kullanılmalıdır.

Servis output parametreleri

Servis http tabanlı bir rest servisidir. Tüm servis çağrılarının neticesinde bir HttpStatusCode response olarak döner.

Muhtemel HttpStatusCode’ları ve anlamları şu şekiledir;

200 - Başarılı. (İptal edilen biletin id si ve iptal tarihi döner)

404 - Verilen id için sistemde kayıtlı bir bilet bulunamadı.

400 - İşlem sırasında bir hata meydana geldi. (Hata detayı açıklama olarak döner)

Örnek Postman response’u ekran görüntüsü;

CancelTicket Servisi Request Model;

public class CancelledTicketModel
{
    public long TicketId { get; set; }

    public DateTime CancelDate { get; set; }
}

GetTicket

Service Endpoint : https://ebiletservicetest.isim360.com/v1/eventtickets/{id}

Bilet bilgisi almak için kullanılacak servistir. Servis ile her seferinde tek e-bilet bilgisi alınabilir.

Örnek Postman request’i ekran görüntüsü

Örnek Postman response’u ekran görüntüsü

GetTicketPdf(Ziplenmiş Pdf olarak)

Service Endpoint : https://ebiletservicetest.isim360.com/v1/ticketpdf/{id}

İmzalanmış ve pdf olarak hazır hale gelen biletleri base64 string formatında pdf file olarak almak için kullanılacak servistir. Servisten dönen base64string değeri ziplenmiş pdf dosyasını içerdiğinden, pdf’e erişmek için öncelikle zip’ten çıkarılması gerekmektedir. Servis ile her seferinde tek e-bilet pdf’i alınabilir.

Örnek Postman request’i ekran görüntüsü

Örnek Postman response’u ekran görüntüsü