Autorizaciones Offline
Contenidos
Como se explica en la Autorización de envíos, el resultado esperado del POST de autorización contra los servicios del correo es un 200, con la siguiente información en el payload:
- Tracking Number (T.N.): número de guía devuelto por el carrier, para el seguimiento de paquetes
- Custom Data (C.D.): información necesaria, por el carrier, para la generación de la etiqueta (en general información de canalización)
Cuando los servicios del carrier no se encuentran disponibles, no es posible obtener el T.N. ni la C.D., y por lo tanto no se podrá liberar la etiqueta para su impresión y posterior despacho del envío.
La integración con la AUTORIZACIÓN OFFLINE facilita, a Mercado Libre, la generación de un T.N. y una C.D. permitiendo la liberación de la etiqueta, evitando que un envío se trabe hasta tanto se recuperen los servicios del carrier.
Una vez generada la autorización offline se realizarán sucesivos intentos de notificación al carrier de la autorización liberada con el T.N. y la C.D. generada offline, durante al menos 10 días. De esta manera se asegurará que la información del envío llegue al carrier al momento de su recuperación.
Estrategias de integración
La implementación de la autorización offline, exige la definición y adecuación de los siguientes mecanismos de generación:
1. Generación de un T.N.
Para la generación de un T.N. que acompañe la etiqueta se podrán implementar alguna de las siguientes estrategias:
- T.N. MeLi
- T.N. Generado
- T.N. Prefetch
T.N. MeLi
En esta estrategia Mercado Libre asignará al envío un T.N. propio que luego comunicará al carrier.
El T.N. tendrá el siguiente formato: ME###################LM
Ej:ME20300000405919697110LM
T.N. Generado
En esta estrategia el Carrier podrá reservar un patrón de T.N. a Mercado Libre para que pueda generar uno para cada autorización offline liberada.
Algunos ejemplos de patrones, pueden ser:
- Rango numérico desde/hasta:
Ej: desde 3361000000 al 3362000000- Prefijo (numérico o alfabético): MEL o 399 + ########
Ej: 3990000001, MEL00000001T.N. Prefetch
En esta estrategia el Carrier compartirá a Mercado Libre una bolsa de T.N. A medida que se cosuman los T.N. de esta bolsa, y al alcanzar la cantidad mínima configurada para el carrier, se realizará una petición de un nueva cantidad de T.N.
Esta bolsa de T.N., podrá ser un rango, o bien un listado de T.N.
Para la implementación de esta estrategia el carrier deberá desarrollar una API que permita la obtención de un nuevo listado de T.N. para la renovación del stock.
La solicitud de un nuevo rango de T.N. Prefetch se realizará mediante un POST a la URL del carrier de la siguiente manera
Request:
POST https://carrier-host-name/trackingnumbersFormato Request
Dentro del body se enviará un objeto JSON con los campos listados a continuación:
| Nombre | Tipo de dato | Descripción | Tipo |
|---|---|---|---|
| service_id | Long | Identificador del servicio utilizado internamente por Mercado Libre para diferenciar un servicio contractual específico del carrier. Se puede consultar la API de Servicios (https://api.mercadolibre.com/sites/xxx/shipping_services/) para mayor información. | Opcional |
| carrier_information | Nodo | Contiene elementos relevantes para el carrier. | Opcional |
| 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. | Mandatorio |
| carrier_information.password | String | Identifica la contraseña asociada al usuario del sistema. | Mandatorio |
Formato Response
Dentro del body de la respuesta, el sistema deberá incluir la siguiente información:
| Nombre | Tipo de dato | Descripción | Tipo |
|---|---|---|---|
| type | String | Identificador del tipo de respuesta:
| Mandatorio en caso de type = RANGED |
| range_from | Long | Rango inferior de T.N. | Mandatorio en caso de type = RANGED |
| range_to | Long | Rango superior de T.N. | Mandatorio en caso de type = RANGED |
| values | String[] | Listado de T.N. asignados. | Mandatorio en caso de type = LIST. |
Ejemplos
Request:
POST https://carrier-host-name/trackingnumbers{
"service_id": 10000,
"carrier_information": {
"account": "0012006140",
"contract": "400010295",
"user": "MERCADOLIBRE_WS",
"password": "#######"
}
}Response:
SUCCESS (200 OK)
Para rango de T.N.
{
"type":"ranged"
"range_from": 10000,
"range_to": 19000
}Para rango de T.N.
{
"type":"list"
"values": ["TN110lk0","TN110A00","TN110A03"...]
}FAILED (4xx)
{
"message": "No TN availables for the account",
"error": "unavailable_tracking_numbers",
}ERROR (5xx)
{
"message": "Internal Server Error",
"error": "unexpected_error",
}2. Generación de una C.D.
Para la generación de una C.D. que acompañe la etiqueta se podrán implementar alguna de las siguientes estrategias:
- Sin C.D.
- C.D. Generada
- C.D. vía API
Sin C.D.
En esta estrategia Mercado Libre generará una autorización offline sin información de custom Data; por lo tanto la misma tampoco será enviada al notificar al carrier
C.D. Generada
En esta estrategia Mercado Libre generará la información de C.D., cuando deba liberar una autorización offline. Para esto, previamente, se coordinará con el Carrier los campos mínimos indispensables que deberán incluirse, como así los algoritmos necesarios para generar la C.D.
C.D. Vía API
En esta estrategia Mercado Libre obtendrá la información de la C.D. de la autorización consumiendo una API del Carrier.
Para la implementación de esta estrategia el carrier deberá desarrollar una nueva API que permita la obtención la información, y que deberá asegurar su disponibilidad aún cuando los servicios de autorización se encontraran fuera de servicio.
La solicitud de la C.D. vía API se realizará mediante un POST a la URL del carrier de la siguiente manera
Request:
POST https://carrier-host-name/shipping/authorization/custom_dataFormato Request
Dentro del body se enviará un objeto JSON con los mismos campos definidos para la autorización incluyendo, adicionalmente, el T.N. generado por Mercado Libre, para la autorización offline
Formato Response
Dentro del body de la respuesta, el sistema deberá incluir la siguiente información:
| Nombre | Tipo de dato | Descripción | Tipo |
|---|---|---|---|
| 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. | |
| 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 |
Ejemplos
Request:
POST https://carrier-host-name/shipping/authorization/custom_data{
"id":10101033319242,
"service_id":1010001,
"status_history":[],
"carrier":"carrier1010",
"logistic":"fulfillment",
"market_place":"MELI",
"direction":"forward",
"site_id":"MLA",
"carrier_information":{
"account":"",
"contract":"",
"user":"",
"password":"****"
},
"shipment_information":{
"id":10101033319242,
"sender":{
"nickname":"GOLANDS",
"first_name":"PY",
"last_name":"S.A.",
"email":"py.9crb8z@mail.mercadolibre.com",
"phone":{
"area_code":"1010",
"number":"522175123929",
"extension":""
},
"address":{
"address_line":"Calle 12",
"street_name":"Calle 12",
"street_number":"S/N",
"comment":","
"zip_code":"1870",
"city":{
"id":"TUxBQ0xBTWF0YW56",
"name":"La Matanza"
},
"state":{
"id":"AR-B",
"name":"Buenos Aires"
},
"country":{
"id":"AR",
"name":"Argentina"
},
"neighborhood":{
"id":null,
"name":"Villa Celina"
},
"municipality":{
"id":null,
"name":"Villa Celina"
},
"geolocation":{
"geolocation_type":"ROOFTOP",
"latitude":-14.10100206,
"longitude":-52.10104811
},
"facility_id":"101010"
},
"full_name":"GOLANDS",
"id":10101098879
},
"receiver":{
"nickname":"CENTER MEL",
"first_name":"MEL",
"last_name":"PY",
"email":"mel.h283j6@mail.mercadolibre.com",
"phone":{
"area_code":"",
"number":"10108508106",
"extension":""
},
"address":{
"address_line":"Calle 23",
"street_name":"Calle 23",
"street_number":"S/N",
"comment":"",
"zip_code":"1625",
"city":{
"id":"TUxBQ0VTQzQ3YTc0",
"name":"Escobar"
},
"state":{
"id":"AR-B",
"name":"Buenos Aires"
},
"country":{
"id":"AR",
"name":"Argentina"
},
"neighborhood":{
"id":null,
"name":null
},
"municipality":{
"id":null,
"name":null
},
"geolocation":{
"geolocation_type":"RANGE_INTERPOLATED",
"latitude":-32.101012822,
"longitude":-52.10102059
},
"delivery_preference":"business"
},
"identification":{
"type":"DNI",
"number":"1234123",
},
"full_name":"Mel py",
"id":10010389392
},
"package":{
"items":[
{
"item_id":"MLA101010618394",
"description":"Lampara 100w",
"tariff_code":"LFH80000234",
"made_in":"United States",
"quantity":1
}
],
"description":"MLA101010618394",
"dimensions":{
"height":15,
"width":25,
"length":70,
"weight":1900
},
"amount":2420,
"currency_id":"USD"
}
},
"order_id":101010669519,
"test":false,
"tracking_number": "360000226808570"
}Mecanismos de notificación
Como mencionamos anteriormente una vez liberada la autorización offline, desde Mercado Libre seguiremos intentando notificar la misma al carrier. Para ellos se realizará un POST con la autorización generada, respetando el contrato definido en Autorizaciones de Envíosincluyendo adicionalmente el T.N. y la C.D.
Ejemplos
Request:
POST https://carrier-host-name/shipping/authorization{
"id":10101033319242,
"service_id":1010001,
"status_history":[],
"carrier":"carrier1010",
"logistic":"fulfillment",
"market_place":"MELI",
"direction":"forward",
"site_id":"MLA",
"carrier_information":{
"account":"",
"contract":"",
"user":"",
"password":"****"
},
"shipment_information":{
"id":10101033319242,
"sender":{
"nickname":"GOLANDS",
"first_name":"PY",
"last_name":"S.A.",
"email":"py.9crb8z@mail.mercadolibre.com",
"phone":{
"area_code":"1010",
"number":"522175123929",
"extension":""
},
"address":{
"address_line":"Calle 12",
"street_name":"Calle 12",
"street_number":"S/N",
"comment":","
"zip_code":"1870",
"city":{
"id":"TUxBQ0xBTWF0YW56",
"name":"La Matanza"
},
"state":{
"id":"AR-B",
"name":"Buenos Aires"
},
"country":{
"id":"AR",
"name":"Argentina"
},
"neighborhood":{
"id":null,
"name":"Villa Celina"
},
"municipality":{
"id":null,
"name":"Villa Celina"
},
"geolocation":{
"geolocation_type":"ROOFTOP",
"latitude":-14.10100206,
"longitude":-52.10104811
},
"facility_id":"101010"
},
"full_name":"GOLANDS",
"id":10101098879
},
"receiver":{
"nickname":"CENTER MEL",
"first_name":"MEL",
"last_name":"PY",
"email":"mel.h283j6@mail.mercadolibre.com",
"phone":{
"area_code":"",
"number":"10108508106",
"extension":""
},
"address":{
"address_line":"Calle 23",
"street_name":"Calle 23",
"street_number":"S/N",
"comment":"",
"zip_code":"1625",
"city":{
"id":"TUxBQ0VTQzQ3YTc0",
"name":"Escobar"
},
"state":{
"id":"AR-B",
"name":"Buenos Aires"
},
"country":{
"id":"AR",
"name":"Argentina"
},
"neighborhood":{
"id":null,
"name":null
},
"municipality":{
"id":null,
"name":null
},
"geolocation":{
"geolocation_type":"RANGE_INTERPOLATED",
"latitude":-32.101012822,
"longitude":-52.10102059
},
"delivery_preference":"business"
},
"identification":{
"type":"DNI",
"number":"1234123",
},
"full_name":"Mel py",
"id":10010389392
},
"package":{
"items":[
{
"item_id":"MLA101010618394",
"description":"Lampara 100w",
"tariff_code":"LFH80000234",
"made_in":"United States",
"quantity":1
}
],
"description":"MLA101010618394",
"dimensions":{
"height":15,
"width":25,
"length":70,
"weight":1900
},
"amount":2420,
"currency_id":"USD"
}
},
"order_id":101010669519,
"test":false,
"tracking_number": "360000226808570",
"authorization_information": {
"date": "2001-07-04T12:08:56.235-07:00",
"custom_data":{
"ruta_1":"RUTA"
}
}
}