The idea is to provide a base template solution to make it easier to integrate with the Cartrack API. Bring your integration requirement, add your system connectors and call the Cartrack API with the provided functions.
Getting Started
We have built a template solution that will allow you to interact with the Cartrack API easily. All you need to provide is your Cartrack authentication details (token and user). You can then use the pre-created function in the Linx solution to interact with the Cartrack API, meaning that you simply need to build the interactions with the system you are integrating with.
Working with the Cartrack web service
Cartrack Fleet API has good documentation on their web services and how to use them. As of the time of writing, the API is a REST service where you send JSON requests.
The web service uses a Basic Authentication method that must be placed in the header. You can obtain your API key and details about your user name here: Cartrack for Developers.
Once you have those details, you can start making calls to the API. This means that a big part of the integration is already done.
Calling Cartrack Fleet API with Linx
To start, we will call the API with the CallRESTEndpoint function. Most of the GET operations are rather straightforward in that you call the endpoint with your authentication details in the header. There are some parameters that can be passed in depending on what endpoint you are calling; these parameters can be seen in the API documentation.
In our sample solution, we created functions for the following endpoints:
Get Drivers
Get a list of all drivers. This uses the drivers endpoint without passing in any parameters. The output is defined to be a Type that mimics the response body, making it easier to access, manage and manipulate values in the response. The response is then returned to the output of the function, meaning that you will receive a list of all drivers when calling this function.
Get Jobs
Similar to the above Get Drivers function, the Get Jobs function will return a list of jobs. It will do this by calling the Jobs endpoint, but this time round, it takes two parameters: a start date and an end date. The request will only return jobs between those dates using the create_ts_from and create_ts_to query parameters. When the function is called, it will return a list of jobs between that date range.
Get Specific Job
Just like the above-mentioned Get Jobs function, this function will return a specific job based on a passed-in Job ID.
Save New Job
This function creates a Job by calling the Jobs endpoint with a POST method. The request body was created as a type, making it easier to assign the values that should be sent to the API. When calling the function, you must pass in a CarTrackDelivery type. The function will return whether the call was successful or not, alongside the error message if the call does fail.
More functions can be added as the functionality is required by replicating what has been done in the above functions. Import the request and response bodies by using the samples provided in the API documentation.
Using settings for fast-paced development
You may need to reuse a specific value across various functions during your development. In such a case, creating a setting will be helpful. These settings can be reused in many places. We made settings for all the authentication credentials, with some of them (specifically the Token) being a secret, meaning the value will not be visible. What makes settings especially useful is that you can set them in the Linx Server to match a specific value for a particular environment. If you have a test server, you can use a different test version of your Sage credentials for that environment.
Final thoughts
Integrations come with unique challenges, depending on what system you need to integrate with, what you need to do with the data and what business rules you need to apply.
Working with the Cartrack Fleet API can be simplified by choosing a solution that allows you to streamline the web service call and manipulate the data. You can use the Cartrack Fleet API with Linx to get the job done efficiently, and after interacting with the API you can integrate to anywhere.