e-VT Web Servis Kılavuzu Nisan 2014 ANKARA e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 1/13 Versiyon Yayım Tarihi Eklenen/Silinen/Değişen Bölüm Açıklama 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. e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 2/13 WSDL Yapısı Bu bölümde TÜİK tarafından e-VT sistemi ile cevaplanacak olan 2013 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, string, 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 Veri Tipinin Adı Property'ler Karışık Veri Tipi içinde tanımlanan property'ler, veri tipleri ve kullanım amaçları şeklinde sıralanmaktadır. Veri Tipi Property-1 Property'nin veri tipi belirtilmektedir. Açıklama Property'nin kullanım amacı açıklanmaktadır. Property-N Açıklama Karışık Veri Tipinin ne amaçla kullanıldığı açıklanmaktadır. Tanımlama Karışık Veri Tipinin WSDL'deki tanımı sunulmaktadır. e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 3/13 1. BaseRequestType BaseRequestType Veri Tipi Açıklama isyeriKayitNo string TÜİK'in işyerlerine verdiği işyeri kayıt numarasını içerir. anahtar string Her işyeri kayıt no için TÜİK'in oluşturacağı biricik anahtar değerini içerir. uygulamaAnahtar string e_VT sistemine uyumlu uygulamalara TÜİK tarafından verilen anahtar bilgisini içerir. Açıklama Tanımlama 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:sequence> <xsd:element name="isyeriKayitNo" nillable="false" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="anahtar" nillable="false" type="xsd:string" minOccurs="1" maxOccurs="1" /> <xsd:element name="uygulamaAnahtar" nillable="false" type="xsd:string" minOccurs="1" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> 2. BaseResponseType BaseResponseType Veri Tipi responseCode e-VT - Web Servis Kılavuzu Versiyon: 1.1 long Açıklama 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 Nisan 2014 4/13 belirtilmiştir. responseMessage string Hata durumunda hata mesajını içerir. WSDL kapsamında tanımlanacak olan tüm web servis dönüş nesneleri bu veri tipinden türetilmiştir. Açıklama <xsd:complexType name="BaseResponseType" abstract="true"> <xsd:sequence> <xsd:element name="responseCode" nillable="false" type="xsd:long" minOccurs="1" maxOccurs="1" /> <xsd:element name="responseMessage" nillable="true" type="xsd:string" minOccurs="1" maxOccurs="1" /> </xsd:sequence> </xsd:complexType> Tanımlama 3. CalismaYuklemeRequestType CalismaYuklemeRequestType Veri Tipi xml Açıklama Tanımlama e-VT - Web Servis Kılavuzu Versiyon: 1.1 base64binary Açıklama 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:sequence> <xsd:element minOccurs='0' maxOccurs='1' name="xml" type="xsd:base64Binary"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> Nisan 2014 5/13 4. CalismaYuklemeResponseType CalismaYuklemeResponseType calismaId Açıklama Tanımlama e-VT - Web Servis Kılavuzu Versiyon: 1.1 Veri Tipi Açıklama string 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:sequence> <xsd:element minOccurs="1" maxOccurs="1" name="calismaId" type="xsd:string" nillable="false"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> Nisan 2014 6/13 5. CalismaType CalismaType Veri Tipi Açıklama calismaId string Anketin sistemde sahip olduğu biricik değeri içerir. calismaAdi string Anket adını içeren alandır. durumKod string Anketin sistemdeki kesinleşme durumuyla ilgili kodu içerir. durumAciklama string Anketin sistemdeki kesinleşme durumuyla ilgili açıklamayı içerir. yuklemeTarihi string 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. Açıklama <xsd:complexType name="CalismaType"> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="1" name="calismaAdi" type="xsd:string" nillable="false"/> <xsd:element minOccurs="1" maxOccurs="1" name="calismaId" type="xsd:string" nillable="false"/> <xsd:element minOccurs="0" maxOccurs="1" name="durumKod" type="xsd:string" nillable="false" /> <xsd:element minOccurs="0" maxOccurs="1" name="durumAciklama" type="xsd:string" nillable="false"/> <xsd:element minOccurs="0" maxOccurs="1" name="yuklemeTarihi" type="xsd:string" nillable="false"/> </xsd:sequence> </xsd:complexType> Tanımlama 6. CalismaSorgulamaRequestType CalismaSorgulamaRequestType Veri Tipi calismaId Açıklama Tanımlama e-VT - Web Servis Kılavuzu Versiyon: 1.1 string Açıklama 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> Nisan 2014 7/13 <xsd:extension base="type:BaseRequestType"> <xsd:sequence> <xsd:element minOccurs="1" maxOccurs="1" name="calismaId" type="xsd:string" nillable="false"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> 7. CalismaSorgulamaResponseType CalismaSorgulamaResponseType calisma Açıklama Tanımlama e-VT - Web Servis Kılavuzu Versiyon: 1.1 Veri Tipi Açıklama 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:sequence> <xsd:element minOccurs='0' maxOccurs='1' name="calisma" type="type:CalismaType"/> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> Nisan 2014 8/13 8. CalismaListesiRequestType CalismaListesiRequestType Açıklama Tanımlama Veri Tipi Açıklama - - İş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> </xsd:complexType> 9. CalismaListesiResponseType CalismaListesiResponseType calismaListesi Açıklama Tanımlama e-VT - Web Servis Kılavuzu Versiyon: 1.1 Veri Tipi Açıklama 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:sequence> <xsd:element minOccurs='0' maxOccurs='unbounded' name="calismaListesi" type="type:CalismaType"/> </xsd:sequence> </xsd:extension> Nisan 2014 9/13 </xsd:complexContent> </xsd:complexType> 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 Bu satırda metodun aldığı parametreler belirtilmektedir. Döndüreceği Değer Metodun, çağrıldığı yere döndüreceği değer belirtmektedir. Açıklama Metodun hangi amaçla kullanıldığı açıklanmaktadır. Örnek WSDL'deki tanımı sunulmaktadır. 1. tuikCalismaGonder() tuikCalismaGonder Aldığı Parametreler - CalismaYuklemeRequestType veri tipinde bir request nesnesi Döndüreceği Değer - CalismaYuklemeResponseType veri tipinde bir response nesnesi Açıklama Metoda parametre olarak gelen request nesnesinin içindeki xml şeklindeki e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 10/13 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. Örnek <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 - CalismaSorgulaRequestType veri tipinde bir request nesnesi Döndüreceği Değer - 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. Açıklama Örnek 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"> e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 11/13 <soap:operation soapAction="" /> <wsdl:input name="CalismaSorgulamaRequest"> <soap:body use="literal" /> </wsdl:input> <wsdl:output name="CalismaSorgulamaResponse"> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> 3. tuikCalismaListele() tuikCalismaListele Aldığı Parametreler - CalismaListesiRequestType veri tipinde bir request nesnesi Döndüreceği Değer - CalismaListesiResponseType veri tipinde bir response nesnesi Açıklama Örnek 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> e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 12/13 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 - 2013 çalışması için , CALISMA_SORGULA 'servisi' hizmet dışıdır.) 9**** Beklenmedik bir hata oluştu. e-VT - Web Servis Kılavuzu Versiyon: 1.1 Nisan 2014 13/13
© Copyright 2024 Paperzz