OneGate
HTTPS Entrypoints
End User Manual
PSD:
CRS
Project code:
CRS
Department Group:
PRSM
Author:
PRSM
Date:
06/10/2014
Version :
S3.1
Status:
Final
Authorized by:
Chris Retsin
Reviewers:
PRSM, DQ
Commentators:
PRSM, DQDQ, External partners
Approvers:
Cellule Research and Development (DQ)
Location:
© National Bank of Belgium, Brussels
All rights reserved.
Reproduction for educational and noncommercial purposes is permitted provided
that the source is acknowledged.
OneGate
Table of Contents
1. Introduction
1.1
1.2
1.3
4
Document history
References
Overview of document
4
4
4
2. Product features and capabilities
6
2.1
2.2
2.3
Product purpose
Scope of intended use
Scenario
6
7
7
3. Generalities
3.1
3.2
3.3
3.4
3.5
3.6
3.7
8
Communication protocol
Authentication
Authorization
Secure data
Binary data
Volume
Useful tools
8
8
8
8
8
8
9
4. HTTPS Entrypoints description
4.1
4.2
4.3
4.4
Overview
Upload file
Request list of available feedback
Request a feedback
5. Error codes
5.1
5.2
10
10
12
15
19
Client error
Server error
19
19
6. Appendix - Sample using cURL
6.1
6.2
10
Prerequisites
Command cURL
20
Error! Bookmark not defined.
20
7. Definition of terms and abbreviations
3
25
OneGate(CSSR)
1. Introduction
This document contains everything you need to automate the data exchange with the application OneGate.
This document describes the prerequisites of the usage of the OneGate HTTPS Entrypoints, the goal of each one
of them, its input, output and possible errors.
Target audience for this document is the external partners who wish to automate the data exchange with the
application OneGate using the HTTPS Entrypoints.
1.1
Document history
Date
03/10/2014
1.2
Ref.
[1]
Version
Author
Description of change
S3.1
PRSM
Entrypoints v1.0
References
Title
Author
Location
OneGate - End user manual
DQ1
French
Dutch
[3]
1.3
OneGate - XML Protocol
PRSM
[Not available]
Overview of document
This manual is structured as follows:
Section
Title
Main Purpose
1
Introduction
Specifies the document version, lists
other,
related
documents
and
summarises the contents of this
manual
2
Product description and environment:
Explains why the product exists, its
scope and the scenario analysed
1 DQ:Department General Statistics
4
OneGate(CSSR)
3
Generalities
Describes the generic points about
the Onegate Entrypoints.
4
HTTPS entrypoints description
Explains how to use the product
5
Error codes
Lists and explains product error codes
and associated corrective actions
6
Appendix - Sample using cURL
Some examples how to use the
product using cURL
7
Definition of terms and abbreviations
Lists and explains any special terms
used in the document.
5
OneGate(CSSR)
2. Product features and capabilities
2.1
Product purpose
Today, the need for information grows continuously. Administrative and statistical institutes interview
the citizens and companies regularly to collect this information. With the dematerialization, the paper
form has given way to electronic form sent via Internet. The goal of the application One Gate is to
become a unique point of data collection and data exchange for the National Bank of Belgium.
The data collection can be done either manually by filling an online form either (semi) automatically by
sending an XML file via a manual file upload, a secured email or a web service call. The current
document is limited to the description of the fully automated data exchange using the HTTPS
entrypoints (drawn in Figure 1 under point 3).
External declarers
1
OneGate(CSSR)
D
HTTPS
L
HTTPS
F
HTTPS
L
HTTPS
M
HTTPS
User U2A
2
U2A
Application Server
D
SMTP
Mail server
3
D
HTTPS
L
HTTPS
F
HTTPS
L
HTTPS
M
HTTPS
User A2A
A2A
Application Server
D
Upload declaration report
L
Request list of available feedbacks
L
Request list of available messages
F
Request feedback
M
Request message
Figure 1 - General overview
6
OneGate(CSSR)
2.2
Scope of intended use
OneGate can be used for all business domains where data must be collected via Internet. Only the authorized
users can use the OneGate Entrypoints.
Once you have done the technical effort to automate the exchange for a certain business domain, you can reuse
this implementation for all other business domains.
2.3
Scenario
For the data collection process, the data exchange with OneGate consists of three chronological activities:

The declarer sends a file containing one declaration report.

The declarer requests the list of the available feedbacks.

