¿Qué es una devolución?

Una devolución es un proceso crucial en la experiencia de compra en nuestra plataforma, mediante el cual un comprador puede devolver un artículo al vendedor. Este procedimiento puede activarse por diversas razones, tales como discrepancias entre la descripción del producto y su estado real, problemas de funcionamiento, o incluso un cambio de opinión por parte del comprador. Gestionar eficazmente las devoluciones es fundamental para mantener la confianza y satisfacción del cliente, asegurando que cualquier problema se resuelva de manera transparente y eficiente.

Gestionar una devolución

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

1. Monitorear la notificación del reclamo: Escucha el feed de reclamos (feed claims), el cual contiene la información de la orden en la que se originó el reclamo.
2. Consultar el recurso /claims/$CLAIMS para acceder al campo "related_entities", que ofrece una lista de entidades vinculadas al reclamo. Si existe el valor "return" significa que hay una devolución asociada a este reclamo. Ahora puedes consultar el recurso de Returns para obtener los detalles de la devolución y tomar las medidas necesarias dentro de los plazos establecidos.

Para más información, consulta la documentación de Gestión de Reclamos.

Consultar una devolución

Para consultar una devolución, realiza una solicitud a post-purchase/v2/claims/$CLAIM_ID/returns, especificando el $CLAIM_ID. Esto te proporcionará información detallada sobre la devolución asociada al reclamo correspondiente.

Llamada:

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

Ejemplo:

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

Respuesta:

{
   "last_updated": "2023-02-25T00:02:22.575-04:00",
   "shipping": {
       "id": 42049162337,
       "status": "cancelled",
       "tracking_number": "MEL42049162337FMDOR01",
       "lead_time": {
           "estimated_delivery_time": {
               "date": "2023-02-20T00:00:00.000-06:00"
           }
       },
       "status_history": [
           {
               "status": "handling",
               "substatus": null,
               "date": "2023-02-15T15:43:14.944-04:00"
           },
           {
               "status": "ready_to_ship",
               "substatus": "ready_to_print",
               "date": "2023-02-15T15:43:18.377-04:00"
           },
           {
               "status": "cancelled",
               "substatus": "return_expired",
               "date": "2023-02-25T00:02:20.394-04:00"
           }
       ],
       "origin": {
           "type": "selling_address",
           "sender_id": 1299347553,
           "shipping_address": {
               "address_id": 1280687101,
               "address_line": "Calle Transportes 234",
               "street_name": "Calle Transportes",
               "street_number": "234",
               "comment": "Referencia: NA",
               "zip_code": "03940",
               "city": {
                   "id": "TUxNQ0JFTjM2MjQ",
                   "name": "Benito juárez"
               },
               "state": {
                   "id": "MX-DIF",
                   "name": "Distrito Federal"
               },
               "country": {
                   "id": "MX",
                   "name": "Mexico"
               },
               "neighborhood": {
                   "id": null,
                   "name": "Crédito Constructor"
               },
               "municipality": {
                   "id": null,
                   "name": null
               },
               "types": [
                   "default_buying_address"
               ],
               "latitude": 19.365558,
               "longitude": -99.179523,
               "geolocation_type": "GEOMETRIC_CENTER"
           }
       },
       "destination": {
           "name": "seller_address"
       }
   },
   "refund_at": "delivered",
   "date_closed": null,
   "resource": "order",
   "date_created": "2023-02-15T15:43:14.694-04:00",
   "claim_id": 5255026166,
   "status_money": "retained",
   "resource_id": 2000007760636316,
   "type": "dispute",
   "subtype": null,
   "status": "opened",
   "warehouse_review": {
       "product_condition": "",
       "product_destination": "",
       "benefited": false
   },
   "seller_review": {
       "status": "",
       "reason_id": null
   }
}

Campos de la respuesta:

La respuesta de un GET al recurso v2/claims/$CLAIM_ID/returns proporcionará los siguientes campos:

• 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.
  • 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 retorno:
    • 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.
    • address_id:
    • address_line:
    • street_name:
    • street_number:
    • comment:
    • zip_code:
    • city:
    • state:
    • country:
    • neighborhood:
    • municipality:
    • types:
    • latitude:
    • longitude:
    • geolocation_type:
• destination: información del destino de la devolución.
  • name
    • 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 creó la devolución.
• claim_id: el id del reclamo al que está asociada 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 parcial.
  • return_total : devolución total.
• status: estados por los cuales puede pasar 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
    • buyer
    • seller
    • 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.
