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 /v1/claims/search, validando si el type es “return”.

Consultar una Devolución

Para consultar una devolución deberás hacer el llamado a /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/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:

• Si el tipo de devolución es Devex (deprecado 30 de noviembre de 2023) los posibles estados son::

• handling: cuando se genera la etiqueta.
• ready_to_ship: etiqueta lista para despachar.
• shipped: enviado.
• delivered: entregado.

• Para Devos v2.0 los posibles estados son:

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

• express: devoluciones v1.0 (deprecado 30/11/2023)
• 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

• Si el tipo de devolución es Devex (deprecado 30 de noviembre de 2023) los posibles estados son:

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

• Para Devos v2.0 los posibles estados son:

• 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 se envía un $CLAIM_ID al que no se tiene acceso usando ese access token:

{
    "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": []
}

2. Error cuando se envía un $CLAIM_ID que no es de tipo numérico.

{
    "error": "BAD_REQUEST",
    "code": 400,
    "message": "key: parameter claim_id must be a number, status_code:400",
    "cause": [
        400,
        "Invalid Param claim_id :aa"
    ]
}

3. Error si el $CLAIM_ID enviado no existe.

{
    "message": "Error executing GET [client:claims]",
    "error": "rest_client_error",
    "status": 404,
    "cause": [
        "{\"status\":404,\"error\":\"not_found\",\"message\":\"Claim not found. claimId: xxxx\"}"
    ]
}

4. Error si el $CLAIM_ID enviado es vacío o 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
    ]
}

5. A partir del 30 de noviembre de 2023 al consultar la v1 se recibirá un código de error 503, ya que esta versión se depreca.