Real Time Tracking - Monitoring

Content

Introduction

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, dron, 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 disable 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.

Request Format

A message with the following structure will be sent:

POST https://{PROVIDER_URL}/rtt/commands

Header

The body attributes are explained below:

{
    "planned_routes": [
        {
            "route_id": "number",
            "rostering_id": "number",
            "estimated_start_date": "date",
            "estimated_end_date": "date",
            "estimated_start_monitoring_date": "date",
            "estimated_end_monitoring_date": "date",
            "country_id": "string",
            "carrier": {
                "id": "number",
                "name": "string"
            },
            "vehicles": [
                {
                    "is_tractor": "boolean",
                    "type": "string",
                    "license_plate": "string"
                }
            ],
            "stops": [
                {
                    "order": "number",
                    "facility": {
                        "id": "string",
                        "address": {
                            "country_name": "string",
                            "state_name": "string",
                            "neighborhood_name": "string",
                            "street_name": "string",
                            "street_number": "string",
                            "zip_code": "string",
                            "geolocation": {
                                "latitude": "number",
                                "longitude": "number"
                            }
                        }
                    },
                    "estimated_time_arrival": "date",
                    "estimated_time_departure": "date"
                }
            ]
        }
    ],
    "command": "string"
}

Status Codes

Examples

Request

{
    "planned_routes": [
        {
            "route_id": 2478385,
            "rostering_id": 18870407,
            "estimated_start_date": "2022-01-20T18:35:40.235Z",
            "estimated_end_date": "2022-01-20T23:35:40.235Z",
            "estimated_start_monitoring_date": "2022-01-20T16:35:40.235Z",
            "estimated_end_monitoring_date": "2022-01-20T23:35:40.235Z",
            "country_id": "MX",
            "carrier": {
                "id": 213245,
                "name": "Tracusa"
            },
            "vehicles": [
                {
                    "is_tractor": true,
                    "type": "Truck",
                    "license_plate": "ADD1236AR"
                }
            ],
            "stops": [
                {
                    "order": 1,
                    "facility": {
                        "id": "AMXMEX",
                        "address": {
                            "country_name": "Mexico",
                            "state_name": "Distrito Federal",
                            "neighborhood_name": "Lic. Benito Juarez",
                            "street_name": "C. Carlos Castillo Breton",
                            "street_number": "12337",
                            "zip_code": "15620",
                            "geolocation": {
                                "latitude": 19.42720919876,
                                "longitude": -99.07522594986
                            }
                        }
                    },
                    "estimated_time_arrival": "2022-01-20T18:35:40.235Z",
                    "estimated_time_departure": "2022-01-20T18:35:40.235Z"
                }
            ]
        }
    ],
    "command": "check_planned_routes"
}

Response

{
    "status": 200,
    "message": "success"
}

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.

Request Format

A message with the following structure will be sent:

POST https://{PROVIDER_URL}/rtt/commands

Header

The body attributes are explained below:

{
    "transport": {
        "id": "number",
        "license_plate": "string",
        "country_id": "string"
    },
    "command": "string"
}

Status Codes

Examples

Request

{
    "transport": {
        "id": 5266555,
        "license_plate": "1234ABC",
        "country_id": "AR"
    },
    "command": "start_tracking"
}

Response

{
    "status": 200,
    "message": "success"
}

2. Register to Meli

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 you access key. Both of them are required.

3. Register Device

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:

POST https://api.mercadolibre.com/shipping/rtt/devices?country_id={countryId}

Header

Params

The body attributes are explained below:

{
    "external_entity": {
        "entity_id": "string",
        "entity_type": "string"
    },
    "transport": {
        "id": "number"
    },
    "device_specs": {
        "device_type": "string",
        "brand": "string",
        "model": "string",
        "equipment_id": "string"
    }
}

Status Codes

Response Format

{
    "id": "string",
    "owner_id": "string",
    "status": "string",
    "external_entity": {
        "entity_id": "string",
        "entity_type": "string"
    },
    "transport": {
        "id": "number"
    },
    "device_specs": {
        "type": "string",
        "brand": "string",
        "model": "string",
        "equipment_id": "string"
    },
    "history": {
        "date_created": "date",
        "last_updated": "date",
        "last_status_updated": "date"
    }
}

Examples

Request

{
    "external_entity": {
        "entity_id": "demo-1",
        "entity_type": "DRIVER_ID"
    },
    "transport": {
        "id": 123456789
    },
    "device_specs": {
        "device_type": "mobile",
        "brand": "samsung",
        "model": "A1",
        "equipment_id": "example-1"
    }
}

Response

{
    "id": "1afb3349-9d42-424c-91c0-6756884b0e00",
    "client_id": 123,
    "owner_id": "",
    "status": "ACTIVE",
    "device_specs": {
        "type": "mobile",
        "brand": "samsung",
        "model": "A1",
        "equipment_id": "example-1"
    },
    "external_entity": {
        "entity_id": "demo-1",
        "entity_type": "DRIVER_ID"
    },
    "transport": {
        "id": 123456789
    },
    "history": {
        "date_created": "2022-01-20T23:35:40Z",
        "last_updated": "2022-01-20T23:35:40Z",
        "last_status_update": "2022-01-20T23:35:40Z"
    }
}

4. Device Start Tracking

To start tracking the device it is necessary to send the following request.

POST https://api.mercadolibre.com/shipping/rtt/devices/{device_id}/start_tracking?country_id={countryId}

Header

Params

Status Codes

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:

POST https://api.mercadolibre.com/shipping/rtt/georeceiver/{provider}/locations?country_id={countryId}

Header

Params

The body attributes are explained below:

