Autorizaciones de Envíos Proximity

Contenidos

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

Ten en cuenta que el Web Service del correo debe proporcionar un endpoint HTTP REST contra el que Mercado Libre pueda autorizar envíos.

Una vez que el envío se registra en Mercado Libre y está listo para ser despachado, se manda una solicitud POST de autorización al Web Service del correo utilizando la siguiente llamada:

POST /shipments/shipment_id/authorization

Nota:

El identificador de envío (shipment_id) es único del lado de Mercado Envíos y deberá utilizarse para validar que no ha sido autorizado con anterioridad, teniendo en cuenta que existe un mecanismo de reintento en caso de que la llamada falle.
Es posible que el identificador de envío esté asociado a más de un tracking number, pero en todo momento solo debe existir un único tracking number “activo” del lado del correo.
Idempotencia: en caso de recibir un request con un envío previamente autorizado, el servicio deberá responder con un “HTTP Code” = 200 y con el mismo body y tracking number que se retornó al momento de la autorización original.
Un envío cancelado podría volver a autorizarse en un futuro por lo que se debe tener en cuenta el siguiente flujo.
Mercado Libre enviará en todos los campos datos con longitudes variables y que pueden cambiar con el tiempo, es responsabilidad del correo truncar los datos de acuerdo a sus requisitos de almacenamiento.

Importante:

El Tracking Number de envío sólo debe cambiar ante “n” autorizaciones si y solo si se solicitó una cancelación previa. En caso de que esto no ocurra, deberá responder con idempotencia.

Dependiendo de si la autorización es satisfactoria o no, se espera que el servicio del correo devuelva un resultado de acuerdo a lo detallado en la sección “Status Codes”. En caso de error, se volverá a intentar la comunicación acorde al esquema de reintento definido en la integración.

Importante:

Para seguridad en autorizaciones se utilizará OAuth 2.0

Formato Request

Dentro del body se enviará un objeto JSON con los campos listados a continuación:

