Developers

Documentación Mercado Libre

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

Última actualización 23/04/2024

Trabajar con reclamos

Importante:

A partir del 20 de mayo 2024, todos los recursos de reclamos https://api.mercadolibre.com/v1/claims/ serán deprecados y unicamente podrás acceder a la información llamando https://api.mercadolibre.com/post-purchase/v1/claims/.

Te invitamos a modificar tu integración para continuar trabajando con los reclamos de manera normal.

El recurso /claims te permitirá obtener el detalle de un reclamo y poder realizar acciones vía API para resolverlos de manera correcta incorporando esta funcionalidad en tu integración.

Notificaciones de reclamos

En Mis aplicaciones, edita tu aplicación y activa el tópico Claims en nuestro feed para informarte siempre que un reclamo haya sido iniciado o recibir alguna interacción. Conoce más información sobre las notificaciones de reclamos.

Buscar reclamos

La búsqueda de reclamos te ayudará a conocer cuáles pertenecen al usuario de un token válido.

Llamada:

>curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/search?status=opened

Respuesta:

{
    "paging": {
        "total": 4,
        "offset": 0,
        "limit": 30
    },
    "data": [
        {
            "id": 5255026166,
            "resource_id": 2000007760636316,
            "status": "opened",
            "type": "mediations",
            "stage": "dispute",
            "parent_id": null,
            "resource": "order",
            "reason_id": "PDD9549",
            "fulfilled": true,
            "quantity_type": "total",
            "players": [
                {
                    "role": "complainant",
                    "type": "buyer",
                    "user_id": 1277895049
                },
                {
                    "role": "respondent",
                    "type": "seller",
                    "user_id": 1582937623,
                    "available_actions": [
                        {
                            "action": "send_message_to_mediator",
                            "mandatory": false,
                            "due_date": null
                        }
                    ]
                }
            ],
            "resolution": null,
            "site_id": "MLB",
            "date_created": "2024-03-06T14:27:27.000-04:00",
            "last_updated": "2024-03-11T22:45:55.000-04:00"
        },
        {
            "id": 5248960694,
            "resource_id": 2000007547872610,
            "status": "opened",
            "type": "mediations",
            "stage": "dispute",
            "parent_id": null,
            "resource": "order",
            "reason_id": "PDD9554",
            "fulfilled": true,
            "quantity_type": "total",
            "players": [
                {
                    "role": "complainant",
                    "type": "buyer",
                    "user_id": 1582937623
                },
                {
                    "role": "respondent",
                    "type": "seller",
                    "user_id": 1278387909
                }
            ],
            "resolution": null,
            "site_id": "MLB",
            "date_created": "2024-02-06T14:46:29.000-04:00",
            "last_updated": "2024-02-06T15:05:45.000-04:00"
        },
        {
            "id": 5247166932,
            "resource_id": 2000007094735454,
            "status": "opened",
            "type": "mediations",
            "stage": "dispute",
            "parent_id": null,
            "resource": "order",
            "reason_id": "PDD9549",
            "fulfilled": true,
            "quantity_type": "total",
            "players": [
                {
                    "role": "complainant",
                    "type": "buyer",
                    "user_id": 1582937623
                },
                {
                    "role": "respondent",
                    "type": "seller",
                    "user_id": 1277895049
                }
            ],
            "resolution": null,
            "site_id": "MLB",
            "date_created": "2024-01-29T10:25:27.000-04:00",
            "last_updated": "2024-02-02T00:00:58.000-04:00"
        },
        {
            "id": 5259768612,
            "resource_id": 2000007920529350,
            "status": "opened",
            "type": "mediations",
            "stage": "dispute",
            "parent_id": null,
            "resource": "order",
            "reason_id": "PDD9549",
            "fulfilled": true,
            "quantity_type": "total",
            "players": [
                {
                    "role": "complainant",
                    "type": "buyer",
                    "user_id": 1277895049
                },
                {
                    "role": "respondent",
                    "type": "seller",
                    "user_id": 1582937623,
                    "available_actions": [
                        {
                            "action": "send_message_to_mediator",
                            "mandatory": false,
                            "due_date": null
                        }
                    ]
                }
            ],
            "resolution": null,
            "site_id": "MLB",
            "date_created": "2024-03-28T11:00:08.000-04:00",
            "last_updated": "2024-04-04T13:44:04.000-04:00"
        }
    ]
}

Nota:

El campo “quantity_type” inicialmente sólo mostrará el valor “total” y en el futuro se visualizará el valor “partial”. Indica si una devolución corresponde a todos los productos de la orden o solo algunos.

