DO NOT USE



[pic]

|Revenue Online Services |

Web Service Specification

iXBRL Financial Statements

|Last Updated |25/10/12 |

|Document Version |0.2 |

Contents

Contents 2

0 Document Information 3

0.1 Synopsis 3

0.2 Change History 3

1 Web Service Overview 4

2 Calling the Service 5

2.1 WSDL File 5

2.2 Web Service Schemas 5

2.3 Namespaces, Schemas and Locations 5

2.4 Operation Headers 5

2.4.1 XBRL/Submit 6

2.5 Digital Signature 6

3 Interpreting The Response 7

3.1 XBRL/Submit 7

3.2 XBRL/CheckSubmissionStatus 7

3.3 XBRL/Validate 7

3.4 XBRL/CheckValidationStatus 7

3.5 Errors 7

Document Information

2.1 Synopsis

Specification for the iXBRL Financial Statements web service.

2.2 Change History

Table 1: Change History

|Version Number |Section Affected |Change Description |Date |

|0.1 |ALL |Initial Draft |10/09/12 |

|0.2 |2.4.3, 2.4.4 |Added PIT Note, and clear down details |25/10/12 |

Web Service Overview

This document is a specification for the ROS iXBRL Financial Statements web service. It covers all the necessary arrangements for calling this web service that are specific to iXBRL Financial Statements. It should be read in conjunction with the Overview Specification, which discusses the general approach to calling a ROS web service.

The ROS web service for the iXBRL Financial Statements provides 4 basic services:

• iXBRL Submission

• Check iXBRL Submission

• iXBRL Validation Only

• Check iXBRL Validation Only

These services are covered in this document.

Calling the Service

The ROS web service for iXBRL Financial Statements is described through the WSDL file and the Schema. This schema is also referenced within the WSDL file.

4.1 WSDL File

Download from

General details relating to ROS WSDL files are discussed in greater detail in the Overview Specification, including

• Where the web service is located

• What protocol must be used

• How to canonicalise messages before signing them

• Methods of signing messages

4.2 Web Service Schemas

Download from the “Specifications and Schemas for Web Services” page on ROS ( )

Please ensure to download the appropriate schemas to use the iXBRL Financial Statements Web Service. These are:

• iXBRL WSDL – xbrl.wsdl

• ROS Basic Types - schema.xsd

• iXBRL – xbrl-schema.xsd

Please ensure to save XSD files in the UTF-8 format.

Review the schema notes for the chosen schema for more information on the elements and their validation rules.

4.3 Namespaces, Schemas and Locations

The iXBRL Financial Statements web service uses the ROS Basic Type namespaces enumerated in the Overview Specification. It also uses an additional namespace specifically for the iXBRL Financial Statements This extra namespace is used to define all the elements for describing the iXBRL Financial Statements and their submission/validation.

|Description |Namespace |Location |

|Basic types for ROS schemas and | | |

|web services | | |

|Web service messages, operations,| | |

|bindings, etc. | | |

|The iXBRL Financial Statements | | |

|elements | | |

4.5 Operation Headers

As discussed in the Overview Specification, it is necessary to provide an Operation header in the SOAP request to identify which web service you wish to call. For the iXBRL Financial Statements web service, there are 4 options depending on which operation you wish to call:

• XBRL/Submit

• XBRL/CheckSubmissionStatus

• XBRL/Validate

• XBRL/CheckValidationStatus

4.5.1 XBRL/Submit

The XBRL/Submit operation allows users to submit iXBRL Financial Statements into ROS.

The message will be of the XBRLSubmissionRequest type (defined in xbrl-schema.xsd). This element must contain a Return Details element and a Statements element. The Return Details element must contain:

• the tax type against which the statements are being submitted (Corporation Tax or Income Tax)

• the registration number for the tax type

• the period start and end dates

The period dates must match available Corporation or Income Tax periods on ROS.

The Statements element contains the actual iXBRL file in an inline xml format or as an encoded Base64Binary string.

Please note that validation of the iXBRL document contained in your message is a-synchronous. Calling the XBRL/CheckSubmissionStatus operation can retrieve issues and errors relating to the validation of your iXBRL document. Technical errors with your request as outlined in section 3.5 will be returned synchronously.