Nombre	Tipo de dato	Descripción	Tipo
id	Long	Identificador único del envío usado por Mercado Libre que se requiere autorizar. Este ID servirá posteriormente para poder notificar las eventos que van ocurriendo en el flujo operativo del envío.	Mandatorio
transport_order_id	String	Identificador único del tramo de transporte	Siempre presente en el request
direction	String	Indica la dirección del envío. Los valores permitidos son: Si la dirección es del vendedor al comprador → "foward" Si la dirección es del comprador al vendedor (devolución) → "return"	Mandatorio
carrier_information	Nodo	Contiene elementos relevantes para el carrier.	Mandatorio
carrier_information.contract	String	Identifica el contrato/servicio definido por el carrier con el cual se va a autorizar el envío. Por ejemplo envío a domicilio desde el XD, envío a sucursal de DS, etc.	Opcional
carrier_information.agency	Nodo	Contiene información relacionada a la agencia de destino. Mandatorio solo cuando es un envío a sucursal.	Opcional
carrier_information.agency.id	String	Id que le da Mercado Libre a la agencia.	Mandatorio
shipment_information	Nodo	Contiene toda la información que se considera relevante para la autorización del envío. Sender, receiver, item, etc. Las medidas son en centímetros y los pesos en gramos.	Mandatorio
shipment_information.package	Nodo	Información relacionada al paquete.	Mandatorio
shipment_information.package.items	Nodo	Información relacionada a los items.	Mandatorio
shipment_information.package.items.item_id	String	Número identificatorio del item en Mercado Libre.	Mandatorio
shipment_information.package.items.description	String	Descripción del item en Mercado Libre.	Mandatorio
shipment_information.package.items.quantity	Numeric	Cantidad de unidades por item.	Mandatorio
shipment_information.package.amount	Numeric	Monto abonado por el contenido del paquete.	Mandatorio
shipment_information.package.description	String	Contenido del paquete.	Opcional
shipment_information.package.dimensions	Nodo	Dimensiones y peso del paquete.	Mandatorio
shipment_information.package.dimensions.height	Numeric	Alto del paquete en centímetros.	Mandatorio
shipment_information.package.dimensions.length	Numeric	Largo del paquete en centímetros.	Mandatorio
shipment_information.package.dimensions.width	Numeric	Ancho del paquete en centímetros.	Mandatorio
shipment_information.package.dimensions.weight	Numeric	Peso del paquete en gramos.	Mandatorio
shipment_information.receiver	Nodo	Información relacionada al receiver.	Mandatorio
shipment_information.receiver.full_name	String	Nombre completo o Razón Social del receiver.	Mandatorio
shipment_information.receiver.first_name	String	Nombre del receiver.	Mandatorio
shipment_information.receiver.last_name	String	Apellido del receiver.	Mandatorio
shipment_information.receiver.phone	Nodo	Información relacionada al teléfono del receiver.	Opcional
shipment_information.receiver.phone.number	String	Número telefónico. Sólo números.	Opcional
shipment_information.receiver.address	Nodo	Información relacionada a direccion del destino.	Mandatorio
shipment_information.receiver.address.street_name	String	Nombre de la calle de destino.	Mandatorio
shipment_information.receiver.address.street_number	String	Número de la calle de destino.	Opcional
shipment_information.receiver.address.intersection	String	Calle secundaria.	Mandatorio en Ecuador
shipment_information.receiver.address.address_line	String	Campo compuesto por los campos street_name y street_number del destino.	Mandatorio
shipment_information.receiver.address.comment	String	Comentarios sobre la dirección del destino.	Opcional
shipment_information.receiver.address.zip_code	String	Código postal del destino.	Mandatorio en Argentina, Brasil, México y Perú. Opcional en Colombia, Uruguay, Chile y Ecuador
shipment_information.receiver.address.city	Node	Ciudad de destino.	Mandatorio
shipment_information.receiver.address.city.id	String	Identificador único que le da Mercado Libre a la ciudad.	Mandatorio en Colombia, Uruguay, Chile y Ecuador. Opcional en Argentina, Brasil, México y Perú
shipment_information.receiver.address.city.name	String	Nombre de la ciudad	Mandatorio
shipment_information.receiver.address.state	Node	Estado, departamento o provincia de destino.	Mandatorio
shipment_information.receiver.address.state.id	String	Identificador único que le da Mercado Libre al estado en Formato ISO 3166.	Mandatorio
shipment_information.receiver.address.state.name	String	Nombre del estado.	Mandatorio
shipment_information.receiver.address.country	Node	País de destino.	Mandatorio
shipment_information.receiver.address.country.id	String	Identificador único que le da Mercado Libre al país en Formato ISO 3166.	Mandatorio
shipment_information.receiver.address.country.name	String	Nombre del país.	Mandatorio
shipment_information.receiver.address.neighborhood	Node	Barrio de destino.	Opcional
shipment_information.receiver.address.neighborhood.id	String	Identificador único del vecindario.	Opcional
shipment_information.receiver.address.neighborhood.name	String	Nombre del vecindario.	Opcional
shipment_information.receiver.address.municipality	Node	Municipalidad de destino.	Opcional
shipment_information.receiver.address.municipality.id	String	Identificador único que le da Mercado Libre al municipio.	Opcional
shipment_information.receiver.address.municipality.name	String	Nombre del municipio.	Opcional
shipment_information.receiver.address.geolocation	Node	Tiene la localización de la dirección.	Opcional
shipment_information.receiver.address.geolocation.geolocation_type	String	Puede ser alguno de los valores siguientes: 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.	Mandatorio
shipment_information.receiver.address.geolocation.latitude	Numeric	Latitud de la localización en formato de número con 8 decimales.	Mandatorio
shipment_information.receiver.address.geolocation.longitude	Numeric	Longitud de la localización en formato de número con 8 decimales.	Mandatorio
shipment_information.receiver.identification	Nodo	Información relacionada a la identificación del receiver.	Siempre presente en el request (Chile y Brasil)
shipment_information.receiver.identification.type	String	Tipo de identificación del receiver.	Siempre presente en el request (Chile y Brasil)
shipment_information.receiver.identification.number	Numeric	Número de identificación del receiver.	Siempre presente en el request (Chile y Brasil)
shipment_information.sender	Nodo	Información relacionada al sender.	Mandatorio
shipment_information.sender.full_name	String	Nombre completo o Razón Social del sender.	Mandatorio
shipment_information.sender.first_name	String	Nombre del sender.	Mandatorio
shipment_information.sender.last_name	String	Apellido del sender.	Mandatorio
shipment_information.sender.phone	Nodo	Información relacionada al teléfono del sender.	Opcional
shipment_information.sender.phone.number	String	Número telefónico. Sólo números.	Mandatorio
shipment_information.sender.address	Nodo	Información relacionada a la dirección de origen.	Mandatorio
shipment_information.sender.address.street_name	String	Nombre de calle del origen.	Mandatorio
shipment_information.sender.address.street_number	String	Número de calle del origen.	Optional
shipment_information.sender.address.intersection	String	Calle secundaria.	Mandatorio en Ecuador
shipment_information.sender.address.address_line	String	Campo compuesto por los campos street_name y street_number del origen.	Mandatorio
shipment_information.sender.address.comment	String	Comentarios sobre la dirección del origen.	Opcional
shipment_information.sender.address.zip_code	String	Código postal del origen.	Mandatorio en Argentina, Brasil, México y Perú. Opcional en Colombia, Uruguay, Chile y Ecuador
shipment_information.sender.address.city	Node	Ciudad de origen.	Mandatorio
shipment_information.sender.address.city.id	String	Identificador único que le da Mercado Libre a la ciudad.	Mandatorio en Colombia, Uruguay, Chile y Ecuador. Opcional en Argentina, Brasil, México y Perú
shipment_information.sender.address.city.name	String	Nombre de la ciudad.	Mandatorio
shipment_information.sender.address.state	Node	Estado, departamento o provincia de origen.	Mandatorio
shipment_information.sender.address.state.id	String	Identificador único que le da Mercado Libre al estado en Formato ISO 3166.	Mandatorio
shipment_information.sender.address.state.name	String	Nombre del estado.	Mandatorio
shipment_information.sender.address.country	Node	País de origen.	Mandatorio
shipment_information.sender.address.country.id	String	Identificador único que le da Mercado Libre al país en Formato ISO 3166.	Mandatorio
shipment_information.sender.address.country.name	String	Nombre del país.	Mandatorio
shipment_information.sender.address.neighborhood	Node	Barrio de origen	Opcional
shipment_information.sender.address.neighborhood.id	String	Identificador único del vecindario.	Opcional
shipment_information.sender.address.neighborhood.name	String	Nombre del vecindario	Opcional
shipment_information.sender.address.municipality	Node	Municipalidad de origen.	Opcional
shipment_information.sender.address.municipality.id	String	Identificador único del municipio.	Opcional
shipment_information.sender.address.municipality.name	String	Nombre del municipio.	Opcional
shipment_information.sender.address.geolocation	Node	Tiene la localización de la dirección	Opcional
shipment_information.sender.address.geolocation.geolocation_type	String	Puede ser alguno de los valores siguientes: 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.	Mandatorio
shipment_information.sender.address.geolocation.latitude	Numeric	Latitud de la localización en formato de número con 8 decimales.	Mandatorio
shipment_information.sender.address.geolocation.longitude	Numeric	Longitud de la localización en formato de número con 8 decimales.	Mandatorio
shipment_information.sender.address.facility_id	String	Identifica una única instalación para la dirección	Opcional
shipment_information.sender.identification	Nodo	Información relacionada a la identificación del sender.	Siempre presente en el request (Chile y Brasil)
shipment_information.sender.identification.type	String	Tipo de identificación del sender.	Siempre presente en el request (Chile y Brasil)
shipment_information.sender.identification.number	Numeric	Número de identificación del sender.	Siempre presente en el request (Chile y Brasil)
shipment_information.order_pickup_information	Nodo	Contiene información relacionada con envios de Proximity Marketplace.	Opcional
shipment_information.order_pickup_information.id	Numeric	Identificador de la orden.	Mandatorio
shipment_information.order_pickup_information.cooking_time	Nodo	Contiene la información necesaria que indica el tiempo que lleva la elaboración de la orden.	Mandatorio
shipment_information.order_pickup_information.cooking_time.value	Numeric	Valor numérico del tiempo de elaboración de la orden.	Mandatorio
shipment_information.order_pickup_information.cooking_time.measure	String	Unidad de medida del tiempo de elaboración de la orden.	Mandatorio
shipment_information.order_pickup_information.store_name	String	Nombre de la tienda.	Mandatorio
shipment_information.order_pickup_information.tip	Nodo	Contiene la información referente al beneficio de propina enviada del buyer al rider. El nodo esta compuesto por los campos: AMOUNT: Representa el valor numerico de la propina. (Cabe la posibilidad de que se presente con decimales) CURRENCY: Representa el valor de la moneda de la propina. El nodo tip solo estara presente si existe un valor de propina asignado. Si el valor de la propina es asignado, pero la api encargada no responde con la información anteriormente mencionada, el flujo de la autorización continuará, sin presentar el nodo tip.	Opcional
shipment_information.order_pickup_information.tip.amount	Numeric	Valor de la propina.	Mandatorio
shipment_information.order_pickup_information.tip.currency	String	Tipo de moneda de cambio que representa el valor de la propina.	Mandatorio
test	Boolean	Indica que la request enviada es para pruebas.	Opcional
keyword	String	Es la Palabra Clave en formato HASH (SHA 256). El valor de este parámetro puede ser vacio. En caso de encontrarse un valor, el Carrier deberá solicitar la Palabra Clave al receptor del paquete.	Opcional

