Get Customer Balances

Service Protocol: REST

This web service uses a REST or RESTful style protocol. This is an HTTP resource-oriented architecture that uses standard HTTP actions (e.g. GET, POST, DELETE) to manipulate resources exposed as URLs. Standard HTTP Status Codes are used for success and error codes.

More information on REST can be found at the following resources:

• Wikipedia: Representational State Transfer

• REST Architecture Style

Service Authentication

The HTTP request must have Basic Authentication credentials included. We strongly recommend that all web service requests be made over SSL (HTTPS).

More information on HTTP Basic Authentication can be found at the following resources:

• Wikipedia: HTTP Basic Authentication

• HTTP Authentication: Basic and Digest Access Authentication

TrackAbout will provide you with a dedicated user account to use when making web service requests.

Troubleshooting Service Authentication/Authorization Issues

When calling a web service, TrackAbout will return a "403 Access Denied" error if there are any issues authenticating the request. These errors can occur under one or more of the following circumstances:

1. The authentication header is missing or not formatted correctly. To correct this, review the links on HTTP Basic Authentication above and ensure that the application you are using to call the web service is building the authorization header correctly.

2. The username and/or password specified in the authentication header is incorrect or the user does not have the permissions needed invoke web services. If you have both a production and test instance of TrackAbout it's important to remember that they each have a distinct set of users and login credentials; a username and password that works in the production environment will not necessarily work in the client test environment and vice-versa.

   To verify and/or correct this:

Service Metadata

TrackAbout creates Web Application Description Language (WADL) documents for all web services that make use of REST architecture. The WADL for a service is accessible via the web service's URL with the word 'meta' appended as a query string parameter. For example, to access the WADL for the simple 'Echo' web service, you would use the following URL: https://www.trackabout.com/ws/Echo.asmx?meta

You can also specify a particular version of a web service to retrieve metadata for by including the major, minor, and revision numbers of the desired version in the query string. For example, to get the WADL for version 2.0.0 of the 'Echo' service, the URL becomes: https://www.trackabout.com/ws/Echo.asmx?v2.0.0&meta

More information on WADL can be found at the following resources:

• Web Application Description Language

Standard Service Parameters

The following standard web service parameters are available for this RESTful web service. These parameters are optionally provided via the querystring of the URL used to access the service.

Friendly Name	Query String Name	Description
Retrieve Metadata	meta	When this parameter is provided, the service will return its WADL document instead of doing the normal processing.
Use Encryption	e	The presence of this parameter enables request and response payload encryption using public/private X.509 certificates. Certificates must be exchanged and configured in advance of using this parameter. This encryption is separate from standard HTTPS/SSL encryption. Both can be used together.
Use Specific Version	vX.X.X	Specifies the version of the service being called. For example, the parameter value 'v2.2.5' specifies that Version 2.2.5 should be used.
Use Gzip Compression	gz	Indicates that gzip compression should be used for the response.
Use Zip Compression	zip	Indicates that zip compression should be used for the response.
Use Bz2 Compression	bz2	Indicates that bz2 compression should be used for the response.

Validations and Restrictions

The following validations are applicable to the data and parameters provided to this service. If one or more of these validations fail, the web service will return a response status code and error message that indicates the source of the failure.

• The username and password provided must be valid

• The XML submitted must conform to the expected schema as outlined in the service metadata.

Processing Rules

• For pending orders, if an existing order is found in the system matching the order number, the existing order is updated. Otherwise, a new order is created.

• For invoiced orders, if a delivery record is not found in the system matching the order number and customer, a delivery record is created in the system.

• Deletion is only supported for pending orders. A HTTP DELETE method is used for the deletion.

Request Output

When all provided data is processed without any errors, the service returns a HTTP status code of 200. When one or more processing errors are encountered, the HTTP status will be set to an HTTP error code. The body of the response will contain text describing the error that occurred.