Devoluciones

Identificar una Devolución

Para identificar correctamente una devolución hacemos las siguientes recomendaciones:

• Escuchar la notificación del reclamo (feed claims) la cual contiene la información de la orden en donde causó.
• Consultar la API de reclamos en el recurso /post-purchase/v1/claims/search, validando si el type es “return”.

Consultar una Devolución

Para consultar una devolución deberás hacer el llamado a post-purchase/v2/claims/$CLAIM_ID/returns, especificando el $CLAIM_ID, ejemplos a continuación:

Ejemplo de llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v2/claims/$CLAIM_ID/returns

Respuesta:

{
  {
    "last_updated": "2024-01-11T16:03:22.2+00:00",
    "shipping": {
        "id": 42998970748,
        "status": "delivered",
        "tracking_number": "101010622106990",
        "lead_time": {
            "estimated_delivery_time": {
                "date": "2024-01-17T00:00:00.000-03:00"
            }
        },
        "status_history": [
            {
                "status": "handling",
                "substatus": null,
                "date": "2024-01-11T12:01:35.576-04:00"
            },
            {
                "status": "ready_to_ship",
                "substatus": "ready_to_print",
                "date": "2024-01-11T12:02:06.839-04:00"
            },
            {
                "status": "shipped",
                "substatus": null,
                "date": "2024-01-11T12:02:10.839-04:00"
            },
            {
                "status": "delivered",
                "substatus": null,
                "date": "2024-01-11T12:02:14.280-04:00"
            }
        ],
        "origin": {
            "type": "selling_address",
            "sender_id": 1632520187,
            "shipping_address": {
                "address_id": 1350834413,
                "address_line": "Calle 34 123",
                "street_name": "Calle 34",
                "street_number": "123",
                "comment": "23  Entre: 67 y 54",
                "zip_code": "5000",
                "city": {
                    "id": "TUxBQ0NBUGNiZGQx",
                    "name": "Córdoba"
                },
                "state": {
                    "id": "AR-X",
                    "name": "Córdoba"
                },
                "country": {
                    "id": "AR",
                    "name": "Argentina"
                },
                "neighborhood": {
                    "id": null,
                    "name": null
                },
                "municipality": {
                    "id": null,
                    "name": null
                },
                "types": [
                    "default_buying_address"
                ],
                "latitude": -31.010405,
                "longitude": -64.075891,
                "geolocation_type": "APPROXIMATE"
            }
        },
        "destination": {
            "name": "seller_address"
        }
    },
    "refund_at": "delivered",
    "date_closed": "2024-01-11T12:03:22.464-04:00",
    "resource": "order",
    "date_created": "2024-01-11T16:01:34.936+00:00",
    "claim_id": 5243352643,
    "status_money": "refunded",
    "resource_id": 2000007357691104,
    "type": "automatic",
    "subtype": null,
    "status": "closed",
    "warehouse_review": {
        "product_condition": "saleable",
        "product_destination": "buyer",
        "benefited": false
    }
 }
 
}

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:

• 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: null

• date: fecha del estado.

• origin dirección de origen del envío de devolución.

• type: tipo de dirección.
• sender_id: código del comprador (buyer_id).
• shipping_address: detalle de la dirección.

• destination: información del destino de la devolución.

• seller_address: destino vendedor.
• warehouse: destino depósito de Mercado Libre.

• refund_at: cuando se devuelve el dinero al comprador.

• 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.

• 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.

• claim: devolución por reclamo.
• dispute: devolución por mediación.
• automatic: devolución automática.

• subtype: el subtipo de devolución.

• 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

• 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.

• warehouse_review: resultado del proceso del triage que se hace en el depósito (revisión del producto), este array tiene información únicamente si el atributo “destination” es igual warehouse, de lo contrario se muestra nulo.

• product_condition:

• saleable: significa que el producto está apto para volver a venderse y se hace el restock automáticamente.
• unsaleable: el producto no está en condiciones para la venta.
• discard: el producto es descartado porque es diferente al que el comprador obtuvo de la transacción y debía devolver, por ejemplo una piedra.

• product_destination: puede ser “buyer”, “seller” o “meli”
• benefited:

• true: se le reintegra el dinero de la venta al vendedor.
• false: se le reintegra el dinero de la transacción al comprador.

Manejo de errores

A continuación se detalla los mensajes de error que el recurso puede responder, y que esperan una acción correctiva:

1. Error cuando el claim no existe::

{
  {
    "code": 404,
    "error": "not_found_error",
    "message": "Error executing GET [client:claims]",
    "cause": null
 }
 

2. Error cuando no se tiene permiso para acceder al recurso. (unauthorized_request_error):

{
  {
    "code": 401,
    "error": "unauthorized_request_error",
    "message": "{\"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]}",
    "cause": null
 }
 

3. Error de autenticación -token- (unauthorized_request_error):

{
  {
    "code": 401,
    "error": "unauthorized_request_error",
    "message": "Invalid caller.id",
    "cause": null
 }
}