{
    "device_id": "string",
    "post_timestamp": "integer",
    "locations": [
        {
            "timestamp": "integer",
            "country_id": "string",
            "latitude": "number",
            "longitude": "number",
            "altitude": "number",
            "accuracy": "number",
            "bearing": "number",
            "bearing_accuracy": "number",
            "metadata": [
                {
                    "name": "string",
                    "value": "string"
                }
            ],
            "telemetry": {
                "timestamp": "number",
                "ignition": "string",
                "odometer": "number",
                "speed": "number",
                "speed_accuracy": "number",
                "others": [
                    {
                        "name": "string",
                        "value": "string"
                    }
                ],
                "....": "...."
            }
        }
    ]
}

Status Codes

Examples

Request

{
    "device_id": "0c709aac-89d3-4acc-aac0-c3d8a7cabc5e",
    "post_timestamp": 161980863,
    "locations": [
        {
            "accuracy": 14.389,
            "altitude": 76.08372940019947,
            "bearing": 15.5,
            "bearing_accuracy": 2.3,
            "latitude": -34.5743988,
            "longitude": -58.4845495,
            "timestamp": 161980861,
            "country_id": "AR",
            "telemetry": {
                "....": "...."
            },
            "metadata": [
                {
                    "name": "delivered",
                    "value": "ship1"
                }
            ]
        }
    ]
}

Response

{
    "status": 202,
    "message": "Accepted"
}

6. Send Events

To register events associated to a device, it is required to send the device_id and occurred events information.

POST https://api.mercadolibre.com/shipping/rtt/georeceiver/{provider}/telemetry/events?country_id={countryId}

Header

Params

The body attributes are explained below:

{
    "device_id": "string",
    "post_timestamp": "number",
    "events": [
        {
            "name": "string",
            "start_date": "date",
            "end_date": "date",
            "distance": "number",
            "latitude": "number",
            "longitude": "number",
            "external_id": "number",
            "last_updated_date": "date",
            "status": "number",
            "metadata": [
                {
                    "name": "string",
                    "value": "string"
                }
            ]
        }
    ]
}

Status Codes

Examples

Request

{
    "device_id": "0c709aac-89d3-4acc-aac0-c3d8a7cabc5e",
    "post_timestamp": 161980861,
    "events": [
        {
            "name": "speeding_route",
            "start_date": "2022-01-20T18:35:40.235Z",
            "end_date": "2022-01-20T18:50:40.235Z",
            "distance": 150,
            "latitude": -34.5743988,
            "longitude": -58.4845495,
            "external_id": 122345,
            "last_updated_date": "2022-01-20T18:35:40.235Z",
            "status": 1,
            "metadata": [
                {
                    "name": "speeding",
                    "value": "130"
                }
            ]
        }
    ]
}

Response

{
    "status": 200,
    "message": "success"
}

7. Stop Tracking

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.

A message with the following structure will be sent:

POST https://{PROVIDER_URL}/rtt/commands

Header

The body attributes are explained below:

{
    "transport": {
        "id": "number",
        "license_plate": "string",
        "country_id": "string"
    },
    "command": "string"
}

Status Codes

Examples

Request

{
    "transport": {
        "id": 5266555,
        "license_plate": "1234ABC",
        "country_id": "AR"
    },
    "command": "stop_tracking"
}

Response

{
    "status": 200,
    "message": "success"
}

8. Device Stop Tracking

To stop tracking the device it is necessary to send the following request.

POST https://api.mercadolibre.com/shipping/rtt/devices/{device_id}/stop_tracking?country_id={countryId}

Header

Params

Status Codes

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.

Request Format

A message with the following structure will be sent:

POST https://{PROVIDER_URL}/rtt/commands

The body attributes are explained below:

{
    "id": "string",
    "transport": {
        "id": "number",
        "license_plate": "string",
        "country_id": "string"
    },
    "travel": {
        "init_date": "date",
        "end_date": "date"
    },
    "command": "string"
}

Status Codes

Examples

Request

{
    "id": "first_mile12358",
    "transport": {
        "id": 5666447,
        "license_plate": "1234ABC",
        "country_id": "BR"
    },
    "travel": {
        "init_date": "2022-01-20T18:35:40.235Z",
        "end_date": "2022-01-20T23:35:40.235Z"
    },
    "command": "process_telemetry_events"
}

Response

{
    "status": 200,
    "message": "success"
}

10. Send Processed events

Once received the request for sending processed events, the provider must prepare these data and send it back with the following proposed structure:

POST https://api.mercadolibre.com/shipping/rtt/georeceiver/{provider}/telemetry/events/deferred?country_id={countryId}

Header

Params

The body attributes are explained below:

{
    "id": "string",
    "route_distance": "number",
    "transport_id": "number",
    "post_timestamp": "number",
    "events": [
        {
            "name": "string",
            "start_date": "date",
            "end_date": "date",
            "distance": "number",
            "latitude": "number",
            "longitude": "number",
            "metadata": [
                {
                    "name": "string",
                    "value": "string"
                }
            ]
        }
    ]
}

Status Codes

Examples

Request

{
    "id": "first_mile12358",
    "route_distance": 278,
    "transport_id": 5666447,
    "post_timestamp": 161980861,
    "events": [
        {
            "name": "speeding_route",
            "start_date": "2022-01-20T18:35:40.235Z",
            "end_date": "2022-01-20T18:50:40.235Z",
            "distance": 150,
            "latitude": -34.5743988,
            "longitude": -58.4845495,
            "metadata": [
                {
                    "name": "speeding",
                    "value": "130"
                }
            ]
        }
    ]
}

Response

{
    "status": 200,
    "message": "success"
}