The Soap message to this operation must be wrapped and signed as per the Overview Specification. Messages should be sent in the UTF-8 format.

Note on canonicalisation

As described in the overview specification, the signature for a SOAP envelope is produced using a canonicalised version of the SOAP body. This is the same for the iXBRL Financial Statements web service.

Users should however, ensure that the SOAP body contains the original non-canonicalised message after signing as the canonicalization algorithm will invalidate iXBRL documents that are submitted in the plain XML format, and these will be rejected.

If you continue to experience issues around this, consider using the Base64Binary option to submit the iXBRL.

4.5.2 XBRL/CheckSubmissionStatus

The XBRL/CheckSubmissionStatus operation allows users to check the status of previously submitted iXBRL, and to view any iXBRL validation response messages if any.

The message will be of the CheckXBRLSubmissionRequest type (defined in xbrl-schema.xsd). This element must contain an acknowledgment number. (The number provided as a response from the XBRL/Submit operation.)

Technical errors with your request as outlined in section 3.5 will be returned synchronously.

The Soap message to this operation must be wrapped and signed as per the Overview Specification. Messages should be sent in the UTF-8 format.

Users may only check the submission status of iXBRL submissions made using the same certificate that has signed the XBRL/CheckSubmissionStatus request.

4.5.3 XBRL/Validate

The XBRL/Validate operation allows users to validate iXBRL Financial Statements via ROS. iXBRL Financial Statemnts sent to this operation will not be stored. Please note this operation is only available in the ROS Public Interface Test environment.

The message will be of the XBRLValidationRequest type (defined in xbrl-schema.xsd). This element must contain a Return Details element and a Statements element. The Return Details element must contain:

• the tax type against which the statements are being validated against (Corporation Tax or Income Tax)

• the period start and end dates

The Statements element contains the actual iXBRL file in an inline xml format or as an encoded Base64Binary string.

Please note that validation of the iXBRL document contained in your message is a-synchronous. Calling the XBRL/CheckValidationStatus operation can retrieve issues and errors relating to the validation of your iXBRL document. Technical errors with your request as outlined in section 3.5 will be returned synchronously.

The Soap message to this operation must be wrapped as per the Overview Specification but does not need to be signed. The message should be sent in the UTF-8 format.

4.5.4 XBRL/CheckValidationStatus

The XBRL/CheckValidationStatus operation allows users to check the status, and to view any iXBRL validation response messages if any of iXBRL previously sent to the XBRL/Validate operation. Please note this operation is only available in the ROS Public Interface Test environment.

The message will be of the CheckXBRLValidationRequest type (defined in xbrl-schema.xsd). This element must contain an acknowledgment number. (The number provided as a response from the XBRL/Validate operation.)

Technical errors with your request as outlined in section 3.5 will be returned synchronously.

The Soap message to this operation must be wrapped as per the Overview Specification but does not need to be signed. The message should be sent in the UTF-8 format.

Validation responses will be cleared down after 7 days. If you attempt to access a cleared down response older than 7 days you will receive the status of –1 in your response.

4.6 Digital Signature

The iXBRL Financial Statements web service may or may not require a digital signature depending on which operation is being accessed, according to the following table.

|Operation |Signature required (Yes/No) |

|XBRL/Submit |Yes |

|XBRL/CheckSubmissionStatus |Yes |

|XBRL/Validate |No |

|XBRL/CheckValidationStatus |No |

Interpreting The Response

The response from this web service will be an Acknowledgement element in the case of calling the submission or validation operations. When calling the check submission or check validation operations a Status Response object will be returned containing iXBRL validation messages if available.

The Specific response messages for each operation are discussed in more detail below.

5.1 XBRL/Submit

The XBRL/Submit operation will return an XBRLSubmissionResponse object. This will contain either an Acknowledgement number indicating successful receipt of your message, or a technical ErrorMessage (see section 3.5).

Please note that an acknowledgment number does not indicate that the iXBRL document submitted was valid. The XBRL/CheckSubmissionStatus operation should be called using the acknowledgment number to check the status of the submitted iXBRL.

