Devoluciones
Cómo identificar una Devolución
- Escuchando la notificación del reclamo que se creó asociado a una orden. (feed claims)
- Consultando el reclamo (recurso /claims)
- Validando si el type del reclamo es "return" (recurso /claims)
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/v1/claims/$CLAIM_ID/returns
Respuesta:
{
"last_updated": "2019-01-04T22:51:47.459-04:00",
"shipping": {
"id": "27768896524",
"status": "cancelled",
"tracking_number": null,
"lead_time": {
"estimated_delivery_time": {
"date": "2018-12-28T00:00:00.000-03:00"
}
},
"status_history": [
{
"status": "handling",
"substatus": null,
"date": "2018-12-20T08:31:14.000-04:00"
},
{
"status": "ready_to_ship",
"substatus": "ready_to_print",
"date": "2018-12-20T08:31:14.000-04:00"
},
{
"status": "cancelled",
"substatus": "return_expired",
"date": "2019-01-04T22:47:01.000-04:00"
}
],
"origin": {
"type": "selling_address",
"sender_id": 388146803,
"shipping_address": {
"address_id": 1018791372,
"address_line": "Testing Street 1450",
"street_name": "Testing Street",
"street_number": "1450",
"comment": "Referencia: The Testing Cavern",
"zip_code": "1430",
"city": {
"id": "TUxBQlNBQTM3Mzda",
"name": "Saavedra"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"country": {
"id": "AR",
"name": "Argentina"
},
"neighborhood": {
"id": null,
"name": "The Neighborhood"
},
"municipality": {
"id": null,
"name": null
},
"types": [
"billing",
"default_buying_address",
"default_selling_address",
"shipping"
],
"latitude": -34.554242,
"longitude": -58.491549,
"geolocation_type": "APPROXIMATE"
}
}
},
"refund_at": "delivered",
"date_closed": null,
"resource": "order",
"date_created": "2018-12-20T08:31:13.813-04:00",
"claim_id": 1028414216,
"status_money": "available",
"resource_id": 1893698454,
"type": "express",
"status": "expired"
}
Descripción de parámetros
La respuesta de un GET al recurso /returns da como resultado los siguientes parámetros:
last_updated: última actualización de la Devolución.
shipping: detalle del envío de la Devolución.
- id: número de identificación del envío
- status: estado en el que se encuentra el envío
- tracking_number: número de seguimiento del envío de la devolución
- estimated_delivery_time: tiempo estimado de llegada del envío de la devolución
status_history: representa el historial de los estados por los que fue pasando el envío de la Devolución.
status: son los 4 estados por los que puede pasar el returns:
handling: cuando se genera la etiqueta
ready_to_ship: etiqueta lista para despachar
shipped: enviado
delivered: entregado
- substatus
- date
origin: información de la Dirección del Seller, donde se envía la Devolución
refund_at: cuando se devuelve el dinero al buyer
values: [‘shipped’|‘delivered’]
‘shipped’: cuando el comprador realiza el despacho del envío de la devolución.
‘delivered’: 3 días después de que el seller recibe el envío.
date_closed: fecha en la que se cierra la devolución
resource: nombre del recurso al cual se asocia la devolución
date_created: fecha en la que se crea la devolución
claim_id: el ID del reclamo al que está asociado la devolución
status_money: estado en el que se encuentra el Dinero de la devolución
- values: [‘RETAINED’|‘REFUNDED’, ‘AVAILABLE’]
RETAINED: dinero en cuenta, pero no disponible, retenido
REFUNDED: dinero devuelto al buyer
AVAILABLE: dinero en cuenta disponible
resource_id: ID del recurso
type: expres
status: estados por los cuales puede pasar una Devolución
Estados de una Devolución
Opened: Cuando el Seller inicia un reclamo a ML por una devolución.
Shipped: Devolución enviada, dinero retenido.
Closed: Estado Final de la devolución al cierre de la misma y del claim_id asociado. Este estado dispara la devolución del Dinero al comprador.
Delivered: Envío en manos del vendedor pero todavía NO pasaron los 3 días para revisarse.
Cancelled: Devolución cancelada, dinero disponible.
Expired: Devolución Expirada, dinero disponible.
Manejo de errores
estructura de error
{
"error":Error Type,
"code":Error code,
"message":error message,
"cause":list of error cause
}
Ejemplo invalid claim_id
{
"error": "Can’t obtain data with id: 18",
"code": 403,
"message": "Cant get data with id: 18, status_code: 403 , response: {'error':'not_owned_order','status':403,'message':'The user has not access to the order.','cause':[]}, url: https://api.mercadolibre.com/v1/claims/10284142/returns",
"cause": []
}
Ejemplo invalid_param
{
"error": "BAD_REQUEST",
"code": 400,
"message": "key: parameter claim_id must be a number, status_code:400",
"cause": [
400,
"Invalid Param claim_id :aa"
]
}
Ejemplo invalid access_token
{
"error": "ACCESS_TOKEN_VERIFICACION_FAILS",
"code": 401,
"message": "Error validating access token, status_code:401",
"cause": [
"ACCESS_TOKEN_VERIFICACION_FAILS",
"Error validating access token",
401
]
}