Parámetros

La respuesta de un GET al recurso /claims da como resultado los siguientes parámetros:

id: ID del reclamo.
type: Tipo de reclamo. puede tomar alguno de los siguientes valores:

mediations: reclamo entre comprador y vendedor.
cancel_purchase: cancelacion decompra por parte del comprador.
return: devolucion del producto. En este caso, no hay mensajes. Para trabar devoluciones, siga la documentacion de Trabajar con devoluciones.
cancel_sale: cancelación de compra por parte del vendedor
- El status siempre va a ser closed.
- El stage siempre va a ser none.
- El rol complainant siempre va ser el type seller, collector o sender dependiendo del resource.
change: cambios de producto. Indica que se va a realizar un cambio del producto.

stage: Etapa del reclamo. Puede tomar alguno de los siguientes valores:

claim: etapa del reclamo donde intervienen el comprador y el vendedor.
dispute: eEtapa 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.

status: estado del reclamo. Puede tomar dos valores: opened y closed.
parent_id: ID de otro reclamo del que depende.
resource: identificador del recurso sobre el que se crea el reclamo. Puede serr:

payment
order
shipment
purchase

resource_id: ID del recurso sobre el que se crea el reclamo y depende del parámetro anterior.
players: lista de los actores que participan del reclamo con sus respectivas acciones y tiempos disponibles.

role: rol dentro del reclamo. Puede ser:

complainant: persona que reclama.
respondent: persona a quién le reclaman.
mediator: persona que interviene para ayudar a solucionar el problema.

type: rol que ocupa la persona sobre la operacion que se esta reclamando.

Puede variar de acuerdo al resource.
- Payment: comprador o collector.
- Order: comprador o vendedor.
- Shipment: receptor o remitente.
user_id: ID del type del parámetro anterior.
available_actions: lista de acciones que pueden eecutar cada una de las partes intervinientes:
action: acciones posibles de realizarse. Para el vendedor será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 comprado. Debe ser realizado por el front de Mercado Libre o Mercado Pago.
open_dispute: iniciar uma 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: generar etiqueta de devolución.
allow_return_label: generar etiqueta de devolución.
send_tracking_number: enviar el número de rastreo de envío (tracking number).

due_date: tiempo límite para realizar la acción.
mandatory: este campo en true indica que la acción es obligatoria y debe ser realizada dentro del tiempo informado.

resolution: forma de resolución del reclamo.
site_id: ID del site donde se desarrolla el reclamo.
date_created: fecha de creación del reclamo.
last_updated: fecha de la última actualización del reclamo.

Filtrar reclamos

Los parámetros disponibles para los filtros son:

id
type
stage
status
resource: order, shipment o purchase.
resource_id: es el id del recurso en que se crea el reclamo y debe ser utilizado en conjunto con el parámetro anterior.
reason_id
site_id
player_role: complainant o respondent.
players_user_id: está relacionado al parámetro anterior.
parent_id
date_created
order_id
last_updated
offset
limit

Por ejemplo, si deseas filtrar por stage y status:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/search?status=opened&stage=dispute

Por ejemplo también, si deseas filtrar por fecha:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/search?stage=dispute&status=opened&range=date_created:after:2020-09-26T14:52:14.000-04:00,before:2020-09-27T14:52:14.000-04:00&sort:desc

Ordenar reclamos

Añade el parámetro sort con el respectivo campo que desea y si la orden debe ser ascendente o decreciente (&sort=:asc|desc) Por ejemplo, para ordenar por fecha de actualización:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/search?status=opened&stage=dispute&sort=last_updated:asc

Paso a paso para utilizar los recursos

Ver el detalle de un mensaje

Llamada:

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

Ejemplo:

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

Respuesta:

{
    "id": 5259768612,
    "resource_id": 2000007920529350,
    "status": "opened",
    "type": "mediations",
    "stage": "dispute",
    "parent_id": null,
    "resource": "order",
    "reason_id": "PDD9549",
    "fulfilled": true,
    "quantity_type": "total",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 1277895049
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 1582937623,
            "available_actions": [
                {
                    "action": "send_message_to_mediator",
                    "mandatory": false,
                    "due_date": null
                }
            ]
        },
        {
            "role": "mediator",
            "type": "internal",
            "user_id": 46622406
        }
    ],
    "resolution": null,
    "site_id": "MLB",
    "date_created": "2024-03-28T11:00:08.000-04:00",
    "last_updated": "2024-04-04T13:44:04.000-04:00"
}

