KolaySoft e-Fatura Entegrasyonu

01 Aug 2024
7 Minutes to read

Dark
Light

KolaySoft e-Fatura Entegrasyonu

Updated on 01 Aug 2024
7 Minutes to read

Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

KolaySoft e-Fatura Entegrasyonu

Servis Adı	InvoiceWS
Endpoint Adresi	https://servis.kolayentegrasyon.net/InvoiceService/InvoiceWS
WSDL Adresi	https://servis.kolayentegrasyon.net/InvoiceService/InvoiceWS?wsdl
Açıklama	Mükellef tarafından oluşturulan UBL XML formatındaki fatura ve uygulama yanıtlarının entegratöre iletildiği servistir. Metot açıklamaları aşağıda yer almaktadır.

KolaySoft e-fatura servisinde gelen faturaları PaperWork platformuna çekmek için kullanılacak bir fonksiyon vardır. Bu fonksiyon, QueryInboxDocumentWithDocumentDate’dir. Eşleştirilecek alan sayısı tahmini 25 adettir.

QueryInboxDocumentWithReceivedDate

Gelen e-Faturaları çekmek için flag değeri ile filtrelenerek aynı faturayı ikinci kez almamak için kullanılacak fonksiyondur. Mükellefin gelen kutusunda, verilen tarih aralığında alınan fatura ve uygulama yanıtlarının durumunu sistem tarafından alınma tarihine göre sorgulamak amacıyla kullanılır.

Parametreler

Tipi	Adı	Açıklama
String	startDate	Dokümanın düzenlenme tarihine göre sorgulanacak faturaların sorgu başlangıç tarihini tutar.
String	endDate	Dokümanın düzenlenme tarihine göre sorgulanacak faturaların sorgu bitiş tarihini tutar.
String	documentType	Dokuman türünün fatura ya da uygulama yanıtı olup olmadığını belirtir. {1,2} değerlerinden birini alır. [1:Fatura, 2:Uygulama yanıtı]
String	queried	Alınan dokumanın durumunun entegratörden daha önce sorgulanıp sorgulanmadığını belirten değişkendir. {“YES”,”NO”,”ALL”} değerlerinden birini alır.
String	withXML	Sorgu sonucunda döndürülecekse dokumanın XML, PDF veya HTML içeriğinin istenilip istenilmediğin belirtildiği parametredir. {“XML”, “PDF”, “HTML”, ”NONE”} değerleri alır. “NONE” herhangi bir içerik döndürmez, diğer seçeneklerde ise içeriğin bayt değerine sorgu sonucunda dönen DocumentQueryResponse nesnesi içerisindeki documents listesinde yer alan ResponseDocument nesnelerindeki ‘content’ alanından ulaşılabilir. Bu alanın “NONE” olmadığı durumlarda dönen dokuman sayısı performans açısından 20 ile sınırlandırılır.
String	takenFromEntegrator	Entegratörden sorgulanan dökümanın lokalde kaydedilip kaydedilmediğini tutar. {“YES”,”NO”,”ALL”} değerlerinden birini alır.
String	minRecordId	Sorgu sonucunda döndürülecek dokümanların en düşük numaralı kayıt numarasını tutar.

Dönüş değeri DocumentQueryResponse nesnesidir.

DocumentQueryResponse Sınıfı

Sınıf Adı	Açıklaması
queryState	Sorgu sonucunda hata oluşup oluşmadığına dair kod bilgisini tutar.
stateExplanation	Sorgu sonucunda hata oluşup oluşmadığına dair açıklama bilgisini tutar.
maxRecordIdinList	Dokuman listesi içerisindeki en yüksek kayıt numaralı dokumanın kayıt numarasını tutar.
documentsCount	Sorgu sonucunda dönen dokuman sayısını sayısını taşır.
documents	Sorgu sonucunda dönen dokümanları ResponseDocument listesi içinde tutar.

ResponseDocument Sınıfı

