Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Última actualización 04/08/2023
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/v2/claims/$CLAIM_ID/returns
Respuesta:
{
"last_updated": "2023-05-30T16:06:08.207-04:00",
"shipping": {
"id": 42313159782,
"status": "delivered",
"tracking_number": "10101015808",
"lead_time": {
"estimated_delivery_time": {
"date": "2023-06-06T00:00:00.000-05:00"
}
},
"status_history": [
{
"status": "handling",
"substatus": null,
"date": "2023-05-30T15:52:05.206-04:00"
},
{
"status": "ready_to_ship",
"substatus": "ready_to_print",
"date": "2023-05-30T15:52:09.736-04:00"
},
{
"status": "shipped",
"substatus": null,
"date": "2023-05-30T16:04:00.689-04:00"
},
{
"status": "delivered",
"substatus": null,
"date": "2023-05-30T16:06:07.644-04:00"
}
],
"origin": {
"type": "selling_address",
"sender_id": 1206328181,
"shipping_address": {
"address_id": 1303663780,
"address_line": "Calle 3 #01-22",
"street_name": "Calle 3",
"street_number": "#01-22",
"comment": "Referencia: casa",
"zip_code": "252201",
"city": {
"id": "TUNPQ1BBUzQ4NjY4",
"name": "Pasca"
},
"state": {
"id": "CO-CUN",
"name": "Cundinamarca"
},
"country": {
"id": "CO",
"name": "Colombia"
},
"neighborhood": {
"id": null,
"name": "Paca"
},
"municipality": {
"id": null,
"name": null
},
"types": [],
"latitude": 4.307708,
"longitude": -74.301528,
"geolocation_type": "ROOFTOP"
}
}
},
"refund_at": "shipped",
"date_closed": "2023-05-30T16:04:01.763-04:00",
"resource": "order",
"date_created": "2023-05-30T15:52:04.476-04:00",
"claim_id": 5195217090,
"status_money": "refunded",
"resource_id": 2000005748875612,
"type": "claim",
"subtype": null,
"status": "closed"
}
Descripción de los parámetros de la respuesta
La respuesta de un GET al recurso /returns da como resultado los siguientes parametros:
- 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: en el que se encuentra el envío.
- tracking_number número de seguimiento del envío de la devolución.
- lead_time:
- estimated_delivery_time: tiempo estimado de llegada del envío de la devolución.
- date: 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 estados por los que puede pasar el returns:
- Devex:
- handling: cuando se genera la etiqueta.
- ready_to_ship: etiqueta lista para despachar.
- shipped: enviado.
- delivered: entregado.
- Devoluciones 2.0:
- pending: cuando se genera el envío.
- ready_to_ship: etiqueta lista para despachar.
- shipped: enviado.
- not_delivered: no entregado.
- delivered: entregado.
- cancelled: envío cancelado.
- substatus:
- date: fecha del estado.
- origin información de la dirección del vendedor, donde se envía la devolución.
- refund_at: cuando se devuelve el dinero al comprador.
- values: [shipped | delivered | n/a]
- shipped: cuando el comprador realiza el despacho del envío de la devolución.
- delivered: 3 días después de que el vendedor recibe el envío.
- n/a: para casos low cost que no generan una devolución.
- 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 comprador.
- available: dinero en cuenta disponible.
- resource_id: ID del recurso.
- type: tipo de devolución;
- values: [ express | claim | dispute | automatic]
- express: devoluciones 1.0
- claim: devolución por reclamo en devos 2.0
- dispute: devolución por mediación en devos 2.0
- automatic: devolución automática en devos 2.0
- subtype: el subtipo de devolución.
- values: [ low_cost | return_partial ]
- low_cost: devolución automática de tipo low cost.
- return_partial: devolución automática de tipo return partial.
- status: estados por los cuales puede pasar una devolución.
- Estados de una devolución
- Devex
- opened: cuando el comprador inicia un reclamo a Mercado Libre 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.
- Devoluciones 2.0
- opened: cuando el comprador inicia un reclamo a Mercado Libre 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.
- delivered: envío en manos del vendedor.
- not_delivered: devolución no entregada.
- cancelled: devolución cancelada, dinero disponible.
- failed: devolución fallida.
- expired:devolución expirada.
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
]
}
Caller id es vacío
{
"message": "key: parameter caller.id is invalid or empty, status_code: 400",
"error": "bad_request",
"status": 400,
"cause": [
"bad_request",
"Invalid Param caller.id",
400
]
}
Caller id no autorizado
{
"message": "key: parameter caller.id unauthorized owner, status_code: 401",
"error": "access_token_verification_fails",
"status": 401,
"cause": [
"access_token_verification_fails",
"Error validating access token, caller.id is not owner",
401
]
}
Claim no encontrada
{
"message": "Error executing GET [client:claims]",
"error": "rest_client_error",
"status": 404,
"cause": [
"{\"status\":404,\"error\":\"not_found\",\"message\":\"Claim not found. claimId: xxxx\"}"
]
}
Parametro invalido
{
"message": "key: parameter claim_id is invalid or empty, status_code: 400",
"error": "bad_request",
"status": 400,
"cause": [
"bad_request",
"Invalid Param claim_id",
400
]
}