The declarer requests a specific feedback.
Declarer A2A
ESB
OneGate(CSSR)
UploadFileRequest
UploadFileResponse
ProcessFile
FeedbackListRequest
FeedbackListRequest
FeedbackListResponse
FeedbackListResponse
{For each entry of the
FeedbackListResponse}
FeedbackRequest
FeedbackRequest
FeedbackResponse
FeedbackResponse
Figure 2 - Scenario of the fully automated data exchange with OneGate for data collection
7
OneGate(CSSR)
3. Generalities
This chapter describes the generalities about the OneGate Entrypoints: the communication protocol, the
authentication, the authorization and the binary data format.
3.1
Communication protocol
The communication protocol used is HTTPS with user+password based authentication.
The method invocation is POST, except for the download of an attachement (using the url received in the
responseFeedback / messageResponse), which will be a HTTPS GET.
3.2
Authentication
The communication protocol used is HTTPS with user+password based authentication.
More information about this can be found on the website of the National Bank:
http://www.nbb.be/DOC/DQ/onegate/en/FAQ_en.html »Access to OneGate» - « How can I request access? »
- »Access by means of Username and Password «
3.3
Authorization
You can request a username and password by mailing to access.onegate@nbb.be . The authorization process
is based on security role. To request the role that will give you access to the application OneGate, you need to
follow the procedure described in document [1]. Once the authority approved your access request, you will be able
to use your user+password to automate the data exchange and have access to the online application.
If you try to consume one of the HTTPS Entrypoints without having requested access before, you will receive an
HTTPS 403 error code.
3.4
Secure data
The communication protocol between the client and OneGate is always HTTPS which guarantees confidentiality of
the data exchange.
3.5
Binary data
The data exchange between the declarer and the application OneGate will be done using XML file formats.
In native HTTPS the payload will be passed in base64 encoded format.
3.6
Volume
The size of the request cannot exceed 10 MB. The size of the payload of the HTTPS GET reply is limited
depending on the specific Institute/Business Domain. To limit this size, payload can be compressed. If zip is used,
the content-type of the attachment will be "application/zip".
8
OneGate(CSSR)
3.7
Useful tools
Before automated the implementation of the usage of the HTTPS Entrypoints, you can easily test it using cURL
(http://curl.haxx.se):
cURL is a command line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP,
SFTP, TFTP, TELNET, DICT, LDAP, LDAPS and FILE. cURL supports SSL certificates, HTTPS POST, HTTPS
PUT, FTP uploading, HTTPS form based upload, proxies, cookies, user+password authentication (Basic, Digest,
NTLM, Negotiate, kerberos...), file transfer resume, proxy tunneling and a busload of other useful tricks.
9
OneGate(CSSR)
4. HTTPS Entrypoints description
4.1
Overview
Figure 3 - HTTPS Entrypoints services
Figure 4 gives an overview of the HTTPS Entrypoints used by the declarer to fully automate the data exchange with
OneGate. As a reminder, the data exchange consists of sending data and retrieving the associated feedback that
contains the result of the validation of the imported data.
4.2
Upload file
4.2.1
Description
The declarer uses the service "Upload file" to send a file with a declaration report to be processed by OneGate and
receives a ticket in return. This ticket is used as an acknowledgement of the file receipt and will be used to uniquely
identify the file transfer. The processing of the file is done asynchronously following the FIFO principle. Due to the
asynchronous process, the validation report will not be available immediatly and there is a delay between the file
upload and the registration of the file reception in OneGate.
Note that the processing of the declaration can be also followed via the online OneGate application using the
function "Exchanges > File exchange log".
10
OneGate(CSSR)
The sent file contains a declaration report that must follow the data exchange protocol published by the business
where the XML schema and the security level will be specified.
List of the supported XML protocols:

Declaration Report (cfr. [3]) ; all new reporting
Supported security level to apply to the sending file:

None
4.2.2
URL
Test:
https//onegate-a2a-test.nbb.be/crs-esb-weak/invoke/uploadFile-v1-0
Production:
https//onegate-a2a.nbb.be/crs-esb-weak/invoke/uploadFile-v1-0
4.2.3
HTTPS Request
4.2.3.1
Body
The payload – body of the request – contains the declaration report to upload to OneGate.
Before being sent, the payload must fulfil the following requirements:

The declaration report must be valid against the XML protocol fixed by the business.

Only one file can be uploaded by request.

The file can be compressed. In this case, the zip file can contain only one file.
So to generate the payload, you need to execute the following steps:

Validate the file against the XML schema ; optional but recommended

Zip file ; optional but recommended
4.2.3.2
Header
You can give a name to the uploaded file by specifying the HTTPS header "filename". This header is optional.
4.2.4
HTTPS Response
If the OneGate has successfully received the payload, the response returns a status code 200 and the ticket ID
associated to the file upload. The response is sent in the XML format described below.
UploadFileResponse
Description
Contains the ticket id associated with the file exchange.
XML format
ComplexType
Children
TicketID
TicketID
Description
Identifies the file transfer uniquely.
The ticket ID is used as an acknowledgement of the file receipt and will be requested
in case of problem by the Service Desk to be able to detect the problem.
11
OneGate(CSSR)
XML format
xs:string
whitespace = collapse
Validation
4.2.5
Required
Error
Status code – Reason phrase
400 range
500 range
Corrective action
Client error.
The request contains bad syntax or cannot be fulfilled.
An overview of HTTP error codes can be found in http://www.rfceditor.org/rfc/rfc2616.txt.
Internal Server Error:
If the problem persists, you can contact the National Bank's
helpdesk (+ 32 (0)2 2214060) or send an e-mail to:
servicedesk@nbb.be.
4.3
Request list of available feedback
4.3.1
Description
The service "requestFeedbackList" is used to request the list of feedback identifiers available. Only the identifier of
the feedback associated with a file sent with this user will be sent back. The feedback associated with files sent by
another user but for a common declarer will not be sent back.
You can choose between requesting a list of either new feedbacks or feedbacks associated to files sent during a
specified time frame. The second option offers you the possibility to request feedbacks that have been retrieved
earlier.
4.3.2
URL
Test:
https//onegate-a2a-test.nbb.be/crs-esb-weak/invoke/requestFeedbackList-v1-0
Production:
https//onegate-a2a.nbb.be/crs-esb-weak/invoke/requestFeedbackList-v1-0
These are general URLs for OneGate. Each Business Domain has his one's own URL. Please consult the URL
document for the desired Institute/Business Domain !
4.3.3
HTTPS Request
4.3.3.1
Body
The request of the feedback list must follow the XML format described below.
12
OneGate(CSSR)
FeedbackListRequest
Description
Contains the attributes to request the list of feedback identifiers available for the
requester.
XML format
ComplexType
Children
NotRead
Read
NotRead
Description
Used to request the identifiers of new feedback.
XML format
ComplexType
Validation
Empty element
Read
Description
Used to request the identifiers of feedback requested earlier during the specified time
frame.
XML format
ComplexType
Children
TimeFrame
TimeFrame
Description
Used to specify the time frame during which the file has been retrieved for the first time
from the application OneGate.
XML format
ComplexType
Children
FromTime
ToTime
FromTime
Description
Timestamp identifying the start of the time frame.
XML format
xs:dateTime
Validation
Required
ToTime
Description
Timestamp identifying the end of the time frame.
XML format
xs:dateTime
Validation
Required
13
OneGate(CSSR)
4.3.3.2
Header
No specific header.
4.3.4
HTTPS Response
If OneGate has successfully processed the request, the response returns a status code 200 and the list of the
available feedbacks in the XML format described below.
FeedbackListResponse
Description
Contains the list of the available feedback identifiers.
XML format
ComplexType
Children
NoFeedback
Feedback
NoFeedback
Description
No feedback found for the specified search criteria.

Not read: no new feedback

Read: no feedback retrieved during the specified time frame
XML format
ComplexType
Validation
Empty element
Feedback
Description
Contains the information about the feedback available for download.
XML format
ComplexType
Minimum occurence: 1
Maximum occurence: unbounded
Children
FeedbackId
TicketId
FeedbackId
Description
Identifier of the feedback
XML format
xs:nonNegativeInteger.
minExclusive: 0
Validation
Required
14
OneGate(CSSR)
TicketID
Description
Identifier of the file transfer to whom the feedback is associated.
XML format
xs:string
whitespace: collapse
Validation
4.3.5
Required
Error
Status code – Reason phrase
Corrective action
400
Identification with code 'userId' not found
You have access to OneGate but not to the requested data.
Please check, in the specific business documentation, if the URL
used to send your request is the right one.
If the right URL is used, please contact the access manager to
request to verify the access rights linked to your credentials.
Client error.
The request contains bad syntax or cannot be fulfilled.
An overview of HTTP error codes can be found in http://www.rfceditor.org/rfc/rfc2616.txt.
4xx range
5xx range
Internal Server Error:
If the problem persists, you can contact the National Bank's
helpdesk (+ 32 (0)2 2214060) or send an e-mail
(servicedesk@nbb.be) mentioning the following:
Correlation ID=xxxxxxxxxxxxxxxxxxxxxxxx
4.4
Request a feedback
4.4.1
Description
The service "feedbackRequest" is used to request a specific feedback by providing its identifier. The format of the
feedback must follow the business requirement in terms of format and security level applied.
4.4.2
URL
Test:
https//onegate-a2a-test.nbb.be/crs-esb-weak/invoke/requestFeedback-v1-0
Production:
https//onegate-a2a.nbb.be/crs-esb-weak/invoke/requestFeedback-v1-0
4.4.3
HTTPS Request
4.4.3.1
Body
The request of a specific feedback must be fulfill the XML format described below.
15
OneGate(CSSR)
FeedbackRequest
Description
Contains the information about the requested feedback
XML format
ComplexType
Children
FeedbackId
FeedbackId
Description
Identifier of the requested feedback
XML format
xs:nonNegativeInteger
minExclusive: 02
Validation
4.4.3.2
Required
Header
No specific header.
4.4.4
HTTPS Response
If OneGate has successfully processed the request, the response returns a status code 200 and the feedback in
the XML format described below.
FeedbackResponse
Description
Contains the requested feedback
XML format
ComplexType
Children
Payload
Payload
Description
Requested feedback encoded in base 64.
XML format
xs:base64Binary
minExclusive: 0
Validation
Required
More details about the Payload
The payload contains the feedback in base 64. When you receive the feedback response, you need to execute the
following steps before being able to process the feedback:

Decode the payload ; required
Once the payload is decoded and the security is removed, the feedback will have the structure displayed in Figure
4. The result structure is similar to the messages that can you find in the OneGate inbox.
2 Max value: 2^63 - 1 = 9223372036854775807
16
OneGate(CSSR)
Figure 4 - XML schema of the payload/feedback
Message
Description
The message is the feedback which contains at least one body or one attachment
XML format
ComplexType
Children
Body
Attachment
Body
Description
Body of the message in plain text.
Example: Validation report for ticket number [480]
XML format
xs:string
Validation
Optional
Attachment
Description
Attachment of the message encoded in base 64

@contentType specify the type of the content using the Internet media type.

@contentName specify the name of the content part in other words the file name.
XML format
xs:base64Binary
minOccurs: 0
maxOccurs: unbounded
Attributes
Validation
Name
Type
Default
contentType
xs:string
text/xml
contentName
xs:string
Optional
If the feedback contains the OneGate Feedback, you need to decode the Attachment and process the XML file
result of the decoding.
4.4.5
Error message
Status code – Reason phrase
Corrective action
400 - Identification with code 'userId' not
found
You have access to OneGate but not to the requested data.
Please contact the access manager to request to verify the access
rights linked to your credentials.
17
OneGate(CSSR)
400 - Feedback with id '<FeedbackId>'
not found.
This error can occur when

The element "TicketId" from the FeedbackListResponse is
used instead of the "FeedbackId".

the requested feedback doesn't exist.

a different user is used to request the list of feedbacks and
the feedback. Note that the same user must be used to
upload a file and request the associated feedbacks.
4xx range
Client error.
The request contains bad syntax or cannot be fulfilled.
An overview of HTTP error codes can be found in http://www.rfceditor.org/rfc/rfc2616.txt.
5xx range
Internal Server Error:
If the problem persists, you can contact the National Bank's
helpdesk (+ 32 (0)2 2214060) or send an e-mail to:
servicedesk@nbb.be.
18
OneGate(CSSR)
5. Error codes
If the request could not be processed due to a client error or a server error, the response will contain respectively a
status code in 400 or 500 range.
An overview of HTTP error codes can be found in
5.1
Client error
If your request contains something wrong, the response returns a status code in the 400 range and a reason
phrase giving an indication that the problem is located at the client side. In this case, please correct your request
before send it again.
5.1.1
Header
Status code - Reason phrase
Detail
400 – Bad request
Consult the body of the response for more details.
403
Different problems can cause this error code:
1. The request exceeds the max allowed content length
Your request exceeds the max size specified in Volume.
Other status code
Please consult http://www.rfc-editor.org/rfc/rfc2616.txt.
5.1.2
Body
If the HTTP error code is 400, the body can contain more details about the error cause. This details will be
presented using the following XML structure:
where "message" contains the error message and "details" can contains more informations about this error.
5.2
Server error
If the server cannot process your request due to a technical problem, the response returns a status code 500 (or in
the 500 range) and a reason phrase given an indication of the problem occurred on the server side. In this case,
please retry to send your request and if the problem persists, please contact the NBB IT Servicedesk (+ 32 2 221
40 60 ; servicedesk@nbb.be).
19
OneGate(CSSR)
6. Appendix - Sample using cURL
6.1
Command cURL
6.1.1
Parameters
--data-binary <data>
(HTTP) This posts data exactly as specified with no extra processing whatsoever. If you start the data with the
letter @, the rest should be a filename. Data is posted in a similar manner as --data-ascii does, except that
newlines are preserved and conversions are never done.
-H/--header <header>
(HTTP) Extra header to use when getting a web page. You may specify any number of extra headers. Note that if
you should add a custom header that has the same name as one of the internal ones curl would use, your
externally set header will be used instead of the internal one. This allows you to make even trickier stuff than curl
would normally do. You should not replace internally set headers without knowing perfectly well what you're doing.
Remove an internal header by giving a replacement without content on the right side of the colon, as in: -H "Host:".
Curl will make sure that each header you add/replace is sent with the proper end-of-line marker, you should thus
not add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up
for you.
-v/--verbose
Makes the fetching more verbose/talkative. Mostly useful for debugging. A line starting with '>' means "header
data" sent by curl, '<' means "header data" received by curl that is hidden in normal cases, and a line starting with
'*' means additional info provided by curl. Note that if you only want HTTPS headers in the output, -i/--include might
be the option you're looking for.
-k/--insecure
(SSL) This option explicitly allows curl to perform "insecure" SSL connections and transfers. All SSL connections
are attempted to be made secure by using the CA certificate bundle installed by default. This makes all
connections considered "insecure" fail unless -k/--insecure is used.
See this online resource for further details: http://curl.haxx.se/docs/sslcerts.html
-o, --output <file>
Writes output to <file> instead of stdout.
--trace <file>
Enables a full trace dump of all incoming and outgoing data, including descriptive information, to the given output
file. Use "-" as filename to have the output sent to stdout.
-u, --user <user:password>
Specifies the user name and password to use for server authentication.
20
OneGate(CSSR)
6.1.2
Upload file
6.1.2.1
Command cURL
With file name:
curl -v --user "<user:password>" --data-binary "@<filepath>" -H ContentType:essa/sresp
-H "filename: <filename>"
-k https://onegate-a2a.nbb.be/crs-esb-weak/invoke/uploadFile-v1-0 --output <file>
Without file name:
curl -v --user "<user:password>" --data-binary "@<filepath>" -H ContentType:essa/sresp
-k " https://onegate-a2a.nbb.be/crs-esb-weak/invoke/uploadFile-v1-0" --output <file>
6.1.2.2
HTTPS Request
Sample of declarationReport.xml:
<?xml version='1.0' encoding='UTF-8'?>
<DeclarationReport xmlns="http://www.onegate.eu/2010-01-01">
<Administration>
<From declarerType="KBO">0000000097</From>
<To>NBB</To>
<Domain>SXX</Domain>
</Administration>
<Report action="replace" date="2014-10" code="EX19E">
<Data close="true" form="EXF19E">
<Item>
<Dim prop="EXTRF">19</Dim>
<Dim prop="EXCNT">NL</Dim>
<Dim prop="EXTTA">3</Dim>
<Dim prop="EXREG">1</Dim>
<Dim prop="EXTGO">73202089</Dim>
<Dim prop="EXWEIGHT">101</Dim>
<Dim prop="EXUNITS">0</Dim>
<Dim prop="EXTXVAL">1098</Dim>
<Dim prop="EXTPC">3</Dim>
<Dim prop="EXDELTRM">CPT</Dim>
</Item>
<Item>
<Dim prop="EXTRF">19</Dim>
<Dim prop="EXCNT">DK</Dim>
<Dim prop="EXTTA">3</Dim>
<Dim prop="EXREG">1</Dim>
<Dim prop="EXTGO">83012000</Dim>
<Dim prop="EXWEIGHT">88</Dim>
<Dim prop="EXUNITS">0</Dim>
<Dim prop="EXTXVAL">73456</Dim>
<Dim prop="EXTPC">3</Dim>
<Dim prop="EXDELTRM">CPT</Dim>
</Item>
</Data>
</Report>
<Report action="replace" date="2014-09" code="EX29S">
<Data close="true" form="EXF29S">
<Item>
<Dim prop="EXTRF">29</Dim>
<Dim prop="EXCNT">NL</Dim>
<Dim prop="EXTTA">3</Dim>
<Dim prop="EXREG">1</Dim>
<Dim prop="EXTGO">73202089</Dim>
<Dim prop="EXWEIGHT">536</Dim>
21
OneGate(CSSR)
<Dim prop="EXUNITS">0</Dim>
<Dim prop="EXTXVAL">89098</Dim>
</Item>
<Item>
<Dim prop="EXTRF">29</Dim>
<Dim prop="EXCNT">DK</Dim>
<Dim prop="EXTTA">3</Dim>
<Dim prop="EXREG">1</Dim>
<Dim prop="EXTGO">84714100</Dim>
<Dim prop="EXWEIGHT">0</Dim>
<Dim prop="EXUNITS">87</Dim>
<Dim prop="EXTXVAL">2156</Dim>
</Item>
<Item>
<Dim prop="EXTRF">29</Dim>
<Dim prop="EXCNT">DK</Dim>
<Dim prop="EXTTA">3</Dim>
<Dim prop="EXREG">1</Dim>
<Dim prop="EXTGO">83012000</Dim>
<Dim prop="EXWEIGHT">867</Dim>
<Dim prop="EXUNITS">0</Dim>
<Dim prop="EXTXVAL">75556</Dim>
</Item>
</Data>
</Report>
</DeclarationReport>
HTTPS Response
<?xml version="1.0"?>
<crs:UploadFileResponse
xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
<crs:TicketID>261342</crs:TicketID>
</crs:UploadFileResponse>
6.1.2.3
6.1.3
Request list of feedback
6.1.3.1
Command cURL
curl -v --user "<user:password>" --data-binary "@requestFeedbackList.xml" -H ContentType:essa/sresp
-k https://onegate-a2a.nbb.be/crs-esb-weak/invoke/requestFeedbackList-v1-0 --output
<file>
6.1.3.2
HTTPS Request
Sample of requestFeedbackList.xml (NotRead) :
<?xml version="1.0"?>
<crs:FeedbackListRequest xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
<crs:NotRead/>
</crs:FeedbackListRequest>
Sample of requestFeedbackList.xml (Read) :
<?xml version="1.0"?>
<crs:FeedbackListRequest xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
<esb:Read>
<esb:TimeFrame>
<esb:FromTime>2011-02-04T00:00:00</esb:FromTime>
<esb:ToTime>2011-02-08T00:00:00</esb:ToTime>
</esb:TimeFrame>
</esb:Read>
</crs:FeedbackListRequest>
22
OneGate(CSSR)
HTTPS Response
<?xml version="1.0"?>
<crs:FeedbackListResponse xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
<crs:Feedback>
<crs:FeedbackId>1895548</crs:FeedbackId>
<crs:TicketId>261341</crs:TicketId>
</crs:Feedback>
<crs:Feedback>
<crs:FeedbackId>1895549</crs:FeedbackId>
<crs:TicketId>261342</crs:TicketId>
</crs:Feedback>
</crs:FeedbackListResponse>
6.1.3.3
6.1.4
Request feedback
6.1.4.1
Command cURL
curl -v --user "<user:password>" --data-binary "@requestFeedback.xml" -H ContentType:essa/sresp
-k " https://onegate-a2a.nbb.be/crs-esb-weak/invoke/requestFeedback-v1-0" --output
<file>
6.1.4.2
HTTPS Request
Sample of requestFeedback.xml:
<?xml version="1.0"?>
<crs:FeedbackRequest xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
<crs:FeedbackId>1895549</crs:FeedbackId>
</crs:FeedbackRequest>
HTTPS Response
<?xml version="1.0"?>
<crs:FeedbackResponse xmlns:crs="http://www.onegate.eu/2010-01-01/esb">
6.1.4.3
<crs:Payload>PD94bWwgdmVyc2lvbj0iMS4wIj8+Cjx0bnM6TWVzc2FnZSB4bWxuczpzb2FwZW52PSJodHRw
Oi8v
c2NoZW1hcy54bWxzb2FwLm9yZy9zb2FwL2VudmVsb3BlLyIgeG1sbnM6dG5zPSJodHRwOi8vd3d3
Lm9uZWdhdGUuZXUvMjAxMC0wMS0wMSI+CiAgPHRuczpCb2R5PlByb2Nlc3NpbmcgZmVlZGJhY2sg
Zm9yIGRlY2xhcmVyIFswMDAwMDAwMDk3XSBpbiBkb21haW4gW1NYWF0gKGFzc29jaWF0ZWQgdG8g
ZmlsZSAiW2RlY2xhcmF0aW9uLnhtbF0iIHdpdGggdGlja2V0IG51bWJlciBbMjYxMzQyXSkuPC90
bnM6Qm9keT4KICA8dG5zOkF0dGFjaG1lbnQgY29udGVudFR5cGU9InRleHQveG1sIiBjb250ZW50
TmFtZT0iZmVlZGJhY2sueG1sIj5QRDk0Yld3Z2RtVnljMmx2Ymowbk1TNHdKeUJsYm1OdlpHbHVa
ejBuVlZSR0xUZ25QejRLUEVabFpXUmlZV05yVW1Wd2IzSjBJSGh0Ykc1elBTSm9kSFJ3T2k4dmQz
ZDNMbTl1WldkaGRHVXVaWFV2TWpBeE1DMHdNUzB3TVNJK0NpQWdQRUZrYldsdWFYTjBjbUYwYVc5
dUlHTnlaV0YwYVc5dVZHbHRaVDBpTWpBeE5DMHhNUzB4T0ZRd056b3pPVG8wTnk0ek9ETXJNREU2
TURBaVBnb2dJQ0FnUEVaeWIyMCtUa0pDUEM5R2NtOXRQZ29nSUNBZ1BGUnZJR1JsWTJ4aGNtVnlW
SGx3WlQwaVMwSlBJajR3TURBd01EQXdNRGszUEM5VWJ6NEtJQ0FnSUR4RWIyMWhhVzQrVTFoWVBD
OUViMjFoYVc0K0NpQWdJQ0E4VW1WemNHOXVjMlV2UGdvZ0lEd3ZRV1J0YVc1cGMzUnlZWFJwYjI0
K0NpQWdQRkpsY0c5eWRDQmtZWFJsUFNJeU1ERTBMVEV3SWlCamIyUmxQU0pGV0RFNVJTSStDaUFn
SUNBOFJHRjBZU0JtYjNKdFBTSkZXRVl4T1VVaVBnb2dJQ0FnSUNBOFRtOTBaWE0rQ2lBZ0lDQWdJ
Q0FnUEU1dmRHVWdiR1YyWld3OUlrbE9SazlTVFVGVVNVOU9JaUJqYjJSbFBTSkRRVXhEWDFSUFZF
Rk1VeUkrVkdobGNtVWdZWEpsSURJZ2JHbHVaWE1nYVc0Z2RHaHBjeUJrWldOc1lYSmhkR2x2YmlC
MGIzUmhiR2x1WnlBM05EVTFOQ0JGVlZJdVBDOU9iM1JsUGdvZ0lDQWdJQ0E4TDA1dmRHVnpQZ29n
SUNBZ1BDOUVZWFJoUGdvZ0lEd3ZVbVZ3YjNKMFBnb2dJRHhTWlhCdmNuUWdaR0YwWlQwaU1qQXhO
QzB3T1NJZ1kyOWtaVDBpUlZneU9WTWlQZ29nSUNBZ1BFUmhkR0VnWm05eWJUMGlSVmhHTWpsVElq
NEtJQ0FnSUNBZ1BFNXZkR1Z6UGdvZ0lDQWdJQ0FnSUR4T2IzUmxJR3hsZG1Wc1BTSkpUa1pQVWsx
QlZFbFBUaUlnWTI5a1pUMGlRMEZNUTE5VVQxUkJURk1pUGxSb1pYSmxJR0Z5WlNBeklHeHBibVZ6
SUdsdUlIUm9hWE1nWkdWamJHRnlZWFJwYjI0Z2RHOTBZV3hwYm1jZ01UWTJPREV3NG9Lc0xqd3ZU
bTkwWlQ0S0lDQWdJQ0FnUEM5T2IzUmxjejRLSUNBZ0lEd3ZSR0YwWVQ0S0lDQThMMUpsY0c5eWRE
NEtQQzlHWldWa1ltRmphMUpsY0c5eWREND08L3RuczpBdHRhY2htZW50Pgo8L3RuczpNZXNzYWdl
Pg==</crs:Payload>
</crs:FeedbackResponse>
Sample of Payload after decoding => Message
23
OneGate(CSSR)
<?xml version="1.0"?>
<tns:Message xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:tns="http://www.onegate.eu/2010-01-01">
<tns:Body>Processing feedback for declarer [0000000097] in domain [SXX] (associated
to file "[declaration.xml]" with ticket number [261342]).</tns:Body>
<tns:Attachment contentType="text/xml"
contentName="feedback.xml">PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPEZlZW
RiYWNrUmVwb3J0IHhtbG5zPSJodHRwOi8vd3d3Lm9uZWdhdGUuZXUvMjAxMC0wMS0wMSI+CiAgPEFkbWluaXN
0cmF0aW9uIGNyZWF0aW9uVGltZT0iMjAxNC0xMS0xOFQwNzozOTo0Ny4zODMrMDE6MDAiPgogICAgPEZyb20+
TkJCPC9Gcm9tPgogICAgPFRvIGRlY2xhcmVyVHlwZT0iS0JPIj4wMDAwMDAwMDk3PC9Ubz4KICAgIDxEb21ha
W4+U1hYPC9Eb21haW4+CiAgICA8UmVzcG9uc2UvPgogIDwvQWRtaW5pc3RyYXRpb24+CiAgPFJlcG9ydCBkYX
RlPSIyMDE0LTEwIiBjb2RlPSJFWDE5RSI+CiAgICA8RGF0YSBmb3JtPSJFWEYxOUUiPgogICAgICA8Tm90ZXM
+CiAgICAgICAgPE5vdGUgbGV2ZWw9IklORk9STUFUSU9OIiBjb2RlPSJDQUxDX1RPVEFMUyI+VGhlcmUgYXJl
IDIgbGluZXMgaW4gdGhpcyBkZWNsYXJhdGlvbiB0b3RhbGluZyA3NDU1NCBFVVIuPC9Ob3RlPgogICAgICA8L
05vdGVzPgogICAgPC9EYXRhPgogIDwvUmVwb3J0PgogIDxSZXBvcnQgZGF0ZT0iMjAxNC0wOSIgY29kZT0iRV
gyOVMiPgogICAgPERhdGEgZm9ybT0iRVhGMjlTIj4KICAgICAgPE5vdGVzPgogICAgICAgIDxOb3RlIGxldmV
sPSJJTkZPUk1BVElPTiIgY29kZT0iQ0FMQ19UT1RBTFMiPlRoZXJlIGFyZSAzIGxpbmVzIGluIHRoaXMgZGVj
bGFyYXRpb24gdG90YWxpbmcgMTY2ODEw4oKsLjwvTm90ZT4KICAgICAgPC9Ob3Rlcz4KICAgIDwvRGF0YT4KI
CA8L1JlcG9ydD4KPC9GZWVkYmFja1JlcG9ydD4=</tns:Attachment>
</tns:Message>
Sample of Attachment after decoding => Validation report generated by OneGate
<?xml version='1.0' encoding='UTF-8'?>
<FeedbackReport xmlns="http://www.onegate.eu/2010-01-01">
<Administration creationTime="2014-11-18T07:39:47.383+01:00">
<From>NBB</From>
<To declarerType="KBO">0000000097</To>
<Domain>SXX</Domain>
<Response/>
</Administration>
<Report date="2014-10" code="EX19E">
<Data form="EXF19E">
<Notes>
<Note level="INFORMATION" code="CALC_TOTALS">There are 2 lines in this
declaration totaling 74554 EUR.</Note>
</Notes>
</Data>
</Report>
<Report date="2014-09" code="EX29S">
<Data form="EXF29S">
<Notes>
<Note level="INFORMATION" code="CALC_TOTALS">There are 3 lines in this
declaration totaling 166810€.</Note>
</Notes>
</Data>
</Report>
</FeedbackReport>
24
OneGate(CSSR)
7. Definition of terms and abbreviations
Abbreviation
Description
A2A
Application to Application ; refers to the interaction between two applications.
Acknowledgment of file receipt
Feedback OneGate
Feedback Back-Office
FIFO
HTTPS
Internet Media Type
NBB
SOAP
SSL
U2A
Web Service
WSDL
This acknowledgment of file receipt indicates that a file was received, that the file
transfer is recorded under a identification number (TickeId). This acknowledgment
does not contain any information about the validity of the document.
Feedback OneGate is the validation report generated automatically by OneGate when
the sending file is processed. The feedback format is fixed (XML following the protocol
used for the FeedbackReport).
The feedback back-officeis a report generated manually or automatically by the
specific business application that will exploit the data collected via OneGate. This
report can contain information related to a second level of validation of the reported
data or other types of information such as complementary question or various
information.
The file format of the business report is free (HTML, xls, doc, PDF,…)
First In First Out can be translated as "First-come, First-served". This expression
describes the principle of a queue processing where what comes in first is handled
first, what comes in next waits until the first is finished before being handled.
Hypertext Transfer Protocol Secure is a combination of the Hypertext Transfer
Protocol with the SSL/TLS protocol to provide encryption and secure identification of
the server.
An Internet Media Type, originally called “MIME type” or “Content-type”, is a two-part
identifier for file formats no the Internet. A media type is composed of at least two
parts: a type, a subtype and one or more optional parameters (e.g. “image/png”).
National Bank of Belgium
Simple Object Access Protocol
SOAP is a lightweight protocol intended for exchanging structured information in a
decentralized, distributed environment. It uses XML technologies to define an
extensible messaging framework providing a message construct that can be
exchanged over a variety of underlying protocols. The framework has been designed
to be independent of any particular programming model and other implementation
specific semantics. (Definition from http://www.w3.org/TR/soap/)
Secure Socket Layer are cryptographic protocols that provide security for
communications over networks such as the Internet.
User to Application ; refers to the interaction between an user and an application.
A Web service is a software system designed to support interoperable machine-tomachine interaction over a network. It has an interface described in a machineprocessable format (specifically WSDL). Other systems interact with the Web service
in a manner prescribed by its description using SOAP messages, typically conveyed
using HTTPS with an XML serialization in conjunction with other Web-related
standards. (Definition issue from the W3C)
Web Services Definition Language
WSDL is an XML-based language for describing Web services and how to access
them.
25