• seller_review: brinda información sobre la revisión realizada por el vendedor.
  • status: estado de la revision. Puede tomar alguno de los siguientes valores:
    • pending: la devolución está pendiente de revisión por el vendedor.
    • claimed: el vendedor revisó el producto y decidió que el producto no está en las condiciones esperadas.
    • failed: el responsable de CX decide que el vendedor es beneficiario. (el status anterior es claimed).
    • success: el vendedor revisó la devolución e indicó que llegó en las condiciones esperadas.
  • reason_id:Identificador de la razón por la cual el vendedor ha indicado un problema con el producto. Los posibles valores son los que devuelve el recurso reasons/return-fail. Actualmente los posibles valores son:
  • null:Cuando no hay ninguna razón especificada. Este campo es siempre null salvo cuando el status es ‘claimed’.
  • SRF2: El producto llegó dañado.
  • SRF3: La devolución está incompleta.
  • SRF4: Devolvieron un producto distinto al que se envió.
  • SRF5: El producto no está en el paquete.
  • SRF6: Reportar otra falla en el producto.
  • SRF7: Aún no ha recibido el producto.

Returns - Nueva versión a partir del 20/03/2025

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews

Se han realizado mejoras para simplificar y optimizar la información retornada, eliminando datos redundantes y agregando campos esenciales.

Consultar una devolución

Para consultar una devolución, realiza una solicitud a post-purchase/v2/claims/$CLAIM_ID/returns, especificando el $CLAIM_ID. Esto te proporcionará información detallada sobre la devolución asociada al reclamo correspondiente.

Llamada:

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

Respuesta:

{
    "id": 57341011,
    "last_updated": "2024-09-10T17:26:41.704+00:00",
    "shipments": [
        {
            "shipment_id": 43810672299,
            "status": "delivered",
            "tracking_number": null,
            "destination": {
                "name": "warehouse",
                "shipping_address": {
                    "address_id": 0,
                    "address_line": "Av. Dr. Antonio Joao Abdalla, 3333",
                    "street_name": "Av. Dr. Antonio Joao Abdalla",
                    "street_number": "3333",
                    "comment": "Mercado Livre",
                    "zip_code": "07750020",
                    "city": {
                        "id": "QlItU1BDYWphbWFy",
                        "name": "Cajamar"
                    },
                    "state": {
                        "id": "BR-SP",
                        "name": "São Paulo"
                    },
                    "country": {
                        "id": "BR",
                        "name": "Brasil"
                    },
                    "neighborhood": {
                        "id": null,
                        "name": "Empresarial Colina"
                    },
                    "municipality": {
                        "id": null,
                        "name": null
                    }
                }
            },
            "type": "return"
        },
        {
            "shipment_id": 43825249694,
            "status": "pending",
            "tracking_number": null,
            "destination": {
                "name": "seller_address",
                "shipping_address": {
                    "address_id": 1351779578,
                    "address_line": "Rua Rio Grande SN",
                    "street_name": "Rua Rio Grande",
                    "street_number": "SN",
                    "comment": "Referencia: test",
                    "zip_code": "09831740",
                    "city": {
                        "id": "BR-SP-39",
                        "name": "São Bernardo do Campo"
                    },
                    "state": {
                        "id": "BR-SP",
                        "name": "São Paulo"
                    },
                    "country": {
                        "id": "BR",
                        "name": "Brasil"
                    },
                    "neighborhood": {
                        "id": null,
                        "name": "Rio Grande"
                    },
                    "municipality": {
                        "id": null,
                        "name": null
                    }
                }
            },
            "type": "return_from_triage"
        }
    ],
    "refund_at": "delivered",
    "date_closed": null,
    "resource_type": "order",
    "date_created": "2024-09-06T16:24:26.636+00:00",
    "claim_id": 5298178312,
    "status_money": "retained",
    "resource_id": 2000009229357366,
    "orders": [
        {
            "order_id": 2000009229357366,
            "item_id": "MLB3840513395",
            "variation_id": null,
            "context_type": "total",
            "total_quantity": "1.0",
            "return_quantity": "1.0"
        }
    ],
    "subtype": "return_total",
    "status": "delivered",
    "related_entities": [
        "reviews"
    ],
    "intermediate_check": true
}

Campos de la respuesta

Para que comprendan mejor los cambios realizados en el recurso /returns, hemos preparado un listado de los campos que se han eliminado y los que hemos añadido.

X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' -H 'Authorization: Bearer $ACCESS_TOKEN'

