 |
Fleetmatics Integration Manager Developer Handbook
Contents
Fleetmatics Integration Manager Developer Handbook
App Test Client Configuration Steps
Introduction
The Fleetmatics Integration Manager is a comprehensive management solution that enables customers and partners easy access to support resources during and after the onboarding process:
- Searchable documentation for developers to quickly learn how to use our APIs
- Ability to test requests and responses before committing lines of code
- Additional API security with multiple authentication points
- Our integration manager is designed to unite our customers and partners through a single portal to easily find, consume, and get support for our APIs.
Credentials
In order to access the Fleetmatics Integration Manager, you will need to receive an invitation to join the site. The credentials used to access the Fleetmatics Integration Manager will differ from your login to access Fleetmatics REVEAL.
Additionally, when you start to use the Fleetmatics REST APIs you will need to receive integration credentials for your REVEAL account that will be used to authenticate your API requests.
Documentation and RAMLs
For every API there is searchable documentation to be accessed within the Fleetmatics Integration Manager. Additionally, all APIs have a RAML file that can be reviewed. RAML files are best reviewed using an application like Notepad++.
To review, click on the individual APIs shown within the APP details:
App Test Client
Once you’ve successfully registered your app and have been granted access to the APIs that you will need, you can make test calls to verify if your code will process successful requests and see the types of responses that may occur.
1. Click on the App you’ve registered
2. Select the “Test Client” in the left-hand navigation
The App Details view will show the APIs that are currently connected to the APP for use. The APP ID is also shown within the APP Details view, this value is essential for authenticating the APP.
Accessing the Test Client through your created APP will automatically show all the APIs currently connected to App. When you select “API” the dropdown menu will show all the available options to test the requests and responses for those APIs.
The first API that you will want to test is the TOKEN API. The Token API is a compulsory API that generates a token that must be refreshed every 20 minutes. A valid token, along with a valid APP ID, must be presented in every subsequent API call made. For more information on the TOKEN API and Base64, see the Token API documentation.
The TOKEN API set up is a bit different than the other APIs:
- Content-Type and Accept headers should be set to “text/plain.” All other APIs will have the Content-Type and Accept headers set to “application/json.”
- Authorization header must be added where the user encrypts the integration username and password to Base64. The APP ID is NOT required for invoking the Token API.
Authorization Value
The Authorization broken down to be used within the Fleetmatics Integration Manager for all API calls except the Token API require the following format:
Atmosphere atmosphere_app_id= [App ID], Bearer [add toke from Token API successful response]
An example of how this may appear when the entire authorization value is put together:
Atmosphere atmosphere_app_id=fleetmatics-p-us-Ab3D56gH9jKLm4321 Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vc3RzLmZsZWV0bWF0aWNzLmNvbSIsImF1ZCI6Imh0dHA 6Ly9wcml2YXRlLmZsZWV0bWF0aWNzLmNvbS8iLCJuYmYiOjE0NjI0MTE3XTEsImV4cCI6MTQ2MjQxMjkxMSwidW5pcXVlX25hbWU iOiJ3Y2ZUZXN0aW5nQHFhLmNvbSIsImF1dGhtZXRob2QiOiJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDY vaWRlbnRpdHkvYXV0aGVudGljYXRpb25tZXRob2QvXGFzc3dvcmQiLCJhdXRoX3RpbWUiOiIyMDE2LTA1LTA1VDAxOjI4OjMxLjA 1MFoiLCJodHRwOi8vd3d3LnlvdXJjb21wYW55LmNvbS9hcHAvY2FwYWJpbGl0eS91c2VyIjoie1wiVXNlckluZm9cIjp7XCJBY2N vdW50SWRcIjo0NzM2LFwiVXNlcklkXCS6NTU3MDEsXCJTeXN0ZW1Mb2dpblR5cGVcIjoxfX0iLCJlbWFpbCI6IndjZlRlc3Rpbmd AcWEuY29tIn0.bDA8MajaBYSB4YTMbXYdQCUNAqhIbK0DLQxP85Cb5tY
Important Notes:
- The App ID will be a unique identifier assigned to your app when it is registered within the Fleetmatics Integration Manager followed by a comma
- 1 space after the comma with the word “Bearer”
- Then a single space following “Bearer” with the entire TOKEN
Sample above shows a successful call to the Real-time Aggregated Data API to return a vehicle’s location. Note: this call requires an additional Parameter for the Vehicle Number to be returned. Vehicle Number 10003 was first created within the REVEAL account to return the vehicle location information – the Test Client will retrieve real, up-to-date information from the REVEAL account connected with the integration credentials.
Request and Responses
The user can toggle between Request and Response raw breakdowns in order to confirm the information needed to write to the APIs successfully.
The Request header information can be easily reviewed.
Show the Raw or Formatted response information.
APP Teams
For organizations that will have multiple users working within the Fleetmatics Integration Manager, there is a concept of APP Teams. An APP can be created and then the APP Administrator can select the TEAM functionality to invite other Fleetmatics Integration Manager users to access the same APP:
Monitoring
For each APP, the APP Administrator or APP Team can review analytics related to the calls made to the APIs. There are a variety of views for monitoring that may be helpful to understand the calls being made to the APIs and the performance.
In the “Logs” view, each call can be drilled into in order to see the response time and specifics related to each call invoked.