Obtener todos los mensajes de un reclamo

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/5262798454/messages

Respuesta:

[
    {
        "sender_role": "complainant",
        "receiver_role": "respondent",
        "message": "teste",
        "translated_message": null,
        "date_created": "2024-04-12T09:40:15",
        "last_updated": "2024-04-12T09:40:15",
        "message_date": "2024-04-12T09:40:15",
        "date_read": "2024-04-12T20:11:28",
        "attachments": [],
        "status": "available",
        "stage": "claim",
        "message_moderation": {
            "status": "clean",
            "reason": "",
            "source": "online",
            "date_moderated": "2024-04-12T13:40:15"
        },
        "repeated": false
    }
]

Nota:

Solo se podrán ver los mensajes moderados propios, con el status correspondiente en “moderated”. Los mensajes provenientes de la contraparte que fueron moderados serán filtrados.

Descripción de parâmetros GET

Campos de respuesta

La resputa de un GET de messages del recurso /claims retorna una lista con los siguiente parámetros:

sender_role: player que envió el mensaje.
receiver_role: player hacia quién va dirigido el mensaje.
attachments: listado de adjuntos del mensaje.
message: texto del mensaje.
date_created: fecha en la que se creó el mensaje.
date_read: este valor será null hasta que exista una nueva versión del recurso.
stage: etapa en la que se envió el mensaje.
status: available | moderated | rejected | pending_translation.
moderation.status: resultado del proceso de moderación. Posibles valores:
clean: el mensaje está limpio.
rejected: el mensaje fue moderado.
pending: la moderación está en proceso.
non_moderated: no aplicó la moderación. Por ejemplo: casos antiguos.
moderation.date_moderated: fecha en la cual se realizó la moderación.
moderation.source: modalidad de la moderación. Posibles valores:
online: se modera durante la instancia de creación del mensaje. Única modalidad actualmente.
moderation.reason: razón por la cual se moderó el mensaje. Posibles valores:
OUT_OF_PLACE_LANGUAGE: lenguaje inapropiado.

Responder mensajes y adjuntar archivos

Post de Attachment

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/attachments -F file=$FILE_PATH

Notas:

- El POST debe realizarse como form.data con file = ubicación del archivo.
- Podrán intercambiarse fotos, manuales de instrucciones, facturas y demás archivos adjuntos en JPG, PNG y PDF de hasta un tamaño máximo de 5 MB.
- El nombre del archivo no puede tener más de 125 caracteres y estar compuesto solo por los siguientes caracteres: Letras, números, punto, guion medio, guion bajo ([a-zA-Z0-9._\s-])

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/950463475/attachments 
-H 'content-type: multipart/form-data;  
-F 'file=@/Users/user/Desktop/file.jpg'

Respuesta:

{
    "user_id": 271959653,
    "filename": "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg",
}

Post de Message con el attach anterior

Llamada:

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

Nota:

En la lista de adjuntos se mostrarán todos los devueltos en el POST anterior asociados al mensaje separados por coma.
Además, en el body se puede enviar un mensaje con un adjunto, o sin adjunto.

Ejemplo con anexo:

curl -X POST 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/send-message' 
-H 'Authorization: Bearer $ACCESS_TOKEN' 
-H 'Content-Type: application/json' 
-d '{
 "receiver_role": "complainant",
 "message": "Este es un mensaje de test del respondent al complainant",
 "attachment": ["1330467461_7ed98ebb-03f7-4818-943b-8b4d12a3aaa7.jpg" ]
}'

Respuesta:

{"id":1817133310}

Ejemplo sin anexo:

curl -X POST 'https://api.mercadolibre.com/post-purchase/v1/claims/5262798454/actions/send-message' 
-H 'Authorization: Bearer $ACCESS_TOKEN' 
-H 'Content-Type: application/json' 
-d '{
 "receiver_role": "complainant",
 "message": "Este es un mensaje de test del respondent al complainant",
 "attachment": []
}'

Respuesta:

{"id":1817133310}

Respuesta:

Caso nenhum erro seja apresentado, será devolvido um status created 201.

Descargar el archivo

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/attachments/$ATTACH_ID/download

Ejemplo:

curl -X GET 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/attachments/1325224382_181a6330-d9f6-410c-a2c9-d03f8323bd16.jpg/download' 
-H 'Authorization: Bearer $ACCESS_TOKEN'

Obtener información del archivo

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

Ejemplo:

curl -X GET 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/attachments/exemple.jpg' 
-H 'Authorization: Bearer $ACCESS_TOKEN'

Respuesta:

