ek-3 e-fatura uygulamasi yazilim standartlari ve nesne yapisi - v1.2

E-Fatura Uygulamas (Yazlm Standartlar ve Nesne Yaps) Ocak 2010

Versiyon : 1.0 1/14

e-FATURA UYGULAMASI

(Yazlm Standartlar ve Nesne Yaps)

Mart 2011

ANKARA

E-Fatura Uygulamas (Yazlm Standartlar ve Nesne Yaps) Ocak 2010

Versiyon : 1.0 2/14

GELR DARES BAKANLII

Uygulama ve Veri Ynetimi Daire Bakanl

E-Fatura Uygulamas (Yazlm Standartlar ve Nesne Yaps) Mart 2011

Versiyon : 1.2 3/14

Versiyon Yaym Tarihi

Eklenen/Silinen/Deien Blm

Aklama

1.0 05.03.2010 -- Klavuzun ilk yaym tarihi

1.1 26.04.2010 3 XAdES

3. XMLDsign blm tamamen

kaldrlarak XAdES olarak

deitirildi.

1.2 14.03.2011

3 XAdES

4 Sktrma Format, 6 SSL Mekanizmas

7.7 DocumentType Snf

Metodlar

8 Dnlen Aykr Durum Kodlar

Aklamalar geniletildi.


Versiyon : 1.2 4/14

1 Giri ........................................................................................................................ 5

2 MTOM (Message Transmission Optimization Mechanism) .................................. 5

3 XAdES ..................................................................................................................... 6

4 Sktrma Standard ............................................................................................... 8

5 Mesaj zeti Standard ............................................................................................ 8

6 SSL Mekanizmas .................................................................................................... 8

7 Kullanlan Metot ve Snf Yaplar ........................................................................... 8

7.1 Metot zetleri ................................................................................................. 9

7.2 Metot Detaylar ............................................................................................... 9

7.2.1 sendDocument ......................................................................................... 9

7.2.2 getApplicationResponse .......................................................................... 9

7.3 Kullanlan Snf zetleri ................................................................................... 9

7.4 DocumentRequest Snf Metotlar................................................................ 10

7.5 DocumentResponce Snf Metotlar ............................................................. 10

7.6 DocumentReturnType Snf Metotlar .......................................................... 11

7.7 DocumentType Snf Metotlar ..................................................................... 11

7.8 GetAppRespRequest Snf Metotlar ............................................................ 12

7.9 GetAppRespRequestType Snf Metotlar .................................................... 12

7.10 GetAppRespResponse Snf Metotlar ...................................................... 12

7.11 GetAppRespResponseType Snf Metotlar .............................................. 13

8 Dnlen Aykr Durum(Exception) Kodlar ........................................................... 13


Versiyon : 1.2 5/14

1 Giri Bu klavuz, Elektronik Fatura Uygulamasna entegre olmak isteyenler ile uygulamaya

ilikin yazlm gelitireceklerin uymak zorunda olduklar yazlm standartlar ve nesne

yaps hakknda bilgi vermek amacyla hazrlanmtr.

Elektronik Fatura Uygulamasnn genel zellikleri aada yer almaktadr.

Uygulama ierisinde teknolojik iletiim altyaps olarak Web servis

kullanlmtr.

Web servis iletiim altyaps SOAP mesajlar ile salanmaktadr. SOAP

metotlar iin iki tr kodlama metodu bulunmaktadr. Bunlar RPC ve DOC

kodlamalardr. Uygulamada performans asndan DOC kodlamas

benimsenmitir. SOAP mesajlarnn iletiminde byk dosyalar sz konusu

olduundan MTOM (Message Transmission Optimization Mechanism)

mekanizmas kullanlmtr.

Web Servis belirtiminin dier web servis gerekletirimleri ile sorunsuz

alabilmesi iin WS-I ve WS-I Basic Profile standartlar web servis

gerekletiriminde dikkate alnmtr.

Klavuzun ilk blmnde MTOM mekanizmas genel olarak tantlacak, sonraki

blmlerde ise tanmlanan Web Servis metotlar ve metotlarn kulland parametre,

dn deeri ve nesneler ile ilgili bilgilere yer verilecektir.

2 MTOM (Message Transmission Optimization Mechanism)

MTOM ikilik verilerin etkin bir biimde web servislerden veya web servislere

gnderimini salayan bir metottur. kilik veriyi gndermek iin XOP(XML-binary

Optimized Packaging) kullanr. MTOM byk miktarda ikilik veriyi SOAP mesajyla

gnderme imkn salamakta olup aada sralanan 3 nemli yarar bulunmaktadr.

Gvenlik: MTOM, gvenlikle oluur, verilerin gvenlii SOAP mesaj kadar iyi

korunur. Ayrca DIME'nin desteklemedii baz gvenlik seviyeleri de MTOM


Versiyon : 1.2 6/14

ile desteklenmektedir. (rnein: TCP analizi DIME ile yaplan transferde

gerekletirilirse, dosyann grld grnr ancak MTOM, dosya iine

SOAP mesajna uygulanan gvenlii uygulayabilmektedir.)

