Generate JWT token for authentication #
To be able to create, update or get feedback on a trip in the spot subcontracting module, a JWT token needs to be requested.
For this, you need the client ID and client secret from the integrators page.
More information: Integrator management
The scope should include “PGAPI”.
Use this token in the header of your API request when creating a spot subcontracted trip.
More information on how to create a token: Retrieve the access token.
Create a trip – POST #
A subcontracted trip must include at least 2 missions with an activity: 1 loading and 1 unloading mission
Each mission must include a place (name and address)
More information on how to create a trip: Create a trip.
Update a trip – PUT #
The spot subcontracted trip can only be updated if the trip is not started. The complete trip can be changed by using the corresponding Trip ID.
The body of the update call is the same as for the create trip call.
More information on how to update a trip: Update a trip.
Trip feedback – GET #
A driver adds updates to the trip by pressing the “Arrived” or “Finished” buttons at each mission
(all details on how the driver can add feedback can be found in Driver feedback).
No other updates are sent along the way, we do not track the driver.
If this is a requirement, 2 options are available:
- Use the Trip ID that is specified in the response when creating the trip and poll repetitive
- Create a subscription so the updates are pushed from Spot subcontracting towards the integrator
Trip feedback – Poll #
Use the Trip ID that is specified in the response when creating the trip to do a GET trip datahub API call. The call returns all the trip data including the signature section and feedback section of each mission.
More information on how to retrieve a trip: Retrieve a trip.
Retrieve file #
When a file has been uploaded into the driver form (Driver feedback), it is possible to download it using datahub API calls:
- First, request feedback on the trip to retrieve the fieId(s) of each mission. If no files have been uploaded, an empty array is returned.
- Secondly, use the ‘Get file’ datahub API call to create a temporary link and return it in the reply.
The created URL expires after 5 minutes. If you try to access it after that, an ‘Access Denied’ error message is returned.
More information on how to retrieve a file: Retrieve file(s).
Get signature #
When a signature has been added into the driver form (Driver feedback), it is possible to download it using datahub API calls.
- First, request feedback on the trip to retrieve the signature ID(s) for each mission. If no signatures have been added an empty array is returned.
- Next, use the ‘Get signature’ datahub API call which will return the content of the signature image as a base64 encoded string.
More details on how to get a signature: Retrieve signature(s).
Delete a trip #
It is not possible to manually delete the trip using the datahub API.
A trip is automatically deleted:
- 60 days after the trip has been marked as finished
- when the compliance module requests to delete all data of an organization
When the last update of the trip (by using the form) is longer than 7 days ago, it is automatically marked as finished. The URL will no longer show the trip actions, but the “Trip is finished” page.
