REVENUE ONLINE SERVICE

Transcription

1 REVENUE ONLINE SERVICE Page 1 of 8

2 DOCUMENT CONTROL Document Holder Brian Jones Change History Version Date Change /11/01 Document Created /06/2012 Updated the following fields to allow them to support the new format registration numbers. The update involves a change to the regular expression used to determine if a number is valid. Change Details: Before: [0-9]{7,8}[A-Wa-w][TWXtwx ]? After: [0-9]{7,8}[A-Wa-w][A-ITWXZa-itwxz ]? Sample Numbers: Existing Format: T New Format: FA Section Section 2 Section 2 Appendix A Field Client Search registration TaxRegistration - registration Added A3 Sample response with new format numbers. Page 2 of 8

3 CONTENTS 1. INTRODUCTION CALLING THE SERVICE NAMESPACES, SCHEMAS AND LOCATIONS OPERATION HEADER DIGITAL SIGNATURE INTERPRETING THE RESPONSE... 6 A. EXAMPLES... 7 A.1. REQUEST TO RETRIEVE A FULL CLIENT LIST... 7 A.2. RESPONSE... 8 Page 3 of 8

4 1. INTRODUCTION This document is a specification for the ROS web service for retrieving an agent s client list. It covers all the necessary arrangements for calling this web service that are specific to this operation. 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 retrieving the client list can be used to retrieve a full or partial client list for an agent. The list will include the client s name and a full list of all their registrations, to which the agent has access. A partial list can be retrieved by specifying search criteria for the list. This criteria can consist of the start of the client s name, the date from which the agent-client relationship started, or the registration of the client. Page 4 of 8

5 2. CALLING THE SERVICE The ROS web service for the client list is described through the WSDL file and the schema for the client list. This schema is also referenced within the WSDL file. These files will be located at 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.1. Namespaces, Schemas and Locations The client list web service uses the two namespaces enumerated in the Overview Specification. It also uses an additional namespace specifically for the client list. This extra namespace is used to define all the elements for describing the administration services and its responses. Description Namespace Location The client list elements schemas/client/ schemas/client/schema.xsd Basic types for ROS schemas and web services schemas/rostypes/ schemas/rostypes/schema.xsd Web service messages, operations, bindings, etc. schemas/service/ schemas/ros.wsdl 2.2. Operation Header 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 client list web service, the operation header should be Client/ClientList/Retrieve Client/ClientList/Retrieve This operation can be used to retrieve a full or partial list of an agent s clients Digital Signature The client list web service will always require a digital signature. Page 5 of 8

6 3. INTERPRETING THE RESPONSE The response from this web service will be a ClientList element. This will contain a series of ClientDescription elements, each of which will contain a series of TaxRegistration elements. The ClientDescription element has a name attribute that specifies the client name. It then contains all the registrations of the client to which the agent has access. Each one of these is contained in a TaxRegistration element, which has attributes taxtype and registration which together fully specify the registration of the client. If the search criteria specified in the input does not match any of the agent s clients, an empty ClientList element will be returned. (Note that in the ClientSearch input document, if the registration attribute is completed without the taxtype attribute, it will be ignored). Page 6 of 8

7 A. EXAMPLES A.1. Request to retrieve a full client list <soap:envelope xmlns:soap=" <soap:header> <wsse:security xmlns:wsse= > <wsse:binarysecuritytoken valuetype= wsse:x509v3 encodingtype= wsse:base64binary id= X509Token > MIIEZzCcA9cgwaABQfd86afd2g... </wsse:binarysecuritytoken> <ds:signature xmlns:ds= > <ds:signedinfo> <ds:canonicalizationmethod> Algorithm= /> </ds:canonicalizationmethod> <ds:signaturemethod Algorithm= /> <ds:reference URI= #MsgOperation > <ds:digestmethod Algorithm= /> <ds:digestvalue>djbchm5gk...</ds:digestvalue> </ds:reference> <ds:reference URI= #MsgBody > <ds:digestmethod Algorithm= /> <ds:digestvalue>djbchm5gk...</ds:digestvalue> </ds:reference> </ds:signedinfo> <ds:signaturevalue>lylsf0pi4wpu...</ds:signaturevalue> <ds:keyinfo> <wsse:securitytokenreference> <wsse:reference URI= #X509Token /> </wsse:securitytokenreference> </ds:keyinfo> </ds:signature> </wsse:security> <Operation xmlns=" id= MsgOperation >Client/ClientList/Retrieve</Operation> </soap:header> <soap:body id= MsgBody > <ClientSearch xmlns= /> </soap:body> </soap:envelope> Page 7 of 8

8 A.2. Sample Response 1 (Existing format numbers) <soap:envelope xmlns:soap=" <soap:body> <ClientList xmlns= > <ClientDescription name= The Client Company > <TaxRegistration taxtype= PAYE-Employer registration= D /> <TaxRegistration taxtype= VAT registration= L name= Name for VAT /> </ClientDescription> <ClientDescription name= Firstname Lastname > <TaxRegistration taxtype= Income Tax registration= T /> </ClientDescription> </ClientList> </soap:body> </soap:envelope> A.3. Sample Response 2 (New format numbers) <soap:envelope xmlns:soap=" <soap:body> <ClientList xmlns= > <ClientDescription name= The Client Company > <TaxRegistration taxtype= PAYE-Employer registration= FA /> <TaxRegistration taxtype= VAT registration= NA name= Name for VAT /> </ClientDescription> <ClientDescription name= Firstname Lastname > <TaxRegistration taxtype= Income Tax registration= FA /> </ClientDescription> </ClientList> </soap:body> </soap:envelope> Page 8 of 8