API Overview

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/

Permissions

Note: This permission and API are not available by default. Contact your Account Manager to get access to this API.

To run this API, the nominated 'web-services' role needs to be given permission. If you are not actively using the API, leave the permission off for better security.

Go to Roles / APIs and check on [add permission here].

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method '[METHOD]' for consuming this web service.

URL Examples

https://api.staging.catch-e.com/[path here]

Body (JSON)

JSON	Field Format	Notes	Mandatory
[Field name]	[type]	[description]	yes/no

Response Details

Validation Message	Comments
200 OK	The request was successful
401 - Unauthorized	You have not authenticated or session timeout
403 - Forbidden	You do not have permissions
422 - Unprocessable Entity	Validation failed

API Authentication Overview

Warning: This service is to be used by experienced developers ONLY. Please contact Catch-e Support if in any doubt.

Accessing APIs

A valid accesstoken must be passed in all queries in the 'Authorization' header. A valid accesstoken is generated by the API and returned by the /authenticate method by supplying a valid username and password.

The following syntax must be used in the 'Authorization' header:

Bearer aaaaaa/bbbbbb.ccccccc.dddddd

Security Scheme type: API Key

Header parameter name: Authorisation

Authentication Protocols

Field	Format	Notes	Mandatory
Client-Id	string	This is your client name as found in your Catch-e Login URL. For example: https://demo.catch-e.net.au	Yes
username	string	Catch-e username.	Yes
password	string	Catch-e password.	Yes
token_timeout	string	Timeout for token. If not set, the authenticating user's role session timeout will be used.	No
2fa_code	string	Catch-e two-factor authentication code.	No

JWT Claims

To access a specific API, your user Role must be found in gb_role_api_permissions for the respective gb_api_permissions (API function).

Both the permission and restriction values will be captured and encapsulated as claims within the JSON Web Token (JWT) provided during API authentication and renewal. Changes to the permissions/restrictions will only be refreshed on subsequent API calls to authenticate or renew.

Restrictions stored in gb_user_roles will be translated into the gb_user_api_restrictions table (where applicable).

API Restrictions

Overview

API restrictions control the display of fields in specific table entities for a particular role or user. They also define specific restrict clause predicates injected into the DB table gateway layer of the Zend/Db abstraction library utilised by the API.

Note: User API restrictions DO NOT override the role API restrictions; they simply complement/add to the existing restriction set.

Supported Predicates

The following predicates are supported in both the gb_role_api_restrictions and gb_user_api_restrictions tables:

equalTo
between
greaterThan
greaterThanOrEqualTo
in
isNotNull
isNull
lessThan
lessThanOrEqualTo
like
notBetween
notEqualTo
notIn
notLike

The data field in the predicate definition can be a string, numeric value or an array of the same. An array can be stored in the data field using the notation: [ ['value1', 'value2'] ]

Credential Handling in the API

Authenticate API

Run the Authenticate API first to generate the access token you need to pass on all the other APIs. No other API will run without an access token.

Permissions

Note: This API is not configured for external use. Contact your Account Manager to discuss access to this API.

APIs can only be run by Web Services users. For each API you want to use, give the Web Services role access to run the selected API. If you are not actively using an API, leave the permission off for better security.

To check or add access to an API:

Go to System / Roles and select the 'web_services' role
The role will display in the Roles / Details tab
Navigate to the Roles / APIs tab to see and edit the role's permissions

HTTP Method

Use the HTTP Method 'POST' to consume this API.

API Endpoints

Production: https://api.catch-e.com/authenticate

Other Environments: https://api.[environment].catch-e.com/authenticate

Replace [environment] with 'staging' or 'test' to run this API in those environments.

Input Fields

Key	Format	Notes	Mandatory
Client-Id	string	This is your client name as found in your Catch-e Login URL. For example: https://demo.catch-e.net.au	Yes
username	string	Catch-e username.	Yes
password	string	Catch-e password.	Yes
token_timeout	string	Timeout for token. If not set, the authenticating user's role session timeout will be used.	No
2fa_code	string	Catch-e two-factor authentication code.	No

Response Details - Successful

{ "access_token": "aaaaaa/bbbbbb.ccccccc.dddddd", "expires_in": 3600, "token_type": "bearer" }

Error Responses

401 - Unauthorized

Unauthorized - General

{ "detail": "Unauthorized" }

You have not authenticated before running this API or the token_timeout of the current session has passed. You need to authenticate again.

Authentication Failed - Invalid Credentials

{ "detail": "Authentication Failed - Invalid Username and/or Password. Password is case sensitive." }

Authentication Failed - Login Suspended

{ "detail": "Authentication Failed - Login suspended" }

The user's record is suspended; authentication will not be permitted.

Authentication Failed - Login Locked

{ "detail": "Authentication Failed - Login locked" }

The user's record is locked; authentication will not be permitted.

403 - Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "API access is not enabled for the user role" }

You are trying to authenticate a user that is not configured to use APIs. The user's role must have API access enabled.

422 - Validation Errors

Missing Username

{ "validation_messages": { "username": { "isEmpty": "Value is required and can't be empty" } } }

Pass a valid username.

Invalid Username Format

{ "validation_messages": { "username": { "invalidUserFormat": "Invalid username format" } } }

Pass a valid username.

Missing Password

{ "validation_messages": { "password": { "isEmpty": "Value is required and can't be empty" } } }

Pass a valid password.

Invalid 2FA Code Format

{ "validation_messages": { "2fa_code": { "invalidFormat": "2fa_code must be 6 digits" } } }

2FA must be a 6 digit code.

Invalid Token Timeout

{ "validation_messages": { "token_timeout": { "notDigits": "The input must contain only digits" } } }

Token timeout must be a valid digit. Maximum allowable timeout is 28800 seconds.