Sınıf Adı	Açıklaması
document_uuid	Dokümanın UUID bilgisini taşır.
document_id	Fatura için fatura numarası, uygulama yanıtı için ise UUID formatında eşsiz ID değerini taşır.
envelope_uuid	Dokümanların zarflanmasının akabinde oluşturulan zarfın UUID bilgisini taşır.
document_profile	Dokümana ait senaryo türü bilgisini taşır. TEMELFATURA, TICARIFATURA gibi.
system_creation_time	Dokümanın entegratör tarafından alındığı zamanı tutar.
document_issue_date	Dokümanın düzenlenme tarihini tutar.
source_id	Dokümanı gönderenin VKN ya da TCKN bilgisini taşır.
source_urn	Doküman göndericisinin adres etiketini taşır.
source_title	Dokümanı gönderenin ünvan bilgisini taşır.
destination_id	Doküman alıcısının VKN ya da TCKN bilgisini taşır.
destination_urn	Doküman alıcısının adres etiketini taşır.
state_code	Doküman durumunun kod değerini taşır.
state_explanation	Doküman durumunun açıklama değerini taşır.
content_type	Doküman içeriğinin türünü taşır.
document_content	Doküman içeriğini byte dizisi olarak taşır.
currency_code	Doküman tutarının para birimi değerini tutar. (Örn: TRY)
cause	Dokümanın işlenmesi sırasında bir hata oluşmuşsa, hata nedeni bu alanla geri dönülür.
invoice_total	Dokümanın toplam tutarını taşır.
emailSent	Kullanılmıyor
emailSentDate	Kullanılmıyor
cancelled	Kullanılmıyor
cancel_date	Kullanılmıyor
reference_document_uuid	Mükellefe gelen uygulama yanıtlarında cevap verilen dokümana ait UUID bilgisini taşır.
response_document_uuid	Mükellef tarafından gönderilen uygulama yanıtlarında cevap verilen dokümana ait UUID bilgisini taşır.
response_code	Gönderilen uygulama yanıtlarının RED ya da KABUL bilgisini tutar. {KABUL, RED} değerlerinden birini alır.
response_validation_state	Gönderilen uygulama yanıtlarının GİB yönergelerine göre geçerlilik durumunu taşır.
response_received_date	Gönderilen veya gelen faturaya cevap alınmışsa/verilmişse, bu cevabın alındığı/gönderildiği tarihi taşır.
gtb_reference_no	Sorgulanan ihracat faturalarına ait 23 haneli GTB Referans Numarasını taşır.
gtb_gcb_tescil_no	Sorgulanan ihracat faturalarına ait GÇB Tescil Numarasını taşır.
gtb_fiili_ihracat_tarihi	Sorgulanan ihracat faturalarına ait Fiili İhracat Tarihini taşır.
document_type_code	Faturanın türünü (SATIS, IADE, TEVKIFAT, OZELMATRAH, ISTISNA, IHRACKAYITLI, SGK ) taşır.
notes	Doküman içeriğindeki notları string listesi halinde taşır.
despatchInfo	Doküman içeriğindeki irsaliye bilgilerini taşır.
orderInfo	Doküman içeriğindeki sipariş bilgilerini taşır.
taxInfo	Doküman içeriğindeki vergi bilgilerini taşır.
taxInclusiveAmount	Faturaya ait vergiler dahil toplam fiyatı taşır.
taxExlusiveAmount	Faturaya ait vergisiz toplam fiyatı taşır.
allowanceTotalAmount	Faturaya ait vergisiz toplam fiyatı taşır.
taxAmount0015	Faturaya ait toplam KDV bilgisini taşır.
lineExtensionAmount	Faturaya ait ürün/hizmet kalemleri toplam fiyatını taşır.
supplierPersonName	Göndericinin özel kişi olması halinde kişi adı bilgisini taşır.
supplierPersonMiddleName	Göndericinin özel kişi olması halinde kişi orta adı bilgisini taşır.
supplierPersonFamilyName	Göndericinin özel kişi olması halinde kişi orta soyadı bilgisini taşır.
customerPersonName	Alıcının özel kişi olması halinde kişi adı bilgisini taşır.
customerPersonMiddleName	Alıcının özel kişi olması halinde kişi orta adı bilgisini taşır.
customerPersonFamilyName	Alıcının özel kişi olması halinde kişi soyadı bilgisini taşır.
is_read	Dokümana ait okundu bilgisidir. {0,1} değerlerinden birini alır.
is_archieved	Dokümana ait arşivlendi bilgisidir. {0,1} değerlerinden birini alır.
is_accounted	Dokümana ait muhasebeleştirildi bilgisidir. {0,1} değerlerinden birini alır.
is_transferred	Dokümana ait aktarıldı bilgisidir. {0,1} değerlerinden birini alır.
is_printed	Dokümana ait yazdırıldı bilgisidir. {0,1} değerlerinden birini alır.
local_id	İstemci sisteminde dokümana karşılık gelen kayıt numarası bilgisidir. Bu alan belge gönderim esnasında belirlenir. Gönderilmesi zorunlu değildir.
sendingType	Kullanılmıyor
buyer_customer_party_name	Kullanılmıyor
buyer_customer_person_name	Kullanılmıyor
buyer_customer_person_familyname	Kullanılmıyor

