e-VT Web Servis Kılavuzu

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