QNB eSolutions Elektronik Arşiv Yönetim Sistemi e-Arşiv Çözümü QNB eSolutions e-Arşiv Revizyon Tablosu EarsivWebService Güncel Revizyon Yayımlanma Tarihi Açıklama 1.0 18.10.2014 İlk Revizyon 1.1 25.12.2014 Fatura Numarası Üretme, Fatura Oluşturma, Fatura Verisi Sorgulama servisleri yeniden düzenlendi. Fatura Saklama, Fatura İmzalama, Fatura Görüntüsü Sorgulama, Fatura Postalama servisleri kaldırıldı. 1.2 06.02.2015 Fatura Sorgulama servis parametreleri düzenlendi. 1.3 25.03.2015 aliciEpostaEkleSilGuncelle, ePostaGonder, ePostaDurumSorgula, faturaIptalEt metotları eklendi. Sonuç Kodları Listesi eklendi. 1.4 19.06.2015 Entegrasyon servisleri bölümünde Holder tipi açıklaması eklendi. resultExtra alanı açıklaması detaylandırıldı. Fatura Numarası Üretme servisi açıklamasında output parametresi Holder tipi olarak açıklandı. Fatura Oluşturma servisi açıklamasında output parametresi Holder tipi olarak açıklandı. Fatura Sorgulama servisi açıklamasında output parametresi Holder tipi olarak açıklandı. 1.5 14.02.2016 Yazım hataları düzeltildi. Hata kodları / mesajları listesi güncellendi Mevcut metotlara seçimli alanlar eklendi. Yeni metotlar eklendi. Önemli konulara ilişkin sarı işaretlenmiş not kutuları eklendi. 1.6 28.03.2016 Rapor Bölümleri Oluşturma WS metodu eklendi. 1.7 31.03.2016 Rapor Bölümü Silme WS metodu eklendi. Rapor Bölümü Listesi Detaylı Sorgula metodu eklendi. Rapor Bölüm Bilgisi Al metodu eklendi. 1.8 29.04.2016 raporBolumRaporNoGuncelleImzala metodu eklendi. 1.9 06.05.2016 faturaIptaliKaldir metodu eklendi. 1.10 11.05.2016 rapordaFaturaSorgula metodu eklendi. 1.11 10.11.2016 yapilandirmaAyarlariAl metodu eklendi. 1.12 21.12.2016 servisSaglayicidanEpostaDurumSorgula metodu eklendi. 1.13 28.12.2016 servisSaglayicidanEpostaDurumSorgula açıklamasında düzenleme yapıldı. 1.14 30.01.2017 faturaTaslakOlustur faturaTaslaktanOlustur faturaTaslakSorgula faturaTaslakSil faturaTaslakOnizleme metodları eklendi 1.15 21.09.2017 smsDurumSorgula dönüş parametreleri güncellendi. 1.16 29.05.2018 FaturaSorgulaya saklamadaki faturaları sorgulama özelliği eklendi. FaturaListeSorgulamaya fatura kaynağına göre filtreleme özelliği eklendi. FaturaDTO ya erp kodu eklendi. 1.17 01.07.2018 okcRaporKaydet eklendi 1.18 01.08.2018 FaturaListeSorgulaPortal metodu eklendi. FaturaZipiAl metodu eklendi. 1.19 02.08.2018 FaturaTaslakOnizleme metoduna donenBelgeFormati input alanı eklendi. 1.20 16.10.2018 okcRaporOlusturGonder eklendi. okcRaporBolumAl eklendi. 1.21 18.02.2019 FaturaListeSorgula metoduna creationTime a göre filtreleme özelliği kazandırıldı. FaturaListeSorgula metodunun cevap verisine creationTime eklendi. SiralamaAlani input alanında creationTime ‘da yollanabilir hale getirildi. 1.23 14.05.2019 faturaOlustur input alanına taslagaYonlendir eklendi. 1.24 10.06.2019 efaturaKullanicisiKontrol metodu eklendi. 1.25 25.06.2019 faturaListeSorgula input alanına tasinanFaturalar eklendi. 1.26 27.06.2019 faturaZipAl metoduna donenBelgeFormati, tasinanFaturalar parametreleri eklendi 1.27 07.08.2019 faturaOluştur metodu input alanına “taslagaYonlendir”, “yerelFaturaNo” eklendi. İçindekiler Revizyon Tablosu 1 EarsivWebService 1 Giriş 5 Amaç ve Kapsam 5 Çözüm Modeli 6 Çözüm Mimarisi 7 Toplu İşlem Ara Yüzü ile Entegrasyon 9 WEB Servisleri ile Entegrasyon 10 Kimlik Doğrulama ve Yetkilendirme Yöntemleri 10 Entegrasyon Servisleri 13 Servis Geri Dönüş Değeri 13 Fatura Numarası Üretme 17 Fatura Oluşturma 19 Fatura Sorgulama 23 Fatura İptal Etme 26 Fatura İptali Kaldırma 28 Fatura Taslak Oluşturma 29 Fatura Taslaktan Oluşturma 32 Fatura Taslak Silme 34 Fatura Taslak Önizleme 35 Fatura Taslak Sorgulama 38 E-Posta Gönderme 40 Alıcı E-Postası Ekleme / Silme / Güncelleme 42 E-Posta Durumu Sorgulama 44 E-Posta Servis Sağlayıcı Üzerinden Durumu Sorgulama 46 Ökc Rapor Kaydetme 48 Ökc Rapor Oluşturma ve Gönderme 51 Ökc Rapor Bölümü İndirme 53 SMS Gönderme 55 SMS Durumu Sorgulama 57 Rapor Durum Sorgulama 60 Rapor Bölüm Listesi Sorgulama 62 Rapor Bölüm Sorgulama 64 Rapor Bölümü İndirme 69 Rapor Bölümü Silme 73 Rapor Bölümü Yeniden Numara Verip İmzalama 74 Rapor Gönderme 75 Rapor Oluşturma 77 Toplu Fatura Paket Dosyası Gönderme 79 Toplu Fatura Paket Dosyası Sorgulama 82 Toplu Fatura Paket Sorgulama 85 Toplu Fatura Paket Onaylama 88 Kontör Sorgulama 89 Fatura Önizleme 91 e-Fatura Kayıtlı Kullanıcı Listele 95 e-Fatura Kayıtlı Kullanıcısı Sorgulama 96 e-Fatura Kayıtlı Kullanıcısı Tarih ile Sorgulama 96 Fatura Listesi Sorgulama 97 Fatura Listesi Sorgulama Portal 103 Fatura Zipi Alma 108 Yapılandırma Ayarlarını Alma 110 Giriş Amaç ve Kapsam Elektronik arşiv uygulaması, elektronik fatura uygulamasının kapsamı dışında kalan fatura işlemlerinin de elektronik ortama taşınmasını hedefleyen bir uygulama olarak fatura işlem ve kopyalarının tümüyle elektronik ortama taşınması vizyonunun önemli bir ayağıdır. Bu doküman, QNB eSolutions’ın, 30/12/2013 tarih ve 28867 sayılı Resmi Gazetede yayımlanan 433 sıra no’lu tebliğ ile düzenlenen “e-Arşiv Uygulamasına ilişkin usul ve esaslar” kapsamında, mükelleflerin elektronik arşiv uygulaması ihtiyaçlarını karşılamak üzere geliştirdiği yazılım çözümü e-Arşiv’in çözüm modelini ve e-Arşiv uygulama ve servisleri ile entegre olmak isteyen iş ortaklarımızın ihtiyaç duyabilecekleri teknik bilgileri sunmak için hazırlanmıştır. Çözüm Modeli e-Arşiv, eFatura ürün ailesinin bir üyesi olarak, istendiğinde aynı ürün ailesinden başka ürünlerin de eklenebildiği, kimlik doğrulama, yetkilendirme ve yüksek özelleştirilebilirlik özelliklerini barındıran portal ürünü ile beraber gelir. e-Arşiv’in sunduğu işlevler şunlardır. Fatura numarası üretme. e-Arşiv faturası oluşturma ve kaydetme. Faturayı imzalama. Faturayı veri tabanı / depolama alanına arşivleme ve sorgulama. Faturayı ya da faturaya erişmek için kullanılabilecek tekil internet bağlantısını e-posta ile müşteriye iletme. e-Arşiv raporu oluşturma ve mali mühür ile onaylama. Raporu elektronik ortamda Gelir İdaresi Başkanlığı’na iletme. e-Arşiv uygulama ve servislerini temel ve gelişmiş işlevler olmak üzere iki ana gruba ayırmak mümkündür. Temel işlevler, Gelir İdaresi Başkanlığı tarafından yayınlanan tebliğ ve yönetmeliklere uygun elektronik arşiv fonksiyonlarından oluşmuştur. Fatura oluşturma, imzalama, arşivleme, sorgulama, fatura numarası verme, e-mail olarak müşteriye iletme gibi temel fonksiyonları kapsamaktadır. Gelişmiş işlevler ise, yukarıda belirtilen fonksiyonlara ek olarak ileride gündeme gelebilecek değişiklik, ek işlevler, yeni form ve belgeleri de kapsamaktadır. Gelişmiş işlevler, mevcut entegrasyon yöntemlerini değiştirmedikleri için, müşterilerimiz kesinlikle etkilenmeyecektir. Çözüm Mimarisi e-Arşiv’in dış dünya ile iletişim kurduğu 3 ara yüzü vardır: kullanıcı ara yüzü, web servisleri ara yüzü ve toplu işlem ara yüzü. Bu ara yüzler, kullanıcının, e-Arşiv çekirdeğinin gücünden maksimum düzeyde yararlanabilmek için kullanabileceği farklı yöntemleri seçebilmesine olanak sağlar. Kullanıcı ara yüzü, faturaları ve raporları sorgulamak ve görüntülemek gibi kullanıcının ihtiyaç duyabileceği işlevsellikleri barındırır. Web servisleri ara yüzü, e-Arşiv’in başka sistemlerle birlikte kullanılabilmesine olanak sağlamak üzere tasarlanmıştır. Örneğin, fatura kesmek amacıyla kullanmakta olduğu sistemden vaz geçmek istemeyen fakat faturalarını arşivlemek için e-Arşiv’ı tercih eden bir kullanıcı, fatura numarası üretme işlevini de e-Arşiv’in üstlenmesini sağlayabilir. Web servisleri ara yüzü, e-Arşiv’in, farklı ihtiyaçlara göre konfigüre edilebilen, Gelir İdaresi Başkanlığı’nın belirlediği standarda uygun olarak ürettiği fatura numarasını diğer sisteme aktarmasını mümkün kılar. Toplu işlem ara yüzü ise, kasa örneğindeki gibi anlık olarak başka sistemlerle iletişimi gerektirmeyen fakat başka sistemler tarafından üretilmiş faturaların toplu biçimde ve yüksek performansla içe aktarılması ihtiyacını karşılamak üzere tasarlanmış ara yüzdür. e-Arşiv, web uygulamalarında, HTTP protokolünün doğasından kaynaklanan sorunlardan kaçınabilmeyi mümkün kılan teknolojiler kullanılarak geliştirilmiştir. ActiveMQ kuyrukları ile geliştirilen, entegre olduğu dış sistemlerden veri akışının yoğunlaştığı dönemlerde bile istikrarlı ve kararlı şekilde çalışmaya devam etmesini sağlayan yük dengeleme özelliği, HTTP isteklerinin ulaşıldıkları sıra ile işlenmesine olanak sağlamaktadır. Sisteme ulaşan faturaların geldikleri kaynağa göre (mükellef VKN, şube, kasa), Doküman formatı Faturaya numara verilip verilmeyeceği Fatura numarasının serisi Faturanın üretileceği şablon PDF tipi haricindeki fatura tiplerinde not alanına yazıyla tutar eklenip eklenmeyeceği Postalanırken (e-posta ile) faturanın mı yoksa faturanın tekil web adresinin mi postalanacağı Toplu işlemler için otomatik onaylanıp onaylanmayacağı gibi parametreler kullanıcı ara yüzü aracılığıyla ayrı ayrı konfigüre edilebilmektedir. Örneğin bir firmanın kasadan ürettiği faturalar farklı şablonda merkezi veri tabanından ürettiği faturalar farklı şablonda olabilmekte, bir tanesine numara mükellef tarafından verilmişken diğerine özel entegratörün numara vermesi talep edilebilmektedir. Her müşteri için istenilen tüm konfigürasyonlar bir konfigürasyon tablosunda tutularak, gelen işlenmemiş fatura verileri bu konfigürasyona bağlı olarak işlenerek fatura görüntüsüne dönüştürülmektedir. Görüntü hazır sadece imzala ve arşivle A Firması şablonuna göre fatura oluştur, imzala, arşivle. B Firması şablonuna göre fatura oluştur, imzala, arşivle, müşteriye email gönder C Firması kasa şablonuna göre fatura oluştur, imzala, arşivle, görüntüyü kasaya gönder C Firması merkezi VT 2 şablonuna göre numara ver ve fatura oluştur, imzala ve arşivle C Firması merkezi VT 1 şablonuna göre numara ver ve fatura oluştur, imzala ve arşivle Toplu İşlem Ara Yüzü ile Entegrasyon Toplu işlem ara yüzü, sistem tarafından erişilebilen diskler, depolama birimleri, dışsal veri tabanları, ftp sunucuları gibi dışsal veri kaynaklarından erişilen fatura verilerinin toplu olarak sisteme aktarılabilmesi amacıyla geliştirilmiş çeşitli “konektör” uygulama ya da bileşenlerinden oluşmaktadır. Sisteme bu yolla aktarılan veriler de kullanıcı ara yüzü ya da web servisi ara yüzü kullanılarak aktarılan verilerden farklı şekilde işlenmez. e-Arşiv çekirdeğini oluşturan iş mantığı katmanı, ve bu katmana gücünü veren tüm teknolojiler veriye hangi kaynaktan ulaşıldığından bağımsız olarak ve hatta bundan haberdar dahi olmaksızın veriyi aynı mantıkla işlerler. Burada UBL / CSXML / Özel XML / PDF (UBL/XML gömülü) formatında alınan fatura verileri toplu olarak Veri tabanından çekmek, FTP/SFTP ile aktarmak veya Upload etmek suretiyle gerçekleştirilebilir. Geçici bir alana alınan veriler GIB’in Earşiv fatura standartlarına göre XML (UBL) olarak düzenlenerek fatura görüntüsü oluşturulmak üzere Earşiv uygulama yazılımında işlenir. Fatura verileri Merkezi bir veri tabanı veya kasaların bağlı olduğu her şubedeki bölgesel veri tabanları ile entegre olunarak alınabilmektedir. WEB Servisleri ile Entegrasyon Kasadan veya merkezi sistemlerden gerçekleştirilecek anlık fatura üretimi/faturanın elektronik imzalanmasına yönelik entegrasyon yöntemi olarak web servisleri teknolojisi kullanılmaktadır. Web servislerimiz, servisler için yayımlanan WSDL’e uygun bir biçimde geliştirilen, web servis istemci uygulamaları ile çağrılabilir. Canlı ortam WSDL web servis adresleri proje@destek.qnbefinans.com adresine mail atılarak talep edilmelidir. Kimlik Doğrulama ve Yetkilendirme Yöntemleri e-Arşiv web servislerinde güvenli veri alışverişi için HTTPS protokolü kullanılmaktadır. e-Arşiv web servislerinin kullanılabilmesi için aşağıda belirtilen yöntemlerden biri ile kimlik doğrulama yapılması gerekmektedir. Kullanıcı Servisi (UserService) ile Cookie tabanlı erişim Kullanıcı servisi ve cookie yöntemi, kimlik doğrulama için tavsiye edilen yöntemdir. Her metot çağrısında yeniden kimlik doğrulama yapılmadığı için header tabanlı yönteme göre daha iyi performansa sahiptir. Kullanıcı servisi (UserService), kullanıcı adı ve şifre ile sisteme giriş (login) ve sistemden çıkış (logout) metotları sağlamaktadır. Sisteme başarılı giriş sonrası bir oturum çerezi (session cookie) oluşturulmaktadır. Web servis istemcisi, “cookie” kabul edecek şekilde ayarlanarak kullanılmalıdır. Giriş yapıldıktan sonra yapılan tüm web servis çağırımlarında login sırasında oluşturulan oturum çerezi (cookie) gönderilirse, web servis çağrıları başarıyla çalıştırılacaktır. Örnek pseudo code: // Kullandığınız yazılım platformuna göre cookie kabul etme ayarlarını yapmalısınız CookieManager cm = new CookieManager(); cm.setCookiePolicy(CookiePolicy.ACCEPT_ALL); CookieHandler.setDefault(cm); UserService userService = new UserService_Service().getUserServicePort(); userService.wsLogin(userName, password, "tr"); EarsivWebService servis = new EarsivWebService_Service().getEarsivWebServicePort(); // oturum açıldıktan sonra istediğiniz kadar metot çağırısı yapabilirsiniz servis.birServisMetodu(musteriTCNo); servis.baskaBirServisMetodu(musteriTCNo, miktar); //oturum kapatma userService.logout(); wsLogin metodu Bu servis, kimlik doğrulama ile sisteme girişi sağlar ve bir oturum çerezi (session cookie) oluşmasını sağlar. Servisin bir dönüş değeri yoktur. Eğer doğrulama başarılıysa bir oturum açılıp HTTP seviyesinde bir çerez dönülür. Bu çerezin diğer web servis çağırımlarında HTTP seviyesinde sunucuya gönderilmesi gerekmektedir. Parametre Adı Zorunluluk Parametre Türü Açıklama kullaniciAdi Zorunlu Karakter Sistemde kayıtlı kullanıcı adı sifre Zorunlu Karakter Sistemde kayıtlı kullanıcı şifresi dil Zorunlu Karakter Türkçe için “tr”, İngilizce için “en” girilmelidir wsLogin Servisi Giriş Parametreleri logout metodu Bu servis açılan oturumun kapatılmasını sağlar. Soap header tabanlı erişim Tercih edilen kimlik doğrulama yöntemi olan Cookie tabanlı erişim yöntemi kullanılamadığı durumlarda e-Arşiv web servis metotlarına yapılan her çağrının header bilgisinde kullanıcı adı ve parola gönderilerek kimlik doğrulama yapılabilir. Bunun için soap Xml’inin header bölümünde aşağıdaki örnekteki gibi bir bölüm bulunmalıdır. kullaniciadi sifre Entegrasyon Servisleri Tüm servisler “input” ve gerekli ise “output” giriş / çıkış parametreleri ile çalışırlar. Parametreler ya dizgi türündendir ve JSON dizgisi beklenmektedir ya da “Belge“ / “Holder” türündendir. “Belge” türü, belgenin tipini tanımlayan bir sabit ve belgenin içeriğini temsil eden “byte” dizisinden oluşur. “Holder” ise “value” alanında Object tipinde değer taşıyabilen bir taşıyıcıdır. Tüm servisler, servis çağrısının sonucunu içeren (çağrının başarılı olup olmadığı, değilse oluşan hataya ilişkin bilgi) “result” değerini geri döndürür. Sadece veri sorgulama amacı taşıyan servisler dışında kalan “işlem servisleri”; islemId vkn sube kasa gibi özelliklerini “input” JSON dizgisi içerisinde parametre olarak alırlar. Bu dört parametre ve çağrının alındığı “kaynak”, sistemde tanımlı işlem adımlarının uygulanması ya da atlanmasına karar vermeyi sağlayan bir “konfigürasyon tanımlayıcısı” işlevi görür. E-Arşiv uygulamasının web ara yüzünde uygulama seçeneklerinin kullanıcı tarafından değiştirilebilmesini sağlayan bir menü seçeneği yer almaktır. Kullanıcı, mükellef bazında, örneğin web servisi kaynağından gelen faturaların numaralarının hangi seri ön eki ile üretileceğini uygulama seçeneklerinde belirtir. işlemId ve diğer üç parametre (vkn, sube, kasa), sistem açısından bir işlemin tekil tanımlayıcısı işlevi görürler. islemId parametresi, servisi kullanan istemci tarafından kendi işlemini tekil tanımlamak için üretilerek gönderilen bir referanstır. Eğer işlem her hangi bir uçta (istemci ya da sunucu tarafında), dışsal sebeplerle kesintiye uğrar ve istemci ile sunucu arasındaki iletişim koparsa, tekrar iletişim kurulduğunda, aynı islemId parametresi ile işlem tekrarlanabilir. Bu durumunda, sistem, aynı islemId ile yapılan çağrıya bir önceki çağrıda ürettiği cevabı üretecektir. Aynı islemId ile yapılan çağrıların “denk güçlü” olması bu gibi “çökme” durumlarında sistem tutarlılığının korunmasını sağlamaktadır. Servis Geri Dönüş Değeri Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format resultCode String Çağrı sonucu kodu Bkz: sonuç kodları listesi. resultText String Çağrı sonucunu açıklayan metin Bkz: sonuç kodları listesi. resultExtra Properties Çağrı sonucu ile ilgili ek bilgi “faturaURL”, “uuid”, “faturaNo” gibi değerleri key-value çiftleri olarak içerir. Sonuç Kodları Listesi resultCode resultText AE00000 İşlem başarılı. AE00001 Sistem hatası! AE00002 Belirsiz istisnai durum hatası! AE00003 Fatura belgesi validasyon işlemi başarısız! Hata Detayı : {0} AE00004 Fatura belgesi unmarshal işlemi başarısız! AE00005 Fatura belgesi marshal işlemi başarısız! AE00006 Fatura belgesi unmarshal işlemi validasyonu başarısız! Hata detayı: {0} AE00007 Fatura belgesi marshal işlemi validasyonu başarısız! AE00008 Belirtilen vkn, şube, kasa, kaynak kombinasyonu için tanımlı konfigürasyon bilgisi bulunamadı! AE00009 Belirtilen vkn için belirtilen fatura numarasına sahip kayıtlı fatura mevcut! AE00011 Belirtilen belge tipi imzalama desteği mevcut değil! AE00012 Belirtilen şablon adı mükellef şablonları arasında bulunamadı! AE00013 {0} belge tipi desteklenmiyor. AE00014 Bu işlem ID ile daha önce fatura gönderildi! AE00016 Fatura XML''inde UUID içeren alan okunamadı. AE00017 Fatura XML'inde Fatura No içeren alan okunamadı. AE00018 Veritabanında belirtilen UUID ile kayıtlı Fatura Numarası ile gönderilen Fatura Numarası eşleşmiyor. AE00019 Fatura versiyonu daha önce gönderilenle aynı ya da daha eski. AE00020 Belirtilen UUID'ye sahip kayıtlı fatura mevcut! AE00029 XSLT marshal işlemi başarısız! AE00030 XSLT mapping işlemi başarısız! AE00031 XSLT doğrulama işlemi başarısız! AE00032 XSLT, UBL''in içinde bulunamadı! AE00033 Faturanın ek bilgisi ya da goruntu path''i bulunamadı! AE00035 {0} ozelleştirmesi için özelleştirme tanım dosyası bulunamadı! AE00036 E-Posta listesinde geçersiz eposta adresi bulunmaktadır! Hatalı kayıt : {0} AE00037 E-Posta listesinde geçersiz VKN/TCKN bulunmaktadır! VKN 10 haneli, TCKN 11 haneli olmalıdır. Hatalı kayıt : {0} AE00039 Fatura serisi iki karakterden kısa olamaz! AE00040 Faturayı oluşturduğunuz tarihten en fazla 36 gün öncesine kesebilirsiniz. Daha geçmiş tarihe fatura kesemezsiniz! AE00041 Konfigürasyonda kayıtlı fatura serisiyle geçmiş tarihe fatura kesemezsiniz! Geçmiş tarihe fatura kesebilmeniz için fatura serisi iki karakter olmalıdır. AE00042 {0} fatura sistemde kayıtlı değildir! AE00043 Fatura hatalı durumda! AE00044 Fatura işlemde. AE00045 Faturada belirtilen satıcı kimlik numarası ({0}) ile işlemi yapan kullanıcı kimlik numarası ({1}) uyuşmuyor. AE00047 Bu işlem id ile başarılı bir işlem bulunamadı. AE00050 İptal edilmek istenen fatura imzalı duruma ulaşmamış. İptal işlemi yapılamaz! AE00051 {0} UUID''li fatura sistemde mevcut ve imzalı durumda! AE00052 Kullanıcınn yetkili olduğu VKN bulunamadı! AE00053 Fatura iptal işlemi başarısız! AE00055 Web servis çağrısı "input" alanından fatura bilgisi elde edilemedi, bu alanın boş olmadığından emin olunuz! AE00056 Web servis çağrısı "fatura" alanından belge elde edilemedi, bu alanın boş olmadığından emin olunuz! AE00057 UBL TR {0} belge tipi desteklenmemektedir. Lütfen faturanızı UBL TR {1} formatında gönderiniz. AE00058 Sıkıştırılmış olarak gelen fatura belgesi açılırken hata oluştu! AE00059 {0} VKN''sine ait {1} donemine ilişkin rapor bulunamadı! AE00060 {0} VKN''sine ait {1} rapor numaralı rapor bölümü bulunamadı! AE00061 {0} VKN''sine ait {1} donemine ilişkin rapor durumu {2}. Rapor durumu gönderime hazır (9) olmadığından gonderilemez! AE00062 {0} VKN''sine ait {1} rapor numaralı rapor bölümü okunamadı! AE00063 Fatura UBL''i şema doğrulaması başarısız. Hata detayı : {0} AE00064 Fatura görüntüsü oluşturulurken hata oluştu. Fatura bilgilerine ulaşılamıyor. AE00065 Fatura görüntüsü oluşturulurken hata UUID bilgisine ulaşılamıyor. AE00066 Fatura görüntüsü oluşturulurken hata Fatra No (ID) bilgisine ulaşılamıyor. AE00067 Web servis çağrısı "input" alanından gerekli bilgiler elde edilemedi. Eksik alanlar: {0} bu alan(lar)ın boş olmadığından emin olunuz! AE00068 Web servis çağrısı "paketDosyasiZip" alanından dosya elde edilemedi, bu alanın boş olmadığından emin olunuz! AE00069 Paket dosyasi adından versiyon elde edilemedi. Versiyon numarası dosya adı içindeki numerik karakterlerle oluşturulmaktadır. Aynı paket için daha büyük versiyonlu dosya gelmediği sürece işlem yapılmamaktadır. "input" içindeki paketDosyaAdi parametresini F000001.zip formatında gönderiniz. Mevcut paketDosyaAdi: {0} AE00070 Kayıtlı paketler arasında {0} paketi bulunamadı. Sisteme gönderilen paketler sıralı olarak işlendiğinden kaydın oluşması kullanıma göre zaman alabilmektedir. Lütfen daha sonra tekrar deneyiniz. AE00071 Kayıtlı paketler arasında {0} paketine ait {1} paket dosyası bulunamadı. Sisteme gönderilen paket dosyaları sıralı olarak işlendiğinden kaydın oluşması kullanıma göre zaman alabilmektedir. Lütfen daha sonra tekrar deneyiniz. AE00072 {0} paketi onaylıdır, tekrar onaylanamaz. Paket durumunu paket sorgulama metodu ile sorgulayabilirsiniz. AE00073 Sistemde kayıtlı FTP kullanıcınız bulunamadı. AE00074 Fatura seri alanı 2 ya da 3 haneli olmalıdır. AE00075 Xslt ekleme alani sistem tarafindansa sablon bos olamaz. AE00076 {0} VKN''sine ait {1} kalan kontor bulunamadı. AE00077 Aynı şube, kasa, kaynak kombinasyonu için ikinci bir kayıt girilemez! AE00078 Kullanıcıya ait tanımlı FTP hesabı bulunamadı. AE00079 Web servis çağrısı içeriği uygun değil. Uygun olmayan içerik: {0} AE00080 Web servis çağrısı ile gelen bilgilerden tanımlı bir yapılandırmaya ulaşılamadı (Şube: {0}, Kasa: {1}). Ayrıca {2} VKN'si için tanımlı bir varsayılan seri de tanımlı değil. Numara verilemedi! AE00081 Tanımlı şablon olmadığından görüntü oluşturulamadı. AE00082 {0} belge formatı için görüntü oluşturulamaz. AE00083 {0} VKN''sine ait {1} fatura numarası {2} UUID''si ile kayıtlıdır! AE00084 {0} VKN''si e-Fatura kayıtlı kullanıcısıdır. e-Arşiv faturası kesilemez! AE00085 Fatura oluşturma metodunda donenBelgeFormati parametresi 0 (UBL), 2 (HTML), 3 (PDF) ve 9 (YOK) değerlerini alabilir! AE00086 Fatura önizleme metodunda donenBelgeFormati parametresi 0 (UBL), 2 (HTML) ve 3 (PDF) değerlerini alabilir! AE00087 e-Arşiv ürününüz yok! AE00088 e-Arşiv aktivasyonunuz yapılmamış. AE00089 Fatura zamanı e-Arşiv aktivasyon zamanınızdan öncedir! AE00090 e-Arşiv raporunda zorunlu olan vergi toplamlarının matrah bilgisi fatura verisinden elde edilemedi. Vergi oranı olmadığında ya da 0 olduğunda faturanın toplam vergileri bölümünde matrah (cbc:TaxableAmount) alanının gönderilmesi gerekmektedir! AE00091 İptal edilmek istenen fatura {0} tarihinde iptal edilmiş durumdadır. AE00092 Başlangıç tarihi bitiş tarihinden büyük olamaz. AE00093 Tarih aralığı en fazla 92 gün olabilir. AE00094 Gönderilen işlem ID ({2}) ile sistemde mevcut işlem ID uyuşmuyor. Kayıtı UUID: {0}, Kayıtlı işlem ID : {1} AE00095 {0} VKN''si için gönderilen işlem ID ({1}) ile farklı UUID''ye sahip kayıt mevcut (durum : {2}). Gelen UUID: {3} Kayıtlı UUID: {4} AE00980 Bu VKN için işlem yapmaya yetkili değilsiniz! AE00990 Bu servisi kullanabilmek için giriş yapmalısınız! AE00999 İstek zaman aşımına uğradı!!! AE90000 Bu işlev henüz desteklenmiyor. Fatura Numarası Üretme EarsivServiceResult faturaNoUret(String input, Holder output) Belirtilen seri için sıradaki fatura numarasını “output” parametresi ile geri döndürür. “output” parametresi “value” alanında Object tipinde dönen fatura numarası String’ini taşıyan bir “Holder” objesidir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Bu alanlardan islemId alanı, yapılan işlemi tekil olarak tanımlamak üzere kullanıcı tarafından verilen bir değerdir ve kullanıcı bazında tekil olması zorunludur. Herhangi bir şekilde çağrı tamamlanamadığı durumda kullanıcı aynı islemId değeri ile çağrıyı tekrar ettiğinde önceki çağrıda oluşturulmuş sonuç dönecektir. Başarısız çağrılar eğer yeni bir işlemId ile tekrarlanırsa önceki çağrıda numaranın üretilebildiği durumlarda kullanıcı tarafından alınamamış / atlanmış fatura numaraları oluşmasına sebep olabilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk faturaSeri String Fatura serisi. (gönderildiğinde öncelikli olarak bu seriye göre numara verilir.) Seçimli islemId String İşlemi tanımlayan tekil tanımlayıcı. Zorunlu kasa String Faturanın kesildiği kasanın kodu. (sube alanı ile birlikte faturaSeri belirtilmediği durumlarda yapılandırma ayarında belirtilen seriyi almak için kullanılır) Seçimli sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanı ile birlikte faturaSeri belirtilmediği durumlarda yapılandırma ayarında belirtilen seriyi almak için kullanılır) Seçimli vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu tarih String “YYYYAAGG” formatında tarih değeri gönderilirse fatura numarası bu fatura tarihine göre verilir. Olmadığında çağrının sisteme ulaştığı tarih kullanılır. Seçimli Fatura numarası öncelikle input içinde gelen faturaSeri için verilir. Olmadığı durumlarda gönderilen sube/kasa değerlerine göre tanımlı yapılandırma ayarındaki seriye göre verilir. Her ikisinin de olmadığı durumlarda firma ayarları sayfasında tanımlanan varsayılan seri ayarı kullanılarak numara verilir. Fatura No Uret Response Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format output Holder Value alanında üretilen fatura numarasını taşır. String formatındadır resultExtra Properties (key/value) Üretilen fatura numarası ile ilişkili bir kısa URL değerini taşır. Bu numara ile daha sonra fatura kaydedildiğinde kısa URL’den erişilebilir olacaktır. Değer listesi: - url Örnek Çağrı Soap XML’i {"islemId":"61226122987546131", "vkn" : "1950031078", "sube" : "000000", "kasa" : "0000", "tarih":"20160121"} Örnek Cevap Soap XML’i WS12016000005590 AE00000 url https://earsiv.qnbesolutions.com.tr/bGbo6Z9I İşlem başarılı. Fatura Oluşturma EarsivServiceResult faturaOlustur(String input, Belge fatura, Holder output) Faturayı belge olarak alır, veri tabanı kaydını oluşturur. Konfigürasyona göre, gerekiyorsa, faturaya numara verme, fatura görüntüsünü oluşturma ve faturayı imzalama adımlarını uygular. Faturayı, güncellenmiş (numarası verilmiş ve/veya görüntüsü oluşturulmuş ve/veya imzalanmış) hali ile istenen formatta (UBL, HTML ya da PDF) Belge’yi value alanında taşıyan Holder tipinde geri döndürür. Fatura UUID’si, fatura numarası ve faturaya sistem üzerinden erişmek için kullanılabilecek tekil ağ bağlantısı (URL) servis geri dönüş değerinin resultExtra alanı içerisindedir. Fatura HTML/PDF veya UBL olarak geri alınmak istenmiyorsa (yalnızca resultExtra alanındaki fatura numarası, URL vb. bilgiler isteniyorsa) donenBelgeFormati olarak 9 (YOK) gönderilir. faturaOlusturExt metodu bu metot ile aynı parametreleri alır. Dönen resultExtra alanında ilave bilgiler bulunur. (faturadakiAliciTelNo, faturadakiAliciEPosta) İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar yapılandırmadaki ayarların yerine o çağrıya özel kullanılmak üzere sağlanmaktadır. Yapılandırmada belirtilen şube ve kasa için mevcut ayarlardan farklı işlem yapılmak istenmediği sürece gönderilmesi zorunlu değildir. Bu alanlardan islemId alanı, yapılan işlemi tekil olarak tanımlamak üzere kullanıcı tarafından verilen bir değerdir ve kullanıcı bazında tekil olması zorunludur. Herhangi bir şekilde çağrı tamamlanamadığı durumda kullanıcı aynı islemId değeri ile çağrıyı tekrar ettiğinde önceki çağrıda oluşturulmuş sonuç dönecektir. Başarısız çağrılar eğer yeni bir işlemId ile tekrarlanırsa önceki çağrıda faturanın üretilebildiği durumlarda kullanıcı tarafından alınamamış fatura oluşmasına, diğer bir deyişle çift fatura oluşmasına sebep olabilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format donenBelgeFormati İnt output değeri ile dönecek fatura görüntüsünün hangi formatta (HTML, PDF, UBL) oluşturulacağı. Zorunlu 0 (UBL) 2 (HTML) 3 (PDF) 9 (YOK) goruntuOlusturulsunMu int Fatura belgesi içine gömülecek XSLT’nin sistem tarafından eklenip eklenmeyeceği.(Yapılandırmada belirtilen XSLT ekleme ayarı yerine kullanılmak üzere opsiyonel olarak gönderilir.) Bu ayar 0 yani XSLT eklenmesin olarak kullanıldığında XSLT gönderilen belgenin içinde gömülü olmak zorundadır. Seçimli 0 1 islemId String İşlemi tanımlayan tekil tanımlayıcı. Zorunlu vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu kasa String Faturanın kesildiği kasanın kodu. (sube alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu numaraVerilsinMi int Fatura numarasının sistem tarafından verilmesinin istenip istenmediği. (gönderildiğinde yapılandırmadaki ayar yerine kullanılır) Seçimli 0 1 faturaSeri String Numara sistem tarafından verilecekse fatura serisinin hangi seriden kullanılması istendiği. (Gönderildiğinde yapılandırmadaki ayar yerine kullanılır.) Seçimli sablonAdi String Faturayı oluştururken, bu mükellef için sistemde kayıtlı fatura şablonlarından hangisinin kullanılacağı. (Gönderildiğinde yapılandırmadaki kaydın yerine kullanılır) Seçimli erpKodu String Kullanıcının çağrıyı gönderdiği ERP Sisteminin QNB eSolutions’ta kayıtlı kodudur. QNB eSolutions tarafından sağlanır zorunluluğu mükellef ile QNB eSolutions arasındaki mutabakatla belirlenir. Seçimli gzip int Bu değerle fatura belgesinin içeriğinin (belgeIcerigi) gzip formatında sıkıştırılıp sıkıştırılmadığı ve dönen belgenin içeriğinin sıkıştırılıp sıkıştırılmayacağı belirlenir. Bu alan gönderilmediğinde sıkıştırma yok varsayılır. Seçimli 0 1 taslagaYonlendir İnt Gelen faturanın taslaklara yönlendirilmesini sağlar. 1 ise taslağa yönlendirir, 0 ise fatura oluşturur Seçimli 0 1 yerelFaturaNo String Gelen belgenin kendi sisteminde kayıtlı belge numarasıdır. Belge içeriği gelen fatura için XML ya da PDF formatında dönen output için ise UBL, HTML veya PDF formatındadır. Bu içeriklerin sıkıştırılması ağda taşınan verinin azaltılmasını dolayısıyla gönderim ve almanın daha hızlı yapılabilmesini sağlar. Bu sebeple kullanılması tavsiye edilir. Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL - 0 ÖZEL XML - 4 (Gönderilebilecek özel XML, mükellefe özel, daha önceden çalışılmış ve sisteme tanıtılmış olmalıdır.) PDF_CUSTOM - 7 (Özel XML gömülü PDF) PDF_UBL – 8 (UBL Gömülü PDF) belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır. Aynı şekilde dönen belgede de bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Örnek Çağrı Soap XML’i {"islemId":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb", "vkn" : "1950031078", "sube" : "000000", "kasa" : "0000", "donenBelgeFormati" : "2", "gzip":"1", "erpKodu":"ERP1"} UBL H4sIAAAAAAAAAO09yXbiWJ....AAA= Örnek Cevap Soap XML’i HTML H4sIAAAAAAAAAOy8.....uMQ3JMFAQA= AE00000 islemID 1303d6ed-db9e-4465-b48e-9ec6791a3bcb faturaURL http://localhost:8080/earsiv/goruntule.jsp?vkn=1950031078&uuid=1303d6ed-db9e-4465-b48e-9ec6791a3bcb uuid 1303d6ed-db9e-4465-b48e-9ec6791a3bcb faturaNo UUA2016000000698 İşlem başarılı. Fatura Olustur Response Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format output Holder Value alanında üretilen dönen Belge’yi taşır. Belge formatındadır resultExtra Properties (key/value) Üretilen fatura ile ilişkili ilave alanları taşır. Değer listesi: - islemID - faturaURL - uuid - faturaNo - iptalTarihi (iptal edildiyse eklenir) Fatura Sorgulama EarsivServiceResult faturaSorgula(String input, Holder output) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre faturayı istenen formatta (UBL, HTML ya da PDF) Belge’yi value alanında taşıyan Holder tipinde geri döndürür. Fatura UUID’si, fatura numarası ve faturaya sistem üzerinden erişmek için kullanılabilecek tekil ağ bağlantısı (URL) servis geri dönüş değerinin resultExtra alanı içerisindedir. Fatura HTML/PDF veya UBL olarak geri alınmak istenmiyorsa (yalnızca resultExtra alanındaki fatura numarası, URL vb. bilgiler isteniyorsa) donenBelgeFormati olarak 9 (YOK) gönderilir. faturaSorgulaExt metodu bu metot ile aynı parametreleri alır. Dönen resultExtra alanında ilave bilgiler bulunur. (faturadakiAliciTelNo, faturadakiAliciEPosta) Gönderilen input içinde vkn bulunuyorsa sorgu bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre sorgu yapacağı için aslında kayıtlı olan bir fatura sorgulanırken fatura bulunamadı yanıtı alınabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli donenBelgeFormati int Sorgulanan faturanın hangi formatta geri döneceği. (Gönderilmediğinde varsayılan olarak UBL tipinde cevap döner) Seçimli UBL – 0 HTML – 2 PDF – 3 YOK – 9 faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre sorgu yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli gzip int Bu değerle dönen belgenin içeriğinin sıkıştırılıp sıkıştırılmayacağı belirlenir. Bu alan gönderilmediğinde sıkıştırma yok varsayılır. Seçimli 0 1 faturaTipi String Saklamada bulunan faturalar içinden sorgulama yapılacağını belirtir. Seçimli SAKLAMA Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL – 0 HTML – 2 PDF – 3 belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında dönen belgede bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Belge içeriği dönen output için UBL, HTML veya PDF formatındadır. Bu içeriklerin sıkıştırılması ağda taşınan verinin azaltılmasını dolayısıyla cevabın daha hızlı alınabilmesini sağlar. Bu sebeple kullanılması tavsiye edilir. Holder Type Property name Property type Details Value list / Format value Object Donen Belge objesini tutar Örnek Çağrı Soap XML’i { "vkn":"1950031078", "donenBelgeFormati":"3", "faturaUuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb"} Örnek Cevap Soap XML’i PDF JVBERi0xLjQKMSA...NzUKJSVFT0YK AE00000 islemID 1303d6ed-db9e-4465-b48e-9ec6791a3bcb faturaURL http://localhost:8080/earsiv/goruntule.jsp?vkn=1950031078&uuid=1303d6ed-db9e-4465-b48e-9ec6791a3bcb uuid 1303d6ed-db9e-4465-b48e-9ec6791a3bcb faturaNo UUA2016000000698 İşlem başarılı. Fatura Sorgula Response Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format output Holder Value alanında üretilen dönen Belge’yi taşır. Belge formatındadır resultExtra Properties (key/value) Üretilen fatura ile ilişkili ilave alanları taşır. Değer listesi: - islemID - faturaURL - uuid - faturaNo - iptalTarihi (iptal edildiyse eklenir) Fatura İptal Etme EarsivServiceResult faturaIptalEt (String input) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre faturayı iptal eder ve sistemde kayıtlı olan alıcı e-posta adresine faturanın iptal edildiğine dair e-posta gönderir. Gönderilen input içinde vkn bulunuyorsa iptal işlemi bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre iptal işlemi yapacağı için aslında kayıtlı olan bir faturayı iptal etmeye çalışırken fatura bulunamadı yanıtı alınabilir veya diğer VKN’ye ait aynı fatura numarsına sahip bir fatura iptal edilebilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Örnek Çağrı Soap XML’i { "vkn":"1950031078","faturaUuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb"} Örnek Cevap Soap XML’i AE00000 İşlem başarılı. Fatura İptali Kaldırma EarsivServiceResult faturaIptaliKaldir (String input) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre faturanın iptal durumunu kaldırır ve sistemde kayıtlı olan alıcı e-posta adresine faturanın iptal durumunun kaldırıldığına dair e-posta gönderir. Faturanın iptal tarihine boş değer atılır. İptali kaldırma isteği yollandığı esnada devam eden bir rapor işlemi varsa istek geri çevrilir çünkü iptali kaldırılmak istenen fatura , işlemi devam eden rapora girmiş olabilir. İptal durumunu kaldırmak için faturanın rapora girmemiş olması gerekir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Örnek Çağrı Soap XML’i { "vkn":"1950031078","faturaNo":"WFC20100000002"} Örnek Cevap Soap XML’i AE00000 İşlem başarılı. Fatura Taslak Oluşturma EarsivServiceResult faturaTaslakOlustur (String input, Belge fatura) Fatura taslak kaydeder yada günceller. Faturayı belge olarak alır veri tabanında taslak tablosuna kaydını oluşturur. Parametrelerden gelen konfigurasyon değerlerini taslak tablosunda kaydeder (Görüntü imzalansınmı, numara verilsin mi vs. ). Bu değerler daha sonra taslaktan fatura oluştur fonksiyonu çağrıldığında taslak tablosundan alınıp kullanılacaktır. Gelen belge ve sistem ayarlarına göre veritabanına yada dizine kaydedilir. Bu işlemler sırasında kuyruğa herhangi bir veri gönderilmez. Daha sonra taslaktan fatura oluştur fonksiyonu ile istenen formatta kullanıcıya döndürülebilinir. Fonksiyondan geriye herhangi bir şey dönmez. Başarılı veya varsa hata açıklaması döner. Fonksiyona gelen islemId değerine göre kaydet yada güncelle işlemi yapılır. donenBelgeFormati gönderilmediği taktirde 0 yani UBL olarak algılanacaktır. Taslak kayıt aşamasında islemId zorunludur. faturaUuid belgenin içinden alınacaktır. Eğer yapılan işlem taslak güncelleme ise gelen input içinde faturaUuid olması gerekir. Gelen bu faturaUuid değerine göre güncelleme işlemi olduğu anlaşılmaktadır. Aynı faturaUuid ile farklı bir islemId gönderildiği taktirde eski islemId geçerli sayılacak ve yeni gelen islemId görmezden gelinecektir. Başarısız çağrılar eğer yeni bir işlemId ile tekrarlanırsa önceki çağrıda faturanın üretilebildiği durumlarda kullanıcı tarafından alınamamış fatura oluşmasına, diğer bir deyişle çift fatura taslak kaydı oluşmasına sebep olabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar yapılandırmadaki ayarların yerine o çağrıya özel kullanılmak üzere sağlanmaktadır. Yapılandırmada belirtilen şube ve kasa için mevcut ayarlardan farklı işlem yapılmak istenmediği sürece gönderilmesi zorunlu değildir. Bu alanlardan islemId alanı, yapılan işlemi tekil olarak tanımlamak üzere kullanıcı tarafından verilen bir değerdir ve kullanıcı bazında tekil olması zorunludur. Herhangi bir şekilde çağrı tamamlanamadığı durumda kullanıcı aynı islemId değeri ile çağrıyı tekrar ettiğinde önceki çağrıda oluşturulmuş sonuç dönecektir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıkla ma Zorunluluk Değer Listesi / Format donenBelgeFormati İnt output değeri ile dönecek fatura görüntüsünün hangi formatta (HTML, PDF, UBL) oluşturulacağı. Seçimli 0 (UBL) 2 (HTML) 3 (PDF) 9 (YOK) goruntuOlusturulsunMu int Fatura belgesi içine gömülecek XSLT’nin sistem tarafından eklenip eklenmeyeceği.(Yapılandırmada belirtilen XSLT ekleme ayarı yerine kullanılmak üzere opsiyonel olarak gönderilir.) Bu ayar 0 yani XSLT eklenmesin olarak kullanıldığında XSLT gönderilen belgenin içinde gömülü olmak zorundadır. Seçimli 0 1 islemId String İşlemi tanımlayan tekil tanımlayıcı. Zorunlu vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu kasa String Faturanın kesildiği kasanın kodu. (sube alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu numaraVerilsinMi int Fatura numarasının sistem tarafından verilmesinin istenip istenmediği. (gönderildiğinde yapılandırmadaki ayar yerine kullanılır) Seçimli 0 1 faturaSeri String Numara sistem tarafından verilecekse fatura serisinin hangi seriden kullanılması istendiği. (Gönderildiğinde yapılandırmadaki ayar yerine kullanılır.) Seçimli sablonAdi String Faturayı oluştururken, bu mükellef için sistemde kayıtlı fatura şablonlarından hangisinin kullanılacağı. (Gönderildiğinde yapılandırmadaki kaydın yerine kullanılır) Seçimli erpKodu String Kullanıcının çağrıyı gönderdiği ERP Sisteminin QNB eSolutions’ta kayıtlı kodudur. QNB eSolutions tarafından sağlanır zorunluluğu mükellef ile QNB eSolutions arasındaki mutabakatla belirlenir. Seçimli gzip int Bu değerle fatura belgesinin içeriğinin (belgeIcerigi) gzip formatında sıkıştırılıp sıkıştırılmadığı ve dönen belgenin içeriğinin sıkıştırılıp sıkıştırılmayacağı belirlenir. Bu alan gönderilmediğinde sıkıştırma yok varsayılır. Seçimli 0 1 Belge içeriği gelen fatura için XML ya da PDF formatında dönen output için ise UBL, HTML veya PDF formatındadır. Bu içeriklerin sıkıştırılması ağda taşınan verinin azaltılmasını dolayısıyla gönderim ve almanın daha hızlı yapılabilmesini sağlar. Bu sebeple kullanılması tavsiye edilir. Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL - 0 ÖZEL XML - 4 (Gönderilebilecek özel XML, mükellefe özel, daha önceden çalışılmış ve sisteme tanıtılmış olmalıdır.) PDF_CUSTOM - 7 (Özel XML gömülü PDF) PDF_UBL – 8 (UBL Gömülü PDF) belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır. Aynı şekilde dönen belgede de bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Örnek Çağrı Soap XML’i {"islemId":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb", "vkn" : "1950031078", "sube" : "000000", "kasa" : "0000", "donenBelgeFormati" : "2", "gzip":"1", "erpKodu":"ERP1"} UBL H4sIAAAAAAAAAO09yXbiWJ....AAA= Örnek Cevap Soap XML’i AE00000İşlem başarılı. Fatura Taslaktan Oluşturma EarsivServiceResult faturaTaslaktanOlustur (String input, Holder output) Taslak olarak kaydedilmiş faturalardan gerçek fatura kayıtları oluşturur. Kullanıcıdan faturaUuid değerini alır. Bu değer ile gelen taslak bilgisi sorgulandıktan sonra kuyruk işlemleri başlatılacaktır. İnput ile gelen değerler göz ardı edilir. Sistem için gerekli olan sadece faturaUuid değeridir. Çağrı ile kuyruğa gönderme işlemleri başlatılır. Burada önceden kuyruğa gönderilmiş ise faturaOlustur metodundaki gibi farklı kuyruk işlemlerine gönderilecektir. Taslak kaydından fatura oluşturulduktan sonra bu taslak tablodan silinir. Kullanıcının tekrardan taslak sil metodunu çağırmasına gerek yok. Parametreler “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre sorgu yapılır.) Zorunlu Örnek Çağrı Soap XML’i { "faturaUuid":"dae56e11-42cd-4624-b1b6-b226471fc2a2" , "vkn":"1950031078"} Örnek Cevap Soap XML’i HTML H4sIAAAAAAAAANS865KrSLYm+LvOU0TvY212jlGZzv2S... AE00000 islemID dae56e11-42cd-4624-b1b6-b226471fc2a2 faturadakiAliciTelNo 1111111 faturaURL http://localhost:8080/earsiv/goruntule.jsp?vkn=1950031078&uuid=dae56e11-42cd-4624-b1b6-b226471fc2a2 uuid dae56e11-42cd-4624-b1b6-b226471fc2a2 faturaNo WSA2017000000018 faturadakiAliciEPosta test@test.com.tr İşlem başarılı. Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL - 0 ÖZEL XML - 4 (Gönderilebilecek özel XML, mükellefe özel, daha önceden çalışılmış ve sisteme tanıtılmış olmalıdır.) PDF_CUSTOM - 7 (Özel XML gömülü PDF) PDF_UBL – 8 (UBL Gömülü PDF) belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır. Aynı şekilde dönen belgede de bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Fatura Olustur Response Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format output Holder Value alanında üretilen dönen Belge’yi taşır. Belge formatındadır resultExtra Properties (key/value) Üretilen fatura ile ilişkili ilave alanları taşır. Değer listesi: - islemID - faturaURL - uuid - faturaNo Fatura Taslak Silme EarsivServiceResult faturaTaslakSil (String input) Taslak kayıtlarını siler. İnput içinde gelen faturaUuid yeterlidir. Faturadan taslak oluşturulduğunda zaten bu taslak kaydı otomatik olarak silinecektir. Tekrardan sil metodunu çağırmaya gerek yoktur. Parametreler “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre sorgu yapılır.) Seçimli Örnek Çağrı Soap XML’i {"faturaUuid":"caae5e71-5218-4bd2-b572-096c1e3d7196" } Örnek Cevap Soap XML’i AE00150 caae5e71-5218-4bd2-b572-096c1e3d7196 faturaUuid li taslak kaydı bulunamadı! İşlem başarılı. Fatura Taslak Önizleme EarsivServiceResult faturaTaslakOnizleme (String input, Holder output) Önceden oluşturulmuş taslak kaydını görüntüler. Taslak oluşturulurken tüm fatura ve kontrol kuralları uygulanmıştır. (şema, şematron kontrolleri vs.). oluştutulan görüntü faturanın son hali olacaktır. Faturayı önceden kaydedilmiş belge içeriğinden alır. DönenBelgeFormat, GelenBelgeFormat gibi bilgiler taslaktan tekrar okunur. Faturayı istenen formatta (UBL, HTML ya da PDF), Belge’yi value alanında taşıyan Holder tipinde geri döndürür. İnput dizgisi (JSON formatında) faturaUuid alanı yeterlidir. Diğer alanlar gönderildiği taktirde göz ardı edilecektir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format faturaUUid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre sorgu yapılır.) Zorunlu Zorunlu donenBelgeFormati int Taslağın önizlemesinin hangi formatta döneceğini belirtir. (boş bırakılması durumunda değer ubl(0) olarak atanır.) Seçimli UBL – 0 HTML – 2 PDF - 3 Belge içeriği gelen fatura için XML ya da PDF formatında dönen output için ise UBL, HTML veya PDF formatındadır. Bu içeriklerin sıkıştırılması ağda taşınan verinin azaltılmasını dolayısıyla gönderim ve almanın daha hızlı yapılabilmesini sağlar. Bu sebeple kullanılması tavsiye edilir. Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL - 0 ÖZEL XML - 4 (Gönderilebilecek özel XML, mükellefe özel, daha önceden çalışılmış ve sisteme tanıtılmış olmalıdır.) PDF_CUSTOM - 7 (Özel XML gömülü PDF) PDF_UBL – 8 (UBL Gömülü PDF) belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır. Aynı şekilde dönen belgede de bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Örnek Çağrı Soap XML’i earsiv 1 {"faturaUuid":"1a9cdb3b-d4c1-4575-9d3e-b17a73a2e800" } Örnek Cevap Soap XML’i AE00000 islemID 1a9cdb3b-d4c1-4575-9d3e-b17a73a2e800 faturadakiAliciTelNo Yok faturaURL http://localhost:8080/earsiv/goruntule.jsp?vkn=null&uuid=1a9cdb3b-d4c1-4575-9d3e-b17a73a2e800 uuid 1a9cdb3b-d4c1-4575-9d3e-b17a73a2e800 faturaNo WST2015000000065 faturadakiAliciEPosta 2222222223 İşlem başarılı. HTML H4sIAAAAAAAAANS865KrSLYm+LvOU0TvY... Fatura Taslak Sorgulama EarsivServiceResult faturaTaslakSorgula (String input, Holder> output) Gönderilen parametrelere göre kayıtlı taslakları sorgulayarak dönen taslakları liste halinde dönen metottur. Bu sorgulama QNB eSolutions portal üzerinde arayüzde yapılan sorgulama ile aynı parametrelerle çalışır. Dönen sonuç input ile gönderilen pagingLimit ve pagingStart değerlerine göre n’inci sıradan itibaren m adet fatura içerir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar sorguyu ilgilenilen fatura grubunu dönecek şekilde belirler. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunlu /Seçimli Değer Listesi /Format mukellefVkn String Kullanıcının işlem yaptığı mükellefin VKN’sidir. Zorunlu aliciVkn String Fatura alıcısının VKN /TCKN’sidir. Seçimli pagingLimit int Bir seferde kaç fatura listelenmek istediğidir. Seçimli Max 100 pagingStart int Kaçıncı kayıttan itibaren listenin başlayacağıdır. Seçimli siralamaAlani String Faturaların hangi alana göre sıralanacağıdır. Gönderilmediğinde tarihe göre azalan olarak sıralanır. Seçimli receiverContact receiverName invoiceId issueDate toplamTutar payableAmount vergilerToplami creationTime siralamaYonu String Artan mı azalan mı sıralanacağı. Seçimli ASC DESC faturaTarihiBaslangic String Bu tarih ve sonraki faturaları listelemek içindir. Zorunlu YYYYAAGG faturaTarihiBitis String Bu tarih ve önceki faturaları listelemek içindir. (başlangıç bitiş arası 3 ayı geçemez) Zorunlu YYYYAAGG sube String Şube adı Seçimli Paging start değeri 0’dan itibaren sayılır, pagingLimit değeri ise cevapta kaç adet fatura bulunacağını belirler ve en fazla 100 olabilir. Örneğin pagingLimit 100 iken ikinci sayfa alınmak istendiğinde pagingStart 100 olarak, üçüncü sayfa alınmak istendiğinde 200 olarak gönderilmelidir. Sorguda kaç adet fatura olduğu resultExtra’nın toplamAdet değeri ile her çağrıda döner. Çağrı sonucunda dönen liste FaturaDTO tipindendir ve aşağıdaki alanları içerir. EFaturaKullanici Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi /Format uuid String Fatura tekil tanımlayıcısı (ETTN) islemId String Fatura gönderilirken kullanılan işlem ID senderContact String Satıcı VKN/TCKN receiverContact String Alıcı VKN/TCKN receiverName String Alıcı adı / ünvanı invoiceId String Fatura numarası issueDate String Fatura Tarihi YYYYAAGG kagitFatura Boolean Kağıt fatura mı olduğu True – Kağıt False - Elektronik currency String Para birimi payableAmount Big Decimal Ödenecek Tutar iptalTarihi String İptal tarihi YYYYAAGG toplamTutar Big Decimal Toplam tutar vergilerToplami Big Decimal Vergiler toplamı epostaGonderimDurumu İnt e-posta gönderim durumu 0 - eposta gönderme ayarlarına göre gönderim istenmemiş 1 - eposta göndermek üzere kaydedildi, henüz servis sağlayıcısına gönderilmedi 2 - servis sağlayıcısına gönderilirken hata oluştu (yerel eposta format kontrolünden geçmemedi) 3 - servis sağlayıcısına gönderildi 4 - servis sağlayıcısına gönderme işlemi yapılıyor 5 - Servis sağlayıcısından dönen yanıt eposta geçersiz 6 - Servis sağlayıcısından dönen yanıt e-posta ulaşmadı 7 - Servis sağlayıcısı tarafından iletildi 8 - Okundu receiverIdentifier String Faturada kayıtlı alıcı e-posta adresi telNo String Faturada kayıtlı alıcı telefon numarası versiyon İnt Toplu gönderilen faturalarda paket versiyon numarası sube String Şube adı kasa String Kasa adı faturaSiraNo int Toplu gönderilen faturalarda paket dosyası içindeki fatura sırası durum int Faturanın sistemdeki durumu 0 - ISLEMDE 1 - ONAYSIZ_HATALI 2 - ONAYLANABILIR 3 - ONAYLI_ISLEMDE 4 - ONAYLI_HATALI 5 - IMZALI Ayrıca ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama toplamAdet Sorgu kriterlerine göre toplam kayıt sayısı pagingStart Sorgunun kaçıncı faturadan itibaren pagingLimit adet fatura içerdiği pagingLimit Sorgunun pagingStart’tan itibaren kaç adet fatura içerdiği E-Posta Gönderme EarsivServiceResult ePostaGonder(String input,String ilaveEposta, String tanimliEpostayaGonder) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre fatura bilgisini parametrelerle belirlenen e-posta adreslerine gönderir. Tanımlı e-postaya gönderilmek istenildiğinde, öncelikli olarak alıcı e-posta listesinde belirtilen e-posta adresine, bulunamadığı takdirde faturada kayıtlı e-posta adresine faturayı gönderir. Bunların haricinde bir e-posta adresine gönderilmek istenirse, ilave e-posta adresi olarak belirtilir. Parametreler Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format İnput JSON Bkz. “input” JSON dizgisi içindeki alanlar ilaveEposta String Alıcı e-posta listesinde ya da faturada kayıtlı e-posta adresi haricinde belirtilen e-posta adresi. tanimliEpostayaGonder int Alıcı e-posta listesinde ya da faturada kayıtlı e-posta adresine gönderme durumu. 0 – Gönderme 1 – Gönder Fatura belgesi içinde alıcı bilgilerinde bulunan tanımlı eposta haricinde belirtilen ilaveEposta alanına virgülle ayrılmış olarak birden çok eposta yazılabilir. Gönderilen input içinde vkn bulunuyorsa işlem bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre iptal işlemi yapacağı için aslında kayıtlı olan bir fatura için eposta göndermeye çalışırken fatura bulunamadı yanıtı alınabilir veya diğer VKN’ye ait aynı fatura numarsına sahip bir fatura için işlem yapılabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Örnek Çağrı Soap XML’i { "vkn":"1950031078","faturaUuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb"} eposta1@qnbesolutions.com.tr, eposta2@qnbesolutions.com.tr 0 Örnek Cevap Soap XML’i AE00000 İşlem başarılı. Alıcı E-Postası Ekleme / Silme / Güncelleme EarsivServiceResult aliciEpostaEkleSilGuncelle(String inputGuncellenecekEposta, String inputSilinecekEposta) Alıcı e-postalarını ekler, siler ve günceller. Alıcı epostaları bir VKN/TCKN için sistemde varsayılan eposta adresi belirlemek için kullanılır. Bu şekilde belirlenen VKN’ler için fatura işlenirken yapılandırma ayarlarına göre gönderilen epostalar ve e-posta gönderme web servis metodu ile gönderilirken tanımlıEpostayaGonder seçeneği 1 ise yollanan epostalar fatura belgesi içindeki eposta adresi yerine bu listede tanımlı eposta adresine gönderilir. Fatura belgesi içinde bulunan firmanın fatura üzerinde görünmesini istediği eposta adresi ile otomatik gönderileceğinde kullanılması istenen eposta adresinin farklı olduğu durumlarda kullanılabilir. (Bu listenin güncellenmesi portal üzerindeki ilgili arayüzden de yapılabilmektedir.) Parametreler Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format inputGuncellenecekEposta Properties Sistemde kayıtlı olması halinde güncellenecek, aksi takdirde eklenecek olan alıcı VKN/TCKN ve e-posta adresi için key/value çiftleri listesi. inputSilinecekEposta List Sistemde kayıtlı olması halinde silinecek e-posta adreslerine ait alıcı VKN/TCKN listesi. Örnek Çağrı Soap XML’i {"1234567890":"eposta1@qnbesolutions.com.tr", "1234567891":"eposta2@qnbesolutions.com.tr"} ["1234567892", "1234567893"] Örnek Cevap Soap XML’i AE00000 İşlem başarılı. E-Posta Durumu Sorgulama EarsivServiceResult ePostaDurumSorgula(String input,String outputDurum, String outputEposta) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre fatura ile her hangi bir yolla ilişkilendirilmiş (fatura içerisindeki iletişim bilgisi olarak ya da gönderilecek e-posta listesi) e-posta adresini ve gönderim durumunu geri döndürür. Gönderilen input içinde vkn bulunuyorsa işlem bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre işlemi yapacağı için aslında kayıtlı olan bir fatura için eposta durumu sorgulamaya çalışırken fatura bulunamadı yanıtı alınabilir veya diğer VKN’ye ait aynı fatura numarsına sahip bir fatura için işlem yapılabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Cevap olarak dönen outputDurum fatura genelindeki eposta gönderim durumunu belirtir, outputEposta ise o fatura için şu ana kadar kaydı yapılmış tüm eposta gönderim işlemlerine ait bilgileri gösterir. Bu alan bir JSON dizisidir. Dizinin her elemanı aşağıdaki alanları bulundurur. Özellik Adı Açıklama oid e-posta durum kaydının tekil tanımlayıcısı uuid Faturanın tekil tanımlayıcısı epostaOid e-posta kaydının tekil tanımlayıcısı epostaAdres e-posta adresi konu e-posta konusu code e-posta servis sağlayıcısından dönen durum kodu aciklama e-posta durumuna ilişkin açıklama metni ilkGondermeZamani e-postanın servis sağlayıcısına gönderilme zamanı sonKontrolZamani e-posta durumunun servis sağlayıcısından en son sorgulanma zamanı durum e-posta durumu kodları 0 - eposta gönderme ayarlarına göre gönderim istenmemiş 1 - eposta göndermek üzere kaydedildi, henüz servis sağlayıcısına gönderilmedi 2 - servis sağlayıcısına gönderilirken hata oluştu (yerel eposta format kontrolünden geçmemedi) 3 - servis sağlayıcısına gönderildi 4 - servis sağlayıcısına gönderme işlemi yapılıyor 5 - Servis sağlayıcısından dönen yanıt eposta geçersiz 6 - Servis sağlayıcısından dönen yanıt e-posta ulaşmadı 7 - Servis sağlayıcısı tarafından iletildi 8 - Okundu outputDurum alanında belirtilen durum bu fatura için gönderim kaydı bulunan e-postalardan en düşük durumdakinin durumudur. Örneğin bir eposta okundu durumunda iken diğeri iletilemedi durumundaysa, faturanın durumu iletilemedi olacaktır. Örnek Çağrı Soap XML’i {"vkn":"1950031078", "faturaUuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb"} Örnek Cevap Soap XML’i e-Posta Servisine Iletilemedi. [{"oid":"5eikpkgmty102a", "uuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb", "epostaOid":"5eikpkgmty1029", "epostaAdres":"eposta1@qnbesolutions.com.tr", "konu":"İptal Edilen Test Firmasi A.Ş. e-Arşiv Faturanız | Your Cancelled Test Firmasi A.Ş. e-Archive Invoice", "postId":null, "code":"_EAR_INV", "aciklama":"e-posta servis sağlayıcısına iletilemedi.", "ilkGondermeZamani":"20160217133827", "sonKontrolZamani":"20160217133827", "durum":2}, {"oid":"5eikpkgmty102c", "uuid":"1303d6ed-db9e-4465-b48e-9ec6791a3bcb", "epostaOid": "5eikpkgmty102b", "epostaAdres":"eposta2@qnbesolutions.com.tr", "konu":"İptal Edilen Test Firmasi A.Ş. e-Arşiv Faturanız | Your Cancelled Test Firmasi A.Ş. e-Archive Invoice", "postId":"36EC94B128E94B5595D389FD3A2E6EB6", "code":"RE", "aciklama":"e-posta servis sağlayıcısı tarafından iletildi. (Okunma bilgisi yok)", "ilkGondermeZamani":"20160217141736", "sonKontrolZamani":"20160217141958", "durum":7}] AE00000 İşlem başarılı. E-Posta Servis Sağlayıcı Üzerinden Durumu Sorgulama EarsivServiceResult servisSaglayicidanEpostaDurumSorgula (String input,String outputEposta) Halihazırda mevcut ePostaDurumSorgula metodu yanıtı olarak, outputEposta alanında liste olarak sorgulanan faturanın tüm eposta gönderim işlemlerine ilişkin kayıtları döndür. Bu kayıtlar eposta gönderim işlemine ait tüm durum bilgileri euromessage, postID değerleri vs. ve esas önemli olan oid değerlerini içeriyor. Buradan alınabilecek olan tekil tanımlayıcı olarak aldığı oid değeri ile FaturaEposta tablosundan sorgulama yapar Gönderilen input içinde vkn de olacaktır ve işlem bu VKN değeri için yapılır. Gönderilen vkn ile tablodan epostaOid ile sorgulanan kaydın vknsi aynı değilse hata döndürülür. Durumu okundu, gönderildi veya hatalı olan yani gönderim süreci sona ermiş gönderiler için kayıtlı durum dönülür. Diğer gönderiler için son bir saatte durumu kontrol edilmiş ise mevcut durum dönülür, aksi halde euromessage servisi ile eposta durumu sorgulanır ve e-Arşiv sistemindeki durum, son kontrol zamanı, açıklama alanları güncellenir ve eposta kaydı döndürülür. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu faturaEpostaOid String e-posta kaydının tekil tanımlayıcısı Zorunlu Cevap olarak outputEposta o fatura için şu ana kadar kaydı yapılmış tüm eposta gönderim işlemlerine ait bilgileri gösterir. Bu alan bir JSON dizisidir. Dizinin her elemanı aşağıdaki alanları bulundurur. Özellik Adı Açıklama oid e-posta durum kaydının tekil tanımlayıcısı uuid Faturanın tekil tanımlayıcısı epostaOid e-posta kaydının tekil tanımlayıcısı epostaAdres e-posta adresi konu e-posta konusu code e-posta servis sağlayıcısından dönen durum kodu aciklama e-posta durumuna ilişkin açıklama metni ilkGondermeZamani e-postanın servis sağlayıcısına gönderilme zamanı sonKontrolZamani e-posta durumunun servis sağlayıcısından en son sorgulanma zamanı durum e-posta durumu kodları 0 - eposta gönderme ayarlarına göre gönderim istenmemiş 1 - eposta göndermek üzere kaydedildi, henüz servis sağlayıcısına gönderilmedi 2 - servis sağlayıcısına gönderilirken hata oluştu (yerel eposta format kontrolünden geçmemedi) 3 - servis sağlayıcısına gönderildi 4 - servis sağlayıcısına gönderme işlemi yapılıyor 5 - Servis sağlayıcısından dönen yanıt eposta geçersiz 6 - Servis sağlayıcısından dönen yanıt e-posta ulaşmadı 7 - Servis sağlayıcısı tarafından iletildi 8 - Okundu Örnek Çağrı Soap XML’i { "vkn":"1950031078","faturaEpostaOid":"0jio2l1rsk1002"} Örnek Cevap Soap XML’i {"oid":"0jio2l1rsk1002","uuid":"D088829C-8D0F-432F-8632-E484712ADBBA","epostaOid":null,"epostaAdres":"zaman.safari@cs.com.tr","konu":"Zaman Ozkan kardesler Elektrik Su Isleri A.S. e-Arşiv Faturanız Hakkında | About Your Zaman Ozkan kardesler Elektrik Su Isleri A.S. e-Archive Invoice","postId":"FB4734067022401FBB540AC4F22B34CE","code":"RE","aciklama":"e-posta servis sağlayıcısı tarafından iletildi. (Okunma bilgisi yok)","ilkGondermeZamani":"20160511110907","sonKontrolZamani":"20161221151511","durum":7, "body":null,"ilkGondermeTarihi":"20160511","vkn":"1950031078","kimdenAdres":"yereltest"} AE00000 İşlem başarılı. Ökc Rapor Kaydetme EarsivServiceResult okcRaporKaydet (String input, DosyaInput rapor) Okc mali raporunu XMl ya da CSV olarak alır. Eğer xml gönderilecek ise Gib’,in istediği standartlarda ÖKC Mali Raporu Veri Formatında , şema ve şematron kontrollerinden geçebilecek şekilde beklenir. CSV formatı için bir çalışma yapılacaktır. Xlm olarak alınan rapor kontroller tamamlandıktan sonra imzalanır ve şema şematron işlemleri gerçekleştirilir. Gelen rapor kaydedildikten sonra firmanın ayarına göre Ökc raporu otomatik olarak oluşturulur ve gönderilir. Oluşturma ve gönderme her ikisi de ayrı ayrı ayarlara bağlıdır. Zorunlu olan alanlar DosyaInput raporu içerisinde XML olarak iletilen alanlarla aynı olmalıdır. Xml belgeyi açmadan bazı kontroller yapabilmek için bu değerler beklenmektedir. bolumBaslangicTarihi ve bolumBitisTarihi ayın ilk günü ve son günü olmalıdır. raporNo tekil kontrolü yapılmaktadır. bolumNo ilgili dönem için 1 den başlamalı ve sıralı gitmelidir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu gzip int Bu değerle rapor belgesinin içeriğinin (belgeIcerigi) gzip formatında sıkıştırılıp sıkıştırılmadığı belirlenir Seçimli 0 1 raporNo String ÖKC Mali Rapor numarası Zorunlu bolumNo int Bölüm numarası Zorunlu bolumBaslangicTarihi String bölümün başlangıç tarihi Zorunlu yyyyMMdd bolumBitisTarihi String bölümün bitiş tarihi Zorunlu yyyyMMdd DosyaInput rapor Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format genelBelgeFormatEnum String Belgenin formatı. XML CSV belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır ResultExtra içindeki alanlar Özellik Adı Açıklama raporNo Rapor numarası bolumSiraNo Bölümün sıra numarası donem Bölümü tanımlayan dönem (yyyyMM) oid Oluşturulan kaydın tekil numarası Örnek Çağrı Soap XML’i {"vkn":"1950031078" , "raporNo":"58831c27-4900-4a76-be08-35f7219f0999" , "bolumNo":"1","bolumBaslangicTarihi":"20180401","bolumBitisTarihi":"20180430"} PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48ZUFyc2l2UmFwb3J1IHhtbG5z PSJodHRwOi8vZWFyc2l2LmVmYXR1cmEuZ292LnRyIiB4bWxuczpkcz0iaHR0cDovL3d3dy53My5v… XML Örnek Cevap Soap XML’i AE00000 raporNo 58831c27-4900-4a76-be08-35f7219f0999 oid 4sjilt7kux10ff donem 201804 bolumSiraNo 5 İşlem başarılı. Ökc Rapor Oluşturma ve Gönderme EarsivServiceResult okcRaporOlusturGonder (String input) Bir önceki okcRaporKaydet metodu ile gelen rapor dosyası geçici tabloda tutuluyordu. Firma ayarlarına göre bu tablodan rapor oluşturulup gönderme işlemi otomatik yapılabilir. Firma kullanıcısı aynı işlemi bu metod ile de yapabilir. Metod Eğer rapor oluşturulmamış ise raporu oluşturur ve gönderir Rapor oluşmuş ise gönderir. Gönderilmiş ve kontör yetersiz hatası almış ise tekrar gönderilecek olarak işaretler ve yeniden gönderir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu raporNo String ÖKC Mali Rapor numarası Zorunlu ResultExtra içindeki alanlar Özellik Adı Açıklama bolumNo Bölüm sıra numarası raporBolumDurum 0 - ISLEMDE, 1 - IMZALANDI, 2 - GONDERILDI, 3 - HATALI, 4 - BASARILI, 5 - TEKRAR_OLUSTURULACAK, 6 - TEKRAR_GONDERILECEK, 7 - FATURA_YOK, 8 - PLANLI, 9 - GONDERIME_HAZIR, 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin bolumBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu bolumBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) islemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i {"vkn":"1950031078" , "raporNo":"65534757-4900-4a76-be08-35f7219f0111"} Örnek Cevap Soap XML’i AE00000 raporDurum 1 raporNo 65534757-4900-4a76-be08-35f7219f0111 bolumBitisZamani 20180901 bilgiHataAciklama bilgiHataKodu bolumBaslangicZamani 20180901 sonIslemZamani 20180930 İşlem başarılı. Ökc Rapor Bölümü İndirme EarsivServiceResult okcRaporBolumAl(String input, Holder output) bolumRaporNo değeri gönderilerek ilgili bölüm output alanı ile alınır. Output Belge tipindedir (Fatura WS metotlarında input/output için kullanılan ile aynı) outPut’un belgeIcerigi alanında base64 encode edilmiş olarak zipli rapor bölümü dönecektir. Ayrıca resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama bolumNo Bölümün sıra numarası bolumRaporNo Bölümü tanımlayan tekil tanımlayıcı raporBolumDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bolumBaslangicZamani Rapor bölüm başlangıç tarihi (YYYYAAGG) bolumBitisZamani Rapor bölüm bitiş tarihi (YYYYAAGG) bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin bilgiHataKodu Hata kodu Örnek Çağrı Soap XML’i {"vkn":"1950031078" , "raporNo":"65534757-4900-4a76-be08-35f7219f0111"} Örnek Cevap Soap XML’i AAAQABAFYAAABRNQAAAAA= AE00000 bolumBitisZamani 20180930 bolumRaporNo 65534757-4900-4a76-be08-35f7219f0111 islemZamani 20181018132843840 durum 2 bilgiHataKodu Dosya kaydedildi bolumNo 6 bolumBaslangicZamani 20180901 raporBolumDurum 2 İşlem başarılı. SMS Gönderme EarsivServiceResult smsGonder(String input,String ilaveTelefonNo, String tanimliTelefonNoyaGonder) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre fatura bilgisini parametrelerle belirlenen telefon numaralarına gönderir. Tanımlı numaraya gönderilmek istenildiğinde, öncelikli olarak alıcı telefon numarası listesinde belirtilen numaraya, bulunamadığı takdirde faturada kayıtlı telefon numarasına faturayı gönderir. Bunların haricinde bir telefon numarasına gönderilmek istenirse, ilave telefon numarası olarak belirtilir. Parametreler Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format input JSON Bkz. “input” JSON dizgisi içindeki alanlar ilaveTelefonNo String Alıcı telefon numarası listesinde ya da faturada kayıtlı telefon numarası haricinde belirtilen telefon numarası. tanimliTelefonNoyaGonder int Alıcı telefon numarası listesinde ya da faturada kayıtlı numaraya gönderme durumu. 0 – Gönderme 1 – Gönder Fatura belgesi içinde alıcı bilgilerinde bulunan tanımlı telefon numarası haricinde belirtilen ilaveTelefonNo alanına tek telefon numarası yazılabilir. Gönderilen input içinde vkn bulunuyorsa işlem bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre iptal işlemi yapacağı için aslında kayıtlı olan bir fatura için SMS göndermeye çalışırken fatura bulunamadı yanıtı alınabilir veya diğer VKN’ye ait aynı fatura numarsına sahip bir fatura için işlem yapılabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Örnek Çağrı Soap XML’i {"vkn":"1950031078", "faturaUuid":"00076C88-0A9F-41F3-B800-720930C29FF8"} 05416904383 0 Örnek Cevap Soap XML’i AE00000 İşlem başarılı. SMS Durumu Sorgulama EarsivServiceResult smsDurumSorgula(String input,String outputSmsDurum) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre fatura ile her hangi bir yolla ilişkilendirilmiş telefon numarasını ve gönderim durumunu geri döndürür. Gönderilen input içinde vkn bulunuyorsa işlem bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. Web Servis çağrıları yapılırken kullanılan kullanıcının birden çok VKN için işlem yapma yetkisi varsa input içinde vkn alanı muhakkak gönderilmelidir. Aksi halde sistem tanımlı VKN’lerden ilkine göre işlemi yapacağı için aslında kayıtlı olan bir fatura için SMS durumu sorgulamaya çalışırken fatura bulunamadı yanıtı alınabilir veya diğer VKN’ye ait aynı fatura numarsına sahip bir fatura için işlem yapılabilir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli Cevap olarak dönen outputSmsDurum fatura genelindeki SMS gönderim durumunu belirtir. Durum listesi o fatura için şu ana kadar kaydı yapılmış tüm SMS gönderim işlemlerine ait bilgileri gösterir. Bu alan bir JSON dizisidir. Dizinin her elemanı aşağıdaki alanları bulundurur. Özellik Adı Açıklama oid SMS kaydının tekil tanımlayıcısı uuid Faturanın tekil tanımlayıcısı vkn İşlem yapılan mükellefin VKN’sidir. aliciTel Telefon numarası mesajBody SMS mesajının içeriği formCode SMS servis sağlayıcısından dönen durum kodu creationDate SMS kaydının yaratıldığı tarih creationTime SMS kaydının yaratıldığı zaman lastUpdateTime SMS durumunun servis sağlayıcısından en son sorgulanma zamanı statusCode SMS servis sağlayıcısının ürettiği durum kodu 0 - Mesaj SMS servisinde işlemde 1 - Mesaj SMS servisinde işlemde 2 – SMS Servisi Başarısız 3 – SMS Servisi Başarılı smsId SMS servis sağlayıcısının ürettiği SMS ID’si aciklama SMS’in hangi aşamada olduğunu gösteren açıklama kontorDurum Kontör olup olmadığın gösteren durum durum SMS durumu kodları 1 - SMS_SERVISINE_GONDERILIYOR 2 - SMS_SERVISINE_GONDERILEMEDI 3 - SMS_SERVISINE_GONDERILDI 4 - SMS_SERVISINDE_ISLEMDE 5 - SMS_SERVISI_BASARISIZ 6 - SMS_SERVISI_BASARILI 7 - SMS_SERVISINE_TEKRAR_GONDERILECEK 8 - SMS_KONTORU_YETERSIZ outputDurum alanında belirtilen durum bu fatura için gönderim kaydı bulunan SMS’lerin en son durumdakinin durumudur. Örnek Çağrı Soap XML’i {"vkn":"1950031078", "faturaUuid":"00076C88-0A9F-41F3-B800-720930C29FF8", "faturaNo":"WFA2016000000065"} Örnek Cevap Soap XML’i AE00000 İşlem başarılı. [{"oid":"4pinlqep4v1000","uuid":"00076C88-0A9F-41F3-B800-720930C29FF8","vkn":"1950031078","aliciTel":"5416904383","mesajBody":"Zaman Ozkan kardesler Elektrik Su Isleri A.S. tarafından QNB eSolutions aracılığı ile 06/04/16 tarihli 10620.00 TRY tutarlı e-Arşiv faturanız için http://localhost:8080/jr0mcidh","formCode":"QNB_ESOLUTIONS_EARSIV_CODE","creationDate":"20160429","creationTime":"20160429160452","lastUpdateTime":"20160429160533","durum":4,"statusCode":"1","smsId":"20002554702","aciklama":"Mesaj SMS servisinde işlemde.","kontorDurum":2}] Rapor Durum Sorgulama EarsivServiceResult raporDurumSorgula(String donem) Dönem parametresini YYYYMM formatında (Örn: 201601) göndererek rapor durumunu içeren bilgiler alınır. ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama raporDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin donemBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu donemBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) sonIslemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i 201601 Örnek Cevap Soap XML’i AE00000 raporDurum 3 bilgiHataAciklama 1950031078 kimlik numaralı şirketinizin 201601 dönemine ilişkin e-Arşiv raporunun 44ceac55-e8e5-4879-922f-7f7acbe45a9a numaralı 4. bölümü oluşturulmuş olup, 09/02/2016 22:00:54 tarihinde başarıyla Gelir İdaresi Başkanlığı'na gönderilmiştir. Raporunuzda 4 bölüm yer almaktadır. donemBaslangicZamani 20160101 bilgiHataKodu 30 donemBitisZamani 20160131 sonIslemZamani 20160209220054 İşlem başarılı. Rapor Bölüm Listesi Sorgulama EarsivServiceResult raporBolumListesiSorgula(String donem, String outputBolumList) Donem parametresini YYYYMM formatında (Örn: 201601) göndererek rapor bölümlerinin bolumRaporNo değerlerini içeren liste output alanı ile alınır. Ayrıca Result’ın resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama raporDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin donemBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu donemBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) sonIslemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i 201601 Örnek Cevap Soap XML’i ["27d0e3ff-1491-401d-90f4-2f92fe4c4f60","cdb5714a-18f1-43f9-b706-789272c73ba0","eaca6a17-4896-4b70-9a73-0ab9adc5c9c6","44ceac55-e8e5-4879-922f-7f7acbe45a9a"] AE00000 raporDurum 3 bilgiHataAciklama 1950031078 kimlik numaralı şirketinizin 201601 dönemine ilişkin e-Arşiv raporunun 44ceac55-e8e5-4879-922f-7f7acbe45a9a numaralı 4. bölümü oluşturulmuş olup, 09/02/2016 22:00:54 tarihinde başarıyla Gelir İdaresi Başkanlığı'na gönderilmiştir. Raporunuzda 4 bölüm yer almaktadır. donemBaslangicZamani 20160101 bilgiHataKodu 30 donemBitisZamani 20160131 sonIslemZamani 20160209220054 İşlem başarılı. Rapor Bölüm Sorgulama EarsivServiceResult raporBolumListesiDetayliSorgula (String donem, Holder> outputBolumList) Donem parametresini YYYYMM formatında (Örn: 201601) göndererek rapor bölümlerinin değerlerini RaporBolumDTOlistesi içeren liste output alanı ile alınır. Çağrı sonucunda dönen liste RaporBolumDTO tipindendir ve aşağıdaki alanları içerir. RaporBolumDTO Özellik Adı Özellik Tipi Açıklama Değer Listesi /Format Durum int Rapor bölümünün durumu durumKodu String Hata bilgi kodu durumAciklama String Hata bilgi açıklaması baslangicTarihi String Rapor bölümünün başlangıç tarihi bitisTarihi String Rapor bölümünün bitiş tarihi sonIslemeZamani String İşlem tarihi bolumRaporNo String Bölüm rapor numarası YYYYAAGG bolumNo Long Bölüm numarası True – Kağıt False - Elektronik Ayrıca Result’ın resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama raporDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin donemBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu donemBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) sonIslemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i 201602 Örnek Cevap Soap XML’i AE00000 raporDurum 7 bilgiHataAciklama Beklenmeyen bir hata oluştu! Hata detayı : Rapor XSD Schema kontrolu esnasinda hata! cvc-pattern-valid: Value '11111RS002' is not facet-valid with respect to pattern '\d\d\d\d\d\d\d\d\d\d' for type 'vknType'. donemBaslangicZamani 20160201 bilgiHataKodu 999 donemBitisZamani 20160229 sonIslemZamani 20160329104918 İşlem başarılı. 20160201 20160229 1 8f832ab3-ac06-41d9-9165-4da7ce951b16 7 Beklenmeyen bir hata oluştu! Hata detayı : Rapor XSD Schema kontrolu esnasinda hata! cvc-pattern-valid: Value '11111RS002' is not facet-valid with respect to pattern '\d\d\d\d\d\d\d\d\d\d' for type 'vknType'. 999 20160329104918254 EarsivServiceResult rapordaFaturaSorgula (String input) Tekil tanımlayıcı olarak aldığı fatura numarası ya da UUID’ye göre faturayı raporların içinde arar. Faturanın içinde geçtiği raporu ve varsa iptal raporunu döndürür. Gönderilen input içinde vkn bulunuyorsa iptal işlemi bu VKN değeri için yapılır. Eğer bu değer yoksa kullanıcının yetkili olduğu ilk VKN kullanılır. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Seçimli faturaUuid String Faturanın tekil tanımlayıcısı. (Mevcutsa faturaNo alanı dikkate alınmadan UUID’ye göre iptal yapılır.) Seçimli faturaNo String Fatura numarası. (UUID belirtilmemişse zorunludur.) Seçimli ResultExtra içindeki alanlar rapor yada iptal raporu varsa dolar. Fatura raporlandıysa: raporlandi 1 değerini alır ve bolumNo, bolumRaporNo, raporBolumDurum, bolumBaslangicZamani, bolumBitisZamani alanları doldurulur. Fatura iptal olarak raporlandıysa: iptal_raporlandi 1 değerini alır ve iptal_bolumNo, iptal_bolumRaporNo, iptal_raporBolumDurum, iptal_bolumBaslangicZamani, iptal_bolumBitisZamani alanları doldurulur. ResultExtra içindeki alanlar Özellik Adı Açıklama raporlandi 0 - Raporlanmadi 1 - Raporlandi bolumNo Bölümün sıra numarası bolumRaporNo Bölümü tanımlayan tekil tanımlayıcı raporBolumDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bolumBaslangicZamani Rapor bölüm başlangıç tarihi (YYYYAAGG) bolumBitisZamani Rapor bölüm bitiş tarihi (YYYYAAGG) iptal_raporlandi 0 –İptal raporunda raporlanmadı 1 – İptal raporunda raporlandı iptal_bolumNo İptal raporu bölümün sıra numarası iptal_bolumRaporNo İptal raporu bölümü tanımlayan tekil tanımlayıcı iptal_raporBolumDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR iptal_bolumBaslangicZamani İptal raporu bölüm başlangıç tarihi (YYYYAAGG) iptal_bolumBitisZamani İptal raporu bölüm bitiş tarihi (YYYYAAGG) Örnek Çağrı Soap XML’i { "vkn":"1950031078","faturaNo":"WFU2016000000001"} Örnek Cevap Soap XML’i AE00000 raporlandi 1 bolumBitisZamani 20160430 bolumRaporNo 2ba768dd-fc7f-403f-9dcd-5af4a1c9c383 bolumNo 1 iptal_raporlandi 0 bolumBaslangicZamani 20160401 raporBolumDurum 9 İşlem başarılı. Rapor Bölümü İndirme EarsivServiceResult raporBolumAl(String bolumRaporNo, Holder output) Rapor Bölüm Listesi Sorgulama metodu ile alınan rapor bölümlerine ait bolumRaporNo değeri gönderilerek ilgili bölüm output alanı ile alınır. Output Belge tipindedir (Fatura WS metotlarında input/output için kullanılan ile aynı) outPut’un belgeIcerigi alanında base64 encode edilmiş olarak zipli rapor bölümü dönecektir. Ayrıca resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama bolumNo Bölümün sıra numarası bolumRaporNo Bölümü tanımlayan tekil tanımlayıcı raporBolumDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bolumBaslangicZamani Rapor bölüm başlangıç tarihi (YYYYAAGG) bolumBitisZamani Rapor bölüm bitiş tarihi (YYYYAAGG) Örnek Çağrı Soap XML’i 44ceac55-e8e5-4879-922f-7f7acbe45a9a Örnek Cevap Soap XML’i UEsDBBQACAgIAEB....ZAQAAAA== AE00000 bolumBitisZamani 20160131 bolumRaporNo 44ceac55-e8e5-4879-922f-7f7acbe45a9a bolumNo 4 bolumBaslangicZamani 20160120 raporBolumDurum 4 İşlem başarılı. EarsivServiceResult raporBolumBilgisiAl (String bolumRaporNo) Rapor bölümüne ait bolumRaporNo değeri gönderilerek ilgili rapor bölümünün değerleri döndürülür. RaporBolumAl metodundan farkı out parametre almaz. Sadece bolumRaporNo yu alır ve bölümün değerlerini döndürür. Ayrıca resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama bolumNo Bölümün sıra numarası bolumRaporNo Bölümü tanımlayan tekil tanımlayıcı raporBolumDurum 0 - ISLEMDE 1 - IMZALANDI 2 - GONDERILDI 3 - HATALI 4 - BASARILI 5 - TEKRAR_OLUSTURULACAK 6 - TEKRAR_GONDERILECEK 7 - FATURA_YOK 8 - PLANLI 9 - GONDERIME_HAZIR 10 - GONDERILIYOR bolumBaslangicZamani Rapor bölüm başlangıç tarihi (YYYYAAGG) bolumBitisZamani Rapor bölüm bitiş tarihi (YYYYAAGG) Örnek Çağrı Soap XML’i 8f832ab3-ac06-41d9-9165-4da7ce951b16 Örnek Cevap Soap XML’i AE00000 bolumBitisZamani 20160229 bolumRaporNo 8f832ab3-ac06-41d9-9165-4da7ce951b16 islemZamani 20160329104918254 durum 7 bilgiHataKodu Beklenmeyen bir hata oluştu! Hata detayı : Rapor XSD Schema kontrolu esnasinda hata! cvc-pattern-valid: Value '11111RS002' is not facet-valid with respect to pattern '\d\d\d\d\d\d\d\d\d\d' for type 'vknType'. bolumNo 1 bolumBaslangicZamani 20160201 raporBolumDurum 7 İşlem başarılı. Rapor Bölümü Silme EarsivServiceResult raporBolumSil (String bolumRaporNo) BolumRaporNo parametresi ile rapor numarasını alır ve silmeye çalışır. Şu anda devam eden bir rapor işlemi var ise silme işlemini yapmaz. Rapor durumu ancak hatalı ise ya da gönderime hazır ise silme işlemi yapılabilir. Rapor döneminden sonra tarihli bir rapor var ise silme işlemi yapmaz. Dönemi aynı olup daha büyük numaralı bir rapor var ise yine silme işlemini yapmaz. Parametreler Özellik Adı Açıklama bolumRaporNo Silinecek olan rapor bölüm numarası. Örnek Çağrı Soap XML’i 3e6ec3c7-f678-45aa-8f06-e5d9935434yy Örnek Cevap Soap XML’i AE00000 İşlem başarılı. Rapor Bölümü Yeniden Numara Verip İmzalama EarsivServiceResult raporBolumRaporNoGuncelleImzala (String bolumRaporNo) GİB tarafında imza doğrulama esnasındaki teknik sorunlardan dolayı yeniden rapor no alıp imzalamak için kullanılır. Rapor bölümüne yeniden bir raporno verdikten sonra rapor dosyasını yeniden oluşturup imzalama işlemini gerçekleştirir. Yeniden rapor no alınacak olan bölümün durumu HATALI ve hata bilgi kodu 154 olmalıdır. Başarılı olması durumunda rapor bölümünün ve raporun durumunu ilgili konfigurasyona göre IMZALANDI yada GONDERIME_HAZIR olarak işaretler. Parametreler Özellik Adı Açıklama bolumRaporNo Raporno alıp imzalanacak olan rapor bölüm numarası. Örnek Çağrı Soap XML’i b7497694-ad39-4ecb-aed9-cd0f8548270c Örnek Cevap Soap XML’i AE00000 İşlem başarılı. Rapor Gönderme EarsivServiceResult raporGonder(String donem) Donem parametresini YYYYMM formatında (Örn: 201601) göndererek, GÖNDERİME_HAZIR durumda olan rapor gönderilmek üzere işleme alınır. (Rapor bu duruma ancak firma ayarı manuel gönderme seçildikten sonra oluşturulmuş ise ulaşacaktır. GÖNDERİME_HAZIR durumunda olmayan raporlar için bu metot hata döner.) Raporun durumu (GÖNDERİLDİ ve daha sonra GİB tarafından işlendiğinde BAŞARILI veya hata olması durumunda hata durumu) raporDurumSorgula metodu ile takip edilir. Rapor gönderme ve kontrol worker periyotları 1 saattir güncel durum sorgulaması yeterli süre beklenmelidir. Rapor gönderme işlemi web servis metoduyla yapıldığında, rapor gönderilmek üzere kayıtlara alınır. Raporun gönderilmesi ve GİB tarafındaki durumunun sorgulanması zamanlanmış görevler ile yapılmaktadır. Web servis metodunun cevabı olarak dönen başarılı yanıtı bu kaydın yapıldığını belirtir. Raporun GİB tarafındaki durumunu belirtmez. Result’ın resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama raporDurum 0 - ISLEMDE, 1 - IMZALANDI, 2 - GONDERILDI, 3 - HATALI, 4 - BASARILI, 5 - TEKRAR_OLUSTURULACAK, 6 - TEKRAR_GONDERILECEK, 7 - FATURA_YOK, 8 - PLANLI, 9 - GONDERIME_HAZIR, 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin donemBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu donemBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) sonIslemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i 201601 Örnek Cevap Soap XML’i AE00000 raporDurum 9 bilgiHataAciklama Raporun 4. bölümü imzalanmıştır. donemBaslangicZamani 20160101 bilgiHataKodu 30 donemBitisZamani 20160131 sonIslemZamani 20160209220054 İşlem başarılı. Rapor Oluşturma EarsivServiceResult raporBolumleriOlustur (String input, String donem, String sonGun) Donem parametresini YYYYAA formatında (Örn: 201601), sonGun parametresini YYYYAAGG formatında (Örn: 20160113) göndererek, belirtilen dönem için en son songun parametresinde belirtilen tarihli faturaları içerecek şekilde rapor oluşturma işlemi başlatılır. Rapor oluşturma anında mevcut bölümler aynı kalmak koşuluyla yeni oluşan bölümler eklenir. Seçilen tarihlere göre ortaya çıkan fatura adedine göre birden fazla bölüm oluşturulabilir. Kullanıcının gönderme ayarlarına göre oluşturma işlemi tamamlandığında ya rapor GİB’e gönderilir ya da GÖNDERİME_HAZIR duruma ulaşır, kullanıcı tarafından ayrıca gönderilir. WS’ten dönen başarılı cevabı raporun oluşturulmaya başlandığını gösterir. Raporun işlem durumu ilgili WS metotları ile takip edilebilir. Rapor oluşturma işlemi, kullanıcı tarafından tetiklenmediği durumlarda her ayın sonunda bir sonraki ayın 15’ine kadar (ayarlarda belirtilen gün) otomatik olarak oluşturulur. Ancak ay içinde veya sonrasında bu metot veya arayüzdeki ilgili işlem kullanılarak rapor oluşturulduğunda rapor oluşturma işlemleri, o dönem için kullanıcı kontrolüne geçer. Otomatik oluşturma yapılmaz. Bu sebeple ay sonunda, rapor dönemi içinde eksik tarih kalmadığı kullanıcı tarafından kontrol edilmelidir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu ResultExtra içindeki alanlar Özellik Adı Açıklama raporDurum 0 - ISLEMDE, 1 - IMZALANDI, 2 - GONDERILDI, 3 - HATALI, 4 - BASARILI, 5 - TEKRAR_OLUSTURULACAK, 6 - TEKRAR_GONDERILECEK, 7 - FATURA_YOK, 8 - PLANLI, 9 - GONDERIME_HAZIR, 10 - GONDERILIYOR bilgiHataAciklama Hatanın ya da mevcut durumun açıklamasını içeren metin donemBaslangicZamani Rapor dönemi başlangıç tarihi (YYYYAAGG) bilgiHataKodu Hata kodu donemBitisZamani Rapor dönemi bitiş tarihi (YYYYAAGG) sonIslemZamani Son işlem zamanı (YYYYAAGGSSDDss) Örnek Çağrı Soap XML’i {"vkn" : "1950031078"} 201603 20160328 Örnek Cevap Soap XML’i AE00000 raporDurum 4 bilgiHataAciklama Başarılı donemBaslangicZamani 20160301 bilgiHataKodu 30 donemBitisZamani 20160331 sonIslemZamani 20160325134437 İşlem başarılı. Toplu Fatura Paket Dosyası Gönderme EarsivServiceResult topluFaturaPaketDosyaGonder(String input, Belge paketDosyasiZip) QNB eSolutions e-Arşiv sistemine FTP veya upload gibi yöntemlerle toplu fatura gönderilebildiği gibi web servis metotları ile de toplu fatura gönderilebilir. Toplu fatura işlemleri her bir faturanın cevabının alınmasına imkan vermediği için dosya kaydedilerek arka planda işlenmeye devam eder. Toplu işlemlerin durumu paket veya paket dosyaları sorgulanarak takip edilir. Her bir paket bir paket adı ile belirlenir ve bu pakete referans vererek oluşturulan paket dosyaları aynı gruba ait faturalar olarak işlenir. Sorgulamalar neticesinde bazı faturalar düzeltilecekse yine aynı pakete ikinci bir paket dosyası gönderilerek düzeltmeler de toplu olarak yapılır. Paket onaylanabilir duruma geldiğinde ayrı bir web servis metodu ile onaylanarak bu paketteki tüm faturalar imzaya gönderilir. Eğer kullanıcı yapılandırma ayarlarında otomatik onaylama seçmişse hatalı faturalar göz ardı edilerek hatasızlar otomatik onaylanır. Bu durumda hatalı fatura varsa ayrı bir pakette düzeltilmiş halleri gönderilir. Gönderilen paketDosyasiZip Belge tipindedir ve yalnızca zip formatında belge içeriğini taşır. Belge formatı bu alan için kullanılmaz, dosyanın içindeki faturalar yapılandırma ayarlarında belirtilen belge formatı olarak işlenir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu kasa String Faturanın kesildiği kasanın kodu. (sube alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu paketAdi String Bu fatura grubunu takip etmek için kullanılacak paket adıdır. Kullanıcı tarafından belirlenir. Zorunlu paketDosyaAdi String Paketteki dosyanın adıdır. Dosya adından paketin gönderim sırasını temsil eden versiyon bilgisi elde edilir. Bu sebeple sırasıyla, 1,2.. gibi sayısal bölüm içerecek bir ad verilmelidir. Zorunlu Paket adı kullanıcı tarafından bu paketi takip için kullanılır isimlendirilmesinde herhangi bir zorunluluk yoktur. Paket dosya adı ise sistemde işlenme sırasında adından elde edilen (Örn. F00001.zip adlı dosya versiyon 1, F00002.zip adlı dosya versiyon 2 olarak kabul edilir.) versiyon numarasına işlenir. Örneğin versiyonu 2 olan bir dosya işlendikten sonra aynı pakete tekrar versiyonu 2 olan bir dosya gelirse bir daha işlenmez. Bu ikinci dosya ile güncellenmiş bir faturanın daha eski bir dosya ile hatalı şekilde güncellenmesini önlemek içindir. Result’ın resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama paketDosyaVersiyon Paket dosya adından elde edilen versiyon numarası paketDosyaAdi Paket dosya adı paketAdi Paket adı Web servis soap xml’indeki karakter sayısı limiti 15M dur. Bu sebeple dosya göndermedeki zip dosyasının boyutu ve dolayısıyla fatura miktarı bu limite bağlıdır. Fatura içeriğinde göre bu zip dosyasının alabileceği fatura adedi değişmekle birlikte 100 adetten fazla gönderilmesi tavsiye edilmez. Bu limitin aşılması durumunda web servis çağrısı request seviyesinde kesildiğinden cevap hata olarak verilememektedir. Örnek Çağrı Soap XML’i {"vkn" : "1950031078", "sube" : "000000", "kasa" : "0000", "paketAdi":"201602171625", "paketDosyaAdi":"F0000001.zip"} UEsDBBQAA...AAAvwoAAAAA Örnek Cevap Soap XML’i AE00000 paketDosyaVersiyon 1 paketDosyaAdi F0000001.zip paketAdi 201602171625 İşlem başarılı. Toplu Fatura Paket Dosyası Sorgulama EarsivServiceResult topluFaturaPaketDosyasiSorgula(String input, Holder output) Gönderilen paket dosyasının durumunun sorgulandığı metottur. Paket dosyasının işlenmesi tamamlanmışsa hatalı ve başarılı faturaların bilgilerini içeren bir xml dosyası output olarak döner. İnput dizgisi (JSON formatında) aşağıdaki alanları içerir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu paketAdi String Bu fatura grubunu takip etmek için kullanılacak paket adıdır. Kullanıcı tarafından belirlenir. Zorunlu paketDosyaAdi String Paketteki dosyanın adıdır. Dosya adından paketin gönderim sırasını temsil eden versiyon bilgisi elde edilir. Bu sebeple sırasıyla, 1,2.. gibi sayısal bölüm içerecek bir ad verilmelidir. Zorunlu Output xml belgesi formatı aşağıdaki gibidir: 201602131318 F00001.zip 20160213131830 20160213131831 20160213131851 10 0 1 9 AE0001 Hata Açıklaması 20160113153011 1 1950031078-201602131318-1-faturalar-1 754fd48b-588d-4137-8d4e-9182b979bb71 AE00003 Fatura belgesi validasyon işlemi başarısız! Hata Detayı : cbc:ID elemanı shemeId değeri 'TCKN' olduğunda yanlızca sayı içerebilir. 20160213131830 2 7542d837-3e24-482c-9198-b90330a58f31 ZT12016000007041 3 413e3562-a5a3-4882-8eb4-b3f4e592b8b7 ZT12016000007042 Ayrıca resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama paketDosyaAdi Paket dosya adı paketAdi Paket adı paketDosyaVersiyon Paket dosya adından elde edilen versiyon numarası paketDosyaIslemeZamani Paket dosyasının işlenme zamanı paketOnayZamani Onaylanmışsa paketin onay zamanı paketDosyaAlmaZamani Paket dosyasının sisteme geliş zamanı paketDosyaAcmaZamani Paket dosyasının açılma zamanı paketAlmaZamani İlgili paketin alınma zamanı paketOnayTamamlanmaZamani Paket onaylanmışsa onay sonrasında işlemlerin tamamlanma zamanı Örnek Çağrı Soap XML’i {"paketAdi":"201602171625","paketDosyaAdi":"F0000001.zip", "vkn":"1950031078"} Örnek Cevap Soap XML’i PD94bWwgdm.....CjwvTG9nPgo= AE00000 paketAdi 201602171625 paketDosyaAdi F0000001.zip paketDosyaVersiyon 1 paketDosyaIslemeZamani 20160217162625 paketOnayZamani paketDosyaAlmaZamani 20160217162601 paketDosyaAcmaZamani 20160217162601 paketAlmaZamani 20160217162601 paketOnayTamamlanmaZamani İşlem başarılı. Toplu Fatura Paket Sorgulama EarsivServiceResult topluFaturaPaketSorgula(String input, Holder output) Gönderilen paketin durumunun sorgulandığı metottur. Paketin işlenmesi tamamlanmışsa hatalı ve başarılı faturaların bilgilerini içeren bir xml dosyası output olarak döner. İnput dizgisi (JSON formatında) aşağıdaki alanları içerir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu paketAdi String Bu fatura grubunu takip etmek için kullanılacak paket adıdır. Kullanıcı tarafından belirlenir. Zorunlu Output xml belgesi formatı aşağıdaki gibidir: 201602131318 20160215130545 10 0 10 5cd54ad4-78f8-4c75-9053-10a24d83e1b6 4 ONAYLI_HATALI 754fd48b-588d-4137-8d4e-9182b979bb71 ZT12016000007040 http://localhost:8080/earsiv/goruntule.jsp?vkn=1950031078&uuid=754fd48b-588d-4137-8d4e-9182b979bb71 7542d837-3e24-482c-9198-b90330a58f31 ZT12016000007041 http://localhost:8080/earsiv/goruntule.jsp?vkn=1950031078&uuid=7542d837-3e24-482c-9198-b90330a58f31 Ayrıca resultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama paketAdi Paket adı paketOnayZamani Onaylanmışsa paketin onay zamanı paketAlmaZamani Paketin alınma zamanı paketOnayTamamlanmaZamani Paket onaylanmışsa onay sonrasında işlemlerin tamamlanma zamanı Örnek Çağrı Soap XML’i {"paketAdi":"201602171625","vkn":"1950031078"} Örnek Cevap Soap XML’i AE00000 paketAlmaZamani 20160217162601 paketOnayTamamlanmaZamani paketOnayZamani paketAdi 201602171625 İşlem başarılı. Toplu Fatura Paket Onaylama EarsivServiceResult topluFaturaPaketOnayla(String input) Yapılandıra ayarı otomatik onaylansın olduğunda bu metot kullanılmaz. Onaylanabilir aşamaya gelen paket otomatik onaylanır. Yapılandırma ayarı otomatik onaylanmasın olduğunda bu servis kullanılarak onaylanabilir aşamaya gelen rapor onaylanabilir. Bu servisten dönen başarılı cevabı tüm paketin işlenmiş olduğu anlamına gelmez, onaylama işleminin başladığı anlamına gelir. Paket durum sorgulama metoduyla onaylanmış paketin durumu takip edilmelidir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu paketAdi String Bu fatura grubunu takip etmek için kullanılacak paket adıdır. Kullanıcı tarafından belirlenir. Zorunlu ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama paketAlmaZamani Paketin alınma zamanı paketAdi Paket adı Örnek Çağrı Soap XML’i {"paketAdi":"201602131104","vkn":"1950031078"} Örnek Cevap Soap XML’i AE00000 paketAlmaZamani 20160213110428 paketAdi 201602131104 İşlem başarılı. Kontör Sorgulama EarsivServiceResult kontorBilgisiGetir(String vknTckn, String kontorTipi, String kontorBirimi) Kullanıcılar kontör sorgulama metodu ile kalan kontörlerini sorgulayabilirler. Belirtilen VKN kullanıcının yetkili olduğu bir VKN ise işlem yapılır, aksi halde hata döner. Kontör tipi ve birimi alanları e-Arşiv fatura kontörü için aşağıdaki gibi gönderilmelidir. Parametre Adı Değer kontorTipi 5 kontorBirimi 1 ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama kontorTipi Kontör tipi limitAsimMiktari Limit aşım miktarı kalan Kalan kontör miktarı vknTckn Vkn / TCKN toplamAlinan Toplam alınan kontör miktarı kontorBirimi Kontör birimi Örnek Çağrı Soap XML’i 1950031078 5 1 Örnek Cevap Soap XML’i AE00000 kontorTipi 5 limitAsimMiktari 999999.00 kalan 991370.00 vknTckn 1950031078 toplamAlinan 1000000.00 kontorBirimi 1 İşlem başarılı. Fatura Önizleme EarsivServiceResult faturaOnizleme(String input, Belge fatura, Holder output) Fatura oluşturma metodundaki parametrelerle belge gönderip faturanın oluştuğunda oluşacak görüntünün önizlemesinin alındığı metottur. Bu metot fatura işlenirken yapılan tüm kontrolleri ve veritabanı işlemlerini kapsamadığı için faturanın içerik olarak doğruluğunu kontrol etmez. Yalnızca gönderilen parametreler ve mevcut ayarlara göre gelen verinin nasıl görüntüleneceğini döner. Faturayı belge olarak alır. Faturayı istenen formatta (UBL, HTML ya da PDF), Belge’yi value alanında taşıyan Holder tipinde geri döndürür. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar yapılandırmadaki ayarların yerine o çağrıya özel kullanılmak üzere sağlanmaktadır. Yapılandırmada belirtilen şube ve kasa için mevcut ayarlardan farklı işlem yapılmak istenmediği sürece gönderilmesi zorunlu değildir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format donenBelgeFormati İnt output değeri ile dönecek fatura görüntüsünün hangi formatta (HTML, PDF, UBL) oluşturulacağı. Zorunlu 0 (UBL) 2 (HTML) 3 (PDF) goruntuOlusturulsunMu int Fatura belgesi içine gömülecek XSLT’nin sistem tarafından eklenip eklenmeyeceği.(Yapılandırmada belirtilen XSLT ekleme ayarı yerine kullanılmak üzere opsiyonel olarak gönderilir.) Bu ayar 0 yani XSLT eklenmesin olarak kullanıldığında XSLT gönderilen belgenin içinde gömülü olmak zorundadır. Seçimli 0 1 islemId String İşlemi tanımlayan tekil tanımlayıcı. Zorunlu vkn String Faturayı kesen mükellefin vergi kimlik numarası. Zorunlu sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu kasa String Faturanın kesildiği kasanın kodu. (sube alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Zorunlu numaraVerilsinMi int Fatura numarasının sistem tarafından verilmesinin istenip istenmediği. (gönderildiğinde yapılandırmadaki ayar yerine kullanılır)serb Seçimli 0 1 faturaSeri String Numara sistem tarafından verilecekse fatura serisinin hangi seriden kullanılması istendiği. (Gönderildiğinde yapılandırmadaki ayar yerine kullanılır.) Seçimli sablonAdi String Faturayı oluştururken, bu mükellef için sistemde kayıtlı fatura şablonlarından hangisinin kullanılacağı. (Gönderildiğinde yapılandırmadaki kaydın yerine kullanılır) Seçimli erpKodu String Kullanıcının çağrıyı gönderdiği ERP Sisteminin QNB eSolutions’ta kayıtlı kodudur. QNB eSolutions tarafından sağlanır zorunluluğu mükellef ile QNB eSolutions arasındaki mutabakatla belirlenir. Seçimli gzip int Bu değerle fatura belgesinin içeriğinin (belgeIcerigi) gzip formatında sıkıştırılıp sıkıştırılmadığı ve dönen belgenin içeriğinin sıkıştırılıp sıkıştırılmayacağı belirlenir. Bu alan gönderilmediğinde sıkıştırma yok varsayılır. Seçimli 0 1 Belge içeriği gelen fatura için XML ya da PDF formatında dönen output için ise UBL, HTML veya PDF formatındadır. Bu içeriklerin sıkıştırılması ağda taşınan verinin azaltılmasını dolayısıyla gönderim ve almanın daha hızlı yapılabilmesini sağlar. Bu sebeple kullanılması tavsiye edilir. Belge Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi / Format belgeFormati String Belgenin formatı. UBL - 0 ÖZEL XML - 4 (Gönderilebilecek özel XML, mükellefe özel, daha önceden çalışılmış ve sisteme tanıtılmış olmalıdır.) PDF_CUSTOM - 7 (Özel XML gömülü PDF) PDF_UBL – 8 (UBL Gömülü PDF) belgeIcerigi byte[] Belgeyi oluşturan “byte” dizisi. gzip alanı 1 olarak kullanıldığında bu içerik gzip formatında sıkıştırılarak sıkıştırılmış içeriğin “byte” dizgisi kullanılmalıdır. Aynı şekilde dönen belgede de bu alan gzip formatında sıkıştırılmış output içeriğini tutacaktır. Örnek Çağrı Soap XML’i {"islemId":"1aff0136-381a-4463-abf0-c88d254a0285", "vkn" : "1950031078", "sube" : "000000", "kasa" : "0000", "donenBelgeFormati" : "3", "gzip":"1"} UBL PD94bWwgdmVyc...52b2ljZT4NCg== Örnek Cevap Soap XML’i PDF JVBERi0xLjQKM...cwNDMKJSVFT0YK AE00000 İşlem başarılı. e-Fatura Kayıtlı Kullanıcı Listele List eFaturaKayitliKullaniciListele(String kayitZamani) YYYYAAGG formatında gönderilen kayıt zamanından daha sonra kaydedilmiş e-Fatura kullanıcılarının listesini dönen metottur. EFaturaKullanici tipi içerisindeki alanlar aşağıdaki gibidir. EFaturaKullanici Tipi Özellik Adı Açıklama etiket Etiket değeri kamuKurulusu Kamu kuruluşu olup olmadığı (true/false) kayitZamani Kayıt tarihi (YYYYAAGG) unvan Ünvanı vergiTcKimlikNo VKN / TCKN Örnek Çağrı Soap XML’i 200151101 Örnek Cevap Soap XML’i etiket1 true 20160101 Ünvan 1 1234567890 etiket2 false 20151201 Ünvan 2 1234567891 e-Fatura Kayıtlı Kullanıcısı Sorgulama boolean efaturaKullanicisi(String vergiTcKimlikNo) Gönderilen VKN / TCKN’nin e-Fatura kayıtlı kullanıcısı olup olmadığını sorgulamak için kullanılan metottur. Şuanda efatura kullanıcısı olup olmadığını sorgular. Örnek Çağrı Soap XML’i 1234567890 Örnek Cevap Soap XML’i true e-Fatura Kayıtlı Kullanıcısı Tarih ile Sorgulama boolean efaturaKullanicisiKontrol(String input) Gönderilen VKN / TCKN’nin e-Fatura kayıtlı kullanıcısı olup olmadığını sorgulamak için kullanılan metottur. “efaturaKullanicisi” metoduna ek olarak “input” parametresi ile tarih bilgisi gönderilebilir. Tarih parametresi yok ise şu anda efatura kullanıcısı olup olmadığını sorgular. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk Değer Listesi / Format vkn String Sorgulanan mükellefin VKN’sidir. Zorunlu tarih String Sorgulanacak tarih. (girilmediyse şuanda efatura mükellefi olup olmadığını sorgular) Seçimli YYYYAAGG Örnek Çağrı Soap XML’i {"vkn":"1950031082","tarih":"20133231"} Örnek Cevap Soap XML’i false Fatura Listesi Sorgulama EarsivServiceResult faturaListeSorgula(String input, Holder> output) Gönderilen parametrelere göre kayıtlı faturaları sorgulayarak dönen faturaları liste halinde dönen metottur. Bu sorgulama QNB eSolutions portal üzerinde arayüzde yapılan sorgulama ile aynı parametrelerle çalışır. Dönen sonuç input ile gönderilen pagingLimit ve pagingStart değerlerine göre n’inci sıradan itibaren m adet fatura içerir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar sorguyu ilgilenilen fatura grubunu dönecek şekilde belirler. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunlu /Seçimli Değer Listesi /Format mukellefVkn String Kullanıcının işlem yaptığı mükellefin VKN’sidir. Zorunlu aliciVkn String Fatura alıcısının VKN /TCKN’sidir. Seçimli pagingLimit int Bir seferde kaç fatura listelenmek istediğidir. Seçimli Max 100 pagingStart int Kaçıncı kayıttan itibaren listenin başlayacağıdır. Seçimli siralamaAlani String Faturaların hangi alana göre sıralanacağıdır. Gönderilmediğinde tarihe göre azalan olarak sıralanır. Seçimli receiverContact receiverName invoiceId issueDate toplamTutar payableAmount vergilerToplami creationTime siralamaYonu String Artan mı azalan mı sıralanacağı. Seçimli ASC DESC faturaNo String Fatura numarsının tamamı veya bir bölümü ile sorgulama için kullanılır Seçimli gonderimSekli String Kağıt / Elektronik fatura Seçimli KAGIT ELEKTRONIK dovizCinsi String Faturanın para birimi Seçimli faturaTarihiBaslangic String Bu tarih ve sonraki faturaları listelemek içindir. Seçimli (creationTimeBaslangic ve bitiş alanlarının boş bırakılması durumunda zorunludur.) YYYYAAGG faturaTarihiBitis String Bu tarih ve önceki faturaları listelemek içindir. (başlangıç bitiş arası 3 ayı geçemez) Seçimli (creationTimeBaslangic ve bitiş alanlarının boş bırakılması durumunda zorunludur.) YYYYAAGG creationTimeBaslangic String Bu tarih ve sonraki zamanda oluşturulmuş faturaları listelemek içindir. Seçimli (faturaTarihiBaslangic ve bitiş alanlarının boş bırakılması durumunda zorunludur.) YYYYAAGGSSDDSS creationTimeBitis String Bu tarih ve önceki zamanda oluşturulmuş faturaları listelemek içindir. (başlangıç bitiş arası 3 ayı geçemez) Seçimli (faturaTarihiBaslangic ve bitiş alanlarının boş bırakılması durumunda zorunludur.) YYYYAAGGSSDDSS iptalTarihiBaslangic String İptal faturaları sorgulanırken kullanılır. Bu tarihten sonra iptal edilen faturaları listeler Seçimli YYYYAAGG iptalTarihiBitis String İptal faturaları sorgulanırken kullanılır. Bu tarihten önce iptal edilen faturaları listeler Seçimli YYYYAAGG sonrakiRaporaGirecekFaturalar int Bu değer 1 olarak gönderildiğinde sorgu en son gönderilmiş rapora göre bir sonraki rapor dönemine girecek faturaları listeler. Seçimli 0 1 minTutar Big Decimal Fatura ödenecek tutarı alt sınırı Seçimli maxTutar Big Decimal Fatura ödenecek tutarı üst sınırı Seçimli yalnizIptalEdilenFaturalar int Bu değer 1 olarak gönderildiğinde yanlızca iptal edilmiş faturalar sorgulanır Seçimli 0 1 faturaUuid String Fatura tekil tanımlayıcısı (ETTN) Seçimli kasa String Kasa adı Seçimli sube String Şube adı Seçimli hataliFaturalar İnt Bu alan 1 olarak gönderildiğinde yalnızca hatalı faturalar listelenir. Rapora girecek faturalar gibi kesişimi olmayan parametrelerle birlikte kullanılmamalıdır. Seçimli 0 1 epostaGonderimDurumu int Yalnızca eposta durumu belirtilen faturalar sorgulanır Seçimli 0 (Tümü) 1 (İletildi) 2 (Hatalı) 3 (Gönderiliyor) 4 (Gönderim talebi yok) kaynak int Yanlızca fatura kaynağı belirtilen faturalar sorgulanır. Seçimli 0 (Web Servis) 1 (Ftp) 2 (Upload) 3 (Portal) 4 (Web Servis Toplu) tasinanFaturalar int Bu alan 1 olarak gönderildiğinde sadece taşınan faturalar listelenir. Seçimli 0 1 Paging start değeri 0’dan itibaren sayılır, pagingLimit değeri ise cevapta kaç adet fatura bulunacağını belirler ve en fazla 100 olabilir. Örneğin pagingLimit 100 iken ikinci sayfa alınmak istendiğinde pagingStart 100 olarak, üçüncü sayfa alınmak istendiğinde 200 olarak gönderilmelidir. Sorguda kaç adet fatura olduğu resultExtra’nın toplamAdet değeri ile her çağrıda döner. Çağrı sonucunda dönen liste FaturaDTO tipindendir ve aşağıdaki alanları içerir. EFaturaKullanici Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi /Format uuid String Fatura tekil tanımlayıcısı (ETTN) islemId String Fatura gönderilirken kullanılan işlem ID senderContact String Satıcı VKN/TCKN receiverContact String Alıcı VKN/TCKN receiverName String Alıcı adı / ünvanı invoiceId String Fatura numarası issueDate String Fatura Tarihi YYYYAAGG kagitFatura Boolean Kağıt fatura mı olduğu True – Kağıt False - Elektronik currency String Para birimi payableAmount Big Decimal Ödenecek Tutar iptalTarihi String İptal tarihi YYYYAAGG toplamTutar Big Decimal Toplam tutar vergilerToplami Big Decimal Vergiler toplamı epostaGonderimDurumu İnt e-posta gönderim durumu 0 - eposta gönderme ayarlarına göre gönderim istenmemiş 1 - eposta göndermek üzere kaydedildi, henüz servis sağlayıcısına gönderilmedi 2 - servis sağlayıcısına gönderilirken hata oluştu (yerel eposta format kontrolünden geçmemedi) 3 - servis sağlayıcısına gönderildi 4 - servis sağlayıcısına gönderme işlemi yapılıyor 5 - Servis sağlayıcısından dönen yanıt eposta geçersiz 6 - Servis sağlayıcısından dönen yanıt e-posta ulaşmadı 7 - Servis sağlayıcısı tarafından iletildi 8 - Okundu receiverIdentifier String Faturada kayıtlı alıcı e-posta adresi telNo String Faturada kayıtlı alıcı telefon numarası versiyon İnt Toplu gönderilen faturalarda paket versiyon numarası sube String Şube adı kasa String Kasa adı faturaSiraNo int Toplu gönderilen faturalarda paket dosyası içindeki fatura sırası durum int Faturanın sistemdeki durumu 0 - ISLEMDE 1 - ONAYSIZ_HATALI 2 - ONAYLANABILIR 3 - ONAYLI_ISLEMDE 4 - ONAYLI_HATALI 5 - IMZALI erpKodu String Erp Kodu creationTime String Faturanın sisteme kayıt zamanı Ayrıca ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama toplamAdet Sorgu kriterlerine göre toplam kayıt sayısı pagingStart Sorgunun kaçıncı faturadan itibaren pagingLimit adet fatura içerdiği pagingLimit Sorgunun pagingStart’tan itibaren kaç adet fatura içerdiği Örnek Çağrı Soap XML’i {"mukellefVkn":"1950031078", "pagingLimit":"100", "pagingStart":"0","faturaTarihiBaslangic":"20160101","faturaTarihiBitis":"20160204"} Örnek Cevap Soap XML’i AE00000 toplamAdet 1154 pagingStart 0 pagingLimit 100 İşlem başarılı. TRY UUA2016000000687 313c77be-3362-4b86-84f9-b559dc6d386f 20160204 true 0000 2092.06 22222222222 eposta1@qnbesolutions.com.tr Adı Soyadı 1950031078 BAYINO1 (000000) 1111111 1540.00 313c77be-3362-4b86-84f9-b559dc6d386f 552.06 0 TRY UUA2016000000688 ca8a4a37-f154-4e17-a75c-497bf92a2269 20160204 true 0000 2092.06 22222222222 eposta1@qnbesolutions.com.tr Adı Soyadı 1950031078 BAYINO1 (000000) 1111111 1540.00 ca8a4a37-f154-4e17-a75c-497bf92a2269 552.06 0 Fatura Listesi Sorgulama Portal EarsivServiceResult faturaListeSorgulaPortal(String input, Holder> output) Gönderilen parametrelere göre portal ve upload üzerinden kaydedilmiş faturaları sorgulayarak dönen faturaları liste halinde dönen metottur. Kaynak olarak sadece portal(3) ve upload(2) gönderilebilir. Kaynağın boş bırakılması durumunda kaynak tipi 2 ve 3 olan faturalar listelenir. Bu sorgulama QNB eSolutions portal üzerinde arayüzde yapılan sorgulama ile aynı parametrelerle çalışır. Dönen sonuç input ile gönderilen pagingLimit ve pagingStart değerlerine göre n’inci sıradan itibaren m adet fatura içerir. İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar sorguyu ilgilenilen fatura grubunu dönecek şekilde belirler. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunlu /Seçimli Değer Listesi /Format mukellefVkn String Kullanıcının işlem yaptığı mükellefin VKN’sidir. Zorunlu aliciVkn String Fatura alıcısının VKN /TCKN’sidir. Seçimli pagingLimit int Bir seferde kaç fatura listelenmek istediğidir. Seçimli Max 100 pagingStart int Kaçıncı kayıttan itibaren listenin başlayacağıdır. Seçimli siralamaAlani String Faturaların hangi alana göre sıralanacağıdır. Gönderilmediğinde tarihe göre azalan olarak sıralanır. Seçimli receiverContact receiverName invoiceId issueDate toplamTutar payableAmount vergilerToplami creationTime siralamaYonu String Artan mı azalan mı sıralanacağı. Seçimli ASC DESC faturaNo String Fatura numarsının tamamı veya bir bölümü ile sorgulama için kullanılır Seçimli gonderimSekli String Kağıt / Elektronik fatura Seçimli KAGIT ELEKTRONIK dovizCinsi String Faturanın para birimi Seçimli faturaTarihiBaslangic String Bu tarih ve sonraki faturaları listelemek içindir. Seçimli YYYYAAGG faturaTarihiBitis String Bu tarih ve önceki faturaları listelemek içindir. Seçimli YYYYAAGG creationTimeBaslangic String Faturanın sistemde oluşturulma zamanı bu tarih ve sonrakileri listelemek içindir. Zorunlu YYYYAAGGSSDDSS creationTimeBitis String Faturanın sistemde oluşturulma zamanı bu tarih ve öncesini listelemek içindir. (başlangıç bitiş arası 3 ayı geçemez) Zorunlu YYYYAAGGSSDDSS iptalTarihiBaslangic String İptal faturaları sorgulanırken kullanılır. Bu tarihten sonra iptal edilen faturaları listeler Seçimli YYYYAAGG iptalTarihiBitis String İptal faturaları sorgulanırken kullanılır. Bu tarihten önce iptal edilen faturaları listeler Seçimli YYYYAAGG sonrakiRaporaGirecekFaturalar int Bu değer 1 olarak gönderildiğinde sorgu en son gönderilmiş rapora göre bir sonraki rapor dönemine girecek faturaları listeler. Seçimli 0 1 minTutar Big Decimal Fatura ödenecek tutarı alt sınırı Seçimli maxTutar Big Decimal Fatura ödenecek tutarı üst sınırı Seçimli yalnizIptalEdilenFaturalar int Bu değer 1 olarak gönderildiğinde yanlızca iptal edilmiş faturalar sorgulanır Seçimli 0 1 faturaUuid String Fatura tekil tanımlayıcısı (ETTN) Seçimli kasa String Kasa adı Seçimli sube String Şube adı Seçimli hataliFaturalar İnt Bu alan 1 olarak gönderildiğinde yalnızca hatalı faturalar listelenir. Rapora girecek faturalar gibi kesişimi olmayan parametrelerle birlikte kullanılmamalıdır. Seçimli 0 1 epostaGonderimDurumu int Yalnızca eposta durumu belirtilen faturalar sorgulanır Seçimli 0 (Tümü) 1 (İletildi) 2 (Hatalı) 3 (Gönderiliyor) 4 (Gönderim talebi yok) kaynak int Yanlızca fatura kaynağı belirtilen faturalar sorgulanır. Seçimli 2 (Upload) 3 (Portal) Paging start değeri 0’dan itibaren sayılır, pagingLimit değeri ise cevapta kaç adet fatura bulunacağını belirler ve en fazla 100 olabilir. Örneğin pagingLimit 100 iken ikinci sayfa alınmak istendiğinde pagingStart 100 olarak, üçüncü sayfa alınmak istendiğinde 200 olarak gönderilmelidir. Sorguda kaç adet fatura olduğu resultExtra’nın toplamAdet değeri ile her çağrıda döner. Çağrı sonucunda dönen liste FaturaDTO tipindendir ve aşağıdaki alanları içerir. EFaturaKullanici Tipi Özellik Adı Özellik Tipi Açıklama Değer Listesi /Format uuid String Fatura tekil tanımlayıcısı (ETTN) islemId String Fatura gönderilirken kullanılan işlem ID senderContact String Satıcı VKN/TCKN receiverContact String Alıcı VKN/TCKN receiverName String Alıcı adı / ünvanı invoiceId String Fatura numarası issueDate String Fatura Tarihi YYYYAAGG kagitFatura Boolean Kağıt fatura mı olduğu True – Kağıt False - Elektronik currency String Para birimi payableAmount Big Decimal Ödenecek Tutar iptalTarihi String İptal tarihi YYYYAAGG toplamTutar Big Decimal Toplam tutar vergilerToplami Big Decimal Vergiler toplamı epostaGonderimDurumu İnt e-posta gönderim durumu 0 - eposta gönderme ayarlarına göre gönderim istenmemiş 1 - eposta göndermek üzere kaydedildi, henüz servis sağlayıcısına gönderilmedi 2 - servis sağlayıcısına gönderilirken hata oluştu (yerel eposta format kontrolünden geçmemedi) 3 - servis sağlayıcısına gönderildi 4 - servis sağlayıcısına gönderme işlemi yapılıyor 5 - Servis sağlayıcısından dönen yanıt eposta geçersiz 6 - Servis sağlayıcısından dönen yanıt e-posta ulaşmadı 7 - Servis sağlayıcısı tarafından iletildi 8 - Okundu receiverIdentifier String Faturada kayıtlı alıcı e-posta adresi telNo String Faturada kayıtlı alıcı telefon numarası versiyon İnt Toplu gönderilen faturalarda paket versiyon numarası sube String Şube adı kasa String Kasa adı faturaSiraNo int Toplu gönderilen faturalarda paket dosyası içindeki fatura sırası durum int Faturanın sistemdeki durumu 0 - ISLEMDE 1 - ONAYSIZ_HATALI 2 - ONAYLANABILIR 3 - ONAYLI_ISLEMDE 4 - ONAYLI_HATALI 5 - IMZALI erpKodu String Erp Kodu Ayrıca ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama toplamAdet Sorgu kriterlerine göre toplam kayıt sayısı pagingStart Sorgunun kaçıncı faturadan itibaren pagingLimit adet fatura içerdiği pagingLimit Sorgunun pagingStart’tan itibaren kaç adet fatura içerdiği Örnek Çağrı Soap XML’i {"mukellefVkn":"1950031078","pagingLimit":"50","creationTimeBaslangic":"20180201101010" ,"creationTimeBitis":"20180301101010","kaynak":"2"} Örnek Cevap Soap XML’i AE00000 toplamAdet 3 pagingStart 0 pagingLimit 50 İşlem başarılı. 0 TRY 20180210235959 0 GGE2018000874897 1950031078-201802131451-1-New folder/sorunlu faturalar-4 20180210 false 0000 0 0 254.43 42703106092 destekbkavm@gmail.com Teyibe Kocyigit 1950031078 000000 5357750179 215.62 0cf209d9-c0aa-48f7-94fb-c2016206094e 38.81 1 0 0 TRY 20180210235959 0 GGE2018000870600 1950031078-201802131451-1-New folder/sorunlu faturalar-3 20180210 false 0000 0 0 2.01 11111111111 kamilsorenzo7@yandex.com Suleyman Sahin 1950031078 000000 1.70 9df18f78-d8ad-457e-85b0-42772f1760b4 0.31 1 0 Fatura Zipi Alma EarsivServiceResult faturaZipiAl(String input, Holder output) Gönderilen fatura ETTN numaralarına göre faturaların ubllerini içeren zipi base64 encode edilmiş olarak döner. (ETTN listesi tek seferde en fazla 100 ETTN içerebilir.) İnput dizgisi (JSON formatında) aşağıdaki alanları içerebilir. Belirtilen seçimli alanlar sorguyu ilgilenilen fatura grubunu dönecek şekilde belirler. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunlu /Seçimli Değer Listesi /Format uuidList List Zipin içine konulacak faturaların ETTN’lerinin listesidir. Zorunlu Max 100 donenBelgeFormati int output değeri ile dönecek belge görüntüsünün hangi formatta ( PDF,XML) oluşturulacağı. Seçimli 0 (XML) 3 (PDF) 9 (YOK) tasinanFaturalar İnt Bu alan 1 olarak gönderildiğinde sadece taşınan faturalar listelenir. Seçimli 0 1 Çağrı sonucu base64 encode edilmiş olarak zipi içerir. Ayrıca ResultExtra alanında aşağıdaki değerler döner: ResultExtra içindeki alanlar Özellik Adı Açıklama toplamAdet Sorgu kriterlerine göre toplam kayıt sayısı pagingStart Sorgunun kaçıncı faturadan itibaren pagingLimit adet fatura içerdiği pagingLimit Sorgunun pagingStart’tan itibaren kaç adet fatura içerdiği Örnek Çağrı Soap XML’i {"uuidList":["00140cc5-af35-4b73-b511-658416d92bba","00588466-79C9-487F-91DA-EABCAB8314AF"]} Örnek Cevap Soap XML’i AE00000 İşlem başarılı. UEsDBBQACAgIABZMAk0AAAAAAAAAAAAAAAAoAAAAMDA Yapılandırma Ayarlarını Alma EarsivServiceResult yapilandirmaAyarlariAl (String input, Holder outputYapilandirma) Yapılandırma ayarları vkn ile sorgulanabilir. Şube ve kasa da filtreye dahil edilebilir. Yapılandırma ayarlarını JSON formatında liste şeklinde döndürür. İnput dizgisi (JSON formatında) aşağıdaki alanları içerir. “input” JSON dizgisi içindeki alanlar Özellik Adı Özellik Tipi Açıklama Zorunluluk vkn String İşlem yapılan mükellefin VKN’sidir. Zorunlu sube String Faturanın kesildiği mükellef şubesinin kodu. (kasa alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Seçimli kasa String Faturanın kesildiği kasanın kodu. (sube alanında gelen değerle birlikte faturanın hangi kurallara göre işleneceği yapılandırma kaydı bu değerle alınır.) Seçimli “outputYapilandirma” JSON dizgisi içindeki alanlar Özellik Adı Açıklama oid Ayarın tekil tanımlayıcısı vkn VKN/TCKN sube Şube adı kasa Kasa adı kaynak 0 - WEB_SERVICE 1- FTP 2- UPLOAD 3- WEB_FORM 4- WEB_SERVICE_TOPLU faturaSeri Şubelerin oluşturacağı faturalar için kullanılacak seri kodu. Şubeler arası farklı veya aynı kod kullanılabilir. ‘numaraVerilsinMi’ 1 olduğunda kullanılır. numaraVerilsinMi 0- Numara müşteri tarafından verilecek anlamına gelir 1- Numara sistem tarafından verilecek anlamına gelir goruntuOlusturulsunMu 0- XSLT Müşteri tarafından eklenecek anlamına gelir 1- sablonAdi ile belirtilen XSLT Sistem tarafından eklenecek anlamına gelir sablonAdi XSLT formatında hazırlanan fatura görüntü oluşturma şablonu adıdır. Mükellef ayarlar sayfasından yüklenmiş olan listedekilerden birinin adı kullanılmalıdır. goruntuImzalansinMi 0- Fatura UBL’i müşteri tarafından imzalanmıştır anlamına gelir 1- Fatura sistem tarafından imzalanacak anlamına gelir gecerlilikBaslangicTarihi Bu yapılandırma kaydının kaydetme/güncellenme tarihi. Örnek: ‘20161007’ gecerlilikBitisTarihi Bu yapılandırma kaydının silinme tarihi. Aktif yapılandırmalarda bu alan boştur. Örnek ‘20161007’ durum 0-Yapılandırma kaydının durumu aktif 1-Yapılandırma kaydının durumu pasif multipleInvoiceInXmlSupported Bu ayar toplu gönderim (FTP, UPLOAD, WS TOPLU) durumlarında kullanılır. 0-Her xml bir fatura içerir 1-Her xml birden fazla fatura içerir epostaGonderimi e-posta gönderiminin hangi durumlarda yapılacağını belirler. 0- Tüm faturalara 1- e-Posta alıcı listesindeki faturalara 2- Posta gönderilmesin 3- Fatura gönderim şekli elektronik olanlara paketCiktiFormati Toplu gönderimlerde (FTP, UPLOAD, WS TOPLU) FTP’ye geri bırakılacak çıktı dosyasının içeriğini belirlemek için kullanılır. 0- Çıktı Yok 1- Fatura URL 2- PDF ve Fatura URL smsGonderimi SMS gönderiminin hangi durumlarda yapılacağını belirler. 0- Sms gönderilmesin 1- Sms alıcı listesindeki faturalara 2- Tüm faturalara 3- Fatura gönderim şekli elektronik olanlara otomatikOnaylama Toplu gönderimlerde (FTP, UPLOAD, WS TOPLU) onay aşamasında ulaşan paketlerin onayının otomatik yapılmasına ilişkin ayardır. 0- Otomatik Onaylanmasın 1- Hatasız ise Onaylansın 2- Otomatik Onaylansın yaziylaTutar Faturaya yazıyla tutar değerinin eklenip eklenmeyeceğini belirler. (İmzalı gelen faturalar için uygulanamaz) 0- Eklenmesin 1- Sistem Tarafından Eklensin Örnek Çağrı Soap XML’i {"vkn":"1950031078"} Örnek Cevap Soap XML’i AE00000 İşlem başarılı. [{"oid":"5eiuaarpet1002","kaynak":3,"vkn":"1950031078","sube":"000000","kasa":"0000","faturaSeri":"AD ","dokumanFormati":0,"numaraVerilsinMi":1,"goruntuOlusturulsunMu":1,"sablonAdi":"invoice_QNB_ esolutions_15_06_04_3.xslt","goruntuImzalansinMi":1,"gecerlilikBaslangicTarihi":"20161015","gecerlilikBitisTarihi":" ","durum":1,"multipleInvoiceInXmlSupported":0,"epostaGonderimi":1,"paketCiktiFormati":0,"smsGonderimi":1,"otomatikOnaylama":2,"yaziylaTutar":0,"xpathMap":null},{"oid":"5einhdecf01007","kaynak":4,"vkn":"1950031078","sube":"000000","kasa":"0000","faturaSeri":" ","dokumanFormati":12,"numaraVerilsinMi":0,"goruntuOlusturulsunMu":1,"sablonAdi":"invoice_QNB_esolutions_15_06_04_3.xslt","goruntuImzalansinMi":1,"gecerlilikBaslangicTarihi":"20160426","gecerlilikBitisTarihi":" ","durum":1,"multipleInvoiceInXmlSupported":0,"epostaGonderimi":2,"paketCiktiFormati":0,"smsGonderimi":1,"otomatikOnaylama":2,"yaziylaTutar":0,"xpathMap":null}]