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