Notificaciones Pull

Contenidos

Introducción Formato Request Formato Request OAuth Formato Response Status Codes Ejemplos

El servicio del correo debe proporcionar un endpoint HTTP REST para que podamos obtener los eventos de los envíos.

Importante:

Recomendamos que la cantidad de envíos consultados sea como mínimo 50.
Para seguridad en pull tracking se utilizará OAuth 2.0.

Formato Request

Se enviará un mensaje con la siguiente estructura:

POST /tracking

Nombre	Tipo de dato	Descripción	Tipo
id	Long	Identificador único del envío usado por Mercado Libre.	Mandatorio
tracking_number	String	Identificador el envío.	Mandatorio

[
  {
    "id": long,
    "tracking_number": string
  },
  {
    "id": long,
    "tracking_number": string
  }
]

Formato Request OAuth

Para el mecanismo de autenticación a través de la generación de un token con OAuth, se debe agregar el siguiente encabezado a la petición:

--request POST 'https://hostname/tracking'
--header 'Authorization: Bearer + TOKEN'
--body 'Se mantiene lo descrito en cada integración'

Formato Response

Respuesta Satisfactoria

Los atributos del body se explican en la siguiente tabla:

Nombre	Tipo de dato	Descripción	Tipo
id	Long	Identificador único del envío usado por Mercado Libre.	Mandatorio
tracking_number	String	Identificador el envío.	Mandatorio
events	Array	Array de eventos históricos asociados al envío. En caso de no hayan eventos se debe devolver una lista vacía.	Mandatorio
code	String	Código del evento.	Mandatorio
carrier_code	String	Código del evento interno del carrier.	Mandatorio
payload	Node	Contiene información relevante a un evento en particular
payload.date	Date (ISO8601)	Fecha de ocurrencia del evento. Valores válidos: en UTC 2001-07-04T12:08:56.235Z o en hora local relativa 2001-07-04T12:08:56.235-07:00.	Mandatorio
payload.reason	String	Indica el motivo específico asociado al código informado, proporcionando información adicional predefinida que explica la ocurrencia del evento. Posibles valores de 'reason' para el código 0114: establishment_not_found waiting_time_exceeded establishments_closed load_capacity_exceeded address_unsafe already_picked_up delivery_cancelled delivery_not_found payment_requested other_pickup_problems Posibles valores de 'reason' para el código CBT-0272: oversize overweight overprice prohibited_item other	Mandatorio para el código 0114 (Proximity) o CBT-0272 (Consolidación)
payload.comment	String	Comentario adicional al código de estado.	Opcional
payload.flight.awb	String	Número de Air Waybill	Opcional
payload.declaration_number	String	Número del pedimento/documento aduanero	Mandatório para código CBT-0283
payload.agency_id	String	Código de identificación de la agencia o sucursal.	Mandatorio para códigos 0201 y 0215
payload.agency.phone_number	String	Número de teléfono de la agencia o sucursal donde se puede retirar el paquete. El formato debe ser un número de hasta quince dígitos que comience con "+". [+][código de país][número del suscriptor incluido el código de área]. Ejemplo: +541142345678	Disponible solo para la novedad CBT-0215 de CBT
payload.cost	BigDecimal	Costo de envío del ítem.	Mandatorio para código 0260 y 0265.
payload.location	Node	Contiene información relevante a la localización donde ocurrió el evento.	Opcional
payload.location.zip_code	String	Zipcode donde ocurrió el evento.	Opcional
payload.location.state_name	String	Nombre del estado/provincia donde ocurrió el evento.	Opcional
payload.location.city_name	String	Nombre de la ciudad donde ocurrió el evento.	Opcional
payload.location.neighborhood_name	String	Nombre del barrio donde ocurrió el evento.	Opcional
payload.location.country_id	String	Identificador de país donde ocurrió el evento. Debe enviarse el campo "id" del siguiente recurso.	Mandatorio para códigos con prefijo "CBT"
payload.location.facility	String	Identificador del Centro Logístico donde ocurrió el evento.	Mandatorio para códigos 0271 y 0273
payload.location.geolocation	Node	Geolocalización del lugar donde ocurrió el evento.	Mandatorio para códigos 0227, 0271 y 0273
payload.location.geolocation.geolocation_type	String	Precisión de la geolocalización brindanda. Puede contener alguno de los siguientes valores: APPROXIMATE: geolocalización aproximada. GEOMETRIC_CENTER: se ubica el centro de una región que se usa de referencia. RANGE_INTERPOLATED: restringe la precisión al punto medio de 2 puntos de referencia cercanos. ROOFTOP: Indica que la ubicación es exacta. UNKNOWN: Indica que la ubicación no fue validada.
payload.location.geolocation.latitude	BigDecimal	Latitud de la geolocalización.
payload.location.geolocation.longitude	BigDecimal	Longitud de la geolocalización.
payload.dimensions	Node
payload.dimensions.height	BigDecimal	En centímetros.	Opcional
payload.dimensions.width	BigDecimal	En centímetros.	Opcional
payload.dimensions.length	BigDecimal	En centímetros.	Opcional
payload.dimensions.weight	BigDecimal	Peso bruto en gramos.	Mandatorio para código 0260
payload.redispatch	Node		Opcional
payload.redispatch.tracking_number	String	Identificador del envío del carrier de redespacho.	Opcional
payload.redispatch.carrier_id	BigDecimal	Identificador del carrier de redespacho definido por Mercado Libre.	Opcional
payload.redispatch.tracking_url	String	URL de seguimiento web del carrier de redespacho.	Opcional
payload.estimated_delivery_date	Date (ISO8601)	Fecha estimada de entrega del envío. Valores válidos: en UTC 2001-07-04T12:08:56.235Z o en hora local relativa 2001-07-04T12:08:56.235-07:00.	Mandatorio para código 0265.
payload.estimated_pickup_date	String	Fecha estimada de recoleccion del envío. Valores válidos: en UTC 2001-07-04T12:08:56.235Z o en hora local relativa 2001-07-04T12:08:56.235-07:00.	Mandatorio para código 0265 y 0133.
payload.proof_of_delivery	Node		Opcional
payload.proof_of_delivery.receiver_document	Node		Opcional
payload.proof_of_delivery.receiver_document.type	String	Tipo de documento de identidad de la persona que recibe el paquete. Puede contener algunos de los siguientes valores: CI: Cédula de Identificación. PASSPORT: Pasaporte. CPF: Registro de Persona Física. RG: Registro General. CURP: Clave Única de Registro de Población. INE_IFE: Instituto Nacional Electoral. LICENCIA: Licencia de conducir. RFC: Registro Federal de Contribuyentes. RUT: Rol Único Tributario. CC: Cédula de ciudadanía. DNI: Documento Nacional de Identidad.	Mandatorio
payload.proof_of_delivery.receiver_document.number	String	Número de documento de identidad de la persona que recibe el paquete.	Mandatorio
payload.proof_of_delivery.receiver_last_name	String	Apellido de la persona que recibe el paquete.	Opcional
payload.proof_of_delivery.receiver_name	String	Nombre de la persona que recibe el paquete.	Opcional
payload.proof_of_delivery.receiver_relationship	String	Quien recibió el paquete. Puede contener algunos de los siguientes valores: BUYER FAMILY NEIGHBOUR DOORMAN RECEPTION FRIEND HOLDER OTHER	Opcional
payload.proof_of_delivery.image	String	Imagen con la firma del receptor que contenga el nombre completo y número de documento. La imagen debe enviarse codificada en Base64.	Opcional
payload.driver	Node	Información del repartidor del provider	Opcional
payload.driver.id	String	Id del repartidor en el registro del carrier	Mandatorio para código 0133
payload.driver.name	String	Nombre del repartidor	Mandatorio para código 0133
payload.driver.email	String	Correo electrónico del repartidor	Opcional
payload.driver.phone	String	Número de teléfono del repartidor. El formato debe ser un número de hasta quince dígitos que comience con "+". [+][código de país][número del suscriptor incluido el código de área]. Ejemplo: +541142345678	Opcional
payload.driver.license_plate	String	Identificación del vehículo de entrega	Opcional
payload.vehicle	String	Información del repartidor del provider	Opcional
payload.vehicle.reference_type	String	Tipo de información relativa al vehículo, que puede ser: ID: id del repartidor en el registro del carrier LICENSE_PLATE: identificación del vehículo de entrega	Opcional
payload.vehicle.reference	String	Información sobre el campo payload.vehicle.reference_type	Opcional
payload.consolidated_packages	Node	Nodo que contiene información sobre la consolidación.	Mandatorio para el código CBT-0272
payload.consolidated_packages.consolidation_id	String	Identificación enviada en el flujo de consolidación.	Mandatorio para el código CBT-0272
payload.consolidated_packages.tracking_number	String	Número de seguimiento asignado a la consolidación.	Mandatorio para el código CBT-0272
payload.consolidated_packages.shipments	Lista	Lista de IDs de envíos incluidos en la consolidación.	Mandatorio para el código CBT-0272