{
   "filename": "e3abaa4b-c1b9-41ee-80ed-19f22872777c.jpeg",
   "original_filename": "_b7b5df12-7153-4bf5-a0a0-caa582592c3b.jpeg",
   "size": 128759,
   "date_created": "2024-04-12T08:16:16",
   "type": "image/jpeg"
}

Solicitar mediación

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/open-dispute

Respuesta:

{
   "id": 5262782707,
   "resource_id": 2000008026430162,
   "status": "opened",
   "type": "mediations",
   "stage": "dispute",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9549",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "send_message_to_mediator",
                   "mandatory": false,
                   "due_date": null
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46622406
       }
   ],
   "resolution": null,
   "site_id": "MLB",
   "date_created": "2024-04-12T08:26:23.000-04:00",
   "last_updated": "2024-04-12T08:27:43.000-04:00"
}

Una vez iniciada la mediación, no pueden enviarse mensajes al comprador. Toda comunicación será realizada por Mercado Libre. Para esto, es necesario cambiar el receiver_role para mediator.

Llamada:

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

Ejemplo:

curl -X POST 'https://api.mercadolibre.com/post-purchase/v1/claims/5262798454/actions/send-message' 
-H 'Authorization: Bearer $ACCESS_TOKEN' 
-H 'Content-Type: application/json' 
-d '{
 "receiver_role": "mediator",
 "message": "Este es un mensaje de test del respondent al complainant",
 "attachment": []
}'

Respuesta:

Caso nenhum erro seja apresentado, será devolvido um status created 201.

Ver resoluciones esperadas

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/950463475/expected-resolutions

Respuesta:

[
   {
       "player_role": "complainant",
       "user_id": 1277895049,
       "expected_resolution": "return_product",
       "details": [],
       "date_created": "2024-03-28T11:00:08",
       "last_updated": "2024-03-28T11:00:08",
       "status": "pending"
   }
]

Descripción de parámetros

player_role: role del player del reclamo.
user_id: ID del player del reclamo.
expected_resolution: resolución del reclamo cargada por el player indicado en el parámetro anterior. Los valores posibles son:
- refund: el player espera que se devuelva el dinero.
- product: el player espera que le llegue el producto.
- change_product: el player espera cambiar el producto.
- return_product: el player espera que se devuelva el producto con la posterior devoluvión del dinero.
details: este campo da informacion adicional sobre expected-resolution
date_created: fecha de creación de la resolución esperada.
date_created: fecha de última actualización de la resolución esperada.
status: estado de la resolución esperada. Puede tomar los siguientes valores:
- pending: el player cargó la resolución esperada pero no aún no fue aceptada por la contraparte.
- accepted: la resolución cargada por el player fue aceptada por su contraparte o en su defecto por el mediador de Mercado Libre.
- rejected: la resolución cargada por el player fue rechazada por su contraparte y en su defecto cargó una nueva opción de resolución.

Notas:

Independientemente de las resoluciones cargadas por los participantes, en determinados casos la resolución final es la define un representante de Mercado Libre en caso que las partes no se pongan de acuerdo.

Opciones para resolver reclamos

Importante:

A partir del 20 de mayo de 2024 los recursos para resolver reclamos dejaran de funcionar.

Liberamos tres nuevo recursos que permiten resolver reclamos según la acción que quiera realizar el vendedor

- Reembolso Parcial - /expected-resolutions/partial-refund

- Reembolso Total - /expected-resolutions/refund

- Devolución de producto - /expected-resolutions/allow-return

Reembolso parcial

El flujo de reembolso parcial está vinculado al proceso de reclamo del comprador, donde dependiendo de las acciones disponibles para el vendedor, es posible ofrecer una solución al reclamo devolviendo parte del dinero pagado por la compra.

Por eso es necesario que el array available_actions, una de las acciones sea allow_partial_refund, como se muestra en el siguiente ejemplo:

 {
    "id": 123,
    "type": "mediations",
    "stage": "claim",
    "status": "opened",
    "parent_id": null,
    "client_id": null,
    "resource_id": 123,
    "resource": "order",
    "reason_id": "PDD9551",
    "fulfilled": true,
    "players":
    [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 123,
            "available_actions":
            []
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 123,
            "available_actions":
            [
                {
                    "action": "send_message_to_complainant",
                    "due_date": "2023-01-27T22:43:59.000-04:00",
                    "mandatory": true
                },
                {
                    "action": "refund",
                    "due_date": null,
                    "mandatory": false
                },
                {
                    "action": "allow_partial_refund",
                    "due_date": null,
                    "mandatory": false
                }
            ]
        }
    ],
    "resolution": null,
    "labels": null,
    "site_id": "MLB",
    "date_created": "2023-01-23T09:59:05.000-04:00",
    "last_updated": "2023-01-23T11:18:01.000-04:00"
}

