API Overview & Authentication: Consume Web Service Rest

Consume Web Service Rest

Our REST based web services are called using a URL directly over HTTPS with additonal input values passed as POST or GET parameters. A response is given in the form of a simple XML document.

Using HTTPS to consume our web services provides a high level of security. For increased security, each web service call must include the login and password of an existing user account in the POST (or GET) parameters. This user account must belong to the role 'web_services'. If no such user exists in Catch-e, you will need to create one first.

Web Services are accessed by using a user login with a 'webservice' role. If a login fails, this will be recorded in the gbusersaccesslog table.

Output format selection

By default, the web-service will respond with data in an XML format.

This can be changed by passing the restresponseformat variable in your POST/GET request to the REST endpoint.

The REST interface currently supports two response mode values: xml and json.

Example web-service call utilising a JSON response format:

https://yourname.catch-e.net.au/services/fm/drivers/signon?driver_id=100000&surname=Quinn&rest_response_format=json

Consuming Web Service from JQuery

The following example uses the popular JQuery JavaScript library. You would need to replace values such as 'username' with applicable values:

var webserviceAPI = 'https://yourname.catch-e.net.au/services/qt/quotes/getQuote?login=username&password=password&rest_response_format=json&output_mode=fields&quote_id=100000';$.getJSON(webserviceAPI, function(data) { // data contains the JSON response data if (data.error == undefined) { // web service call successful // Example referencing data from the JSON response alert(data.quote.quote_id); } else { // web service error has been triggered. Failure reason contained in JSON structure. alert('An API error has been triggered: ' + data.error); }}).fail(function { // Failure invoking web-service URI alert('An API error has occured. Aborting...');});

Consuming Web Service from PHP

The following example uses the Curl library. You need to replace values such as 'yourname' with applicable values:

if (strstr(PHP_OS, 'WIN') && !extension_loaded('curl')) { dl('php_curl.dll'); }$curl_handle = curl_init;curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);curl_setopt($curl_handle, CURLOPT_SSL_VERIFYPEER, 0);curl_setopt($curl_handle, CURLOPT_SSL_VERIFYHOST, 0);curl_setopt($curl_handle, CURLOPT_HTTPPROXYTUNNEL, 0);curl_setopt($curl_handle, CURLOPT_URL, 'https://yourname.catch-e.net.au/services/fm/drivers/signon?driver_id=100000&surname=Quinn');curl_setopt($curl_handle, CURLOPT_POST, 1);curl_setopt($curl_handle, CURLOPT_POSTFIELDS, 'login='.urlencode('??????').'&password='.urlencode('#######'));$curl_result = explode("\r\n\r\n", curl_exec($curl_handle));

Consuming Web Service from .NET

Note: this C# code snippet is indicative and not production ready.

protected string FetchesWebPageUsingHttpRequest(StringDictionary sd, string url, string method) { string postParameters = ""; // used to build entire input StringBuilder sb = new StringBuilder; // used on each read operation byte[] buf = new byte[8192]; // prepare the web page we will be asking for HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); if (method == "POST") { // Add each of the input elements to the request IEnumerator e = sd.GetEnumerator; while (e.MoveNext) { DictionaryEntry de = (DictionaryEntry)e.Current; postParameters += "&" + de.Key + "=" + de.Value; } request.ContentType = "application/x-www-form-urlencoded"; request.ContentLength = postParameters.Length; } // Set the method type "POST" or "GET" request.Method = method; // Write the request StreamWriter stOut = new StreamWriter(request.GetRequestStream, System.Text.Encoding.ASCII); stOut.Write(postParameters); stOut.Close; // Do the request to get the response StreamReader stIn = new StreamReader(request.GetResponse.GetResponseStream); string strResponse = stIn.ReadToEnd; stIn.Close; return strResponse.ToString;}

Legacy Web Services

Overview

This page documents our legacy web services that are password based.
Visit the APIs page for details about our current token based APIs.

Legacy Web Services are being progressively deprecated and the planned end date is 31/12/2024.
Access is managed by Catch-e staff using the control 'webservicesaccess_flag').

When these services have been deprecated, your HTML quote will need an update to continue work.
Visit the Quote Template Setup page for the update details.

Warning:
Our password based legacy web services are no longer supported by Catch-e.
You must use the token based APIs instead.
New use of legacy web services is not authorised by Catch-e.

General Ledger (gl)