Bilgi

Yukarıda giriş ve çıkış parametreleri verilen QueryInboxDocumentWithReceivedDate fonksiyonu ile ilgili firmaya ait e-faturaların çekilmesi gerekmektedir.

QueryInboxDocumentWithReceivedDate Giriş Parametreleri

Parametre Adı	Örnek veri
startDate
endDate
documentType
queried
withXML
minRecordId
takenFromEntegrator

QueryInboxDocumentWithReceivedDate Çıkış Parametreleri

Parametre Adı	Örnek veri
DocumentQueryResponse Nesnesi
queryState
stateExplanation
maxRecordIdinList
documentsCount
documents

Bilgilendirme

Metodun tanımlı işlerinde her gün 06:00 ile 14:00 arasında çalışacak olan kolaysoft e-fatura servisi ile günde iki kez çalışarak gelen tüm faturaları çekmesi gerekmektedir.

QueryInboxDocument

Çekilen her bir faturanın bilgilerine ulaşılır. Alınan fatura ve uygulama yanıtlarının durumunu sorgulamak amacıyla kullanılır.

Parametreler

Tipi	Parametre Adı	Açıklama
String	paramType	Dokumanın sorgulanacağı parametre tipini tutar. Fatura UUID’si, Fatura Numarası veya Zarf UUID’si bilgilerinden herhangi birisi ile sorgulama yapılabilir. {“Document_UUID”,”Document_ID”,”Envelope_UUID”} değerlerinden birini alır.
String	parameter	paramType ile belirtilen parametrenin değerini tutar.
String	withXML	Sorgu sonucunda döndürülecekse dokumanın XML, PDF veya HTML içeriğinin istenilip istenilmediğin belirtildiği parametredir. {“XML”, “PDF”, “HTML”, ”NONE”} değerleri alır. “NONE” herhangi bir içerik döndürmez, diğer seçeneklerde ise içeriğin bayt değerine sorgu sonucunda dönen DocumentQueryResponse nesnesi içerisindeki documents listesinde yer alan ResponseDocument nesnelerindeki ‘content’ alanından ulaşılabilir. Bu alanın “NONE” olmadığı durumlarda dönen Doküman sayısı performans açısından 20 ile sınırlandırılır.

Dönüş Değeri

DocumentQueryResponse nesnesi döndürür. Sorgunun sonucu ve açıklaması bu sınıf içerisindeki queryState ve stateExplanation alanları ile kontrol edilebilir. Eğer sorgu sonucunda doküman(lar) bulunursa documentCount alanı bulunan Doküman sayısını gösterir. ResponseDocument listesi tipindeki documents alanından ise her bir Doküman ile ilgili detaylı bilgiye ulaşılabilir.

Aşağıda giriş ve çıkış parametreleri verilen QueryInboxDocument fonksiyonu ile ilgili firmaya ait faturanın txt formatı halinde response döner.

Giriş Parametreleri

Parametre Adı	Örnek veri
paramType
parameter
withXML

Çıkış Parametreleri

Parametre Adı	Örnek veri
DocumentQueryResponse Nesnesi
queryState
stateExplanation
maxRecordIdinList
documentsCount
documents

setDocumentFlag

Çekilen her bir faturanın tekrar tekrar içeriye alınmaması için ilgili faturaya flag atacağımız fonksiyondur. Dokümana ait belli işaretlemelerin yapılmasını sağlayan metottur.

Parametreler

Tipi	Parametre Adı	Açıklama
FlagSetter	flagSetter	EntResponse nesnesi döndürür. İşlem sonucu bu nesneye ait ‘code (kod)’, ‘explanation (açıklama)’ alanlarında yer alır.

Dönüş Değeri

EntResponse nesnesi döndürür. İşlem sonucu bu nesneye ait ‘code (kod)’, ‘explanation (açıklama)’ alanlarında yer alır

flagSetter Sınıfı

