Salesforce and AutoGuru Interfaces

Technical documentation covering Salesforce and AutoGuru CRM integrations for Catch-e fleet management system, including setup procedures, API endpoints, global controls, and export business rules.

Salesforce Integration Overview

Catch-e enables integration with Salesforce.com/au using web services. For new Salesforce integrations, Catch-e recommends and prefers Apex method over legacy SOAP.

Integration processes and functionality can be applied to other CRM packages as required. Prospective CRM providers can be provided with Salesforce Guide covering available integration services.

CRM Interface Functionality Examples

• Transfer quote and product information

• Transfer changes or updates to quotes

• Call for and use Catch-e documents in CRM system

Salesforce Key Fields

Following fields in Catch-e created for Salesforce interface use:

WSDL File Setup

Create WSDL File Type

New file type record and directory created by Catch-e staff.

Directory path: /clients/{client}/core/fleet/lib/interfaces/wsdls

Add WSDL File

To add or update WSDL file:

1. Navigate to Setup / Import/Export Files menu

2. Choose file type: 'Salesforce WSDLs'

3. Choose WSDL file applicable to environment:

   • salesforce-test.wsdl

   • salesforce-staging.wsdl

   • salesforce-live.wsdl

4. Upload file

Salesforce Apex Integration

For new Salesforce integrations, Apex method preferred over legacy SOAP/web services.

Global Controls Configuration

Configure following Global Controls for Apex Salesforce APIs:

Apex API Permissions

Verify required API permissions configured for Salesforce Apex APIs.

Check API Permissions

SELECT * FROM gb_api_permissions WHERE permission = 'InterfaceSalesforceApex:SyncQuote'; SELECT r.name, r.access_type, rap.* FROM gb_role_api_permissions AS rap INNER JOIN gb_roles AS r ON r.role_id = rap.role_id WHERE permission = 'InterfaceSalesforceApex:SyncQuote'; 

Apex API Error Codes

Apex REST Endpoints

apexrest/syncquote

Synchronize quote data to Salesforce.

Trigger Events

Called when following functions run in Catch-e:

• Create

• Save

• Apply

• Accept

Timestamp Tracking

Quotes / Contract "Salesforce By" field shows call timestamp and response.

Suppression Rules

Call suppressed if:

• API createQuoteWebService used to create quote

• copyQuote API used to copy quote

When suppressed, Quotes / Contract "Salesforce By" field blank.

apexrest/synccontract

Synchronize contract data to Salesforce.

Trigger Events

Called when following functions run in Catch-e:

• Accept Quote

• Copy Contract

• Edit Contract

• Create, Edit or Delete Contract Event (where Event triggers update to Contract data, e.g. Driver Change)

Non-Trigger Events

NOT called when following functions run:

• Contracts / Finance Apply button clicked

• Contracts / Finance Get Application Status button clicked

• Contracts / Finance Get Documents button clicked

• Scheduler / Job executeScript updates

Suppression Rules

Call suppressed if contract edited by running API "Insert or update a record with auditing".

Salesforce Legacy Web Services (SOAP)

For existing Salesforce integrations using legacy web services method.

Note: For new integrations, use Apex method. Legacy SOAP method not recommended for new implementations.

Global Controls Configuration

Configure following Global Controls for legacy web services:

Queue Processing (Standard Method)

When Quote or Contract saved, transaction record inserted into queue with queued timestamp.

Queue processed one transaction at a time from oldest to newest:

1. Log in to Salesforce to get session token (if current session token not cached)

   • Session Tokens timeout after 8 hours

   • Current tokens re-used avoiding login

2. Sleep 1 second

3. Perform Update Opportunity in Salesforce

4. Perform Update History for Opportunity in Salesforce

5. Repeat for next transaction in queue

Queue Processing using SQS FIFO

When Quote or Contract saved, transaction record inserted into SQS FIFO queue.

MessageGroupId Formats

Queued Salesforce operations contain MessageGroupId:

• qt:salesforce?opportunityid=OPPORTUNITYID

• qt:salesforce?contractid=CONTRACTID

• qt:salesforce?quoteid=QUOTEID

Messages with same MessageGroupId processed in FIFO order. Messages in same group always processed one by one, in strict order.

MessageDeduplicationId Formats

Queued Salesforce operations contain MessageDeduplicationId:

• qt:salesforce:updateOpportunityFromContract/{serialized-parameters}

