Trabajar con 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 2 tipos de devoluciones:

  • Las denominadas "express" que dependen de la decisión del comprador.

  • Las que se generan a través de un reclamo.

Nota: Este recurso por el momento permitirá consultar las de tipo "express" y gestionarlas de manera sencilla. Desde el mismo recurso se podrá acceder a las que vienen desde un reclamo próximamente.

Contenidos

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)

Llamada:

Curl -X GET  
https://api.mercadolibre.com/v1/claims/{claim_id}/returns?access_token=$ACCESS_TOKEN”

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 buyer 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 del 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?access_token=APP_USR-1505-112714-9e75ec9d61d116d6510b2385f8be31fb-379926",
    "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
    ]
}

Forma parte de nuestra comunidad