Specification - ROS

Document Sample
Specification - ROS Powered By Docstoc
					Revenue Online Services
CT1                                                 Web Service Specification




                          Revenue Online Services

                    Web Service Specification
                              CT1




           Last Updated                 13/01/11
           Document Version             1.0




                                   Page 1 of 7
  Revenue Online Services
  CT1                                                                                                                                            Web Service Specification

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        CT1/Calculate ................................................................................................................................................ 5
     2.4.2        CT1/File .......................................................................................................................................................... 6
  2.5     Digital Signature ..................................................................................................................................................... 6
3    Interpreting The Response............................................................................................................................................. 7
  3.1     CT1/Calculate ........................................................................................................................................................ 7
  3.2     CT1/File .................................................................................................................................................................. 7
  3.3     SummaryCalculation .............................................................................................................................................. 7
  3.4     Errors ..................................................................................................................................................................... 7




                                                                                    Page 2 of 7
Revenue Online Services
CT1                                                              Web Service Specification

0        DOCUMENT INFORMATION

0.1      Synopsis
       Specification for the CT1 web service.

0.2      Change History
       Table 1: Change History

      Version       Section        Change Description                            Date
      Number        Affected
        0.1           ALL          Initial Draft                                13/01/11
        1.0           ALL          Final                                        13/01/11




                                                   Page 3 of 7
Revenue Online Services
CT1                                                                                          Web Service Specification

1 WEB SERVICE OVERVIEW
      This document is a specification for the ROS CT1 web service. It covers all the necessary arrangements for calling
      this web service that are specific to the CT1 Return. 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 CT1 Return provides 2 basic services:
             Anonymous validation and calculation of a CT1
             Submission of the CT1 to Revenue


      These services are covered in this document.




                                                     Page 4 of 7
 Revenue Online Services
 CT1                                                                                            Web Service Specification

2 CALLING THE SERVICE
        The ROS web service for the CT1 Return is described through the WSDL file and the Schema. This schema is also
        referenced within the WSDL file.



2.1     WSDL File
        Download from http://www.ros.ie/schemas/ros.wsdl
        The WSDL file is discussed in greater detail in the Overview Specification, including
                Where the web service is located
                What protocol must be used



2.2     Web Service Schemas
        Download from http://www.ros.ie/PublisherServlet/info/wsindex
        Please ensure to download the appropriate schema for the return and period that you are attempting to file.
        Review the schema notes for the chosen return schema for more information on the elements and their validation
        rules.



2.3     Namespaces, Schemas and Locations
        The CT1 web service uses the two namespaces enumerated in the Overview Specification. It also uses an
        additional namespace specifically for the CT1 Return. This extra namespace is used to define all the elements for
        describing the CT1 Return and its calculation.


 Description                  Namespace                                 Location
 Basic types for ROS          http://www.ros.ie/schemas/rostypes/       http://www.ros.ie/schemas/rostypes/schema.xsd
 schemas and web
 services
 Web service messages,        http://www.ros.ie/schemas/service/        http://www.ros.ie/schemas/ros.wsdl
 operations, bindings, etc.
 The CT1 Return               Determine the namespace from the          http://www.ros.ie/PublisherServlet/info/wsindex
 elements                     Correct Schema Version for the
                              required period




2.4     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 CT1 web service, there are 2 options depending on which
        operation you wish to call:
                CT1/Calculate
                CT1/File

2.4.1    CT1/Calculate
        This operation can be used to indicate that the CT1 should be validated and the liability calculated, but not
        submitted. When this service is being used, neither the Company name nor the Company Reference number need
        be completed. The result from this will be an Acknowledgement, as defined in the schema. Either an ErrorList or a
        SummaryCalculation will be returned in the acknowledgement, depending on whether or not the validation was
        successful. The NoticeNumber will never be present.




                                                        Page 5 of 7
 Revenue Online Services
 CT1                                                                                         Web Service Specification

2.4.2    CT1/File
        This operation can be used to indicate that the CT1 should be validated and submitted to Revenue. If this is
        successful, the CT1 will be processed by Revenue. The return value will be an Acknowledgement with a
        NoticeNumber and a SummaryCalculation. If the validation of the CT1 is unsuccessful, the CT1 will not be
        processed any further by Revenue. The return value in this case will be an Acknowledgement with only an ErrorList
        present.



2.5     Digital Signature
        The CT1 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)
 CT1/Calculate                                        No
 CT1/File                                             Yes




                                                       Page 6 of 7
Revenue Online Services
CT1                                                                                            Web Service Specification

3 INTERPRETING THE RESPONSE
      The response from this web service will be an Acknowledgement element. This element extends the
      AcknowledgementType described in the Overview Specification.


      In addition to the elements and attributes declared as part of the AcknowledgementType type, there may also be a
      SummaryCalculation element. This element will only be returned if the validation was successful. It contains details
      of the calculation and total liability as calculated by Revenue for the submitted CT1.



3.1   CT1/Calculate
      If the operation is CT1/Calculate, then a successful validation of the form will return a SummaryCalculation while
      an unsuccessful one will return an ErrorList containing the errors. See below for an explanation of the
      SummaryCalculation & ErrorList elements.
      A NoticeNumber will never be returned.

3.2   CT1/File
      If the operation is CT1/File, then a successful validation of the form will return a SummaryCalculation while an
      unsuccessful one will return an ErrorList containing the errors. See below for an explanation of the
      SummaryCalculation & ErrorList elements.



3.3   SummaryCalculation
      When validation is successful, a SummaryCalculation will be returned. This element breaks down the liability
      calculation performed by Revenue. This calculation changes from year to year, so the SummaryCalculation
      element must be interpreted in the context of which version was submitted. Please see the appropriate Appendix
      below.



3.4   Errors
      There are two different checks done for any form submitted via Webservice. Firstly, the XML file 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 data within the form is checked. This will include checks on the values for each
      element and for discrepancies between values in different elements. Attributes of elements are also checked.


      Any errors in these checks will produce error text with the name of the element that contained the error and the
      Panel the error occurred in, like the following:
      PPSN (Personal Details) is a required field.




                                                       Page 7 of 7

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:3
posted:11/14/2012
language:Latin
pages:7