Developers

Documentación Mercado Libre

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

Última actualización 03/09/2024

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

Nota:

El recurso /post-purchase/v2/claims/$CLAIM_ID/returns es una herramienta esencial que te permite acceder a los detalles específicos de cada devolución, identificada por su $CLAIM_ID, incluyendo sus tipos, subtipos y estados.

En Mercado Libre, gestionamos varios tipos de devoluciones para asegurar una experiencia de compra transparente y justa:

claim: Devolución iniciada a través de un reclamo del comprador.
dispute: Devolución resultante de una disputa entre el comprador y el vendedor.
automatic: Devolución iniciada por el comprador, procesada automáticamente por el sistema.

Estos diferentes tipos de devoluciones nos permiten abordar cada situación de manera específica, garantizando que tanto compradores como vendedores reciban el soporte adecuado en cada etapa del proceso post-compra.

Gestionar una devolución

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

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

Nota:

Recuerda que el recurso /shipments/$SHIPMENT_ID/costs devuelve los costos del envío que deberá afrontar el usuario.

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

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 GET -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 GET -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

params	Type	Detalle value
claim_id	Integer	Identificador único del reclamo al cual se quiere indicar la revisión fallida de su devolución (obligatorio)
reson	String	Identificador único de la razón por la cual el vendedor indica que el producto no llegó como se esperaba (obligatorio). Los posibles valores de este campo se obtienen del recurso returns/reasons
message	String	Mensaje ingresado por el vendedor indicando el motivo de la revisión fallida (obligatorio)
attachments	Array[String]	Nombres de las evidencias a adjuntar en la revisión. Los valores de este campo se obtienen del recurso returns/attachments (obligatorio para las reason_id SRF2 y SRF4)

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