e-İrsaliye Entegrasyon Kılavuzu

Servis test çağrıları için https://eirsaliyeservicetest.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-İrsaliye 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ü;

İrsaliye Gönderme - Post

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch

e-İrsaliye kayıt servisidir. Servis ile her seferinde tek e-İrsaliye 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 **

DespatchAdvice

Zorunlu alandır. UBL in base63 string karşılığını içermelidir.

LocalReferenceId

Opsiyonel alandır.

TargetAlias

Opsiyonel alandır.İrsaliye kesilen pk bilgisini içermelidir.

Status

Zorunlu alandır. 0(Taslak) - 20(Kuyrukta) değerlerinden birini alabilir.

UseManualDespatchAdviceId

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

Prefix

Opsiyonel alandır. 16 haneli irsaliye 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, irsaliye 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 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 irsaliyein 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ü

Not: Servis response da şuan için 4 alan vardır. ilerleyen versiyonlarda ihtiyaçların netleşmesiyle yeni alanlar eklenecektir.

Post Servis Request Model;

     public string DespatchAdvice { get; set; }

     public string LocalReferenceId { get; set; }

     public string Prefix { get; set; }

     public bool UseManualDespatchAdviceId { get; set; }

     public bool CheckLocalReferenceId { get; set; }

     public string TargetAlias { get; set; }

     public int Status { get; set; }

İrsaliye Güncelleme - Put

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch

Taslak durumundaki irsaliye bilgisini güncellemek için kullanılacak servistir. Servis ile her seferinde tek e-İrsaliye bilgisi güncellenebilir.

Servis request modeli Post metodu ile aynıdır.

İrsaliye Yanıtı Gönderme - Post

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt

e-İrsaliye yanıt servisidir. Servis ile her seferinde tek e-İrsaliye yanıt 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

ReceiptAdvice

Zorunlu alandır. UBL in base63 string karşılığını içermelidir.

Status

0(Taslak) - 20(Kuyrukta) değerlerinden birini alabilir.

UseManualDespatchAdviceId

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

Prefix

Opsiyonel alandır. 16 haneli irsaliye 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, irsaliye 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 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 irsaliyein tüm bilgileri döner)

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

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

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

Put Servis Request Model;

     public string ReceiptAdvice { get; set; }

     public string Prefix { get; set; }

     public bool UseManualReceiptAdviceId { get; set; }

     public int Status { get; set; }

İrsaliye Yanıtı Güncelleme - Put

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt

Taslak durumundaki irsaliye yanıtını güncellemek için kullanılacak servistir. Servis ile her seferinde tek e-İrsaliye yanıtı güncellenebilir.

Servis request modeli Post metodu ile aynıdır.

ARAMA SERVİSLERİ - İRSALİYE

Giden irsaliye listeleme - Search

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch

Listeleme/filtreleme servisidir. Servis çağrısı için Http Post request yapılmalıdır. Servis request olarak json object alır.

Search Servis Request Model;

public class SearchCriteria
{
    public DateTime? StartDate { get; set; }

    public DateTime? EndDate { get; set; }

    public string TargetVknTckn { get; set; }

    public bool EnableSorting { get; set; }

    public string SortingName { get; set; }

    public string SortingDir { get; set; }

    public int PageSize { get; set; }

    public int PageIndex { get; set; }
}

PageIndex, PageSize alanları zorunludur. SortingName alanının default değeri “CreatedName”, SortingDir ‘in ise “desc” dir.

Örnek postman reqeust ve response ekran görüntüsü

Giden irsaliye tek kayıt - Get

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch/{id}

Verilen {id} değerine karşılık gelen giden irsaliye bilgisini döner. Gelen irsaliye için endpoint teki outbox kısmı inbox’ile yer değiştirilir.

Giden irsaliye tek kayıt - getubl

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch/getubl/{id}

Verilen {id} değerine karşılık gelen giden irsaliye nin UBL ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.

Giden irsaliye tek kayıt - getpreviewhtml

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch/getpreviewhtml/{id}

Verilen {id} değerine karşılık gelen giden irsaliye html ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.

Giden irsaliye tek kayıt - getpreviewpdf

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxdespatch/getpreviewhpdf/{id}

Verilen {id} değerine karşılık gelen giden irsaliye pdf ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.

ARAMA SERVİSLERİ - İRSALİYE YANITI

Giden irsaliye yanıtı listeleme - Search

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt

Listeleme / filtreleme servisidir. Servis çağrısı için Http Post request yapılmalıdır. Servis request olarak json object alır.

Search Servis Request Model;

public class SearchCriteria
{
    public DateTime? StartDate { get; set; }

    public DateTime? EndDate { get; set; }

    public string TargetVknTckn { get; set; }

    public bool EnableSorting { get; set; }

    public string SortingName { get; set; }

    public string SortingDir { get; set; }

    public int PageSize { get; set; }

    public int PageIndex { get; set; }
}

PageIndex, PageSize alanları zorunludur. SortingName alanının default değeri “CreatedName”, SortingDir ‘in ise “desc” dir.

Örnek postman reqeust ve response ekran görüntüsü

Giden irsaliye yanıtı tek kayıt - Get

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt/{id}

Verilen {id} değerine karşılık gelen giden irsaliye bilgisini döner. Gelen irsaliye için endpoint teki outbox kısmı inbox’ile yer değiştirilir.

Giden irsaliye yanıtı tek kayıt - getubl

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt/getubl/{id}

Verilen {id} değerine karşılık gelen giden irsaliye nin UBL ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.

Giden irsaliye yanıtı tek kayıt - getpreviewhtml

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt/getpreviewhtml/{id}

Verilen {id} değerine karşılık gelen giden irsaliye html ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.

Giden irsaliye yanıtı tek kayıt - getpreviewpdf

Service Endpoint : https://eirsaliyeservicetest.isim360.com/v1/outboxreceipt/getpreviewpdf/{id}

Verilen {id} değerine karşılık gelen giden irsaliye pdf ini zipli base64 formatında döner. Gelen irsaliye için endpoint teki outbox kısmı inbox ile yer değiştirilir.