Cancelación de envíos

Contenidos

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

En caso de tener que cancelar un envío, Mercado Libre hará una solicitud PUT a la URL de autorización:

PUT service_url/shipments/shipment_id/authorization

Nota:

Idempotencia: En caso de recibir un request, con un envío previamente cancelado, el servicio deberá responder con un “HTTP Code” = 200 y con el mismo body que se retornó al momento de la cancelación original.
Un envío cancelado podría volver a autorizarse en un futuro por lo que se debe tener en cuenta el flujo.
Cuando un envío ya está en posesión del correo, si se solicita una cancelación debería bloquearse el paquete y comenzar el flujo de devolución.

Dependiendo de si la cancelació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 cancelaciones 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
status	String	Contiene los valores de status. CANCEL
tracking_number	String	Identificador del envío provisto por el carrier cuando fue autorizado.

Formato Response

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

Nombre	Tipo de dato	Descripción	Tipo
status	String	estado del pedido de cancelación. CANCELLED FAILED ERROR	Mandatorio.
status_message	String	Cualquier detalle relevante al estado.	Mandatorio en caso de fallo.
tracking_number	String	Identificador el envío.	Mandatorio.

Status Codes

Status	Status Message	Código HTTP	Descripción	Acción
CANCELLED	-	200	Cuando la cancelación fue procesada satisfactoriamente.	El envío ya fue cancelado y no se volverá a reintentar.
CANCELLED	BLOCKED	200	Para el escenario de bloqueo de paquetes en poder del carrier se espera que retorne "status": "CANCELLED" junto con el "status_message": "BLOCKED".	Bloquear la entrega y comenzar el flujo de devolución.
FAILED	-	400	Cuando la cancelació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 PUT 'https://hostname/shipments/{shipment_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:

{
  "carrier_information": {
    "account": "A432765637",
    "contract": "000123ABC87",
    "user": "",
    "password": "pa$word",
    "client_id": "432765637"
  },
  "status": "CANCEL",
  "tracking_number": "1234NLUG123"
}

Response:

Cancelled (200 OK)

{
  "status":"CANCELLED",
  "status_message":"",
  "tracking_number": "1234NLUG123"
}

Blocked (200 OK)

{
  "status":"CANCELLED",
  "status_message":"BLOCKED",
  "tracking_number": "1234NLUG123"
}

Failed (400 FAILED)

{
  "status":"FAILED",
  "status_message":"Invalid tracking number",
  "tracking_number": "1234NLUG123"
}

Error (500 ERROR)

{
  "status":"ERROR",
  "status_message":"Internal error occurred",
  "tracking_number": "1234NLUG123"
}