Autorizaciones de Venta de Capacidad

Contenidos

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

Venta de Capacidad (Sale of Capacity) nos permite contar con una herramienta que permita generar una customer order con el objetivo de hacer un uso más eficiente de la capacidad de nuestra red logística, en particular para los tramos aéreos.

Para realizar la autorización de este tipo de envíos se debe proporcionar a Mercado Libre un endpoint HTTP REST contra el que se solicitará su autorización.

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

POST /shipments/#{shipment_id}

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 de tracking number: en el request de autorización se enviará el tracking number correspondiente al envío. En la autorización, el correo deberá responder con el mismo tracking number.
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.
El request puede tener más campos de los especificados, pero no serán obligatorios.

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
tracking_number	String	Tracking number de la capacidad producto de la venta	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.account	String	Identifica la cuenta dada por el carrier a Mercado Libre.	Opcional
carrier_information.user	String	Identifica un usuario de sistema del correo asignado al cliente de Mercado Libre.	Opcional
carrier_information.password	String	Identifica la contraseña asociada al usuario del sistema.	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 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/{shimentId}'
--header 'Authorization: Bearer + TOKEN'
--body 'Se mantiene lo descrito en cada integración'

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
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. Este valor debe ser el mismo que fue enviado en el request.	Mandatorio
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.	Mandatorio
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.

Ejemplos

Request:

POST https://hostName/shipments/41731043250

{
  "id":41731043250,
  "tracking_number": "360000226808570",
  "carrier_information": {
    "account": "1234",
    "contract": "54321",
    "user": "MercadoLibre",
    "password": "****"
  }
}

Response:

Authorized (200 OK)

{
  "status":"AUTHORIZED",
  "status_message":"OK",
  "tracking_number": "360000226808570",
  "authorization_information": {
    "date": "2001-07-04T12:08:56.235-07:00",
    "custom_data":{
    }
  }
}