Dosya Boyutunun Korunmas: MTOM sayesinde hat zerinde ekstra yk

olumaz ve bylece dosya boyutu korunmu olur.

Basit Programlama Modeli: MTOM destei etkinletirilerek servisteki btn

byte transferleri otomatik olarak ifrelenir.

MTOMin web servis ile uygulamalar eitli web servis gerekletirim rnleriyle

salanmtr. Bunlara rnek axis2 ve Microsoft web servisleri rnek verilebilir.

3 XAdES XAdES, Elektronik Fatura Uygulamas kapsamnda gnderilecek olan belgelerin

(Fatura veya Uygulama Yant) imzalanmas veya onaylanmasnda kullanlmaktadr.

XAdES imzalamada minimum olarak XAdES-BES kullanlmaktadr. XML imzalama iin

Enveloped teknii kullanlmaldr. Enveloping ve Detached teknikleri kabul

edilmeyecektir.

e-Fatura onaylama ileminde bir faturann XML imza olarak minimum aadaki XML

etiketlerini kullanmas gerekmektedir.


Versiyon : 1.2 7/14

Mesaj zetlerinin gvenlik asndan SHA256 olmas nerilmektedir. Yukarda verilen

XAdES xml imza iskeletinde bulunan alanlar mutlaka kullanlmaldr. skelette verilen

nitelik(attribute) deerleri rnek tekil etmesi amacyla verilmitir.

XML imzann (mali mhr) dorulanmas iin kullanlabilecek web siteleri ile eitli

yazlmlar mevcut olup, entegrasyon almas yapan mkellefler bu kaynaklar

yardm ile XML imza (Mali Mhr) kontroln yapabilirler.


Versiyon : 1.2 8/14

4 Sktrma Standard Hazrlanan zarflar zip format ile sktrlmaldr. Zip dosyas sktrma algoritmas

standart zip format olmaldr. Gzip, rar gibi formatlar kullanlmamaldr.

5 Mesaj zeti Standard Elektronik Fatura Uygulamas aracl ile gnderilecek olan belgelerin Zarf XMLi

ierisine konulmas gerekmektedir. Bu XML, zip formatnda sktrldktan sonra Web

servis aracl ile gnderilecektir. Web servis ile bu zip belgesine ait mesaj zeti de

(hash) gnderilmesi uygulama ierisinde beklenen bir durumdur.

Mesaj zeti standard olarak MD5 standardna uyulacaktr. Alnan ve gnderilen

belgelere ait zet deerleri hesaplanacak ve gelen deerler ile karlatrlacaktr.

zet deerleri 32 karakter uzunluunda olacaktr.

6 SSL Mekanizmas Web servis iletiimi HTTPS protokol zerinden SSL mekanizmas ile salanacaktr.

Buna gre istemci uygulamas SSL sunucu uygulamasnn kimliini dorular. Bu

durumda Elektronik Fatura Uygulamasnda bulunan birimlerin gvenilir sunucu

sertifikas temin etmeleri ihtiyatr. Mkelleflerin SSL sunucu sertifikalarn Verisign,

GlobalSign gibi gvenilir sertifika salayclarndan almalar gerekmektedir.

e-Fatura Uygulamasna entegre olacak kurumlarn uygulamalar SSL sunucu sertifikas

ile almaldr. Temin edilen sertifikalar ile web servis yazlmnn uyumu ve

alabilirlii salanmaldr.

7 Kullanlan Metot ve Snf Yaplar Bu blmde anlatlan metot ve snf yaplar Java programlama dili ve axis2

gerekletirimi ile olumu rnek yaplardr. Oluacak metot ve snf yaplar deiik

programlama dilleri ve web servis gerekletirimleri ile deiebilir.


Versiyon : 1.2 9/14

7.1 Metot zetleri

DocumentResponse sendDocument(DocumentRequest request)

Kullancnn zarflarn gnderecei metottur.

GetAppRespResponse getApplicationResponse(GetAppRespRequest request)

Kullancnn zarflarn durumunu sorgulad metottur.

7.2 Metot Detaylar

7.2.1 sendDocument

public DocumentResponse sendDocument(DocumentRequest request) throws EFaturaFaultMessage

Kullancnn zarflarn gnderilecei metottur. kilik veriyi(Binary Data), dosya adn ve

ikilik verinin zetini ieren DocumentRequest nesnesi alr ve kendi hesaplad zet

deeri ile mesaj ieren DocumentResponse nesnesini dner.

Throws: EFaturaFaultMessage

7.2.2 getApplicationResponse

public GetAppRespResponse getApplicationResponse(GetAppRespRequest request) throws EFaturaFaultMessage

Kullancnn zarflarn durumunu sorgulad metottur. Zarf IDyi ieren

GetAppRespRequest nesnesini alr ve sistem yantn ieren GetAppRespResponse

nesnesini dner.

Throws: EFaturaFaultMessage

7.3 Kullanlan Snf zetleri

DocumentRequest sendDocument metoduna parametre olarak


Versiyon : 1.2 10/14

verilen snftr.

DocumentResponse sendDocument metodundan dnlen snftr.