X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' -H 'Authorization: Bearer $ACCESS_TOKEN'

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPPING_ID/history

Posibles errores

404 Not Found:

{
    "code": 404,
    "error": "not_found_error",
    "message": "Claim not found. claimId: 1234",
    "cause": null
}

Reviews - Disponible a partir del 20/03/2025

El recurso /reviews proporciona información sobre la revisión de devoluciones, ya sea de MELI (almacén), del vendedor o apelaciones. Para identificar las devoluciones que tienen revisiones, es necesario consultar el campo “related_entities”, que contendrá el ítem "reviews".

¿Qué son las apelaciones?

Las apelaciones ocurren cuando una devolución ha sido revisada por el equipo de triage, y el vendedor puede impugnar la decisión.

¿Cuál es la diferencia entre apelaciones y revisione fallidas de devoluciones?

Una revision fallida de devolucion se presenta cuando no hay revisión por parte de triage, y el vendedor es responsable de dicha revisión, indicando que el producto llegó con algún problema.

Llamada:

  
    curl -L -X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' \
      -H 'Authorization: Bearer $ACCESS_TOKEN'
  

Ejemplo:

  
    curl -L -X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/57341011/reviews' \
       -H 'Authorization: Bearer $ACCESS_TOKEN'
  

Respuesta:

  
   {
   "reviews": [
       {
           "resource": "order",
           "resource_id": 2000008958860420,
           "method": "triage",
           "resource_reviews": [
               {
                   "stage": "",
                   "status": "success",
                   "product_condition": "unsaleable",
                   "product_destination": "seller",
                   "reason_id": "accepted",
                   "benefited": "buyer",
                   "seller_status": "failed",
                   "seller_reason": "SRF2",
                   "benefited_type": null,
		           "benefited_reason": null,
		           "missing_quantity": 1
               }
           ],
           "date_created": "2024-08-27T14:58:21.978Z",
           "last_updated": "2024-08-27T14:58:21.978Z"
       }
   ]
}
  

Campos de la respuesta

reviews (list): Lista de las revisiones finalizadas por el proceso de triage y por el vendedor.

resource (string): Tipo de recurso que estará relacionado con la revisión. Para el carrito, será "order". En los casos diferentes al carrito, el recurso también será "order".

resource_id (string): ID del recurso indicado en "resource".

method (string): Indica cuál es el método de revisión de la devolución. Posibles valores:

• none: revisión del vendedor.
• triage: revisión realizada por la triage de MELI.

date_created (string): fecha de creación de la revisión.

last_updated (string): fecha de actualización de la revisión.

resource_reviews (list): Lista de revisiones realizadas sobre el recurso.

stage (string): De acuerdo con este campo, es posible identificar los casos que pueden tener apelaciones del vendedor y los de timeout. Posibles valores:

• closed: la revisión ha sido finalizada, ya sea mediante una triage que puede incluir una apelación del vendedor o una revisione fallida de devoluciones.
• pending: la revision fallida de devolucion está pendiente de resolución.
• seller_review_pending: revisión de triage que puede tener una apelación del vendedor y está pendiente.
• timeout: el tiempo para que la triage analice el producto ha expirado.

status (string): Estado de la revisión realizada por la triage. Posibles valores:

• success: revisión realizada y el producto está OK.
• failed: indica que el operador detectó que el producto tiene algún problema. El campo "product_condition" detalla esta condición del producto.
• "" no hay una revisión de la triage.
• null: es una revisión realizada por el vendedor.

product_condition (string): Condición del producto. Posibles valores:

• saleable: el producto está en buenas condiciones para la venta.
• discard: el producto ha sido descartado.
• unsaleable: el producto no está apto para la venta.
• missing: el producto no llegó para su revisión.
• "" o null: cuando no contamos con una revisión.

product_destination (string): Destino del producto después del análisis de la revisión. Posibles valores:

• meli: el producto va a Mercado Libre.
• buyer: el producto va al comprador.
• seller: el producto va al vendedor.
• "" en los casos de "missing", el valor de este campo está vacío.
• null: cuando no contamos con una revisión.

reason_id (string): Tipificación seleccionada en el proceso de revisión. Posibles valores:

• accepted: el producto fue aceptado.
• different_product: producto diferente.
• discard: producto descartado.
• misused: producto mal usado.
• not_working: el producto no funciona.
• incomplete: producto incompleto.
• blocked: producto bloqueado.
• open_box: producto de caja abierta.
• missing: producto no encontrado.
• default: en los casos en que la revisión no pudo ser generada.
• null: no contamos con una revisión.