Nota:

Cabe destacar que el orden de importancia de los datos de cuenta del correo es el siguiente:

Contract: es el número que utiliza el correo para identificar el contrato (convenio) de precios establecidos con Mercado Libre. Lo usan para saber cómo deben cobrar esos envíos. Por ejemplo: El precio de un envío a domicilio por “drop_shipping” tiene un precio distinto al de “fulfillment” por alguna cuestión definida en un contrato. Es el campo más utilizado por los correos.
Account: es el identificador que utiliza el correo para diferenciar las distintas áreas de Mercado Libre. Por ejemplo CBT y ME tienen diferente account id del lado del correo.
User: es un usuario de sistema asignado al cliente de Mercado Libre.
Password: es la contraseña asociada a ese usuario.

Formato Response

Dentro del body, el sistema devolverá todos los datos resultantes de la autorización, listados a continuación:

Nombre	Tipo de dato	Descripción	Tipo
id	Long	Identificador único del envío usado por Mercado Libre que se requiere autorizar.	Mandatorio
status	String	Estado del pedido de autorización: AUTHORIZED FAILED ERROR	Mandatorio
status_message	String	Cualquier detalle relevante del estado.	Mandatorio en caso de fallo (status = FAILED o status = ERROR).
tracking_number	String	Número de tracking.	Mandatorio en caso de que la autorización sea procesada con éxito (status = AUTHORIZED).
authorization_information	Nodo	Contiene información relativa a la fecha y hora de la actualización junto con cualquier información relevante para el armado de la etiqueta de envío.
authorization_information.date	Date (ISO 8601)	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 en caso de éxito (status = AUTHORIZED)
authorization_information.custom_data	Nodo	Contiene todos los datos necesarios para el armado de la etiqueta. Pueden ser tantos conjuntos de claves-valores como sean necesarios para el armado.	Opcional
authorization_information.custom_data.key	String\|Long	“Key” hace referencia al nombre de la clave del conjunto clave-valor particular. El campo “valor” puede ser texto o numérico.	Mandatorio

