Each Mercado Envíos vehicle can have one or more devices that send information related to locations, telemetry, incidents, events or other relevant info. This vehicle is called TRANSPORT. A transport can also be other type of things such as a car, van, drone, motorcycle, bicycle, person or anything with transportation capabilities.
Transport and Device relation
How it works?
Assuming that third-party devices are already installed on transports.
Step 1. Mercado Envíos sends a "Start Tracking Request" informing to the third-party provider the "License Plate" and "Transport ID" corresponding to the transport to be monitored. 3P System must save this information in order to register further devices for that transport.
Step 2. Third-party provider registers the Device in Mercado Envíos RTT providing the "Transport ID" and his own device identifier in the field "external_entity_id". RTT will return a device id which will be the one that needs to be used to send further information.
Step 3. Third-party provider acknowledges the start-tracking by sending a request with the "device_id" or the fields "external_entity_id" and "external_entity_type". Now the device is able to send info to RTT.
Step 4. Third-party provider device starts sending Locations and/or Telemetry data using the provided rtt "device_id" obtained in the step 2.
Step 5. Mercado Envíos sends a "Stop Tracking Request" informing to the third-party provider the "License Plate" and "Transport ID" corresponding to the transport that will no longer be monitored. 3P System must save this information in order to stop tracking the devices associated with that transport.
Step 6. Third-party provider acknowledges the stop-tracking by sending a request with the "device_id" or the fields "external_entity_id" and "external_entity_type". Now the device is disabled to send info to RTT.
Route Planification
Every route that will be monitored must be sent beforehand to the provider so he can verify if all the required configuration is set prior to receiving a start tracking command (ex. License Plate is registered by the AVL and available in the monitoring system). For that purpose the provider should provide a HTTP REST endpoint to allow Mercado Envios to send planned and cancelled routes information.
Depending on the nature of the error, attempts will be made to correct the data, before re-processing the request. There should be no periodic retry.
403
The client does not have permission
It will not retry.
500
Internal Server Error
It will retry indefinitely until a satisfactory response is obtained.
Examples
Request
json
1{2"planned_routes":[3{4"route_id":2478385,5"rostering_id":18870407,6"estimated_start_date":"2022-01-20T18:35:40.235Z",7"estimated_end_date":"2022-01-20T23:35:40.235Z",8"estimated_start_monitoring_date":"2022-01-20T16:35:40.235Z",9"estimated_end_monitoring_date":"2022-01-20T23:35:40.235Z",10"country_id":"MX",11"carrier":{12"id":213245,13"name":"Tracusa"14},15"vehicles":[16{17"is_tractor":true,18"type":"Truck",19"license_plate":"ADD1236AR"20}21],22"stops":[23{24"order":1,25"facility":{26"id":"AMXMEX",27"address":{28"country_name":"Mexico",29"state_name":"Distrito Federal",30"neighborhood_name":"Lic. Benito Juarez",31"street_name":"C. Carlos Castillo Breton",32"street_number":"12337",33"zip_code":"15620",34"geolocation":{35"latitude":19.42720919876,36"longitude":-99.0752259498637}38}39},40"estimated_time_arrival":"2022-01-20T18:35:40.235Z",41"estimated_time_departure":"2022-01-20T18:35:40.235Z"42}43]44}45],46"command":"check_planned_routes"47}
Response
json
1{2"status":200,3"message":"success"4}
Steps to send real time information
1. Start Tracking
We need to tell you when a device should "Start" sending locations to Shipping RTT. For that purpose the provider should provide a HTTP REST endpoint to allow Mercado Envios to request start and stop tracking of a particular transport.
Idempotence: Notice that start tracking requests are expected to be done more than one time given that the origin of those requests could be originated on different sources, so is expected that both requests are comply with idempotence concept.
Request Format
A message with the following structure will be sent:
bash
1POST https://{PROVIDER_URL}/rtt/commands
Header
Name
Type of data
Description
Authorization
String
Access token for the requested resource (Bearer + TOKEN).
The body attributes are explained below:
Name
Type of data
Description
Type
transport
Node
Information about the transport where the device is used.
Mandatory
transport.id
Number
Transport identifier generated by Mercado Libre. This identifier will be needed when creating a device.
Mandatory
transport.license_plate
String
License plate is the common identifier known to both systems.
Mandatory
transport.country_id
String
ID of the country where the vehicle is registered. The Country Id must be taken from this resource.
Mandatory
command
String
A string value representing a specific event: ["start_tracking"].
To do api calls against Shipping RTT you will need two identifiers to get access, the first is a Client ID that identified you as a client of Shipping RTT and the second is a ML Token that is your access key. Both of them are required.
To register a "DEVICE" we need information like brand, type, model of the device and external_entity associated with it, this is any value that could be useful to do queries in the future. Also transport information associated with the device can be sent.
Request Format
A message with the following structure will be sent:
If the device is already registered and currently active (matching with external entities values), the API returns 208 with all the entity data and the original device is not modified by this call.
It will not retry.
400
Data validation failed.
Depending on the nature of the error, attempts will be made to correct the data, before re-processing the request. There should be no periodic retry.
403
Invalid token or missing caller.scope
It will not retry.
429
Too many request
Try again after five minutes.
500
Internal Server Error
It will retry indefinitely until a satisfactory response is obtained.
Response Format
Fields
Type of Data
Description
id
String
Unique identifier created by RTT to track locations.
owner_id
String
Represents the userId that created the Oauth Token.
status
String
possible values: "active" or "inactive".
external_entity
Node
Id and type of an external entity associated to device.
external_entity.entity_id
String
Id of an external entity associated to device.
external_entity.entity_type
String
Type of an external entity associated to device.
transport
Node
Information about the transport where the device is used.
transport.id
Number
The "transport_id" was sent at the time of creating the monitoring request (Step 1).
device_specs
Node
For stats proposed, we may collect some device data.
device_specs.type
String
Type of the device.
device_specs.brand
String
Brand of the device.
device_specs.model
String
Model of the device.
device_specs.equipment_id
String
Physical identifier of the device.
history
Node
Device history information.
history.date_created
Date (ISO8601)
Device creation date. Valid values: UTC 2001-07-04T12:08.235Z or relative local time 2001-07-04T12:08.235-07.
history.last_updated
Date (ISO8601)
Device last update date. Valid values: UTC 2001-07-04T12:08.235Z or relative local time 2001-07-04T12:08.235-07.
history.last_status_updated
Date (ISO8601)
Device status last update date. Valid values: UTC 2001-07-04T12:08.235Z or relative local time 2001-07-04T12:08.235-07.
Authorization token for the request. The header value should be the word Bearer plus the generated token. Eg. Authorization: Bearer token.
Params
Name
Type of data
Type of param
Description
Type
country_id
String
Query
ID of the country where the device is operational. The Country Id must be taken from this resource.
Mandatory
device_id
String
Path
Device ID obtained from device registration (Step 3).
Mandatory
Status Codes
Status
Message
Description
200
Success
Tracking started successfully
208
Already reported
Tracking has already been started previously
403
Forbidden
The access_token provided is not valid
404
Not found
The device was not found with the ID or the external entity values provided
429
Too many request
Try again after five minutes.
500
Internal Server Error
It will retry indefinitely until a satisfactory response is obtained.
Important:
This call is idempotent, so we can receive multiple start tracking events.
5. Sending Locations
To register a location associated to a device, it is required to send the device_id and associated locations information. Also telemetry information associated with the location can be sent in the same request.
A message with the following structure will be sent:
We need to tell you when a device should "Stop" sending locations to Shipping RTT. When we request an stop, upon confirmation new locations associated with it will be rejected.
Idempotence: Notice that stop tracking requests are expected to be done more than one time given that the origin of those requests could be originated on different sources, so is expected that both requests are comply with idempotence concept.
A message with the following structure will be sent:
bash
1POST https://{PROVIDER_URL}/rtt/commands
Header
Name
Type of data
Description
Authorization
String
Authorization token for the request. The header value should be the word Bearer plus the generated token. Eg. Authorization: Bearer token.
The body attributes are explained below:
Name
Type of data
Description
Type
transport
Node
Information about the transport where the device is used.
Mandatory
transport.id
Number
Transport identifier generated by Mercado Libre. This identifier will be needed when creating a device.
Mandatory
transport.license_plate
String
License plate is the common identifier known to both systems.
Mandatory
transport.country_id
String
ID of the country where the vehicle is registered. The Country Id must be taken from this resource.
Mandatory
command
String
A string value representing a specific event: ["stop_tracking"].
Authorization token for the request. The header value should be the word Bearer plus the generated token. Eg. Authorization: Bearer token.
Params
Name
Type of data
Type of param
Description
Type
country_id
String
Query
ID of the country where the device is operational. The Country Id must be taken from this resource.
Mandatory
device_id
String
Path
Device ID obtained from device registration (Step 3).
Mandatory
Status Codes
Status
Message
Description
200
Success
Tracking stopped successfully
208
Already reported
Tracking has already been stopped previously
403
Forbidden
The access_token provided is not valid
404
Not found
The device was not found with the ID or the external entity values provided
429
Too many request
Try again after five minutes.
500
Internal Server Error
It will retry indefinitely until a satisfactory response is obtained.
Steps to send summarized information
9. Request processed events
There are some telemetry events that must be processed from the provider side. These are complex telemetry events that involve physical sensors of the vehicle and needs to be calculated within the provider system. For that purpose the provider should provide a HTTP REST endpoint to allow Mercado Envios to request processed telemetry events.
