Real Time Tracking - Delivery

Content

Register to Meli
Sending Locations

Introduction

The following information provides the API details required to get real time tracking information of a shipment being delivered by the carrier. All the web services should be HTTP REST.

Steps to send information

1. 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.

Generate Client ID and ML Token

2. Sending Locations

To register a location associated to a traceable unit, it is required to send the following information: driver_id, traceable_id and associated locations.

A message with the following structure will be sent:

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

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.

Params

Name	Type of data	Type of param	Description	Type
country_id	String	Path	ID of the country where the device is operational. The Country Id must be taken from this resource.	Mandatory
provider	String	Path	Provider name.	Mandatory

The body attributes are explained below:

Name	Type of data	Description	Type
post_timestamp	Integer	UTC time local from the device, at the moment of sending the data, in seconds since epoch (January 1, 1970).	Mandatory
locations	Array	Array of locations.	Mandatory
locations[i].timestamp	Integer	UTC time of the moment in which the location data was obtained, in seconds since epoch (January 1, 1970).	Mandatory
locations[i].latitude	Number	GPS latitude in degrees.	Mandatory
locations[i].longitude	Number	GPS longitude in degrees.	Mandatory
locations[i].altitude	Number	GPS altitude (mts above sea level).	Optional
locations[i].accuracy	Number	Estimated horizontal accuracy of this location, radial, in meters.	Optional
locations[i].bearing	Number	Horizontal direction of travel of this device, in degrees.	Optional
locations[i].bearing_accuracy	Number	Estimated bearing accuracy of this location, in degrees.	Optional
locations[i].metadata	Array	Array of objects “key-value”. Any extra info associated with the location like events. Maximum of 20 items.	Optional
locations[i].metadata[i].name	String	Key of metadata defined by the client or by Mercado Envíos.	Mandatory
locations[i].metadata[i].value	String	Value for corresponding key defined by the client.	Mandatory
device	Node	Data of the driver that carries the traceable.	Mandatory
device.external_id	String	Id of an external entity associated to driver.	Mandatory
device.external_type	String	Type of an external entity associated to driver. We must create a new type for you.	Mandatory
traceables	Array	Array of traceables.	Mandatory
traceables[i].id	String	Tracked traceable_id.	Mandatory
traceables[i].type	String	Tracked traceable type.	Mandatory

{
    "post_timestamp": "integer",
    "locations": [
        {
            "timestamp": "integer",
            "latitude": "number",
            "longitude": "number",
            "altitude": "number",
            "accuracy": "number",
            "bearing": "number",
            "bearing_accuracy": "number",
            "metadata": [
                {
                    "name": "string",
                    "value": "string"
                }
            ],
            "device": {
                "external_id": "string",
                "external_type": "string"
            },
            "traceables": [
                {
                    "id": "string",
                    "type": "string"
                }
            ]
        }
    ]
}

Status Codes

Status	Description	Action
202	valid request	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	The provider has not permission.	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.

Examples

Request

{
    "post_timestamp": 161980863,
    "locations": [
        {
            "timestamp": 161980863,
            "latitude": -34.5743988,
            "longitude": -58.4845495
        }
    ],
    "device": {
        "external_id": "54564asdda",
        "external_type": "DRIVER_ID"
    },
    "traceables": [
        {
            "id": "457543234",
            "type": "shipment"
        }
    ]
}

Response

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