Performance

Importante:

Se espera que el tiempo de respuesta promedio del correo sea menor a un segundo .

Status Codes

Status	Código HTTP	Descripción	Acción
AUTHORIZED	200	Cuando la autorización fue procesada satisfactoriamente	El envío ya fue autorizado y no se volverá a reintentar.
FAILED	400	Cuando la autorización no pudo ser procesada por un error en el request. Se espera que se retorne “status”: “FAILED” junto con el “status_message” describiendo el motivo del error.	Dependiendo de la naturaleza del error, se intentarán corregir los datos, antes de volver a procesar la solicitud. Podrían existir reintentos periódicos.
ERROR	500	Cualquier error del lado del servidor. En este caso, status y status_message son opcionales.	Se volverá a intentar indefinidamente hasta obtener una respuesta satisfactoria de acuerdo al esquema de reintento definido.

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/shipments/{shiment_id}/authorization'
--header 'Authorization: Bearer + TOKEN'
--body 'Se mantiene lo descrito en cada integración'

Nota:

Una vez implementada la solución de OAuth, se deberá deprecar el uso de usuario y contraseña en las integraciones en favor del uso del token. Los campos a deprecar son los siguientes:

Campo	Tipo	Descripción
carrier_information.user	String	Identifica un usuario de sistema del correo asignado al cliente de Mercado Libre.
carrier_information.password	String	Identifica la contraseña asociada al usuario del sistema.