benefited (string): Indica quién fue el beneficiario de la revisión de triage. Posibles valores:

• both: el beneficiario es tanto el comprador como el vendedor.
• buyer: el beneficiario es el comprador.
• seller: el beneficiario es el vendedor.
• null: no tenemos una revisión.

seller_status (string): Estado de la revisión del vendedor, si es aplicable. Posibles valores:

• pending: el vendedor está revisando el producto.
• success: el vendedor indicó que el producto está en buenas condiciones.
• failed: el vendedor indicó que el producto tiene problemas.
• claimed: el vendedor reclamó el producto.
• "" no se necesita revisión por parte del vendedor.
• null: el vendedor no recibió el producto o no es necesario que lo revise.

seller_reason (string): Identifica el motivo alegado por el vendedor si la revisión no es exitosa. Posibles valores:

• "SRF2"
• "SRF3"
• "SRF6"
• "SRF7"
• null: cuando no se ha indicado un motivo.

missing_quantity (long): Se utiliza para identificar la cantidad de artículos que no han sido revisados, ya que el producto no llegó para su evaluación.

Posibles errores

404 Not Found:

{
    "code": 404,
    "error": "not_found_error",
    "message": "return review not found",
    "cause": null
}

Revisión OK de una devolución

Cuando una devolución llega al vendedor, éste tiene la posibilidad de hacer una revisión de la misma indicando si el producto llegó en las condiciones esperadas o si hay algún problema con el mismo.

Para realizar una revisión OK de una devolución, confirmando que el producto llegó en las condiciones esperadas, se habilitó el recurso /claims/$CLAIM_ID/actions/return-review-ok

Para saber si el vendedor ya tiene habilitada la opción de hacer una revisión ok de una devolución, se puede utilizar el recurso /claims/$CLAIM_ID. Dentro del array de “players”, buscamos el player “type”: “seller” y validamos que en sus "available_actions" exista "action": "return_review_ok"

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-ok

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-ok

Respuesta:

{
   "id":5255026166,
   "resource_id": 2000007760636316,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9949",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": true,
                   "due_date": "2024-06-03T22:43:00.000-04:00"
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46122402,
           "available_actions": []
       }
   ],
   "resolution": {
       "reason": "item_returned",
       "date_created": "",
       "benefited": [
           "complainant"
       ],
       "closed_by": "mediator",
       "applied_coverage": true
   },
   "site_id": "MLA",
   "date_created": "2024-05-29T23:48:32.000-04:00",
   "last_updated": "2024-05-29T23:51:26.370-04:00"
}

Campos de la respuesta

La respuesta exitosa de un GET al recurso /actions/return-review-ok devolverá un status code 201 y los siguientes campos:

• id: ID del reclamo
• resource: ID del recurso sobre el que se crea el reclamo. Depende del “resource”
• status: Estado del reclamo
  • opened
  • closed
• type: Tipo de reclamo
  • mediations: reclamo entre comprador y vendedor.
  • return: Devolución de producto.
  • fulfillment: Reclamo entre comprador y Mercado Libre con origen de compra con envío full.
  • ml_case: Cancelación de la compra por parte del comprador debido a envío demorado.
  • cancel_sale: Cancelación de compra por parte del vendedor. Siempre en status: "closed" y stage: "none". El rol complainant siempre va a ser del tipo seller, collector o sender dependiendo el recurso del reclamo.
  • cancel_purchase: cancelación de compra por parte del comprador
  • change: Cambio de Producto.
  • service: Cancelación de un servicio ordenes bundle.
• stage: Etapa del reclamo
  • claim: etapa de reclamo donde intervienen el comprador y el vendedor
  • dispute: etapa de mediación donde interviene un representante de Mercado Libre
  • recontact: etapa en la que alguna de las partes se contacta luego de cerrado el reclamo/disputa
  • none: no aplica
  • stale: Etapa de reclamo donde intervienen el comprador y Mercado Libre para reclamos de tipo ml_case.
• parent_id: ID de otro reclamo del que depende
• resource: Identificador del recurso sobre el que se crea el reclamo. Interfiere en los actores del reclamo
  • payment: Pago
  • order: Orden
  • shipment: Envío
  • purchase: Compra
• reason_id: Razón/motivo por el cual fue creado el reclamo. Interfiere directamente con las soluciones que se pueden proponer
  • PNR: Producto No Recibido
  • PDD: Producto Diferente o Defectuoso
  • CS: Compra Cancelada