Ofrecer reembolso parcial de dinero

Para ofrecer un reembolso parcial, el reclamo debe ser PDD con expected_resolution: return_product y status pending.

Calcular valor de la devolución parcial

Verifica los percentuales de devoluciones disponibles y cuanto es el valor de devolución utilizado en el siguiente recurso.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/partial-refund/available-offers

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json'
https://api.mercadolibre.com/post-purchase/v1/claims/5224172034/partial-refund/available-offers

Respuesta:

{
     "currency_id": "USD"
    "available_offers":
    [
        {
            "amount": 90.0,
            "percentage": 90
        },
        {
            "amount": 80.0,
            "percentage": 80
        },
        {
            "amount": 70.0,
            "percentage": 70
        },
        {
            "amount": 60.0,
            "percentage": 60
        },
        {
            "amount": 50.0,
            "percentage": 50
        },
        {
            "amount": 40.0,
            "percentage": 40
        },
        {
            "amount": 30.0,
            "percentage": 30
        },
        {
            "amount": 20.0,
            "percentage": 20
        }
    ]
}

Campos de la respuesta

currency_id: moneda.
amount: valor de la devolución.
percentage: percentual de devolución representando el valor (amount).

Elija el porcentaje para la devolución: si no envía un porcentaje de reembolso, se asignará por defecto default_percentege = 50.

Nota:

Cuando ofrezcas reembolso parcial, el campo expected_resolution que estaba del lado del vendedor player_role: complainant será rechazado y se creará expected_resolution=partial_refund, donde el estado será pending y la respuesta estará del lado del comprador (player_role: respondent).

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/expected-resolutions/partial-refund

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/5262579966/expected-resolutions/partial-refund 
- d {"percentage": 50}

Respuesta:

[
    {
        "player_role": "complainant",
        "user_id": 1680903379,
        "details": [],
        "expected_resolution": "return_product",
        "date_created": "2024-04-11T11:22:06",
        "last_updated": "2024-04-11T11:22:06",
        "status": "rejected"
    },
    {
        "player_role": "respondent",
        "user_id": 1277895049,
        "details": [
            {
                "key": "percentage",
                "value": "50.0"
            },
            {
                "key": "seller_amount",
                "value": "2500.0"
            },
            {
                "key": "seller_currency",
                "value": "R$"
            }
        ],
        "expected_resolution": "partial_refund",
        "date_created": "2024-04-16T13:05:04",
        "last_updated": "2024-04-16T13:05:04",
        "status": "pending"
    }

]

Si envía un valor distinto de los permitidos, recibirá esta respuesta:

{
    "message": "Percentage not found 35.0",
    "error": "error checking configuration percentage",
    "status": 400,
    "cause": []
}

Si el vendedor no tiene habilitado el reembolso parcial, así será:

