REST Web Services

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

Security

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 gb_users_access_log table.

Output Format Selection

By default, the web service will respond with data in an XML format. This can be changed by passing the rest_response_format 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

Code Examples

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

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.

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 with a planned end date of 31/12/2024. Access is managed by Catch-e staff using the control 'webservices_access_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.

Legacy Web Service Families

General Ledger (gl)

Class: system

The 'system' family of web services provides administrative calls for maintenance of the general ledger sub-system.

Method	Synopsis	Status
reserveBatchNos	Reserve a sequence of batch numbers	Deprecated - Use ReserveBatchNosWebService instead
reserveInvoiceNos	Reserve a sequence of invoice numbers	Deprecated - No replacement available
reservePaymentNos	Reserve a sequence of payment numbers	Deprecated - Use ReservePaymentNosWebService instead

Global (gb)

Class: system

The 'system' family of web services provides system access operations.

Method	Synopsis	Status
executeScript	Execute a script	Deprecated - Use executeScript API instead
exportQuery	Executes a SELECT type query, stored in gb_queries, returning the output directly in an XML format. This service is typically used by external systems as an export interface.	Active
query	Execute a query	Deprecated - Use Print a report query API instead
getToken	Allows you to access a web service via a token rather than using a login and password. This allows you to securely call a web service directly from your web page.	Active
useToken	Consume a web service using a token issued by getToken	Active
signon	Issues a single signon session ID	Deprecated - Use Generate a signon token API instead
reserveMailBatchNos	Reserve mail batch numbers	Deprecated - No longer available
reserveInterfaceBatchNos	Reserve interface batch numbers	Deprecated - Use ReserveInterfaceBatchNosWebService instead

Class: record

The 'record' family of web services provides access to the database for CRUD operations.

Method	Synopsis	Status
upsert	Insert or update a record	Deprecated - Use Insert or update a record with auditing API instead
readRecord	Allows you to read values for a single record	Deprecated - No longer supported
lockRecord	Lock a record	Deprecated - No longer supported
unlockRecord	Unlock a record	Deprecated - No longer supported
deleteLock	Delete a lock	Deprecated - Use deleteLocks API instead

Class: attachments

The 'attachments' family of web services provides attachment handling operations.

Warning: The 'attachments' family of web services has been deprecated and is no longer supported by Catch-e. You must use APIs > Attachments to develop attachment API functions.

Method	Synopsis	Status
saveAttachment	Allows you to save an attachment via a web service rather than using the regular web-based attachment upload function.	Deprecated
loadAttachment	Allows you to load attachment source details via a web service.	Deprecated
deleteAttachment	Allows you to delete an attachment via a web service.	Deprecated

Class: systemmaintenance

The 'systemmaintenance' family of web services provides access to maintenance processes at the system level.

Method	Synopsis
rebuildCostCentreAllocations	Allows you to rebuild the fm_contract_cost_centre_allocations table. This can be useful after you have imported some 'CC' type contract events and want to run certain reports straight away, e.g. the Accidents report. The scheduler typically runs this at 10pm daily.
rebuildDivisionAllocations	Allows you to rebuild the fm_contract_division_allocations table. This can be useful after you have imported some 'DIV' type contract events and want to run certain reports straight away, e.g. the Accidents report. The scheduler typically runs this at 10pm daily.
rebuildDriverAllocations	Allows you to rebuild the fm_contract_driver_allocations table. This can be useful after you have imported some 'DRIVER' type contract events and want to run certain reports straight away, e.g. the Accidents report. The scheduler typically runs this at 10pm daily.

Fleet Management (fm)

Class: drivers

Method	Synopsis
signon	Issues a single signon session ID that can bypass the login screen once only. This service is normally used from a secure web page, e.g. from an intranet page that itself is password protected, so the user doesn't have to log into both systems.

Quick Quotes (qq)

Class: vehicle_lookup

Warning: The vehicle_lookup family has been deprecated and is no longer supported by Catch-e. You must use Quotes / Variants APIs instead.

Class: vehicle

Method	Synopsis	Status
getMakes	Get a list of vehicle makes as make_id / name pairs. Suitable for use in a list box.	Active
getModels	Get a list of models for a given vehicle make as model_id / name pairs. Suitable for use in a list box.	Active
getModelYears	Get a list of model years for a given vehicle model. Suitable for use in a list box, using as both the option and value properties.	Active
getBodyTypes	Get a list of body_type_id / body_type pairs for a given vehicle model and model year. Suitable for use in a list box.	Active
getVariants	Get a list of variant_id / description pairs for a given vehicle model, model year, and body type. Suitable for use in a list box.	Active
getVariant	Get field values for a given vehicle variant returning individually requested fields or all fields if none are requested. These values can be used with other services in the lease web services family, e.g. getQuote.	Active
getVariantPhotos	Get list of photo codes and corresponding types for a given vehicle variant. Photo codes are provided by the vehicle data supplier and are typically used as the file name for each image. Types describe the orientation of the photo e.g. 'front'.	Active
getOptionalEquipment	Get list of optional equipment and price for a given vehicle variant. The value returned is in a Description and List Price (Gross) pair identified by a unique ID.	Active
getStandardEquipment	Get list of standard equipment for a given vehicle variant. The value returned is the Description identified by a unique ID.	Active

Quick Quotes Lease (qq / lease)

Class: lease

The 'lease' family of web services provides access to the novated lease calculation engine in the Catch-e Quotes module.

Method	Synopsis	Status
getQuote	Get quote information	Deprecated - Use getQuickQuoteWebService instead

Salesforce (salesforce)

Class: quotes

The 'salesforce' family of web services provides access to sales related functionality within Catch-e, e.g. generating quotes, creating drivers, printing quote PDFs.

Method	Synopsis	Status
createQuote	Create a new quote	Deprecated - Use createQuoteWebService API instead

Quotes (quotes)

Class: quotes

The 'quotes' family of web services provides access to quote related functionality from Catch-e.

Method	Synopsis	Status
copyQuote	Copy an existing quote	Deprecated - Use copyQuote API instead
getQuote	Get quote information	Deprecated - Use getQuoteFieldsWebService or Render Quote PDF API instead
getDealerOrder	Generates dealer order (default format is Excel) based on an existing Catch-e quote.	Deprecated - No longer supported
getAftermarketOrder	Get aftermarket order	Deprecated - No longer available
recalculateQuote	Recalculate quote	Deprecated - Use patchQuote API instead

Migration Path

The following table summarizes the migration path from legacy web services to current token-based APIs:

Legacy Service	Replacement API
reserveBatchNos	ReserveBatchNosWebService
reservePaymentNos	ReservePaymentNosWebService
reserveInterfaceBatchNos	ReserveInterfaceBatchNosWebService
executeScript	executeScript API
query	Print a report query API
upsert	Insert or update a record with auditing API
deleteLock	deleteLocks API
signon (gb)	Generate a signon token API
getQuote (qq/lease)	getQuickQuoteWebService
createQuote (salesforce)	createQuoteWebService API
copyQuote	copyQuote API
getQuote (quotes)	getQuoteFieldsWebService or Render Quote PDF API
recalculateQuote	patchQuote API
Attachments family	APIs > Attachments
vehicle_lookup family	Quotes / Variants APIs

Notes

All legacy web services requiring deprecated functionality should migrate to the corresponding token-based APIs
XML and JSON response formats are supported for REST services
Web service user accounts must be configured with the 'web_services' role
HTTPS is required for all web service calls
End of support for legacy services is 31/12/2024
Your HTML quote templates will need updating when legacy services are fully deprecated