• fulfilled: Indica si el reclamo se inicia por un producto entregado o no
• quantity_type: informa si el claim es una reclamo parcial o no
  • partial: indica que es un reclamo parcial
  • total: indica que es un reclamo total
• players: Lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles
  • role: rol dentro del reclamo
    • complainant: persona que reclama.
    • respondent: persona a quién le reclaman.
    • mediator: persona que interviene para ayudar a solucionar el problema.
    • warehouse_dispatcher: persona encargada de revisar el producto en las devoluciones al warehouse.
  • type: rol que ocupa la persona sobre la operación que se está reclamando
    • payment: comprador - collector.
    • order: comprador - vendedor.
    • shipment: receptor - remitente.
    • purchase: comprador - Mercado Libre
  • user_id: ID del usuario en ML que cumple el rol
  • available_actions: Lista de acciones que pueden ejecutar cada una de las partes intervinientes
    • players: lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles.
      • action: Nombre de la acción
        • send_message_to_complainant: enviar mensaje para el comprador (con o sin anexos).
        • send_message_to_mediator: enviar mensaje para el mediador (con o sin anexos).
        • recontact (no disponible aún): reabrir un reclamo ya cerrado, por medio de una interacción, como un mensaje.
        • refund: devolver el dinero del comprador. Debe ser realizado por el front de Mercado Libre o Mercado Pago.
        • open_dispute: iniciar una mediación.
        • send_potential_shipping: enviar una promesa de post, una fecha.
        • add_shipping_evidence: publicar una evidencia de que el producto fue enviado.
        • send_attachments: enviar mensaje con adjuntos.
        • allow_return_label: generar etiqueta de devolución.
        • allow_partial_refund: ofrecer devolución parcial del dinero al comprador. Debe ser realizado por el front de Mercado Libre.
        • send_tracking_number: enviar el número de envío (tracking number).
        • return_review_fail: realizar una revisión fallida de una devolución.
        • return_review_ok: realizar una revisión ok de una devolución.
        • mandatory: tipo de acción
          • respondent: persona a quién le reclaman.
          • warehouse_dispatcher: persona encargada de revisar el producto en las devoluciones al warehouse.
• resolution: Lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles
  • reason: Motivo de resolución/cierre
    • already_shipped: Producto en camino
    • buyer_claim_opened: Cierre de devolución por apertura de otro reclamo
    • buyer_dispute_opened: Cierre de devolución por apertura de otro reclamo en disputa (con mediación de Mercado Libre)
    • charged_back: Cierre por contracargo
    • coverage_decision: Disputa cerrada con cobertura por ML
    • found_missing_parts: Comprador encontró las partes faltantes
    • item_returned: Producto devuelto
    • no_bg: Cierre sin cobertura por parte de ML
    • not_delivered: Producto no entregado
    • opened_claim_by_mistake: Comprador creó el reclamo por error
    • other: Otro caso
    • partial_refunded: Reembolso parcial del pago al comprador
    • payment_refunded: Pago devuelto al comprador
    • preferred_to_keep_product: Comprador prefirió quedarse con el producto
    • product_delivered: Fallo de un representante de MercadoLibre
    • reimbursed: Reembolso
    • rep_resolution: Fallo de un representante de MercadoLibre
    • respondent_timeout: Vendedor no contesta
    • return_cancelled: Devolución cancelada por el comprador
    • return_expired: Devolución vencida sin cambio o sin envío
    • seller_asked_to_close_claim: Vendedor pidió al comprador que cierre el reclamo
    • seller_did_not_help: Comprador pudo solucionar el inconveniente sin ayuda del vendedor
    • seller_explained_functions: Vendedor explicó cómo funcionaba el ítem
    • seller_sent_product: Vendedor envió el producto
    • timeout: Cierre por timeout de acción al comprador
    • warehouse_decision: Cierre por revisión de producto en Warehouse
    • warehouse_timeout: Cierre por demora en revisión de producto en Warehouse
    • worked_out_with_seller: Comprador lo solucionó con el vendedor por fuera de ML
    • low_cost: Cierre porque el costo del envío es mayor que el del producto
    • item_changed: Cierre porque el cambio se hizo de forma interna
    • change_expired: No se realizó el cambio y se cumplió el tiempo permitido
    • change_cancelled_buyer: Cierre de un cambio por parte del buyer
    • change_cancelled_seller: Cierre proactivo de un cambio por parte del seller
    • change_cancelled_meli: Cierre de un cambio por parte de Meli
    • shipment_not_stopped: Cierre porque el envío no se logró detener
    • cancel_installation: Cancelación de servicio de instalación
  • created: Fecha de la resolución/cierre del reclamo
  • benefited: Beneficiarios/a de la resolución
    • respondent
  • closed_by: Actor que cerró el reclamo
    • mediator
    • buyer
    • respondent
    • false
  • applied_coverage: Se paga al comprador
  • site_id: ID del site donde se desarrolló el reclamo
  • date_created: Fecha de creación/apertura del reclamo
  • last_updated: Fecha de la última actualización sobre el reclamo