{
    "message": "Action allow_partial_refund not available for player",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Si el reembolso parcial es aceptado por el comprador, el reclamo se cerrará y se devolverá al comprador el dinero correspondiente al porcentaje ofrecido.
Si el reembolso parcial no es aceptado por el comprador, la resolución de reembolso parcial esperado tendrá estado rechazado.

Ofrecer devolución total del dinero

En los casos que existe una available_actions como refund, se puede utilizar el siguiente recursos para generar la devolución total del dinero al comprador a través del reclamo.

Llamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/expected-resolutions/refund

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json'
https://api.mercadolibre.com/post-purchase/v1/claims/5262579966/expected-resolutions/refund

Respuesta:

[
    {
        "player_role": "complainant",
        "user_id": 1680903379,
        "expected_resolution": "return_product",
        "status": "rejected",
        "detail": [],
        "date_created": "2024-04-11T11:22:06",
        "last_update": "2024-04-11T11:22:06"
    },
    {
        "player_role": "respondent",
        "user_id": 1277895049,
        "expected_resolution": "partial_refund",
        "status": "rejected",
        "detail": [
            {
                "key": "percentage",
                "value": "50.0"
            },
            {
                "key": "seller_amount",
                "value": "2500.0"
            },
            {
                "key": "seller_currency",
                "value": "R$"
            }
        ],
        "date_created": "2024-04-16T13:05:04",
        "last_update": "2024-04-16T13:05:04"
    },
    {
        "player_role": "respondent",
        "user_id": 1277895049,
        "expected_resolution": "refund",
        "status": "accepted",
        "detail": [],
        "date_created": "2024-04-16T13:06:41",
        "last_update": "2024-04-16T13:06:41"
    }
]

Nota:

En esta respuesta podés ver un ejemplo que muestra el flujo que inicia con una devolución de producto, el cual es rechazado; se ofrece un reembolso parcial, que también es rechazado; Y finalmente se acepta el reembolso completo.

Devolución del producto

Importante:

El recurso /expected-resolutions/allow-return se agrega para realizar la devolución, lo que reemplaza la funcionalidad "aceptar resolución" o "cargar una nueva resolución", ya que ambos flujos resultaban en una devolución.

Llamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/expected-resolutions/allow-return

Ejemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/5263380301/expected-resolutions/allow-return

Respuesta:

[
    {
        "player_role": "complainant",
        "user_id": 1680903379,
        "expected_resolution": "return_product",
        "status": "pending",
        "details": [],
        "date_created": "2024-04-15T12:13:28",
        "last_update": "2024-04-15T12:13:28"
    }
]

El tipo de reclamo interfiere directamente con las soluciones que se pueden proponer. Hay reclamos del tipo PNR (pagado y no recibido) y PDD (producto defectuoso). Para identificar el tipo de reclamo, verifica las 3 primeras letras del campo reason_id. Por ejemplo, si en el campo la información es "PNR3430", entonces el reclamos es del tipo PNR.

De esta manera, para los reclamos del tipo PNR, debemos utilizar:

- refund: devolución del dinero.

- product: envío del producto.

Si el comprador elige product, el vendedor puede elegir product o refund. Pero si el comprador elige refund, el vendedor debe aceptar esa resolución. Algo similar ocurre con los casos PDD:

- return_product: devolución del producto con devolución del dinero.

- change_product: cambio del producto.

Si el comprador elige change_product, el vendedor puede elegir change_product o return_product. Pero si el comprador elige return_product debe aceptar esa resolution.
Las resoluciones refund y return_product hacen referencia a que el comprador quiere la devolución del dinero, por este motivo solo puede aceptar esa resolución.
Aceptar o proponer la opción de refund no devolverá el pago. Hoy, vía API de reclamos, todavía no es posible realizar esta acción.
Los casos del tipo PDD donde la compra tiene Mercado Envíos y el status del envío está 'delivered' cuando el seller acepta la resolución, se genera una etiqueta para que el comprador haga la devolución del producto. Si la resolución es la devolución del dinero, esta se va a realizar cuando el envío return pase a shipped o delivered.

Para compras realizadas con ME2:

Las soluciones para el tipo de reclamo PDD generarán una etiqueta para que el comprador devuelva el producto. Para que esto ocurra, el status del pedido que originó el reclamo debe ser delivered.

Si la solución elegida es return_product, la devolución de dinero será solo cuando la etiqueta generada tenga el status shipped o delivered, según las validaciones internas.

Para identificar si la compra es con ME2, revisa la API de Envíos. La información estará en el campo Mode.

Obtener evidencias del reclamo

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/555555555/evidences

Nota:

Actualmente solo existe la carga de evidencia de envío que realiza el vendedor.

Respuesta:

[
    {
        "attachments": [],
        "type": "shipping_evidence",
        "date_shipped": "2018-03-07T05:00:00Z",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": "servientrega",
        "shipping_method": "mail",
        "tracking_number": "132456787"
    }
]

Cargar evidencias de envíos

Cuando el comprador abre un reclamo para recibir su producto o tener una solución al respecto, y el vendedor ya envió su producto y tiene evidencias, deberá utilizar el siguiente recurso.

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/evidences'
-H 'Content-Type: application/json' 
-d '{
    "type": "shipping_evidence",
    "shipping_method": "entrusted",
    "shipping_company_name": "Total",
    "destination_agency": "Agencia",
    "date_shipped": "2018-08-17T05:00:01.858-03:00",
    "receiver_name": "Jose da Silva",
    "receiver_id": "12345678",
    "tracking_number": "XX123456789XX",
    "attachments": []
}'

Respuesta:

[
    {
        "attachments": [],
        "type": "shipping_evidence",
        "date_shipped": "2018-03-07T05:00:00Z",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": "servientrega",
        "shipping_method": "mail",
        "tracking_number": "132456787",
        "handling_date": null, 
    }
]

Campos del recurso