[
    {
        "id": "long",
        "tracking_number": "string",
        "events": [
            {
                "code": "string",
                "carrier_code": "string",
                "payload": {
                    "date": "date",
                    "reason": "string",
                    "comment": "string",
                    "flight": {
                        "awb": "string"
                    },
                    "declaration_number": "string",
                    "agency_id": "string",
                    "agency": {
                        "phone_number": "string"
                    },
                    "cost": "bigdecimal",
                    "location": {
                        "zip_code": "string",
                        "state_name": "string",
                        "city_name": "string",
                        "neighborhood_name": "string",
                        "country_id": "string",
                        "facility": "string",
                        "geolocation": {
                            "geolocation_type": "string",
                            "latitude": "bigdecimal",
                            "longitude": "bigdecimal"
                        }
                    },
                    "dimensions": {
                        "height": "bigdecimal",
                        "width": "bigdecimal",
                        "length": "bigdecimal",
                        "weight": "bigdecimal"
                    },
                    "redispatch": {
                        "tracking_number": "string",
                        "carrier_id": "bigdecimal",
                        "tracking_url": "string"
                    },
                    "estimated_delivery_date": "date",
                    "proof_of_delivery": {
                        "receiver_document": {
                            "type": "string",
                            "number": "string"
                        },
                        "receiver_last_name": "string",
                        "receiver_name": "string",
                        "receiver_relationship": "string",
                        "image": "string"
                    },
                    "driver": {
                        "id": "string",
                        "name": "string",
                        "email": "string",
                        "phone": "string",
                        "license_plate": "string"
                    },
                    "vehicle": {
                        "reference_type": "string",
                        "reference": "string"
                    },
                    "consolidated_packages": {
                        "consolidation_id": "string",
                        "tracking_number": "string",
                        "shipments": [
                            "integer",
                            "integer",
                            "integer"
                        ]
                    }
                }
            }
        ]
    }
]