• qt:salesforce:updateQuotationHistoryVehicleOptions/{serialized-parameters}

• qt:salesforce:updateOpportunityFromQuote/{serialized-parameters}

If message with particular deduplication ID sent successfully, messages with same ID accepted but not delivered during 1-minute deduplication interval. Prevents frequent updates for same opportunity/contract impacting queue worker.

Sync Quote with Salesforce Legacy Interface API

Legacy API for Salesforce integration with Catch-e.

Note: For new integrations, Catch-e recommends and prefers Apex method.

Permissions

Nominated 'web-services' role needs permission to run this API.

If not actively using API, leave permission off for better security.

Check permission: Roles / Apis > InterfaceSalesforceLegacy:SyncQuote

HTTP Method

Use HTTP Method: POST

Input Fields

Header

Header should contain 'accept' Key with Value:

• application/problem+json or

• application/vnd.catch-e-api.v1+json

Body

URL Examples

https://api.catch-e.com/gb/interface/salesforce-legacy/sync-quote 

Response Details

204 No Content

Request successful. No response required.

401 Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" } 

Not authenticated or token_timeout passed. Re-authenticate.

403 Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" } 

No permissions for request. Go to System > Roles, enter 'web_services', navigate to Roles / APIs tab, verify permission checked.

422 Unprocessable Entity

{ "validation_messages": { "message": "message for this task" }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" } 

Validation failure explanation included.

423 Locked

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Locked", "status": 423, "detail": "Locked" } 

One of records in JSON Body already being edited. Entire batch fails.

500 Unexpected Error

{ "status": 500, "title": "Unexpected error", "describedBy": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "JSON encoding error occurred: Malformed UTF-8 characters, possibly incorrectly encoded" } 

Query has encrypted fields not decrypted using AES_DECRYPT in JSON response. Decrypt fields in query before adding to table.

patchQuote API Note

Warning: patchQuote request will NOT trigger data pushed to Salesforce. If data from patchQuote needs updating in Salesforce, use API 'salesforceLegacySyncQuote' instead.

AutoGuru Vehicle Export

For complete information about AutoGuru integration jobs, process, and setup steps, refer to AutoGuru documentation page.

Export Business Rules

Records exported via scheduled AutoGuru jobs.

Vehicle Selection Criteria

Contract vehicle data exported if following criteria met:

• Contract Types / Details "Autoguru Export" checked

• Contracts / Contract "Reg Number" is not 'ORDER'

• Contracts / Contract "Contract Start" is today or earlier

• Contracts / Contract "Suspend Date" is blank or after today

• Contracts / Vehicle "Autoguru Export" checked

• Contracts / Vehicle "Build Date" in suitable report format

• Contracts / Vehicle "VIN": if populated, 17 characters long and not duplicated on another selected contract. Can be blank.

• Contracts / Vehicle "Manufacturer Name" does not contain commas

• Contracts / Vehicle "Model Name" does not contain commas

Odometer, Expenses, Budgets Selection

Odometer, Expenses and Budgets data selected based on:

• Odometer: Valid Odometer record with status = 'posted' or 'history-only'

• Expenses: Expense record with status = 'posted' or 'history-only' AND linked = 'yes'

• Budgets: Budget record with status = 'posted' AND on or before end of current month AND linked = 'yes'

AutoGuru Field Mappings

AutoGuru Daily Booking File Structure

Booking File Data Structure and Mapping

OnChargeIncTax Recharge Logic

Notes

• Salesforce integration supports both Apex (recommended for new integrations) and legacy SOAP methods

• WSDL files environment-specific; verify correct file for deployment environment

• Global Controls must be encrypted for sensitive credentials

• API permissions require explicit role assignment; disable if not actively used

• Queue processing supports both standard and AWS SQS FIFO methods

• patchQuote API requires explicit legacy sync call if Salesforce update needed

• AutoGuru export excludes suspended, incomplete, and on-order contracts

• Tyre balance calculation specific to contract group type (Lease, Novated, Fleet)

• Build date year extraction flexible; accepts multiple date formats

• VIN validation critical for booking history continuity; duplicates excluded

• Product codes limited to S (Service), M (Maintenance), T (Tyre) for AutoGuru export

• OnChargeIncTax drives recharge flag and status for maintenance records

• MessageDeduplicationId prevents queue worker overload from frequent same-opportunity updates