Revisión fallida de una devolución

Cuando una devolución llega al vendedor, éste tiene la posibilidad de hacer una revisión de la misma indicando si el producto llegó en las condiciones esperadas o si hay algún problema con el mismo.

Para saber si el vendedor ya tiene habilitada la opción de hacer una revisión fallida, podemos consultar el recurso /claims/$CLAIM_ID. Dentro del array de “players”, buscamos el player “type”: “seller” y validamos que en sus "available_actions" exista "action": "return_review_fail"

Para realizar una revisión fallida de una devolución, indicando que el producto llegó con algún problema, se utilizan tres recursos que se describen a continuación:

Obtener razones para crear una revisión fallida de una devolución

Para crear una revisión fallida tendrás que conocer la razón por la cual el vendedor identifica que el producto no llegó en las condiciones esperadas.

La lista de las posibles razones que el vendedor puede seleccionar se obtienen en el recurso returns/reasons/return-fail.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/returns/reasons/return-fail

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/returns/reasons/return-fail

Respuesta:

[
   {
       "id": "SRF2",
       "name": "product_damaged",
       "detail": "El producto llegó dañado",
       "position": 1
   },
   {
       "id": "SRF3",
       "name": "return_incomplete",
       "detail": "La devolución está incompleta",
       "position": 2
   },
   {
       "id": "SRF4",
       "name": "returned_product_different",
       "detail": "Devolvieron un producto distinto al que envié",
       "position": 3
   },
   {
       "id": "SRF5",
       "name": "product_not_in_package",
       "detail": "El producto no está en el paquete",
       "position": 4
   },
   {
       "id": "SRF6",
       "name": "another_failure_with_product",
       "detail": "Reportar otra falla en el producto",
       "position": 5
   },
   {
       "id": "SRF7",
       "name": "return_has_not_arrived",
       "detail": "Aún no me llegó",
       "position": 6
   }
]

Campos de la respuesta

La respuesta exitosa de un GET al recurso /returns/reasons/return-fail devolverá un status code 200 y los siguientes campos:

• id: Identificador de la reason. Este valor es el que se deberá enviar al crear una revisión fallida.
• name: Código de la reason
• detail: Motivo de la devolución fallida para darle contexto al vendedor a la hora de elegir la reason
  • return_product
• position: Posición recomendada de la reason a la hora de mostrarle todas las reasons al vendedor

Obtener nombre de las evidencias a adjuntar en la revisión fallida de una devolución

Al crear una revisión fallida, también se habilita el envío de evidencias, con el fin de colaborar con más información al caso. Por lo tanto podrás utilizar el recurso de /claims/$CLAIM_ID/returns/attachments para la carga de archivos.

Como resultado, se obtendrá el nombre de archivo que se enviará como evidencia en la revisión..

Se debe utilizar este recurso para cada evidencia que se quiera adjuntar a una revisión fallida.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'

Respuesta:

{
    "user_id": 1277895049,
    "file_name": "1277895049_9d6b8d38-a2c2-4d17-a68b-f0845bc35fd1.png"
}

Campos de la respuesta

La respuesta exitosa de un GET al recurso /claims/$CLAIM_ID/returns/attachments devolverá un status code 200 y los siguientes campos:

• user_id: identificador del usuario
• file_name: nombre del archivo que se podrá utilizar a la hora de crear una revisión fallida

Crear revisión fallida

Para crear la revisión fallida de una devolución, indicando que el producto llegó con algún problema, se habilitó el recurso /claims/$CLAIM_ID/actions/return-review-fai

Parámetros

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "reason" : $REASON_ID,	
    "message": $MESSAGE,
    "attachments": [$ATTACHMENTS]
}
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-fail

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "reason" : "SRF2",	
    "message": "Me enviaron el sweater con una mancha",
    "attachments": ["1277895049_4d421a16-31ba-444d-hbbf-68b373ed2g32.png"]
}
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-fail

