Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 04/08/2023

Devoluciones

El nuevo recurso /returns te permite obtener el detalle de una Devolución de producto, conocer sus motivos y estados.
En Mercado Libre trabajamos con 3 tipos de devoluciones:

  • Las denominadas Devex - Devolución express (en el futuro “Automáticas”)
  • Generadas a través de un reclamo (Claims)
  • Por mediación (Dispute)

Nota:
Este recurso por el momento permitirá consultar las de tipo "express" y hacerles seguimiento de manera sencilla.
La nueva versión soportará información sobre: devoluciones por reclamos, mediaciones y automáticas, además de devoluciones express. Una vez que la versión anterior se depreque dejaran de estar disponibles las Devex y pasarán a llamarse automáticas.

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.
Nota:
Recuerda que el recurso /shipments/$SHIPMENT_ID/costs devuelve los costos del envío que deberá afrontar el usuario.


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
    ]
}