Sınıf Adı	Açıklaması
document_direction	Dokümanın gelen veya giden kutusunda aranmasını sağlar. {‘GIDEN’, ’GELEN’} değerlerinden birini alır.
flag_name	Doküman üzerinde yapılacak işaretleme işleminin türünü tutar. {‘ARSIVLENDI’,’OKUNDU’,’MUHASEBELESTIRILDI’,’AKTARILDI’,’YAZDIRILDI’} değerlerinden birini almalıdır.
flag_value	Dokümanın işaretleme değerini tutar. {0,1} değerlerinden birini almalıdır.
document_uuid	İşaretlenecek dokümanın UUID sini taşır.

entResponse Sınıfı

Sınıf Adı	Açıklaması
documentUUID	Dokümanın UUID bilgisini taşır.
code	İşlem sonucuna ait kod değerini taşır.
explanation	İşlem sonucuna ait açıklama değerini taşır.
cause	İşlem sonucunda hata oluşmuşsa hatanın nedenini taşır.

e-Fatura Servisi Giden Fatura

KolaySoft e-Fatura servisinde faturaları çekmek için kullanılacak fonksiyon QueryOutboxDocumentWithDocumentDate’dir.

QueryOutboxDocumentWithReceivedDate

Giden e-Faturaları çekmek için flag değeri ile filtrelenerek aynı faturayı 2.kez almamak için kullanılacak fonksiyondur. Mükellefin giden kutusunda verilen tarih aralığında gönderilen fatura ve uygulama yanıtlarının durumunu sistem tarafından alınma tarihine göre sorgulamak amacıyla kullanılır.

Parametreler

Tipi	Parametre Adı	Açıklama
String	startDate	Dokümanın düzenlenme tarihine göre sorgulanacak faturaların sorgu başlangıç tarihini tutar.
String	endDate	Dokümanın düzenlenme tarihine göre sorgulanacak faturaların sorgu bitiş tarihini tutar.
String	documentType	Doküman türünün fatura ya da uygulama yanıtı olup olmadığını belirtir. {1,2} değerlerinden birini alır. [1:Fatura, 2:Uygulama yanıtı]
String	queried	Gönderilen dokumanın durumunun entegratörden daha önce sorgulanıp sorgulanmadığını belirten değişkendir. {“YES”,”NO”,”ALL”} değerlerinden birini alır.
String	withXML	Sorgu sonucunda döndürülecekse dokumanın XML, PDF veya HTML içeriğinin istenilip istenilmediğin belirtildiği parametredir. {“XML”, “PDF”, “HTML”, ”NONE”} değerleri alır. “NONE” herhangi bir içerik döndürmez, diğer seçeneklerde ise içeriğin bayt değerine sorgu sonucunda dönen DocumentQueryResponse nesnesi içerisindeki documents listesinde yer alan ResponseDocument nesnelerindeki ‘content’ alanından ulaşılabilir. Bu alanın “NONE” olmadığı durumlarda dönen Doküman sayısı performans açısından 20 ile sınırlandırılır.
String	minRecordId	Sorgu sonucunda döndürülecek dokümanların en düşük numaralı kayıt numarasını tutar.

Aşağıda giriş ve çıkış parametreleri verilen QueryOutboxDocumentWithReceivedDate fonksiyonu ile ilgili firmaya ait e-faturaların çekilmesi gerekmektedir.

Giriş Parametreleri

Parametre Adı	Örnek veri
startDate
endDate
documentType
queried
withXML
minRecordId
takenFromEntegrator

Çıkış Parametreleri

Parametre Adı	Örnek veri
DocumentQueryResponse Nesnesi
queryState
stateExplanation
maxRecordIdinList
documentsCount
documents

Bilgilendirme

Metotun tanımlı işlerinde her gün 06:00 ile 14:00 arasında çalışacak olan kolaysoft e-Fatura servisi ile günde iki kez çalışarak gelen tüm faturaları çekmesi gerekmektedir.

QueryOutboxDocument

Gönderilen her bir faturanın bilgilerine ulaşılır. Gönderilen fatura ve uygulama yanıtlarının durumunu sorgulamak amacıyla kullanılır.

Parametreler

