General Overview
This document is intended for developers of SureTax customers who want to consume one or more SureTax Services directly.
SureTax services allow the users to communicate with the calculation engine to perform a particular task within the SureTax application (e.g., calculation of tax liability). In order to perform these tasks, you need to consume the services.
This Application Programming Interface (API) document defines the structures and methods that are used in the CCH SureTax tax rating and calculation system. The CCH SureTax system can be used for tax calculation of product and services on a "real-time" basis by submitting web request/response messages via Internet services using REST or SOAP.
With the API, the request interface is an object in your application's native programming language. Clients are available in different programming languages. Most modern software languages have SOAP/REST toolkits to generate native programming code for the API consumption. Your application can process these generated object properties, and it can send and receive the data by calling the object methods.
Note that the current implementation is synchronous, where a response is provided for each request submitted. Each request can contain one-to-many items (transaction records) which can correlate multiple customers and/or invoices.
Connecting to the API
In order to communicate with the SureTax API you'll need an active SureTax Account. With your account you'll be provided a SureTax Client Number and Validation Key.
Environments
SureTax provides two different environments for every new account: CERT and PRODUCTION. They are completely separate environments, and each is provisioned its own credentials. We keep CERT and PRODUCTION credentials separate to help you test your software in without the risk of accidentially affecting production data.
CERT
https://testapi.taxrating.net/
This is your SureTax Sandbox/Certification environment. All new customers will begin their development, setup and tax calculation configuration in this environment. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION.
Note
SureTax's CERT environment architecture is not as robust and load balanced as our PRODUCTION environment. As you are testing your integration, we ask that do you do not perform any stress or load testing against our CERT environment. It will not be a true representation of PRODUCTION and CERT will be unable to withstand the load.
PRODUCTION
https://api.taxrating.net/ This is your live SureTax account. This account will not be initially actived when your accounts are created. All initial configuration and setup is performed in your CERT account. After you have performed your user acceptance testing in the SureTax CERT environment and provided written sign off to our SureTax implementation team, you will be allowed access to migrate to PRODUCTION. Your implementation team will assist in copying any configuration over from CERT into your PRODUCTION account prior to account activation.
Method Definitions
Calculation Request
This method is used for calculation of taxes for the specified transaction. Transactions are defined in SureTax by their status. There are three transaction statuses available in SureTax:
- Quote - (ReturnFileCode = Q) This status is used for tax calculation lookup only.
- In Progress - (ReturnFileCode = T) This status is used to create an In Progress/Non-Finalized transaction
- Finalized - (ReturnFileCode = 0) This status reflects a Finalized/Posted transaction.
Cancel Request
This method is used to cancel an In-Progress or Finalized transaction. You cannot call the Cancel Request method until you have successfully created an In-Progress transaction or Finalized the transaction in SureTax.
Finalize Request
This method is used to finalize a In-Progress transaction. You cannot call the Finalize Request method until you have successfully called the Calculation Request method at least once creating an In-Progress transaction (ReturnFileCode = T). This method must be called when a user's order is committed/finalized. Utilizing a finalize request will not incur a new tax calculation, it will only change the status of your transaction from In-Progress to Final.
Tax Adjustment Request
This method is used for sending tax adjustment amounts for a transaction. The total tax amount is required to return the correct tax details.
REST
For web requests submitted via REST, the data should be formatted using either JSON or XML format. The response format type is the same as the request format.
When supplying the request as a POST variable, the request value would be supplied as: request={<JSON or XML>} The Headers Content-Type value would be provided as: "Content-Type:application/x-www-form-urlencoded".
If you want the JSON request to be serialized, the request value would be supplied as: {"request":'<JSON>'} The Headers Content-Type value would be provided as: "Content-Type:application/json". This response will be returned wrapped in a "d" object. The object response will contain additional backslashes to escape double quotes around field names and values.
SOAP
For requests submitted via SOAP, responses are provided in same XML format as the request. The SOAP API schema defines the SOAP messages that you can use to access the SureTax API. SOAP clients can handle the generation of the SOAP request, send the data to the SureTax application, and then convert the data back to the programming interface so that you can use the objects in your application.
The SureTax API has a WSDL that describes its web service. The SureTax General API WSDL can be located at: <environment url>/Services/General/V01/SureTax.asmx?wsdl
For example environment URL for CERT and PROD would be:
CERT: https://testapi.taxrating.net/Services/General/V01/SureTax.asmx?wsdl
PROD: https://api.taxrating.net/Services/General/V01/SureTax.asmx?wsdl
Documentation standards
Note
Field names formatted in BOLD are required fields that must be passed to SureTax API.
All Field Names are case-sensitive.
Field values are required unless otherwise noted in their description below.
Order Workflow