type: es el tipo de demostración. Los valores esperados para este campo son:
shipping_evidence: cuando el vendedor ya tiene la prueba de envío
handling_shipping_evidence: que debe usarse cuando existe un previsión de publicaciones.
shipping_method: refiere a cómo enviaron el producto, por correo, encomienda (por un transportista), entrega personal (por una persona) o por email (correo electrónico).
shipping_company_name: debes ingresar el nombre del transportista.
tracking_number: ingrese el número de seguimiento.
date_shipped: fecha de envío.
date_delivered: fecha de entrega.
destination_agency: nombre de la agencia de destino.
receiver_name: nombre del destinatario.
receiver_id: documento de quién recibió el producto.
attachments: archivos.
receiver_email: correo electrónico del destinatario del pedido digital.
handling_date: fecha de publicación.

Notes:

Todas las fechas deben usarse en los siguientes formatos:
- Formato largo: aaaa-MM-dd'T'HH: mm: ss.SSSZ. Ej: 2019-08-06T14: 00: 00.000-0400;
- Formato corto: aaaa-MM-dd. Ej: 2019-08-06

Cada tipo de envío tiene campos obligatorios, síguelos según corresponda:

Entrega por correo

Campos obligatorios: "shipping_company_name", "date_shipped".
Campos opcionales: "tracking_number", "attachments"

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/949903015/actions/evidences
-d {"type": "shipping_evidence",  "shipping_method": "mail" ,  "shipping_company_name": "Correios",  "tracking_number": "XX123456789XX", "date_shipped": "2018-03-07T05:00:01.858-03:00",  "attachments": ["38f4e399-0f18-41e4-8f48-91aecd2dee1a_419059118.png"]
}

Respuesta:

[
    {
        "attachments": [
            {
             "filename":"38f4e399-0f18-41e4-8f48-91aecd2dee1a_419059118.png",
                "original_filename": "Captura de Tela 2019-07-30 a?s 09.45.40.png",
                "size": 63337,
                "date_created": "2019-08-21T09:33:02.325-04:00",
                "type": "image/png",
               
            }
        ],
        "date_shipped": "2018-03-07T04:00:01.858-04:00",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": "Correios",
        "shipping_method": "mail",
        "tracking_number": "XX123456789XX",
        "type": "shipping_evidence"
    }
]

Entrega por encomienda

Campos obligatorios: "shipping_company_name", "destination_agency", "date_shipped", "receiver_name"
Campos opcionales: "receiver_id", "tracking_number", "date_delivered", "receiver_email", "attachments"

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/949903016/actions/evidences
-d {"type": "shipping_evidence",  "shipping_method": "entrusted" , "shipping_company_name": "Total", "destination_agency": "Agencia", "date_shipped": "2018-08-17T05:00:01.858-03:00", "receiver_name": "Jose da Silva", "receiver_id": "12345678", "tracking_number": "XX123456789XX", "attachments": [] }

Respuesta:

[
    {
        "attachments": [],
        "date_shipped": "2018-08-17T04:00:01.858-04:00",
        "date_delivered": null,
        "destination_agency": "Agencia",
        "receiver_email": null,
        "receiver_id": 12345678,
        "receiver_name": "Jose da Silva",
        "shipping_company_name": "Total",
        "shipping_method": "mail",
        "tracking_number": "XX123456789XX",
        "type": "shipping_evidence"
    }
]

Entrega en mano

Campos obligatorios: "date_delivered"
Campos opcionales: "attachments"

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/949903017/actions/evidences 
-d {"type": "shipping_evidence",  "shipping_method": "personal_delivery" , "date_delivered": "2018-03-07T05:00:01.858-03:00", "attachments": [] }

Respuesta:

[
    {
        "attachments": [
            {
                "filename": "38f4e399-0f18-41e4-8f48-91aecd2dee1a_419059118.png",
                "original_filename": "Captura de Tela 2019-07-30 a?s 09.45.40.png",
                "size": 63337,
                "date_created": "2019-08-21T09:39:06.316-04:00",
                "type": "image/png",
               
            }
        ],
        "date_shipped": null,
        "date_delivered": "2018-03-07T04:00:01.858-04:00",
        "destination_agency": null,
        "receiver_email": null,
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": null,
        "shipping_method": "personal_delivery",
        "tracking_number": null,
        "type": "shipping_evidence"
    }
]

Entrega por email

Campos obligatorios: receiver_email", "date_shipped
Campos opcionales: "attachments".

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/949903018/actions/evidences
-d {"type": "shipping_evidence",  "shipping_method": "email" , "receiver_email": "teste@teste.com.br", "date_shipped": "2018-03-07T05:00:01.858-03:00",  "attachments": [] 
}