Tipi	Parametre Adı	Açıklama
String	paramType	Dokumanın sorgulanacağı parametre tipini tutar. Fatura UUID’si, Fatura Numarası veya Zarf UUID’si bilgilerinden herhangi birisi ile sorgulama yapılabilir. {“Document_UUID”,”Document_ID”,”Envelope_UUID”} değerlerinden birini alır.
String	parameter	paramType ile belirtilen parametrenin değerini tutar.
String	withXML	Sorgu sonucunda döndürülecekse dokumanın XML, PDF veya HTML içeriğinin istenilip istenilmediğin belirtildiği parametredir. {“XML”, “PDF”, “HTML”, ”NONE”} değerleri alır. “NONE” herhangi bir içerik döndürmez, diğer seçeneklerde ise içeriğin bayt değerine sorgu sonucunda dönen DocumentQueryResponse nesnesi içerisindeki documents listesinde yer alan ResponseDocument nesnelerindeki ‘content’ alanından ulaşılabilir. Bu alanın “NONE” olmadığı durumlarda dönen Doküman sayısı performans açısından 20 ile sınırlandırılır.

Dönüş Değeri

DocumentQueryResponse nesnesi döndürür. Sorgunun sonucu ve açıklaması bu sınıf içerisindeki queryState ve stateExplanation alanları ile kontrol edilebilir. Eğer sorgu sonucunda dokuman(lar) bulunursa documentCount alanı bulunan Doküman sayısını gösterir. ResponseDocument listesi tipindeki documents alanından ise her bir Doküman ile ilgili detaylı bilgiye ulaşılabilir.

Giriş Parametreleri

Parametre Adı	Örnek veri
paramType
parameter
withXML

Çıkış Parametreleri

Parametre Adı	Örnek veri
DocumentQueryResponse Nesnesi
queryState
stateExplanation
maxRecordIdinList
documentsCount
documents

setDocumentFlag

Gönderilen her bir faturanın tekrar tekrar içeriye alınmaması için ilgili faturaya flag atacağımız fonksiyondur. Dokümana ait belli işaretlemelerin yapılmasını sağlayan metottur.

Parametreler

Tipi	Parametre Adı	Açıklama
FlagSetter	flagSetter	EntResponse nesnesi döndürür. İşlem sonucu bu nesneye ait ‘code (kod)’, ‘explanation (açıklama)’ alanlarında yer alır.

Dönüş Değeri

EntResponse nesnesi döndürür. İşlem sonucu bu nesneye ait ‘code (kod)’, ‘explanation (açıklama)’ alanlarında yer alır

flagSetter Sınıfı

Sınıf Adı	Açıklaması
document_direction	Dokümanın gelen veya giden kutusunda aranmasını sağlar. {‘GIDEN’, ’GELEN’} değerlerinden birini alır.
flag_name	Doküman üzerinde yapılacak işaretleme işleminin türünü tutar. {‘ARSIVLENDI’,’OKUNDU’,’MUHASEBELESTIRILDI’,’AKTARILDI’,’YAZDIRILDI’} değerlerinden birini almalıdır.
flag_value	Dokümanın işaretleme değerini tutar. {0,1} değerlerinden birini almalıdır.
document_uuid	İşaretlenecek dokümanın UUID bilgisini taşır.

entResponse Sınıfı

Sınıf Adı	Açıklaması
documentUUID	Dokümanın UUID bilgisini taşır.
code	İşlem sonucuna ait kod değerini taşır.
explanation	İşlem sonucuna ait açıklama değerini taşır.
cause	İşlem sonucunda hata oluşmuşsa hatanın nedenini taşır.

Giden e-Faturalar için PaperWork de UBL Listesine Kayıt Atma

Her bir fatura için Fatura NO, ETTN NO, Gönderim Tarihi gibi toplam da beş alan için SQL üzerinden bir tablo oluşturup buraya kayıt atacaktır. İçeriye alınan faturalar ile ilgili takibi kolaylaştırmak adına.

E-Arşiv Servisi

Servis Adı	InvoiceWS
Endpoint Adresi	https://servis.kolayentegrasyon.net/InvoiceService/InvoiceWS
WSDL Adresi	https://servis.kolayentegrasyon.net/InvoiceService/InvoiceWS?wsdl
Açıklama	Mükellef tarafından oluşturulan UBL XML formatındaki fatura ve uygulama yanıtlarının entegratöre iletildiği servistir. Metot açıklamaları aşağıda yer almaktadır.

What's Next

UyumSoft e-Fatura Entegrasyonu

Table of contents