Nota:

Los códigos de estado esperados son los provistos por Mercado Envíos y se encuentran especificados en el apartado "Flujo de Novedades de Tracking".
En caso de no haber eventos para un envío, o no tener registrado el tracking number de su lado, el nodo “events” estará vacío.
Enviar todos los datos de "location" disponibles. Sin embargo el dato más valioso para Mercado Libre, en cuanto a localización del evento, es el nodo "geolocation".

Respuesta con Error

Nombre	Tipo de dato	Descripción
status	Integer	Código de error. Coincide con el http status code.
message	String	Cualquier detalle relevante al estado. Mandatorio en caso de fallo.
error	String	http status error message en snake_case.
cause	Array	Listado de errores.

Status Codes

Status	Descripción	Acción
200	Cuando la solicitud fue procesada satisfactoriamente	El envío ya fue cancelado y no se volverá a reintentar.
400	Cuando la solicitud no pudo ser procesada por un error en el request.	Dependiendo de la naturaleza del error, se intentarán corregir los datos, antes de volver a procesar la solicitud. No debería existir reintento periódico.
500	Cualquier error del lado del servidor.	Se volverá a intentar indefinidamente hasta obtener una respuesta satisfactoria.

Ejemplos

Request:

POST https://hostName/tracking

[
  {
    "id": 26379079680,
    "tracking_number": 1234NLUG123
  }
]

Response:

Ok (200 OK)

[
{
  "id": 26379079680,
  "tracking_number": "1234NLUG123",
  "events":[{
             "code": "0260",
             "carrier_code": "a31",
             "payload": {
                         "date": "2021-07-30T00:00:00-04:00",
                         "comment": "Actualización de peso",
                         "agency_id": "1234",
                         "cost" : 67.77,
                         "location": {
                            "geolocation": {
                                "geolocation_type": "ROOFTOP",
                                "latitude": -32.96234,
                                "longitude": -60.64053
                            }
                         },
                         "dimensions":{
                                  "height": 33.3,
                                  "width" : 20.0,
                                  "length" : 10.0,
                                  "weight" : 600
                         }
                        }
            }
          ]
}
]

Error (500 ERROR)

{
  "message": "DB is not available",
  "error": "server_error",
  "status": 500,
  "cause": [
  ]
}