Respuesta:

{
   "id": 5255026166,
   "resource_id": 2000007760636316,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9949",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": true,
                   "due_date": "2024-06-03T22:43:00.000-04:00"
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46122402,
           "available_actions": []
       }
   ],
   "resolution": {
       "reason": "item_returned",
       "date_created": "",
       "benefited": [
           "complainant"
       ],
       "closed_by": "mediator",
       "applied_coverage": true
   },
   "site_id": "MLA",
   "date_created": "2024-05-29T23:48:32.000-04:00",
   "last_updated": "2024-05-29T23:51:26.370-04:00"
}

Campos de la respuesta

La respuesta exitosa de un POST al recurso /claims/$CLAIM_ID/actions/return-review-fail devolverá un status code 201 y los siguientes campos:

• id: ID del reclamo
• resource: ID del recurso sobre el que se crea el reclamo. Depende del “resource”
• status: Estado del reclamo
  • opened
  • closed
• type: Tipo de reclamo
  • mediations: reclamo entre comprador y vendedor.
  • return: Devolución de producto.
  • fulfillment: Reclamo entre comprador y Mercado Libre con origen de compra con envío full.
  • ml_case: Cancelación de la compra por parte del comprador debido a envío demorado.
  • cancel_sale: Cancelación de compra por parte del vendedor. Siempre en status: "closed" y stage: "none". El rol complainant siempre va a ser del tipo seller, collector o sender dependiendo el recurso del reclamo.
  • cancel_purchase: cancelación de compra por parte del comprador
  • change: Cambio de Producto.
  • service: Cancelación de un servicio ordenes bundle.
• stage: Etapa del reclamo
  • claim: etapa de reclamo donde intervienen el comprador y el vendedor
  • dispute: etapa de mediación donde interviene un representante de Mercado Libre
  • recontact: etapa en la que alguna de las partes se contacta luego de cerrado el reclamo/disputa
  • none: no aplica
  • stale: Etapa de reclamo donde intervienen el comprador y Mercado Libre para reclamos de tipo ml_case.
• parent_id: ID de otro reclamo del que depende
• resource: Identificador del recurso sobre el que se crea el reclamo. Interfiere en los actores del reclamo
  • payment: Pago
  • order: Orden
  • shipment: Envío
  • purchase: Compra
• reason_id: Razón/motivo por el cual fue creado el reclamo. Interfiere directamente con las soluciones que se pueden proponer
  • PNR: Producto No Recibido
  • PDD: Producto Diferente o Defectuoso
  • CS: Compra Cancelada
• fulfilled: Indica si el reclamo se inicia por un producto entregado o no
• quantity_type: informa si el claim es una reclamo parcial o no
  • partial: indica que es un reclamo parcial
  • total: indica que es un reclamo total
• players: Lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles
  • role: rol dentro del reclamo
    • complainant: persona que reclama.
    • respondent: persona a quién le reclaman.
    • mediator: persona que interviene para ayudar a solucionar el problema.
    • warehouse_dispatcher: persona encargada de revisar el producto en las devoluciones al warehouse.
  • type: rol que ocupa la persona sobre la operación que se está reclamando
    • payment: comprador - collector.
    • order: comprador - vendedor.
    • shipment: receptor - remitente.
    • purchase: comprador - Mercado Libre
  • user_id: ID del usuario en ML que cumple el rol
  • available_actions: Lista de acciones que pueden ejecutar cada una de las partes intervinientes
    • players: lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles.
      • action: Nombre de la acción
        • send_message_to_complainant: enviar mensaje para el comprador (con o sin anexos).
        • send_message_to_mediator: enviar mensaje para el mediador (con o sin anexos).
        • recontact (no disponible aún): reabrir un reclamo ya cerrado, por medio de una interacción, como un mensaje.
        • refund: devolver el dinero del comprador. Debe ser realizado por el front de Mercado Libre o Mercado Pago.
        • open_dispute: iniciar una mediación.
        • send_potential_shipping: enviar una promesa de post, una fecha.
        • add_shipping_evidence: publicar una evidencia de que el producto fue enviado.
        • send_attachments: enviar mensaje con adjuntos.
        • allow_return_label: generar etiqueta de devolución.
        • allow_partial_refund: ofrecer devolución parcial del dinero al comprador. Debe ser realizado por el front de Mercado Libre.
        • send_tracking_number: enviar el número de envío (tracking number).
        • mandatory: tipo de acción
          • respondent: persona a quién le reclaman.
          • warehouse_dispatcher: persona encargada de revisar el producto en las devoluciones al warehouse.