DocumentReturnType Mesaj ve zet niteliklerini ieren snftr.

DocumentType kili veri, dosya ad ve zet niteliklerini ieren

snftr.

GetAppRespRequest getApplicationResponse metoduna parametre

olarak verilen snftr.

GetAppRespRequestType getApplicationResponse metodundan dnlen

snftr.

GetAppRespResponse Zarf id niteliini ieren snftr.

GetAppRespResponseType Sistem Uygulama Yantn ieren snftr.

7.4 DocumentRequest Snf Metotlar

DocumentType getDocumentRequest()

DocumentType nesnesini dner.

void setDocumentRequest(DocumentType param)

DocumentType nesnesine parametre ile verilen nesneyi atar.

7.5 DocumentResponce Snf Metotlar

DocumentReturnType getDocumentResponse()

DocumentReturnType nesnesini dner.



Void setDocumentResponse(DocumentReturnType param)

DocumentReturnType nesnesine parametre ile verilen

nesneyi atar.

7.6 DocumentReturnType Snf Metotlar

String getHash()

kili verinin zet deerini dner.

String getMsg()

Mesaj dner.

void setHash(String param)

param ile verilen deeri Hashe atar.

void setMsg(String param)

param ile verilen deeri Msga atar.

7.7 DocumentType Snf Metotlar

Base64Binary getBinaryData()

kili (binary) veriyi dner.

String getFileName()

Gnderilen zarfa ait dosya adn dner.

String getHash()

kili verinin zet deerini dner.

void setBinaryData(Base64Binary param)

Bu ksma XML formatnda oluturmu zarfn, ZIP format ile

sktrlm halinin Base64 ile encode edilmi hali yazlacaktr.



void setFileName(String param)

Bu ksma XML formatnda oluturulmu ve daha sonra ZIP

formatnda sktrlm zarfn ad yazlacaktr. Zarf adnn

uzantsnn zip olmas gerekmektedir. Zarf adnn ise e-Fatura

Uygulamas Teknik Klavuzlar Ek-1 e-Fatura Uygulamas Zarf

ema Yaps dokmannda belirtilen InstanceIdentifier deeri

ile ayn olmaldr.

void setHash(String param)

Bu ksma XML formatnda oluturulmu ve daha sonra ZIP format

ile sktrlm zarfn MD5 zeti yazlacaktr.

7.8 GetAppRespRequest Snf Metotlar

GetAppRespRequestType getGetAppRespRequest()

GetAppRespRequestType nesnesini dner

Void setGetAppRespRequest(GetAppRespRequestType param) GetAppRespRequestType nesnesine parametre ile

verilen nesneyi atar.

7.9 GetAppRespRequestType Snf Metotlar

String getInstanceIdentifier()

Zarf idyi dner.

void setInstanceIdentifier(String param)

Zarf idye parametre ile verilen deeri atar.

7.10 GetAppRespResponse Snf Metotlar

GetAppRespResponseType getGetAppRespResponse()



GetAppRespResponseType nesnesini dner.

Void setGetAppRespResponse(GetAppRespResponseType param)

GetAppRespResponseType nesnesine paramere ile

verilen nesneyi atar.

7.11 GetAppRespResponseType Snf Metotlar

String getApplicationResponse()

Uygulama Yantn dner.

void setApplicationResponse(String param)

Uygulama Yantna parametre ile verilen deeri atar.

8 Dnlen Aykr Durum(Exception) Kodlar Aykr durum kodlar iin WSDLde belirtilen EFaturaFaultMessage yaps

kullanlmaldr. EFaturaFaultMessage yapsnn alabilecei aykr durum kodlar ve

aklamalar aadaki tabloda belirtilmitir.

Hata Kodu Hata Aklamas

2000 OZET DEGERLER ESIT DEGIL

2001 ZARF ID SISTEMDE_MEVCUT

2002 ZARF ARSIVE EKLENEMEDI

2003 ZARF KUYRUGA EKLENEMEDI

2004 ZARF ID BULUNAMADI

2005 SISTEM HATASI

2006 GECERSIZ ZARF ADI



rnek:

EFaturaFaultType faultType=new EFaturaFaultType(); EFaturaFault fault=new EFaturaFault(); EFaturaFaultMessage faultMessage=new EFaturaFaultMessage();

faultType.setCode(code)); faultType.setMsg(msg); fault.setEFaturaFault(faultType); faultMessage.setFaultMessage(fault);

throw faultMessage;

Not:

WSDL hata yapsn(WSDL:fault) direk desteklemeyen programlama dilleri/aralar

iin de standartlama asndan EFaturaFaultMessage retilmelidir.

Dndrlen SOAP mesaj yaplandrlarak EFaturaFaultMessage retmek

mmkndr. rnein .Net iin WSDL:fault aralar ile retilemiyorsa

SOAPExceptionn metotlar kullanlarak retilebilmektedir. SoapFault detay(detail)

ksm aadaki mesaja benzemelidir.

2000 OZET DEGERLER ESIT DEGIL

ek-3 e-fatura uygulamasi yazilim standartlari ve nesne yapisi - v1.2

Documents