TehniĊka specifikacija G2B servisa v1.2
[pic][pic]
G2B Service Technical Specification
Version 1.2
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Changelog | |
Changelog
|Edi. |Rev. |Date |Description |Authors |
|0 |4 |22/09/2009 |Initial version | |
|1 |0 |05/03/2010 |first officially announced document version | |
|1 |1 |22/12/2010 |Enhancement of the first officially published version | |
|1 |2 |20/07/2011 |Enhancement of the description of sending from the | |
| | | |Customs to an economic operator | |
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Table of Contents | |
Table of Contents
1. Introduction 7
1.1. Glossary 8
2. The basic features of G2B service 9
3. G2B service usage 10
1. Sending of documents to the Customs for processing 10
2. Receiving the documents from the Customs 11
3. Auxiliary operations 11
4. G2B service usage scenarios 12
1. Sending of documents to the Customs 12
2. Receiving the documents from the Customs 14
4. Description of G2B service operations 15
4.1.1. The G2B document 17
4.1.1.1. Main sections of G2B document 18
2. The "sendDocument" operation 19
3. The "getSentDocument" operation 19
4. The "listSentDocuments" operation 20
5. The "listMsgBox" operation 20
6. The "getDocument" operation 21
7. The "acknowledge" operation 21
5. G2B Service Technical Specification 22
1. The standards used during the development of G2B service 22
2. WSDL description 22
3. Technical specification of the G2B document's electronic signature 23
1. The electronic signature 24
2. 26
3. 26
4. 27
5. 27
6. XAdES extensions - signed properties 27
7. XAdES extensions - unsigned properties 29
8. Distinctive properties of the electronic signature of the G2B service when the Customs sends the document to the economic operator 30
Annex A: Code books 31
Page 3 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Table of Contents | |
Annex B: The XML scheme of G2B document 32
Annex C: G2B service WSDL 36
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Figure list | |
Figure list
Figure 1: Architecture concept 7
Figure 2: UML sequential diagram of sending messages to the IS CCA 10
Figure 3: UML sequential diagram of receiving messages from the IS CCA 11
Figure 4: G2B document version for the direction from the economic operator to the Customs 17
Figure 5: G2B document version for the direction from the Customs to the economic operator 18
Figure 6: Procedure of creating the electronically signed document 23
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Table list | |
Table list
Table 1: G2B service operations 16
Table 2: Possible responses from the "getSentDocument" operation 20
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|1. Introduction | |
1. Introduction
From the organizational and business perspective the G2B1 service is the part of the Customs administration effort within the eCustoms to establish the document exchange process with the economy.
In the implementation sense, the G2B service is a part of joint infrastructure of the Information System of the Croatian Customs Administration (IS CCA) responsible for the integration of IS CCA with business applications of the economic operators, based on principles of document exchange. The G2B service has been technologically implemented as a web service (SOAP / HTTPS) available on the Internet.
This document only describes the technical specification of the G2B service without the details referring to the specific use per each application (e.g. NCTS, ECS, EMCS,...). Specifics of G2B service relating to the specific application are described in separate documents which are a part of the complete documentation for the particular application.
While designing the G2B service, the imperative has been the interoperability between different computing technologies and implementation of open standards.
The Figure below illustrates the position of G2B service within the entire IS CCA environment.
[pic]
HR National Domain
HR external domain
Common EU Domain
National Domain (Member States)
Joint IS CCA Services (infrastructure)
Guarantees
Risk analysis rizika
Guarantees
1 In previous versions of this document, the B2G abbreviation was used (for both the service and the document) which has been changed by Customs decision into G2B. Where possible (free text) the old abbreviation was replaced by the new one, but all technical parts of the specification (XSD, WSDL,...) preserved their old names for pragmatic reasons.
Page 7 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|1. Introduction | |
1.1. Glossary
|Term |Description |
|economic operator's application |the application or the system which the economic operator uses for the communication with the |
| |Customs information system |
|application sub-system |Customs application or its sub-system (e.g. NCTS, ECS, EMCS,...) |
|G2B document |XML data structure (form), which, in addition to the business document being the subject of |
| |the exchange, contains the document metadata, as well as the metadata required for the |
| |communication and the electronic signatures |
|B2G document |same as the "G2B document" |
|electronic signature |A data set in the electronic form, joined or logically connected with other data in the |
| |electronic form, used for the identification of signers and authenticity of the electronically|
| |signed document |
|ETSI |European Telecommunications Standards Institute |
|economic operator |a legal entity communicating with the Customs |
|IS CCA |Information System of the Croatian Customs Administration |
|qualified certificate |every electronic certificate issued by the qualified certification service provider to perform|
| |the authentication of the advanced electronic signature |
|qualified attester |Trading company or craft business in the role of a certification service provider issuing |
| |qualified certificates. Publicly announced electronic form of qualified attesters' list or |
| |"Directory of the qualified attesters" can be found at the "" web |
| |address. |
|advanced electronic signature |The electronic signature having the same legal force and replacing the handwritten signature |
| |or handwritten signature and the stamp-imprint. It reliably guarantees the identity of the |
| |signer. It is solely associated with the signer. It undoubtedly identifies the signer. It |
| |originates by using the resources the signer can independently control being solely under the |
| |signer's control. It contains the direct connection with data referring to, and in the manner |
| |that undoubtedly enables the review of any source data changes. |
|QCP |Qualified Certificate Policy |
|NCP |Normalized Certificate Policy |
|LCP |Lightweight Certificate Policy |
|person authorized by the economic operator |Natural person authorised by economic operator and Customs for the electronic signing and |
|(authorized person) |sending of documents to the IS CCA applications. This term equals the term "declarant". |
|SOAP |communication protocol, platform independent, based on the XML and used for data exchange |
| |between the applications (Simple Object Access Protocol) |
|trader |see "economic operator" |
|XAdES |ETSI standard supporting the advanced electronic signature. It extends the XML-DSig standard |
| |in terms of support for the advanced electronic signature. |
|XML-DSig |W3C recommendation which defines the XML syntax for the digital signing |
Page 8 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|2. The basic features of G2B service | |
2. The basic features of G2B service
The primary purpose of the G2B service is the exchange of the electronic documents between the IS CCA and the economic operator's information systems.
G2B service has the following features:
* G2B service is used for the exchange of electronic documents between the economic operator and the IS CCA. It has been technologically realised as web service (SOAP / HTTPS) and uses the Internet as communication channel
* G2B service uses HTTPS (HTTP over the SSL protocol) as a transport protocol and authentication at the communication level (so-called SSL mutual authentication) while normalised (authentication) certificates are issued by qualified attesters. By the authentication certificates G2B service determines the identity of the economic operator based on which the authorisation check is performed.
* Preconditions for using the G2B service are the registration of the economic operator, the authentication of the certificates and the authorised person, and this procedure has been described in the separate document.
* The communication initiator is always the economic operator, and it does not matter whether documents are being sent from the economic operator to IS CCA or vice versa
* In case of exchange, the document is saved within the so-called G2B document which, in addition to the business data, contains the corresponding metadata and the electronic signature. The electronic signature inside the G2B document is the "enveloped" type, in the accordance with the XAdES standard (the advanced electronic signature is supported) and it refers to the electronic document which is the subject of the exchange, as well as the corresponding metadata.
* The electronic signature serves for the purposes of the identification and authentication of parties which are signing and exchanging the electronically signed documents. For the electronic signing of the G2B document contents, an economic operator's authorised person uses the signature (qualified) digital certificates issued by qualified attesters. The economic operator's authorised person for the electronic signing can only use certificates registered by the Customs administration and at the same time granted the operating authorisation for the specific application.
* After receiving electronically signed G2B document the G2B service will verify it with its own (Customs) electronic signature and return it to the economic operator as a confirmation of successful receiving.
* When sending the documents from the IS CCA to the economic operator the "pull" protocol is used, meaning that documents designated for the specific economic operator are delivered to his "message box", and the economic operator is obliged to periodically check the contents of its "message box".
* Reliability of message exchange has been implemented in the design of the G2B service, as well as within the protocol used by the G2B service.
* The documents being exchanged can be in different formats (XML, PDF, Word, ZIP,...) and the G2B service will not check or modify their contents.
Page 9 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|3. G2B service usage | |
3. G2B service usage
This chapter describes the G2B service usage from the perspective of document exchange protocol and in both directions (from the economic operator to the Customs application and vice versa).
3.1. Sending of documents to the Customs for processing
After the creation of business document, the economic operator's application saves it within the so-called G2B document (a detailed description of the structure can be found in chapter 4.1.1). In addition to the business data, the metadata required for the operation of the exchange process are also saved within the G2B document, such as the application sub-system identification (AppId), economic operator identification (TraderId), economic operator's application identification (TraderAppId) and the unique message identifier assigned by the economic operator (TraderMsgId). It also contains the metadata describing the business document.
The G2B document prepared in this way is signed by the authorised person by using the advanced electronic signature and the economic operator's application sends it to the IS CCA by using the "sendDocument" operation of the G2B service.
The G2B service checks the authorised person's electronic signature and authorisation. If they are both valid, it then sends the business data to the Customs application. At the same time, the economic operator's application returns the received G2B document, now extended with the electronic signature of the Customs G2B service. In case of any errors (invalid signature, authorised person not authorised...) it sends the "SOAP Fault" message with the corresponding text.
If, for any reason, the economic operator's application has not received the response (SendDocumentResponse or SOAP Fault message), it can use the "getSentDocument" operation to check the status of the sent message by using the local (economic operator's) identification message (TraderMsgId).
[pic]
Figure 2: UML sequential diagram of sending messages to the IS CCA
Page 10 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|3. G2B service usage | |
3.2. Receiving the documents from the Customs
The document exchange for the direction from the Customs to the economic operator is performed by using the "listMsgBox" and "getDocument" operations. The "listMsgBox" operation is used to read the economic operator's "message box" contents to get the list of identifiers for non-received documents. After getting the list, the economic operator's application gets the documents one at a time by using the "getDocument" operation. When the document has been successfully received, the economic operator's application must confirm the receiving by using the "acknowledge" operation. Only after receiving the certain document has been confirmed, this document will no longer appear on the list returned by the "listMsgBox" operation.
[pic]
Figure 3: UML sequential diagram of receiving messages from the IS CCA
3.3. Auxiliary operations
For the purposes of checking the validity of sending, as well as for the purpose of eliminating errors in economic operator's applications, the "listSentDocuments" operation has been introduced, which the economic operator can use to get the list including all the messages (from economic operator and Customs) containing the specified correlation identifier (corId) for the particular application sub-system (AppId), as well as the "echo" operation to verify that G2B service is available.
Page 11 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011. |
|3. G2B service usage | |
3.4. G2B service usage scenarios
This chapter explains in detail the typical usage scenarios for the G2B service in a way that the successful scenario has been provided for a particular case, and also the possible scenarios with exceptions.
3.4.1. Sending of documents to the Customs
Preliminary work:
The economic operator's application has created the business document, saved it in the "G2B document" together with the required metadata, and has allowed the authorised person to electronically sign the G2B document with his/her own qualified certificate.
Steps in case of the successful sending:
1. The economic operator's application has successfully connected with the G2B service by using the HTTPS protocol, including the successful authentication and the identification of economic operator based on the authentication certificates.
2. The economic operator's application sends the G2B document by using the "sendDocument" operation of the G2B service.
3. The G2B service checks that the economic operator is authorised to operate the application sub-system
4. The G2B service checks the formal integrity of the G2B document
5. The G2B service checks the electronic signature, from the electronic signature it reads and verifies the identity of the signer and verifies that the signer is authorised by the economic operator and the Customs administration to operate the abovementioned application sub-system.
6. The G2B service redirects the received document to the application for the purpose of
processing.
7. The G2B service returns the response to the economic operator's application in the form of "G2B document" extended with the "DocUuid" and "ReceiveTimestamp" attributes and additionally signed by the Customs certificate.
Steps 1 and 3 are applicable to all sending requests (in all operations).
Exception scenarios:
1. The economic operator's application tries to establish the communication link (HTTPS) with the G2B service.
2. After N seconds of unsuccessfully trying to establish the communication with the G2B service, the economic operator's application triggers time-out.
3. The economic operator's application waits a few minutes and tries to reconnect.
4. If the connection fails to establish after the several repeated time-outs, the economic operator is obliged to check the proper functioning of its application and Internet communication links, and use the "echo" G2B service method to check that the service is available (not necessarily in that order). If the economic operator determines that the problem is at the G2B service side, it is obliged to contact the Customs Call centre.
Page 12 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|3. G2B service usage | |
2.1 When calling the "sendDocument" operation, the economic operator's application receives the error message (E007) instead of the response, which means that the economic operator is not authorised for operating the G2B service. This case applies to all operations of the service.
3.1 When calling the "sendDocument" operation, the economic operator's application, instead of the response receives the error message with the error (E005) which means that the economic operator was not authorised for operation with the application. This case applies to all operations of services.
4.1 When calling the "sendDocument" operation, the economic operator's application, instead of response receives the error message (E006) which means that provided data in the request of operation is not correct. This case applies to all operations of services.
1. When calling the "sendDocument" operation, the economic operator's application, instead of response receives the "fault" message with the warning (W001) which means that the assigned "TraderMsgId" attribute of the message is already used.
2. The economic operator's application checks the status of the message with the assigned "TraderMsgId" attribute (from the step 2.1) using the "getSentDocument" operation. The response of the "getSentDocument" operation will contain the received G2B document, with the requested "TraderMsgId", or the error message with the corresponding code and the description of the error (see 4.1, 5.1 and 6.1).
1. When the economic operator's application calls the "sendDocument" operation, but the G2B service experiences internal problems and returns the error message (E001). This case applies to all operations of the service.
2. The economic operator's application retries to send the message after waiting for 5 minutes and if, in the meantime and by other channels, it does not receive the official information that the G2B service is inaccessible. In case that after many repeated cycles (sending, waiting) the G2B service still returns the error, it is required to contact the Customs Call Centre.
1. The economic operator's application calls the "sendDocument" operation and at the same time it sends the SOAP message which is not a valid XML document. This case applies to all service operations.
1. The G2B service returns the error message(E002)
1. The economic operator's application calls the "sendDocument" operation and at the same time it sends the G2B document with invalid electronic signature.
1. The G2B service returns the error message(E003)
1. The economic operator's application calls the "sendDocument" operation and at the same time it sends the G2B document which is electronically signed by the person who is not authorised to operate the mentioned application sub-system.
1. The G2B service returns the error message (E004)
Page 13 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|3. G2B service usage | |
3.4.2. Receiving the documents from the Customs
Preliminary work:
The Customs application delivers the document to the economic operator's "message box".
Steps in case of the successful sending:
1. The economic operator's application successfully connects with the G2B service by using the HTTPS protocol, including the successful authentication of the economic operator's client certificate and the economic operator's identification.
2. The economic operator's application calls the G2B service's "listMsgBox" operation.
3. The G2B service verifies whether the economic operator is authorised to operate the application sub-system.
4. The G2B service returns a list with document data which satisfy the required condition (according to the "CorId" and "AckStatus" attribute values) to the economic operator's application.
5. Based on the received list with document data, the economic operator's application gets the document from the message box by using the "getDocument" operation, one at a time.
6. After it successfully gets the documents from the message box, the economic operator's application confirms receiving of the documents by using the "acknowledge" operation
Steps 1 and 3 are applicable to all request sends (on all operations).
Exception scenarios:
1.1 When calling the "getDocument" operation, the economic operator's application, instead of response (the G2B document) gets the error message (W003) that the document with mentioned "DocUuid" does not exists.
In addition, exceptions are possible, similar to those already described in the scenario for sending documents to the Customs, namely under 1.1-1.4, 2.1, 3.1, 4.1, 6.1-6.2 and 7.1-7.2.
Page 14 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|4. Description of G2B service operations | |
4. Description of G2B service operations
The table below specifies the G2B service operations with requirement attributes and response attributes.
|Operation name |Request |Response |
|sendDocument |SendDocument |SendDocumentResponse |
| |B2GDocument |B2GDocument |
| |RequestHeader |RequestHeader |
| |AppId |AppId |
| |TraderId |TraderId |
| |TraderAppId |TraderAppId |
| |TraderMsgId |TraderMsgId |
| |Content |ResponseHeader |
| |DocType |DocUuid |
| |MimeType |ReceiveTimestamp |
| |Description |Content |
| |Data |DocType |
| |Encoding |MimeType |
| |Signature |Description Data |
| | |Encoding Signature |
|getSentDocument |GetSentDocument |GetSentDocumentResponse |
| |AppId |B2GDocument |
| |TraderId |RequestHeader |
| |TraderAppId |AppId |
| ||TraderMsgId |TraderId |
| ||DocUuid |TraderAppId |
| | |TraderMsgId ResponseHeader |
| | |DocUuid |
| | |ReceiveTimestamp Content |
| | |DocType |
| | |MimeType |
| | |Description |
| | |Data |
| | |Encoding Signature |
Page 15 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|4. Description of G2B service operations | |
|Operation name |Request |Response |
|listSentDocuments |ListSentDocuments |ListSentDocumentsResponse |
| |AppId |AppId |
| |TraderId |TraderId |
| |TraderAppId |TraderAppId |
| |CorId |SentDocumentsList[] DocUuid TraderMsgId |
| | |Description CorId DocType ReceiveTimestamp |
|listMsgBox |ListMsgBox |ListMsgBoxResponse |
| |AppId |AppId |
| |TraderId |TraderId |
| |TraderAppId |TraderAppId |
| |CorId* |MsgList[] |
| |AckStatus* |DocUuid CorId DocType DocTimestamp |
|getDocument |GetDocument |GetDocumentResponse |
| |AppId |B2GDocument |
| |TraderId |RequestHeader |
| |TraderAppId |AppId |
| |DocUuid |TraderId |
| | |TraderAppId |
| | |DocUuid |
| | |Content DocType MimeType Data |
| | |Encoding |
| | |Signature |
|acknowledge |Acknowledge |AcknowledgeResponse |
| |AppId |AppId |
| |TraderId |TraderId |
| |TraderAppId |TraderAppId |
| |DocUuid[] |DocUuid[] AcknowledgeTimestamp |
|echo |Echo |EchoResponse |
| |Msg |Msg SeverTime |
|Table 1: G2B service operations |
* Optional attributes; [] identification flag for the attribute list
Page 16 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|4. Description of G2B service operations | |
The section below provides the description of the "B2GDocument" XML structure which has a specific role in exchange of business documents, as well as the separate description of each operation.
4.1.1. The G2B document
In the case of document exchange in both directions (from the economic operator towards the IS CCA and vice versa) the G2B service operations use the specific structure (form) called the G2B document (technically it is XML according to the "B2GDocument.xsd" scheme or "B2GDocument XML"). In addition to the business data, the G2B document contains metadata required for the exchange and the enveloped electronic signature which refers to business data according to the XAdES standard. The XML scheme "B2GDocument.xsd" has been included as the annex ("Annex B: the XML scheme of G2B document ")
From the aspect of using the electronic signature and filling in the certain document parts, we can distinguish the following B2GDocument XML usage versions:
1a. B2GDocument XML which economic operator sends to the Customs
1b. B2GDocument XML by which the Customs confirms receiving to the economic operator (1a. extended with the "CounterSignature" electronic signature)
2. B2GDocument XML which the Customs sends to the economic operator
The figures below are illustrating the details of the mentioned B2GDocument XML versions:
[pic]
1a. B2GDocument XML which economic operator 1b. B2GDocument XML by which the Customs
sends to the Custom confirms receiving to the economic operator
Figure 4: Versions of the G2B document for the direction from the economic operator to the Customs
Page 17 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|4. Description of G2B service operations | |
[pic]
2. B2GDocument XML which the Customs sends to the economic operator
Figure 5: Version of the G2B document for the direction from the Customs to the economic operator
Version 2 of the B2GDocument XML is the one returned by the "getDocument" operation.
4.1.1.1. Main sections of the G2B document
The main sections of the G2B document are "RequestHeader", "ResponseHeader", "Content" and "Signature".
The "RequestHeader" section contains the data regarding the applicative sub-system (AppId), the economic operator's identification (TraderId), and the identification of the economic operator's application (TraderAppId). In addition to the mentioned data, the "RequestHeader" section also contains the economic operator's identification message (TraderMsgId) or the unique identifier of the (received) document (DocUuid) depending on the G2B document's usage context. In case when the economic operator sends a document to the Customs, the "TraderMsgId" is used, while in the opposite direction the "DocUuid" is used. The value of the "AppId" attribute is from the standard Code book of Customs applications (see Annex A), and "TraderId" is from the registry office of economic operators (contains the Company Identification Number of the economic operator). "TraderAppId" is used for the statistical monitoring of work of economic operator's applications and the communication between the Customs and the economic operator with the purpose to eliminate errors It is recommended that the provided "TraderAppId" contains the data regarding the application's developer and the its in-house version. If multiple economic operators use the same application, it is recommended for them all to use the same value of this attribute, suggesting that this value is determined by the developer.
The ResponseHeader section contains the data assigned by the G2B service to the received document during the "sendDocument" operation. It is a unique identifier of the received document (DocUuid) and the timestamp of its receiving (ReceiveTimestamp). This section is only used within a G2B document which is returned as the response to the "sendDocument" request operation.
The Content section contains business data (Data) and metadata describing them. The "DocType" attribute determines the business meaning (business message type), the "Encoding" attribute determines the data encoding method ("EMBEDDED" for text or XML, "BASE64" for other formats), the "MimeType" attribute determines the business data format, and the "Description" provides the option for the economic operators to add their own description.
Page 18 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20.07.2011. |
|4. Description of G2B service operations | |
The Signature section is reserved for the electronic signature of the data from the abovementioned sections. Since this section is optional at the technical level, the exchange of business documents by using the G2B document can also be performed without the electronic signature if this has been agreed on, and this is regulated at the business sub-system level. A detailed description on how to use this section or use the electronic signature is provided in a separate chapter.
4.1.2. The "sendDocument" operation
By using the "sendDocument" operation, the economic operator's client application sends business data to the IS CCA sub-system.
The operation's request carries the G2B document composed in accordance with the rules described in the previous chapter. After the G2B service receives the request, the electronic signature is verified, as well as the formal integrity of the G2B document. Based on the electronic signature, the identification of the responsible person is performed and it is then verified whether or not this person is authorised to operate the mentioned application sub-system. Every received G2B document gets its unique identifier (DocUuid). In addition to the mentioned checks, the check of uniqueness of the economic operator's message identification (TraderMsgId) is also performed.
If all checks have successfully passed, the operation returns the G2B document filled in with the unique document identifier (DocUuid) and the timestamp of its receiving (ReceiveTimestamp). In case that any check fails, the SOAP Fault message is returned with the corresponding explanation.
"TraderMsgId" must have a unique value at the application sub-system level for all client applications of the economic operator and it is used to establish the reliability of message transfer. The reliability of message transfer is visible from the fact that the economic operator, by using the message id, can always see what the G2B service did receive. If the same value of the "TraderMsgId" attribute gets repeated, the operation will return an error and it will not receive the sent G2B document.
4.1.3. The "getSentDocument" operation
The "getSentDocument" operation is used by the economic operator to get the sent documents and it is generally not used during the regular course of work.
One situation when this operation is suitable is is when, while using the "sendDocument" operation, a session interruption occurs between the economic operator's client application and the G2B service, before receiving the response. By using the "getSentDocument" operation together with stating the "TraderMsgId", the economic operator's client application can subsequently receive the response which the "sendDocument" operation should have returned. The operation's response depends on the message's status and can have various forms and values. Possible responses are provided in the following table:
Page 19 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011. |
|4. Description of G2B service operations | |
| |Message status |Answer form |
|1. |Message is received as formally correct |GetSentDocumentResponse |
| | |B2GDocument (including DocUuid and ReceiveTimestamp |
|2. |Message is received as formally incorrect |SOAP Fault message with the corresponding description |
|3. |There is no message with specified TraderMsgId |SOAP Fault message with the corresponding description |
| |attribute | |
| |Table 2: Possible responses of the "getSentDocument" operation |
The other usage of this operation is to test the economic operator's client application when it is required to check what the G2B service did receive. As a condition based on which the sent document can be found, the economic operator's message references can be specified (TraderMsgId) or the unique identifier of the (received) document (DocUuid).
After receiving, the documents are stored within the temporary database of received documents and they stay there within the next 6 months, but after that time they are no longer archived and become inaccessible to the "getSentDocument" operation.
4.1.4. The "listSentDocuments" operation
The "listSentDocuments" operation can be used by the economic operator to reach the list which containing all the documents (generated by the economic operator and the Customs sub-system) and which matches the specified values of the "AppId", "TraderId" and "CorId" attributes. This operation is only intended for the purposes of developing the economic operator's client application, as well as the subsequent verifications during the normal operation.
In case that economic operator needs to get the contents of a document specified within the list, the "getSentDocument" operation is used to retrieve messages created by the economic operator, while the "getDocument" operation is used for the message which originated from the Customs sub-system. Messages originating from the Customs sub-system can be identified since the "TraderMsgId" attribute contains the "*" value.
4.1.5. The "listMsgBox" operation
During the reception of business messages from the IS CCA to the economic operator's client application, the "message box" principle is used.
The "listMsgBox" operation is used to view the contents of the message box of the specific economic operator, and the search operation is narrowed down to the documents relating to the application specified within the "B2GHeader.AppId" attribute. By using the "CorId" optional attribute, the search result is narrowed down to the documents with the specified correlation identifier. The usage of the correlation identifier is defined at the application level and can be different for various applications and document types. With the additional "AckStatus" attribute it is possible to specify whether or not the list includes only the unconfirmed messages (AckStatus= "N"), only the confirmed messages (AckStatus="Y") or all messages (AckStatus= "A"). Default value of the "AckStatus" attribute is "N" (only unconfirmed messages), and it is forbidden to set the "AckStatus" to "Y" or "A" without specifying the "CorId" attribute as well.
Page 20 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|4. Description of G2B service operations | |
The result of this operation is a list of document identifiers (DocUuid) matching the values of the attributes specified during the operation request. In addition to the document identifier, for each document the value of the correlation identifier's (CorId) value is returned, as well as the document type (DocType) and document creation timestamp (DocTimestamp).
4.1.6. The "getDocument" operation
Based on the obtained list of documents from the message box, the reception of documents one by one follows, by using the "getDocument" operation. Within the operation request, a unique identifier of the required document (DocUuid) is specified.
As a reply, the operation returns the G2B document (see Chapter "4.1.1 The G2B document") signed by the Customs Administration's electronic certificate.
From the moment of its arrival into the economic operator's message box, the document remains there 6 months and it is possible to retrieve it any time during that period. After the expiration of 6 months, the document gets archived and is no longer available to the "getDocument" operation.
4.1.7. The "acknowledge" operation
The "acknowledge" operation is used to label the received documents within the message box as delivered, so that they can be distinguished from those not received (see the description of the "listMsgBox" operation).
As a result of this operation, and in addition to the "AppId", "TraderId" and "TraderAppId" attributes, a list of unique "verified" document identifiers is returned (DocUuid[]) as well as the acknowledge timestamp (AcknowledgeTimestamp). If the document was previously labelled as delivered, it will not appear on the returned list.
Page 21 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
5. G2B Service Technical Specification
5.1. The standards used during the development of G2B service
During the development of G2B service, the following standards are used:
* W3C Recommendation: "Extensible Markup Language (XML) 1.0".
* W3C Recommendation: "XML Schema Part 0: Primer"
* W3C Recommendation: "XML Schema Part 1: Structures"
* W3C Recommendation: "XML Schema Part 2: Datatypes"
* W3C Recommendation: "Simple Object Access Protocol (SOAP) 1.2"
* W3C Recommendation: "SOAP Message Transmission Optimization Mechanism"
* W3C Recommendation: "Web Services Description Language (WSDL) 1.1"
* W3C Recommendation: "XML-Signature Syntax and Processing"
* W3C Recommendation: "XML Encryption Syntax and Processing"
* ETSI TS 101 903 (V1.4.1): "XML Advanced Electronic Signatures (XAdES)".
* RFC 3339 "Date and Time on the Internet: Timestamps"
* RFC 3629 "UTF-8, a transformation format of ISO 10646"
All XML documents exchanged by using the G2B service must be in UTF-8 format. Date and time (timestamp) values must have a value of UTC time zone (according to the
"YYYY-MM-DDThh:mm:ssZ" format)
5.2. WSDL description
Web service for G2B document transfer uses the "xsd:base64Binary element within the WSDL" strategy. The document being transferred by using the service must be encoded in base64 format. WSDL does not provide a schema which defines the documents being exchanged. Instead of the specific G2B document definition, the "xsd:base64Binary" element is used, which only defines that the binary content is being transferred. The G2B document is provided in a separate XML scheme.
All other operations use types defined within the WSDL.
The G2B document's WSDL file contents and the XML scheme contents are provided in the annex.
Page 22 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
5.3. Technical specification of the G2B document's electronic signature
As already mentioned in previous chapters, one of the basic characteristics of the G2B document, in addition to the fact that it contains the business data and metadata for the exchange, is its ability to contain the advanced electronic signature of that data. The standard on which the format specifications of the document are based is XML Advanced Electronic Signatures (XAdES) - ETSI TS 101 903 V1.4.1
The document must be a valid XML document.
Figure 6 shows the design procedure of the electronically signed G2B document.
[pic]
The business message
The business message
The business message
The electronic signature
The signed B2G document
B2G document
Module for the electronic signing
Figure 6: The creation procedure of electronically signed document
XML Advanced Electronic Signatures (XAdES) [ETSI TS 101 903] defines the format which enables the storage of signed data, signatures and others properties associated with the electronic signature.
Based on the XAdES standard, a format has been developed for the G2B document which is required for document exchange between the information systems of Customs and the external information systems. The document format can be seen as a specialised profile of the XAdES standard..
Figure 6 shows that the document consists of data required for the data exchange between different information systems (Request header), the data itself (business message) and the electronic signature. The signature is in the enveloped form (contained within the document being signed).
Page 23 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
5.3.1. The electronic signature
All the data relating to the electronic signature are included within the / element. Depending on the usage of G2B documents, the / element can contain:
1. the advanced electronic signature of the economic operator's authorised person (version 1a. B2GDocument -> see Chapter "4.1.1 G2B document")
2. the advanced electronic signature of the economic operator's authorised person with the signature from the Customs G2B service, and which is used to sign the signature of economic operator's authorised person (the Customs note on the receipt of document) (version 1b. B2GDocument -> see Chapter "4.1.1 G2B document")
3. the electronic signature of Customs G2B service (version 2. B2GDocument -> see Chapter "4.1.1 G2B document")
Page 24 of 50
Below the structure of the B2GDocument XML is given, which includes the electronic signature of the authorised person and the Customs G2B service (content of the response by the "sendDocument" operation) since this structure includes all the abovementioned versions.
[pic]
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
[pic]
Parentheses are used to group the elements. Elements marked with the "+" sign must appear at least once. Elements marked with the "?" sign are optional and can appear only once. Elements marked with the "*" sign are optional, but can appear once or several times.
Page 25 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
Elements with the b2g belong within the XML namespace
""
Elements with the xades prefix belong within the XML namespace
""
The signature is located within the "Signature" element within the "" namespace (which uses the "ds" prefix) defined in the W3C reference of XML Signature Syntax and Processing (xmldsig-core) and it has the following structure:
* - XML-DSIG block with the data being signed
* - signature value
* - certificate used for signing and the associated public RSA key
* / - extension according to XAdES standard, defined within the namespace "". It contains:
o / -
additional data included into the signature. They include:
* - time of signing
* - data regarding the certificate used
for the signing
■ - signature policy
o/ -
unsigned data consisting of:
■ - countersignature
5.3.2.
The electronic signature is located within the element having the following attributes:
* Id - unique code number of the signature inside the document. Must contain the "SignatureId" value
* xmlns - XML namespace. Must be: "".
5.3.3.
Data being signed are located within the element which is within the same XML namespace, as well as the element. In case that the "xmlns" attribute is not explicitly specified, it is added automatically during the calculation of signature hash values. Signatures are canonised and the signing method is always RSA-SHA1 as seen in the and elements which have fixed contents:
Page 26 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
After these elements, one or more elements follow. Each element has the associated URI attribute which refers to the data being signed.
In case that a document being sent to Customs is being signed, it is mandatory to reference the following by using the URI attribute:
* URI="#ContentId" - reference to the original data
* URI="#RequestHeaderId" - reference to the data within the element
* URI="#SignedPropertiesId" - reference to the additional data added to the signature according to the XAdES upgrade. The element which contains the reference to the element must have the "Type" attribute with the value .
The element contains the , and elements.
The element contains:
The element has a value:
The element contains the value calculated by using the digest algorithm for the referenced element.
5.3.4.
The element contains base64 encoded value which represents the electronic signature within the element. This element has the "Id" attribute with its value in the Id="SignatureValueId" format.
5.3.5.
The element contains data regarding the certificate used for the document signing. The certificate is Base64 encoded in PEM format.
/ contains the Base64 encoded certificate.
5.3.6. XAdES extension - signed properties
The electronic signature follows properties defined with XAdES extension within the and elements.
Page 27 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
The attributes of the element:
* Target - value indicating the signature the Target="#SignatureId" refers to
* xmlns - XML namespace. Must be .
There are two types of properties: signed properties and unsigned properties.
Signed properties are stored within the element and are protected from modification by the hash value signed by the client and containing the URI="#SignedPropertiesId" identifier. These properties are referenced within the
// element with the attribute value
Type="".
The element has the attribute:
• Id - represents the identifier of signature and has a "SignedPropertiesId" value
Signed properties which are contained within the element:
• - time of signing on the computer by the signer, saved in
the UTC format "YYYY-MM-DDTHH24:MM:SSZ". Time zone value is always Z.
• - to protect the certificate modification, the following
attributes are signed within the element:
o / - always has a value
■
o / - the digest value of the certificate is
always the SHA256 digest
o / - serial number of the certificate issuer being signed
o / - identifier of the certificate
• - Description of rules for using the signature. According to the XAdES specification, it is mandatory to indicate the policy used. It contains the element within which the following elements can be found:
o - contains the explicit and unambiguous identifier of the policy used during the signing. In our case, the identifier has a value:
Rules for using the electronic signatures for eCustoms service
Page 28 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
o - contains the hash algorithm's (SHA256) identifier and the calculated hash value of the signature policy
• - contains the information regarding the signature production place.
It consists of the following elements:
o city of signing
o - state or province of signing
o - postal code
o - country name (Croatia)
5.3.7. XAdES extensions - unsigned properties
Unsigned properties are located within the element. Currently supported unsigned signature properties are within the
element. In case that the document has already been signed and its receipt must be confirmed (3rd version of the electronic signature), at this place there is an optional element, or countersignature.
In this specific case we have a simple electronic signature (not an advanced electronic signature) which serves as the acknowledgment of document receipt.
The CounterSignature format is shown in chapter 7.2.4 Countersignatures of document ETSI TS 101 903 v1.4.1 (2009-06, ").
The element signs the element of signature inside which it is located.
The element contains the element, the structure of which has been described in chapter 5.4.1 (), with the following differences:
* the value of attribute Id="CounterSignature"
* within the element, the value of the existing
signature is referenced, and the response header ( element with
Id="#ResponseHeaderId")
• as the canonicalisation method, the "
c14n#WithComments" is used.
This means that within the element there are elements with the following references:
• URI="#SignatureValueId" - reference to the value of the original signature of the authorised person, the element must also contain the value of "Type" attribute
"".
• URI="#ResponseHeaderId" - a reference to the data within the element
Page 29 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|5. G2B Service Technical Specification | |
5.3.8. Distinctive properties of the electronic signature of the G2B service when the Customs sends the document to the economic operator
B2GDocument XML which is created when Customs sends the documents to the economic operator does not contain the XAdES extension, but only the "unexpanded" XML-DSIG electronic signature (see Chapter "4.1.1 G2B document"), with a special remark that, as the canonicalisation method, the "http:/ /2001/10/xml-exc-c14n#WithComments" is used.
The XAdES extensions are used to perform the advanced electronic signature, or storage of data required for this purpose. For the purpose of legal equalisation of the importance of the electronic signature in both directions of sending, it has been decided that in the case when Customs sends the documents to the economic operator, all the required data giving the legal importance to the electronic signature are set within the / element of the B2GDocument, thus becoming the integral part of the signature.
The required data are as follows:
* time of signature
* the identifier of rules for using the electronic signature
* the summary of document rules for using the electronic signature
* the algorithm summary of document rules for using the electronic signature
The format in which the specified data are written is:
Time of signature=
The identifier of rules for using the electronic signature=
The summary of document rules for using the electronic signature=
The algorithm summary of document rules for using the electronic signature=sha256
The specified data need to be merged in a way that they are mutually separated with the ";" character and inserted into the specified location.
Page 30 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex A - Code books | |
Annex A Code books
Code book of Customs applications (applicative sub-systems):
|Identifier of Customs application|Description |
|NTA.HR |Domestic transit application |
|NECA.HR |Domestic application for export control |
|NDEA.HR |Domestic application for record of excise duties |
|ISA.HR |Intrastat application |
The specified values appear within the "AppId" element.
Message list with warnings and errors:
|Message identifier |Message description |
|W001 |The assigned value of "TraderMsgId" attribute has already been used |
|W002 |There is no document with the specified value of "TraderMsgId" attribute |
|W003 |There is no document with the specified value of "DocUuid" attribute |
|E001 |Internal problems in G2B service operation |
|E002 |Received request is not a formally valid XML document |
|E003 |The electronic signature of received message is invalid |
|E004 |The signatory of the received message is not authorised to operate the application |
|E005 |The economic operator is not authorised to operate the application |
|E006 |Invalid data found within the message |
|E007 |The economic operator is not authorised to operate the G2B service |
Page 31 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex B - XML scheme of G2B document | |
Page 32 of 50
Annex B XML scheme of G2B document
[pic]
Page 33 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex B - XML scheme of G2B document | |
[pic]
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex B - XML scheme of G2B document | |
[pic]
The optional document description. Maximum length is 255 characters.
Page 34 of 50
Page 35 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex B - XML scheme of G2B document | |
[pic]
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
Annex C WSDL G2B service
[pic]
ID of the trader application.
ID of the application communicated with.
Page 36 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
ID of message that Trader sends. We recommend the UUID to be used.
The correlation identifier. Defined by the application communicated with (mostly UUID). Always generated by CCA.
Structure with data regarding the documents sent to Customs.
Page 37 of 50
[pic]
The maximum length of description field is 255
characters.
Structure with data regarding the documents sent by the Customs.
Trader identifier.
Page 38 of 50
Pa
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Identifier of the trader application.
Page 39 of 50
Page 40 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 41 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 42 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 43 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 44 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 45 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 46 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 47 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 48 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 49 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |DATE: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
Page 50 of 50
|G2B Service Technical Specification |Version: 1.2 |
| |Date: 20/07/2011 |
|Annex C - WSDL G2B service | |
[pic]
-----------------------
Read the sent document's status
Forward the message
Check authorisation
Check digital signature
Check digital signature
Customs application
[pic][?]&'.24WXdgkoprswy‚ƒ…ðßÔ° °ÔŒxdÔPxPxPxÔŒxÔ&hhwh)’5?OJQJ\?^JmH sH &hhwhC.]5?OJQJ\?^JmH sH &hhwhJX´5?OJQJ\?^JmH sH &hhwhé á5?OJQJ\?^JmH sH hhwh)
§5?CJ-aJ-mH sH "hhwhRequest authorisation
Confirm that message is received
Get the message from message box
Check the authorisation
Check the authorisation
Read message box contents
Check the authorisation
Forward the message
Customs application
Request authorisation
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.