5.2 XBRL/CheckSubmissionStatus

The XBRL/CheckSubmissionStatus operation will return an CheckXBRLSubmissionResponse object. This will contain the status of the iXBRL received and if necessary a list of validation messages. If there was a problem in processing the request, a technical ErrorMessage (see section 3.5) will be the only response.

The status number indicates the current status of the iXBRL file received as part of the earlier submission.

Status values can be interpreted as follows:

|Status Code |Status |Description |

|0 |Invalid |The iXBRL file that you have requested to check was marked as invalid. A list|

| | |of validation messages will also be returned. Please correct the iXBRL file |

| | |as per the validation messages before resubmitting. |

|1 |Valid |The iXBRL file that you have requested to check was marked as valid. No |

| | |further action is necessary. |

|-1 |Processing |The iXBRL file that you have requested to check is still being processed. |

| | |Please check again later. |

5.3 XBRL/Validate

The XBRL/Validate operation will return an XBRLValidationResponse object. This will contain either an Acknowledgement number indicating successful receipt of your message, or a technical ErrorMessage (see section 3.5).

Please note that an acknowledgment number does not indicate that the iXBRL document received was valid. The XBRL/CheckValidationStatus operation should be called using the acknowledgment number to check the status of the iXBRL.

5.4 XBRL/CheckValidationStatus

The XBRL/CheckValidationStatus operation will return an CheckXBRLValidationResponse object. This will contain the status of the iXBRL received and if necessary a list of validation messages. If there was a problem in processing the request, a technical ErrorMessage (see section 3.5) will be the only response.

The status number indicates the current status of the iXBRL file received as part of the earlier validation request.

Status values can be interpreted as follows:

|Status Code |Status |Description |

|0 |Invalid |The iXBRL file that you have requested to check was marked as invalid. A list|

| | |of validation messages will also be returned. Please correct the iXBRL file |

| | |as per the validation messages before resubmitting. |

|1 |Valid |The iXBRL file that you have requested to check was marked as valid. No |

| | |further action is necessary. |

|-1 |Processing |The iXBRL file that you have requested to check is still being processed. |

| | |Please check again later. |

5.5 Technical Errors Code

There are two different technical checks performed on any requests made to the iXBRL Financial Statement web service.

Firstly, the XML message is validated against the schema. Any errors at this stage will result in an error message like the following:

Error validating XML: cvc-complex-type.4: Attribute 'ppsnself' must appear on element 'ns3:Details'.

If the XML validation passes ok, the high-level data within the request is checked. Specifically focussing on the contents of the ReturnDetails object. If an error was encounter trying to process your request, an ErrorMessage type will be returned. Error codes, text and descriptions are outlined in the table below.

|Error Code |Error Text |Description |

|101 |Please provide a valid acknowledgment number |You have attempted to check an acknowledgment number that was not submitted |

| |relating to an XBRL upload you have made. |by you. |

| | |Please ensure if the acknowledgment number you are trying to check was for a |

| | |Submission please ensure that you are using the XBRL/CheckSubmissionStatus |

| | |operation, if it was a Validation please ensure that you are using the |

| | |XBRL/CheckValidationStatus operation. |

|102 |The XBRL service is temporarily unavailable, |ROS is currently unable to provide iXBRL functionality. Please try again |

| |please try again later. |later. |

|103 |You cannot currently file XBRL for this period. |This error relates to Submissions. It will be returned where iXBRL has |

| |You may not have a corresponding period or have |already been submitted for a period and this period has still has a status of|

| |already submitted XBRL for this period that is |Processing. Allow some time for the existing submission to finish processing |

| |still processing. |before re-attempting the new submission. |

| | |This error may also be returned if the period dates provided do not match |

| | |periods for which the user has permission to file on ROS. Period availability|

| | |an dates can be confirmed by logging into ROS. |

|104 |You have exceeded the polling period for which |You may only check the status of an acknowledgment number once every 10 |

| |you can check this acknowledgment number. Please|seconds. Any attempt to exceed this will be rejected. |

| |try again later. | |

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download