• resolution: Lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles
  • reason: Motivo de resolución/cierre
    • already_shipped: Producto en camino
    • buyer_claim_opened: Cierre de devolución por apertura de otro reclamo
    • buyer_dispute_opened: Cierre de devolución por apertura de otro reclamo en disputa (con mediación de Mercado Libre)
    • charged_back: Cierre por contracargo
    • coverage_decision: Disputa cerrada con cobertura por ML
    • found_missing_parts: Comprador encontró las partes faltantes
    • item_returned: Producto devuelto
    • no_bg: Cierre sin cobertura por parte de ML
    • not_delivered: Producto no entregado
    • opened_claim_by_mistake: Comprador creó el reclamo por error
    • other: Otro caso
    • partial_refunded: Reembolso parcial del pago al comprador
    • payment_refunded: Pago devuelto al comprador
    • preferred_to_keep_product: Comprador prefirió quedarse con el producto
    • product_delivered: Fallo de un representante de MercadoLibre
    • reimbursed: Reembolso
    • rep_resolution: Fallo de un representante de MercadoLibre
    • respondent_timeout: Vendedor no contesta
    • return_cancelled: Devolución cancelada por el comprador
    • return_expired: Devolución vencida sin cambio o sin envío
    • seller_asked_to_close_claim: Vendedor pidió al comprador que cierre el reclamo
    • seller_did_not_help: Comprador pudo solucionar el inconveniente sin ayuda del vendedor
    • seller_explained_functions: Vendedor explicó cómo funcionaba el ítem
    • seller_sent_product: Vendedor envió el producto
    • timeout: Cierre por timeout de acción al comprador
    • warehouse_decision: Cierre por revisión de producto en Warehouse
    • warehouse_timeout: Cierre por demora en revisión de producto en Warehouse
    • worked_out_with_seller: Comprador lo solucionó con el vendedor por fuera de ML
    • low_cost: Cierre porque el costo del envío es mayor que el del producto
    • item_changed: Cierre porque el cambio se hizo de forma interna
    • change_expired: No se realizó el cambio y se cumplió el tiempo permitido
    • change_cancelled_buyer: Cierre de un cambio por parte del buyer
    • change_cancelled_seller: Cierre proactivo de un cambio por parte del seller
    • change_cancelled_meli: Cierre de un cambio por parte de Meli
    • shipment_not_stopped: Cierre porque el envío no se logró detener
    • cancel_installation: Cancelación de servicio de instalación
  • created: Fecha de la resolución/cierre del reclamo
  • benefited: Beneficiarios/a de la resolución
    • respondent
  • closed_by: Actor que cerró el reclamo
    • mediator
    • buyer
    • respondent
    • false
  • applied_coverage: Se paga al comprador
  • site_id: ID del site donde se desarrolló el reclamo
  • date_created: Fecha de creación/apertura del reclamo
  • last_updated: Fecha de la última actualización sobre el reclamo

Errores

A continuación, se detallan los posibles mensajes de error que el recurso puede generar:

Si el claim no pertenece al vendedor:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid roleId :12343234 in claim :123454323",
   "cause": null
}

Si el claim no existe:

{
   "code": 404,
   "error": "not_found_error",
   "message": "claim id: 5255026166 not found",
   "cause": null
}

Si no se envía el token:

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

Si el token expiró o es inválido:

{
   "message": "invalid_token",
   "error": "not_found",
   "status": 401,
   "cause": []
}

Si el token es incorrecto:

{
   "message": "{\"message\":\"Malformed access_token: toke n\",\"error\":\"bad_request\",\"status\":400,\"cause\":[]}",
   "error": "",
   "status": 400,
   "cause": []
}

Si el vendedor no tiene habilitada la revisión de una devolución.

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Not valid action return_review_ok for player role respondent",
   "cause": null
}

Si el formato del archivo que se quiere adjuntar no es válido:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid mime_type",
   "cause": null
}

Si el nombre del archivo no es válido:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid file_name: ",
   "cause": null
}

Si no se envia el campo “file”:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Current request is not a multipart request",
   "cause": null
}

Si no se le pasa alguno de los campos obligatorios:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Required request body is missing or incorrect, please see the documentation.",
   "cause": null
}

Ir: Gestionar reclamos