TÜİK e-vt Web Servis Kılavuzu Mayıs 2015 ANKARA Versiyon: 1.2 1/12
Versiyon Yayım Tarihi Eklenen/Silinen/Değişen Bölüm 1.0 20.02.2014 ---- Kılavuzun ilk sürümü. 1.1 17.04.2014 Sayfa 13 Hata Kodu Tablosu Hata Kodu Tablosu güncellendi. 1.2 04.05.2015 Doküman geneli Araştırmanın referans yılı 2014 olarak güncellendi. Versiyon: 1.2 2/12
WSDL Yapısı Bu bölümde TÜİK tarafından e-vt sistemi ile cevaplanacak olan 2014 yılı Yıllık İş İstatistikleri Sanayi ve Hizmet Soru Kağıtları nın TÜİK sistemine gönderilmesi, sistemden sorgulanması ve listelenmesi gibi işlevleri sağlayacak olan Web Servise ait tanımlamanın yapıldığı WSDL dokümanının yapısı açıklanacaktır. WSDL dokümanı başlıca, Web Servis'te kullanılacak olan veri tiplerinin ve metodların tanımlarından oluşmaktadır. TÜİK sistemleriyle e-vt Web Servis Entegrasyonu kurmak isteyen Uygulama Geliştiricilere TÜİK Test Kulanıcısı tanımlanacaktır. Test Kullanıcıları gerekli Test ve Son Kullanıcı WSDL dosyalarını bağlandıkları arayüzden indirebilecektir. Entegrasyonu başarıyla tamamlayan uygulamalar, Kullanıcıların TÜİK sistemine veri gönderebilmeleri için Son Kullanıcı WSDL'ını kullanacaklardır. Uygulama Geliştiriciler için e-vt Test Sistemine başvuru süreci, genel hususların anlatıldığı Teknik Kılavuzda yer almaktadır. Veri Tipleri Oluşturulan WSDL'de, XSD standardı içinde tanımlanan basit veri tipleri (int, float, long, short,, boolean) kullanılarak ihtiyaca yönelik karışık veri tipleri tanımlanmıştır. Kılavuz içerisinde, Web Servis'te kullanılacak olan veri tiplerine ilişkin açıklamaların yapılacağı aşağıdaki tablo yapısı kullanılmıştır. Karışık nin Adı Property'ler Karışık içinde tanımlanan property'ler, veri tipleri ve kullanım amaçları şeklinde sıralanmaktadır. Property-1 Property-N Property'nin veri tipi belirtilmektedir. Property'nin kullanım amacı açıklanmaktadır. Karışık nin ne amaçla kullanıldığı açıklanmaktadır. Karışık nin WSDL'deki tanımı sunulmaktadır. Versiyon: 1.2 3/12
1. BaseRequestType BaseRequestType isyerikayitno anahtar uygulamaanahtar TÜİK'in işyerlerine verdiği işyeri kayıt numarasını içerir. Her işyeri kayıt no için TÜİK'in oluşturacağı biricik anahtar değerini içerir. e_vt sistemine uyumlu uygulamalara TÜİK tarafından verilen anahtar bilgisini içerir. WSDL kapsamında tanımlanacak olan tüm web servis talep(request) nesneleri bu veri tipinden türetilmiştir. Bu şekilde web servise gelen her request için kimlik denetiminin yapılması amaçlanmaktadır. <xsd:complextype name="baserequesttype" abstract="true"> <xsd:element name="isyerikayitno" nillable="false" type="xsd:" minoccurs="1" maxoccurs="1" /> <xsd:element name="anahtar" nillable="false" type="xsd:" minoccurs="1" maxoccurs="1" /> <xsd:element name="uygulamaanahtar" nillable="false" type="xsd:" minoccurs="1" maxoccurs="1" /> 2. BaseResponseType BaseResponseType responsecode long Başarı durumunu gösterir. Başarı durumunda bu değer 0 (sıfır) olarak kurulur. Hata kodları pozitif sayılar olarak kurulur ve biriciktir. Alabileceği değerler Hata Kodu Tablosu(*) bölümünde belirtilmiştir. responsemessage Hata durumunda hata mesajını içerir. WSDL kapsamında tanımlanacak olan tüm web servis dönüş nesneleri bu Versiyon: 1.2 4/12
veri tipinden türetilmiştir. <xsd:complextype name="baseresponsetype" abstract="true"> <xsd:element name="responsecode" nillable="false" type="xsd:long" minoccurs="1" maxoccurs="1" /> <xsd:element name="responsemessage" nillable="true" type="xsd:" minoccurs="1" maxoccurs="1" /> 3. CalismaYuklemeRequestType CalismaYuklemeRequestType xml base64binary Sisteme xml olarak gönderilecek olan doldurulmuş anketi içeren byte dizisidir. Sisteme anket gönderileceği zaman xml biçimindeki anket içeriğini, işyeri kayıt numarasını ve anahtarı taşıyan veri tipidir. <xsd:complextype name="calismayuklemerequesttype"> <xsd:complexcontent> <xsd:extension base="type:baserequesttype"> <xsd:element minoccurs='0' maxoccurs='1' name="xml" type="xsd:base64binary"/> </xsd:extension> </xsd:complexcontent> 4. CalismaYuklemeResponseType CalismaYuklemeResponseType Versiyon: 1.2 5/12
calismaid Sisteme gönderilen her bir anketin sisteme kaydedilirken alacağı biricik değeri içerir Sisteme kaydedilen ankete ait biricik değeri, hata kodunu ve hata mesajını taşıyan veri tipidir. <xsd:complextype name="calismayuklemeresponsetype"> <xsd:complexcontent> <xsd:extension base="type:baseresponsetype"> <xsd:element minoccurs="1" maxoccurs="1" name="calismaid" type="xsd:" nillable="false"/> </xsd:extension> </xsd:complexcontent> 5. CalismaType CalismaType calismaid Anketin sistemde sahip olduğu biricik değeri içerir. calismaadi Anket adını içeren alandır. durumkod durumaciklama Anketin sistemdeki kesinleşme durumuyla ilgili kodu içerir. Anketin sistemdeki kesinleşme durumuyla ilgili açıklamayı içerir. yuklemetarihi Anketin sisteme yüklendiği tarihi içerir. Anket sorgulama veya listeleme işlemlerinde elde edilen her anketin kendine ait değerlerini taşıyan veri tipidir. <xsd:complextype name="calismatype"> <xsd:element minoccurs="1" maxoccurs="1" name="calismaadi" type="xsd:" nillable="false"/> <xsd:element minoccurs="1" maxoccurs="1" name="calismaid" type="xsd:" nillable="false"/> <xsd:element minoccurs="0" maxoccurs="1" Versiyon: 1.2 6/12
name="durumkod" type="xsd:" nillable="false" /> <xsd:element minoccurs="0" maxoccurs="1" name="durumaciklama" type="xsd:" nillable="false"/> <xsd:element minoccurs="0" maxoccurs="1" name="yuklemetarihi" type="xsd:" nillable="false"/> 6. CalismaSorgulamaRequestType CalismaSorgulamaRequestType calismaid Anketin sistemde sahip olduğu biricik değeri içerir. Anket sorgulamak için web servise istek gönderilirken kullanılan veri tipidir. Sorgulanmak istenilen anketin sistemdeki biricik değerini, işyeri kayıt numarasını ve anahtarı taşıyan veri tipidir. <xsd:complextype name="calismasorgulamarequesttype"> <xsd:complexcontent> <xsd:extension base="type:baserequesttype"> <xsd:element minoccurs="1" maxoccurs="1" name="calismaid" type="xsd:" nillable="false"/> </xsd:extension> </xsd:complexcontent> Versiyon: 1.2 7/12
7. CalismaSorgulamaResponseType CalismaSorgulamaResponseType calisma CalismaType Ankete ait biricik değer, anket adı, kesinleşme durumuyla ilgili kod ve açıklama ve anketin yüklendiği tarih bilgilerini içeren nesnedir. Sistemden sorgulanan anketin, web serviste AnketType olarak tanımlanmış olan veri tipi şeklinde içeriğini, hata kodunu ve hata mesajını taşıyan veri tipidir. <xsd:complextype name="calismasorgulamaresponsetype"> <xsd:complexcontent> <xsd:extension base="type:baseresponsetype"> <xsd:element minoccurs='0' maxoccurs='1' name="calisma" type="type:calismatype"/> </xsd:extension> </xsd:complexcontent> 8. CalismaListesiRequestType CalismaListesiRequestType - - - İşyerine ait, sisteme kaydedilmiş olan anketleri listelemek için web servise gönderilen istek nesnesidir. İşyeri kayıt numarasını ve anahtarı taşır. <xsd:complextype name="calismalistesirequesttype"> <xsd:complexcontent> <xsd:extension base="type:baserequesttype"/> </xsd:complexcontent> Versiyon: 1.2 8/12
9. CalismaListesiResponseType CalismaListesiResponseType calismalistesi CalismaType Her bir ankete ait biricik değer, anket adı, kesinleşme durumuyla ilgili kod ve açıklama ve anketin yüklendiği tarih bilgilerini içeren ankettype nesneleri dizisidir. Sistemdeki, işyerine ait anketlerin web serviste AnketType olarak tanımlanmış olan nesneler şeklindeki bir listeyi, hata kodunu ve hata mesajını taşıyan veri tipidir. <xsd:complextype name="calismalistesiresponsetype"> <xsd:complexcontent> <xsd:extension base="type:baseresponsetype"> <xsd:element minoccurs='0' maxoccurs='unbounded' name="calismalistesi" type="type:calismatype"/> </xsd:extension> </xsd:complexcontent> Metodlar Bu bölümde, web serviste kullanılmak üzere WSDL dokümanında tanımı yapılan metodlara ilişkin bilgiler aktarılacaktır. Kılavuz içerisinde metodlara ait bilgilerin verilmesi için aşağıdaki tablo yapısı kullanılmıştır. Metod Adı Aldığı Parametreler Döndüreceği Değer Örnek Bu satırda metodun aldığı parametreler belirtilmektedir. Metodun, çağrıldığı yere döndüreceği değer belirtmektedir. Metodun hangi amaçla kullanıldığı açıklanmaktadır. WSDL'deki tanımı sunulmaktadır. Versiyon: 1.2 9/12
1. tuikcalismagonder() tuikcalismagonder Aldığı Parametreler Döndüreceği Değer Örnek - CalismaYuklemeRequestType veri tipinde bir request nesnesi - CalismaYuklemeResponseType veri tipinde bir response nesnesi Metoda parametre olarak gelen request nesnesinin içindeki xml şeklindeki anketi, yine request nesnesindeki işyeri kayıt numarası ve anahtar değerlerine göre TÜİK'e gönderen bir metoddur. Gönderilen bu anketin sisteme kaydedilmesi sonucunda TÜİK'ten web servise döndürülen biricik calismaid değerini, hata kodu ve hata mesajı değerlerini içeren bir response nesnesini de çağrıldığı yere döndürür. <wsdl:operation name="tuikcalismagonder"> <soap:operation soapaction="" /> <wsdl:input name="calismayuklemerequest"> <soap:body use="literal" /> </wsdl:input> <wsdl:output name="calismayuklemeresponse"> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> 2. tuikcalismasorgula() tuikcalismasorgula Aldığı Parametreler Döndüreceği Değer Örnek - CalismaSorgulaRequestType veri tipinde bir request nesnesi - CalismaSorgulaResponseType veri tipinde bir response nesnesi Metoda parametre olarak gelen request nesnesinin içindeki her ankete ait biricik değer olan calismaid, işyeri kayıt numarası ve anahtar değerleri ile sistemden sorgulanmak istenilen ankete ait bilgilere erişen metoddur. Sorgulanan anketin sistemde kayıtlı olması durumunda bu ankete ait ad, kesinleşme durumuyla ilgili kod ve açıklama, anketin yüklendiği tarih, hata kodu ve hata mesajı değerlerini içeren bir response nesnesini de çağrıldığı yere döndürür. <wsdl:operation name="tuikcalismasorgula"> <soap:operation soapaction="" /> <wsdl:input name="calismasorgulamarequest"> <soap:body use="literal" /> Versiyon: 1.2 10/12
</wsdl:input> <wsdl:output name="calismasorgulamaresponse"> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> 3. tuikcalismalistele() tuikcalismalistele Aldığı Parametreler Döndüreceği Değer Örnek - CalismaListesiRequestType veri tipinde bir request nesnesi - CalismaListesiResponseType veri tipinde bir response nesnesi Metoda parametre olarak gelen request nesnesinin içindeki işyeri kayıt numarası ve anahtar değerleri ile sistemde bu işyerine ait anketlere ait bilgilere erişen metoddur. Ulaşılan anketlerinin adları, kesinleşme durumlarıyla ilgili kod ve açıklamaları, yüklendikleri tarihler bilgilerinden oluşan bir liste, hata kodu ve hata mesajı değerlerini içeren bir response nesnesini de çağrıldığı yere döndürür. <wsdl:operation name="tuikcalismalistele"> <soap:operation soapaction="" /> <wsdl:input name="calismalistesirequest"> <soap:body use="literal" /> </wsdl:input> <wsdl:output name="calismalistesiresponse"> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> Versiyon: 1.2 11/12
HATA KODU TABLOSU KOD AÇIKLAMA 30001 Geçersiz xml dosyası. 30002 Çalisma kesinleşmiş olduğu için güncelleme yapılamaz. 40001 Çalisma id (calismaid) ile örtüşen bir kaydınız bulunmamaktadır. 40002 Çalışma Id geçerli değil. 60001 İşyeri Kayıt No, Servis Anahtarı ve Uygulama Anahtarı bilgilerinden en az birisi geçersiz. 60002 Bu anahtar veya işkayıt numarasıyla kayıtlı calisma bulunmamaktadır. 60003 Servis anahtarı geçerliliğini yitirdiğinden işlem yapılamaz. 60004 Uygulama sistemde kayıtlı değil. 60005 Uygulama geçici olarak veri gönderimine kapatılmıştır. 60006 Uygulama iptal edilmiştir. 60007 {açıklama}+{çalışma adı}+çalışması için+{servis adı}+servisi' hizmet dışıdır. (Örnek ifade: Verilerle ilgili çalışma yapıldığından YILLIK SANAYİ VE HİZMET İSTATİSTİKLERİ TEST - 2014 çalışması için, CALISMA_SORGULA 'servisi' hizmet dışıdır.) 9**** Beklenmedik bir hata oluştu. Versiyon: 1.2 12/12