Troubleshooting - Chrome Password Manager

When using Chrome to Authenticate with the API, you may see an error message caused by stored passwords in Chrome for the requested URL.

To resolve:

Open a Chrome window
Select the three-dot icon in the top right corner
Choose "Settings"
Select "Autofill" option from the menu on the left
Select "Passwords"
From the displayed list under "Saved Passwords", find the site for which the error is shown
Select the delete icon to the right of the identified site
Select 'Remove'

The error will now be resolved.

Generate a Signon Token API

Get a signon token for a user to bypass the login process to gain entry to the system. The token can only be used once. The default screen resolution is 1024 x 768.

Overview

The Roles / Details "Single Signon" field can be used in conjunction with this service to prevent users from logging into the system directly when single signon is in use and another access method is required.

There are some minor differences in screen behaviour between external and internal users:

The Terms of Use and Privacy Policy links for your business are displayed in the screen footers
The Audit Icon is not shown
Quote notes are not displayed in red in the header area of the Quotes module
Credit Application output files are not selectable in the Quotes / Finance tab

Permission

The permission for this API is stored as 'SignonToken:Create'. Only roles with a stored link to this permission can run this API. By default, 'admin' and 'web-services' roles already have access.

HTTP Method

Use the HTTP Method 'POST' to consume this API.

API Endpoints

Production API: https://api.catch-e.com/gb/signon

Other Environments: https://api.[environment].catch-e.com/gb/signon

Replace [environment] with 'staging' or 'test' to run this API in those environments.

Signon URL (Login Page):

Production: https://[client].catch-e.net.au/core/signon.php?signon=[token]

Other Environments: https://[client].[environment].catch-e.net.au/core/signon.php?signon=[token]

Replace [client] with your client prefix and [environment] with 'staging' or 'test'.

Headers

Key	Value
Content-Type	application/json or application/hjson

Body Parameters

Parameter	Format	Notes	Mandatory
user_login	string	Username. This is the user requiring a single signon token. The user's account must exist and not be suspended or locked.	Yes
token_timeout	integer	Sets a timeout for the token (in seconds). If not set, the timeout will default from the user's role.	No
screen_width	integer	Set the screen width in pixels by entering a valid screen resolution width. A width and height must both be specified or the default resolution (1024 x 768) will be applied. If a resolution is specified, the signon will launch a new window, even if the specified resolution is the default. If no resolution is specified, the signon will remain within the existing window.	No
screen_height	integer	Set the screen height in pixels by entering a valid screen resolution height.	No
single_signon_role_flag	string	Prevents a non-single signon user from getting a token if set to 'yes'. If set to 'no' or not set at all, any user can get a token. A single signon user is one that has a role where the Single Signon checkbox on the System / Roles / Details screen is turned off.	No
create_gb_user_with_this_role	string	Pass this parameter to give access to a new user on the fly. This flag can have value 'driver' or 'package_employee'. If the user is 'suspended' or 'locked', request will fail. If the user already has access, this flag will be ignored.	No

Body Example

{ "user_login": "admin", "token_timeout": 3600, "single_signon_role_flag": "yes", "screen_width": 1024, "screen_height": 1080 }

Output Example

{ "signon_token": "c63d258e074e29fb5f54954dbbc350513f072f7f", "expires_in": 3600 }

Error Responses

401 - Unauthorized

{ "detail": "Unauthorized" }

You have not authenticated before running this API or the token_timeout of the current session has passed. You need to authenticate again.

422 - Unprocessable Entity

User Not Single Signon Enabled

{ "validation_messages": { "single_signon_role_flag": { "userRoleNotSingleSignon": "Specified users role is not single signon" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

User is not enabled for single signon and the API requires this. To enable, remove "single_signon_role_flag": "yes" from your API statement or set it to "no".

User Not Found or Invalid Status

{ "validation_messages": { "user_login": { "noRecordFound": "Specified user login is not authorised for signon, locked or is invalid" } } }

The user is not known, the user's "Status" is 'locked' or 'suspended', or the user login is 'fbtdec'.

Missing User Login

{ "validation_messages": { "user_login": { "isEmpty": "Value is required and can't be empty" } } }

The user_login field is missing or is empty.

Unsupported Role

{ "validation_messages": { "user_login": { "unsupportedRole": "A signon token cannot be generated for the specified user" } } }

User has a 'webservices' or 'fbtdeclaration' role.

Reserved User

{ "validation_messages": { "user_login": { "inArray": "Specified user is not allowed" } } }

User login is for 'admin' (a reserved user).

Unsupported Screen Resolution

{ "validation_messages": { "screen_width": { "notInArray": "Specified value is not a supported screen width" }, "screen_height": { "notInArray": "Specified value is not a supported screen height" } } }

You have entered an unsupported width and/or height. See Supported Screen Resolutions for valid options.

User Suspended or Locked (Create User)

{ "validation_messages": { "create_gb_user_with_this_role": { "userInvalidStatus": "A signon token cannot be generated for the specified user" } } }

User is suspended or locked.

User Not Found (Create User)

{ "validation_messages": { "create_gb_user_with_this_role": { "userRoleMismatch": "A signon token cannot be generated for the specified user" } } }

User is not known or does not have an fm_driver record.

No Active Linked Contract

{ "validation_messages": { "create_gb_user_with_this_role": { "noLinkedContract": "The specified user does not have an active linked contract" } } }

User does not have an active linked contract. An active contract has a populated "Contract Start" date, is not suspended, and "Reg Number" is not 'ORDER'.

Invalid Email Address

{ "validation_messages": { "create_gb_user_with_this_role": { "userInvalidEmail": "The specified user does not have a valid email address" } } }

User's email address is blank. Enter an email address.