Ejemplos

Request:

POST https://hostName/shipments/26379079680/authorization

{
                        "id": "10100590151",
                        "transport_order_id": "5c81e696e6d9183ea9190a58c13d4de71816b743",
                        "direction": "forward",
                        "carrier_information": {},
                        "shipment_information": {
                            "package": {
                                "items": [
                                    {
                                        "item_id": "MLA1676542156",
                                        "description": "Combo Whopper 40% Off",
                                        "quantity": 1
                                    }
                                ],
                                "amount": 9300,
                                "description": "Combo Whopper 40% Off",
                                "dimensions": {
                                    "height": 1,
                                    "length": 1,
                                    "width": 1,
                                    "weight": 1
                                }
                            },
                            "receiver": {
                                "full_name": "Erick Fulanito",
                                "first_name": "Erick Fulanito",
                                "last_name": "Erick Fulanito",
                                "phone": {
                                    "number": "11234567890"
                                },
                                "address": {
                                    "street_name": "Colon",
                                    "street_number": "1234",
                                    "address_line": "Colon 1234",
                                    "comment": "",
                                    "zip_code": "1425",
                                    "city": {
                                        "id": "TUxBQlJFQzkyMTVa",
                                        "name": "Recoleta"
                                    },
                                    "state": {
                                        "id": "AR-C",
                                        "name": "Capital Federal"
                                    },
                                    "country": {
                                        "id": "AR",
                                        "name": "Argentina"
                                    },
                                    "neighborhood": {
                                        "id": null,
                                        "name": null
                                    },
                                    "municipality": {
                                        "id": null,
                                        "name": null
                                    },
                                    "geolocation": {
                                        "geolocation_type": "RANGE_INTERPOLATED",
                                        "latitude": -34.183376,
                                        "longitude": -58.103107
                                    }
                                }
                            },
                            "sender": {
                                "full_name": "Store SA",
                                "first_name": "Store",
                                "last_name": "SA",
                                "phone": {
                                    "number": "00000000"
                                },
                                "address": {
                                    "street_name": "San Martin",
                                    "street_number": "1234",
                                    "address_line": "San Martin 1234",
                                    "comment": "Referencia: Local 1",
                                    "zip_code": "1123",
                                    "city": {
                                        "id": "TUxBQlJFQzkyMTVa",
                                        "name": "Recoleta"
                                    },
                                    "state": {
                                        "id": "AR-C",
                                        "name": "Capital Federal"
                                    },
                                    "country": {
                                        "id": "AR",
                                        "name": "Argentina"
                                    },
                                    "neighborhood": {
                                        "id": null,
                                        "name": null
                                    },
                                    "municipality": {
                                        "id": null,
                                        "name": null
                                    },
                                    "geolocation": {
                                        "geolocation_type": "ROOFTOP",
                                        "latitude": -34.195614,
                                        "longitude": -58.19598
                                    }
                                }
                            },
                            "order_pickup_information": {
                                "id": "1091",
                                "cooking_time": {
                                    "value": 11,
                                    "measure": "minutes"
                                },
                                "store_name": "Nombre de fantasia"
                            }
                        },
                        "test": "true",
                        "keyword": "d6b76560dsfbaf2faf18af0afcf7ed3bf063ae40ac2445f9910f1a95fa35f160"
                    }

Response:

Authorized (200 OK)

{
    "id": "10101033319242",
    "status":"AUTHORIZED",
    "status_message":"OK",
    "tracking_number": "ASDfgh123asd",
    "authorization_information": {
        "date": "2001-07-04T12:08:56.235-07:00",
        "custom_data":{
            "ruta_1":"RUTA"
        }
    }
}

Failed (400 FAILED)

{
    "error_code": "invalid_user_information.buyer",
    "status_message":"Missing receiver information",
    "status": "FAILED"
}

Error (500 ERROR)

{
    "status_message":"Internal server error",
    "status": "ERROR"
}