Respuesta:

[
    {
        "attachments": [
            {
                "filename": "38f4e399-0f18-41e4-8f48-91aecd2dee1a_419059118.png",
                "original_filename": "Captura de Tela 2019-07-30 a?s 09.45.40.png",
                "size": 63337,
                "date_created": "2019-08-21T09:44:43.908-04:00",
                "type": "image/png",
               
            }
        ],
        "date_shipped": "2018-03-07T04:00:01.858-04:00",
        "date_delivered": null,
        "destination_agency": null,
        "receiver_email": "teste@teste.com.br",
        "receiver_id": null,
        "receiver_name": null,
        "shipping_company_name": null,
        "shipping_method": "email",
        "tracking_number": null,
        "type": "shipping_evidence"
    }
]

Hay casos en que los productos aún no se enviaron, pero el vendedor tiene la intención de enviar y ya tiene una fecha prevista para hacerlo. Entonces, puede utilizar este recurso:

Llamada:

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

Ejemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/949903019/evidences -d {"type": "handling_shipping_evidence", "handling_date": "2019-08-23" }

Respuesta:

[
    {
        "handling_date": "2019-08-23T22:59:59.000-04:00",
        "type": "handling_shipping_evidence"
    }
]

Nota:

Cuando el stage del reclamo sobre un producto está en discusión/mediación, el vendedor no podrá enviar la prueba del envío. Una vez enviado algún tipo de prueba, no podrá cambiarla. Para esto, te recomendamos completar toda la información posible.

Historial de estados y acciones del reclamo

Accede al historial de estados y escenario por el que pasó el reclamo, también puedes ver el historial de acciones que se tomaron.

Llamada:

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

ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/5248960694/status_history

Respuesta:

[
    {
        "stage": "dispute",
        "status": "closed",
        "date": "2018-03-12T10:33:01.858-03:00",
        "change_by": "mediator"
    },
    {
        "stage": "dispute",
        "status": "opened",
        "date": "2018-03-12T10:17:56.844-03:00",
        "change_by": "respondent"
    },
    {
        "stage": "claim",
        "status": "opened",
        "date": "2018-03-08T11:40:02.390-03:00",
        "change_by": "complainant"
    }
]

Descripción de parámetros

action_id: ID de la acción ejecutada.
action_name: acción ejecutada.
role: player que ejecutó la acción.
claim_stage: etapa en la cual se ejecutó la acción.
claim_status: estado de la etapa en la que se ejecutó la acción.
date_created: fecha en la que se ejecutó la acción.

Obtener detalle del motivo por el que se inició el reclamo

Llamada:

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

Ejemplo:

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

Respuesta:

{
   "id": "PDD9549",
   "flow": "unification_delivered",
   "name": "not_working_item",
   "detail": "A embalagem chegou em bom estado",
   "position": 203,
   "filter": {
       "group": [
           "generic",
           "installable_autoparts"
       ],
       "site_id": [
           "MLC",
           "MCO",
           "MLU",
           "MPE",
           "MLM",
           "MLA",
           "MLB",
           "MEC",
           "CBT"
       ]
   },
   "settings": {
       "allowed_flows": [
           "claim"
       ],
       "expected_resolutions": [
           "change_product",
           "return_product"
       ],
       "rules_engine_triage": [
           "not_working"
       ]
   },
   "parent_id": "PDD9548",
   "children_title": null,
   "status": "active",
   "date_created": "2022-02-24T17:41:05.505-04:00",
   "last_updated": "2023-09-25T14:44:14.473-04:00"
}

Cómo identificar si un reclamo afecta la reputación

El recurso /affects-reputation permite al integrador identificar si un determinado reclamo afecta o no la reputación del vendedor realizando la siguiente llamada.

Llamada:

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

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/post-purchase/v1/claims/5224172034/affects-reputation

Respuesta:

{
    "affects_reputation": affected,
    "has_incentive": true,
    "due_date": "2023-04-19T00:00-04:00"
}

Campos de la respuesta:

affects_reputation: informa si el reclamo afecta la reputación del vendedor. Posibles valores: affected/not_affected/not_applies.
has_incentive: en los casos en que el reclamo está abierto, el campo va tener el resultado true para que el vendedor pueda hacer la tratativa del reclamo. En caso de que esté cerrado, va estar false y el vendedor tendrá el resultado si impacta o no la reputación.
due_date: fecha límite para solucionar el reclamo.

Siguiente: Trabajar con Devoluciones.