Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 23/04/2024

Reclamações

Importante:

A partir de 20 de maio de 2024, todos os recursos de reclamações em https://api.mercadolibre.com/v1/claims/ serão descontinuados e você só poderá acessar as informações através de https://api.mercadolibre.com/post-purchase/v1/claims/.

Convidamos você a ajustar sua integração para continuar trabalhando com as reclamações normalmente.

O recurso /claims permitirá que você obtenha o detalhe de uma reclamação e possa realizar ações via API para resolvê-las de maneira correta, incorporando esta funcionalidade em sua integração.

Receba uma notificação

Em Minhas aplicações, edite seu aplicativo e ative o tópico Claims no nosso feed para ser informado sempre que uma reclamação for iniciada ou receber alguma interação. Obtenha mais informações sobre notificações de reclamações.

Busca das reclamações

A busca das reclamações ajudará identificar quais pertencem a um usuário de um token válido.

Chamada:

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:

O campo “quantity_type” inicialmente exibirá apenas o valor “total” e futuramente exibirá o valor “partial”. Indica se uma devolução corresponde a todos os produtos da ordem ou apenas a alguns.

Descrição de parâmetros

A resposta de um GET ao recurso /claims dá como resultado os seguintes parâmetros:

id: ID da reclamação.
type: Tipo de reclamação. Você pode tomar algum dos seguintes valores:

mediations: reclamação entre comprador e vendedor.
cancel_purchase: cancelamento de compra pelo comprador.
return: Para este tipo de reclamação não há mensagens. Para entender como trabalhar com devoluções verifique a documentação Trabalhar com devoluções.
cancel_sale: cancelamento de compra por parte do vendedor.
- O status sempre será closed.
- O stage sempre será none.
- O rol complainant sempre será o type seller, collector o sender dependendo o resource.
change: É permitido ao comprador devolver o produto para obter outro, ou seja, trocar o produto.

stage: Etapa da reclamação. Você pode tomar algum dos seguintes valores:

claim: etapa de reclamação em que intervêm o comprador e o vendedor.
dispute: etapa de mediação em que intervém um representante do Mercado Livre.
recontact (não disponível): etapa em que alguma das partes entra em contato após a reclamação/disputa ter sido encerrada.
none: não aplica.

status: Status da reclamação. Você pode tomar dois valores: opened e closed.
parent_id: ID de outra reclamação da qual depende.
resource: Identificador do recurso sobre o qual a reclamação é criada. Pode ser:

payment
order
shipment
purchase

resource_id: ID do recurso sobre o qual a reclamação é criada e depende do parâmetro anterior.
players: Lista dos players que participam da reclamação com suas respectivas ações e tempos disponíveis.

role: papel dentro da reclamação. Pode ser:

complainant: pessoa que reclama.
respondent: pessoa de quem reclamam.
mediator: pessoa que intervém para ajudar a solucionar o problema.

type: papel desempenhado pela pessoa na operação que está sendo reclamada.

Pode variar de acordo com o resource.
- Payment: payer ou collector.
- Order: buyer ou seller.
- Shipment: receiver ou sender.
user_id: ID do type do parâmetro anterior.
available_actions: lista de ações que cada uma das partes participantes podem realizar.
action: ações possíveis de serem realizadas. Para o vendedor serão:

send_message_to_complainant: enviar mensagem para o comprador (com ou sem anexo).
send_message_to_mediator: enviar mensagem para o mediador (com ou sem anexo).
recontact (não disponível): reabrir uma reclamação já encerrada, por meio de uma interação que pode ser uma mensagem.
refund: devolver o dinheiro do comprador, deve ser realizado pelo front do Mercado Livre ou Mercado Pago.
open_dispute: iniciar uma mediação.
send_potential_shipping: enviar uma promessa de postagem, uma data.
add_shipping_evidence: postar uma evidência de que o produto foi enviado.
send_attachments: enviar mensagem com anexo.
allow_return: gerar etiqueta de devolução.
allow_return_label: gerar etiqueta de devolução.
send_tracking_number: enviar o tracking number.

due_date: tempo limite para realizar a ação.
mandatory: este campo em true indica que a ação é obrigatória e deve ser realizada dentro do tempo informado.

resolution: forma de resolução da reclamação.
site_id: ID do site onde a reclamação se desenvolve.
date_created: data de criação da reclamação.
last_updated: data da última atualização da reclamação.

Como filtrar?

Os parâmetros disponíveis para os filtros são:

id
type
stage
status
resource: order, shipment ou purchase.
resource_id: é o ID do recurso em que a reclamação é criada e deve ser usado junto com o parâmetro anterior.
reason_id
site_id
player_role: complainant ou respondent.
players_user_id: está relacionado ao parâmetro anterior.
parent_id
date_created
order_id
last_updated
offset
limit

Por exemplo, se deseja 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 exemplo tambén, se deseja filtrar por data:

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

Como ordenar?

Para ordenar os resultados é só adicionar o parâmetro sort com o respectivo campo que deseja que seja ordenado e se a ordem deve ser ascendente ou descendente (&sort=:asc|desc).

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

Passo a passo para utilização de recursos

Ver detalhe de uma reclamação

Chamada:

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

Exemplo:

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

Resposta:

{
    "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"
}

Obter todas as mensagens de uma reclamação

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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:

Somente poderão ser vistas as mensagens moderadas própias, com o status correspondente em “moderated”. As mensagens criadas pela contraparte que foram moderadas serão filtradas.

Descrição de parâmetros GET

A resposta de um GET de messages do recurso /claim retorna uma lista com os seguintes parâmetros:

sender_role: player que enviou a mensagem.
receiver_role: player para quem a mensagem é encaminhada.
attachments: lista de anexos da mensagem.
message: texto da mensagem.
date_created: data em que a mensagem foi criada.
date_read: este valor será null até uma nova versão do recurso ficar disponível.
stage: etapa em que a mensagem foi enviada.
status: available | moderated | rejected | pending_translation.
moderation.status: resultado do processo de moderação. Possiveis valores:
clean: a mensagem está limpa.
rejected: a mensagem foi moderada.
pending: a moderação está em processo.
non_moderated: não se aplicou a moderação. Por exemplo: casos antigos.
moderation.date_moderated: data que se realizou a moderação.
moderation.source: modalidade da moderação. Possiveis valores:
online: se modera durante a instancia de criação da mensagem. Única modalidade atualmente.
moderation.reason: motivo ao qual se moderou a mensagem. Possiveis valores:
OUT_OF_PLACE_LANGUAGE: linguagem inapropiada.

Responder mensagens e anexar arquivos

Post de Attachment

Chamada:

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

Notas:

- O POST deve ser realizado com form.data com file = localização do arquivo.
- Poderão ser compartilhadas fotos, manuais de instruções, notas fiscais e outros arquivos anexados em formato JPG, PNG e PDF com tamanho máximo de até 5 MB.
- O nome do arquivo não pode ter mais de 125 caracteres e ser composto somente pelos seguintes caracteres: Letras, números, ponto, hífen, underline ( [a-zA-Z0-9._\s-]

Exemplo:

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'

Resposta:

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

Post de mensagem com o attach anterior

Chamada:

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

Nota:

Na lista de anexos serão mostrados todos os retornados no POST anterior, associados à mensagem separados por vírgula.
Além disso, no body é possível enviar uma mensagem com um anexo ou sem anexo.

Exemplo com anexos:

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

Exemplo sem anexos:

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": []
}'

Resposta:

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

Descarregar o arquivo

Chamada:

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

Exemplo:

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'

Obter informação do arquivo

Chamada:

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

Exemplo:

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

Resposta:

{
   "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 mediação

Chamada:

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

Exemplo:

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

Resposta:

{
   "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"
}

Quando iniciada a mediação, não é mais possível enviar mensagem para o comprador. Toda comunicação passa a ser realizada com o Mercado Livre. Para isso, é necessário mudar o receiver_role para mediator.

Chamada:

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

Exemplo:

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": []
}'

Resposta:

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

Ver resoluções esperadas dos participantes

Chamada:

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

Exemplo:

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

Resposta:

[
   {
       "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"
   }
]

Descrição de parâmetros

player_role: papel do player da reclamação.
user_id: ID do player da reclamação.
expected_resolution: resolução da reclamação carregada pelo player informado no parâmetro anterior. Os valores possíveis são:
- refund: o player espera a devolução do dinheiro.
- product: o player espera a chegada do produto.
- change_product: o player espera trocar o produto.
- return_product: o player espera a devolução do produto com a posterior devolução do dinheiro.
details: esse campo dá informações adicionais sobre a expected-resolution escolhida
date_created: data de criação da resolução esperada.
date_created: data de última atualização da resolução esperada.
status: status da resolução esperada. Você pode tomar os seguintes valores:
- pending: o player carregou a resolução esperada mas ainda não foi aceita pela contraparte.
- accepted: la resolución cargada por el player fue aceptada por su contraparte o en su defecto por el mediador de Mercado Livre.
- rejected: a resolução carregada pelo player foi aceita pela contraparte ou pelo mediador do Mercado Livre.

Nota:

Para além das resoluções carregadas pelos participantes, em alguns casos, a resolução final é definida por um representante do Mercado Livre, caso as partes não cheguem a um acordo.

Opções para resolver reclamação

Importante:

A partir de 20 de Maio de 2024 os recursos para resolver reclamações deixarão de funcionar.

Liberamos três novos recursos que permitirão resolver as reclamações segundo a ação que queira realizar cada vendedor. Serão 3 novos endpoints:

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

- Reembolso Total - /expected-resolutions/refund

- Devolução de produto - /expected-resolutions/allow-return

Reembolso parcial

O fluxo de reembolso parcial do dinheiro é atrelado ao processo de reclamação do comprador, onde dependendo das ações disponíveis para o vendedor, é possível ofertar como solução da reclamação a devolução de parte do dinheiro pago na compra.

Para isso é necessário que no array de available_actions, uma das ações seja allow_partial_refund. conforme exemplo a seguir:

 {
    "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"
}

Oferecer devolução parcial do dinheiro

Para oferecer uma reemmbolso parcial, a reclamação deve ser PDD com expected_resolution: return_product e status pending.

Calcular valor de reembolso parcial

Verifique os percentuais de devoluções disponíveis e quanto seria o valor a ser reembolsado utilizando o seguinte recurso:

Chamada:

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

Exemplo:

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

Resposta:

{
     "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 resposta

currency_id: moeda.
mount: valor do reembolso.
percentage: percentual de retorno representando o valor (amount).

Escolha a porcentagem para devolver: se você não enviar uma porcentagem de retorno por padrão será atribuído default_percentege = 50.

Nota:

Quando você oferece um reembolso parcial, o campo expected_resolution que estava ao lado do vendedor player_role: complainant será rejeitado e será criado expected_resolution=partial_refund, onde o status será pending e a resposta ficará do lado do comprador (player_role: respondent).

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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"
    }

]

Se você enviar um valor diferente dos permitidos, receberá esta resposta:

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

Caso o vendedor não tenha o reembolso parcial habilitado, será:

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

Se o reembolso parcial for aceito pelo comprador, a reclamação será encerrada e o dinheiro correspondente ao percentual oferecido será devolvido ao comprador.
Caso o reembolso parcial não seja aceito pelo comprador, a resolução esperada de reembolso parcial terá status rejeitado.

Oferecer devolução total do dinheiro

Para os casos em que exista uma available_actions como refund, é possível utilizar o seguinte recurso para gerar a devolução total do dinheiro ao comprador através da reclamação.

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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:

Nesta resposta pode-se visualizar o exemplo que mostra o fluxo que começa com uma devolução do produto, a qual é rejeitada; é oferecido um reembolso parcial, o qual também é rejeitado; e, finalmente, o reembolso total é aceito.

Devolução do produto

Importante:

É adicionado o recurso /expected-resolutions/allow-return para realizar a devolução, o que substitui a funcionalidade de "aceitar a resolução" ou "carregar uma nova resolução", pois ambos os fluxos resultavam em uma devolução.

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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"
    }
]

O tipo da reclamação interfere diretamente nas soluções que podem ser propostas. Existem as reclamações do tipo PNR (paguei e não recebi) e PDD (produto com defeito). Para identificar o tipo da reclamação, verifique às três primeiras letras do campo reason_id. Por exemplo, se no campo a informação for "PNR3430", então a reclamação é do tipo PNR.

Dessa forma, para as reclamações do tipo PNR, temos as seguintes resoluções disponíveis:

- refund: devolução do dinheiro.

- product: envio do produto.

Se ao consultar a resolução esperada e estiver como product, o vendedor pode aceitar essa solução ou propor refund. Porém, se a solução esperada estiver como refund, o vendedor deve aceitar a solução ou negociar via mensagem com o comprador.
Aceitar ou propor a opção de refund não fará com que o pagamento seja devolvido. Hoje via api de reclamações ainda não é possível realizar esta ação.

Para as reclamações do tipo PDD, temos as seguintes soluções disponíveis:

- return_product: devolução do produto com devolução do dinheiro.

- change_product: troca do produto.

Se ao consultar a resolução esperada estiver como change_product, o vendedor pode aceitar essa solução ou propor return_product. Porém se a solução esperada estiver como return_product o vendedor deve aceitar a solução ou negociar via mensagem com o comprador.

Para compras realizadas com ME2

As soluções para o tipo de reclamações PDD gerarão uma etiqueta para o comprador devolver a mercadoria. Para que isso ocorra, o status do envio do pedido que originou a reclamação deve ser delivered.
Se a solução escolhida for return_product, a devolução do dinheiro só ocorrerá quando a etiqueta gerada estiver com o status shipped ou delivered, dependendo de validações internas.
Para identificar se a compra é ME2, utilize a API de Shipping. A informação estará no campo Mode.

Obter evidências da reclamação

Chamada:

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

Exemplo:

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

Nota:

Atualmente, só existe a carga de evidência de envio realizada pelo vendedor.

Resposta:

[
    {
        "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"
    }
]

Carregar evidência de envio

Quando o comprador abre uma reclamação querendo receber o produto, solução esperada = product, mas o vendedor já enviou e tem as evidências, ele deve utilizar o recurso para carregar a evidência do envio.

Chamada:

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

Exemplo:

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": []
}'

Resposta:

[
    {
        "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, 
    }
]

Descrição de parâmetros

type: É o tipo de evidência. Os valores esperados para esse campo são
shipping_evidence quando o seller já possui a evidência do envio ou
handling_shipping_evidence que deve ser utilizado quando existe uma previsão de postagem.
shipping_method: Esta informação faz referência a como o produto foi enviado, pode ser mail (Correios), entrusted (transportadora), personal_delivery (entrega em mãos), email (envio por e-mail).
shipping_company_name: Deve ser informado o nome da transportadora.
tracking_number: código de rastreio.
date_shipped: data do envio.
date_delivered: data de entrega.
destination_agency: nome da agência de destino.
receiver_name: nome de quem recebeu a mercadoria.
receiver_id: documento de quem recebeu o produto.
attachments: anexos.
receiver_email: e-mail de quem recebeu a encomenda digital.
handling_date: data para postagem.

Nota:

Todas as datas devem ser utilizadas nos seguintes formatos:
- Formato longo: yyyy-MM-dd'T'HH:mm:ss.SSSZ. Ex: 2019-08-06T14:00:00.000-0400;
- Formato curto: yyyy-MM-dd. Ex: 2019-08-06

Para cada tipo de envio, ele vai ter uma relação de campos obrigatórios. Segue relação:

Entrega por Correios

Campos obrigatórios: "shipping_company_name", "date_shipped".
Campos opcionais:"tracking_number", "attachments".

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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 transportadora

Campos obrigatórios: "shipping_company_name", "destination_agency", "date_shipped", "receiver_name".
Campos opcionais: "receiver_id", "tracking_number", "date_delivered", "receiver_email", "attachments".

Chamada:

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

Exemplo:

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": [] }

Resposta:

[
    {
        "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 em mãos

Campos obrigatórios: "date_delivered".
Campos opcionais: "attachments".

Chamada:

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

Exemplo:

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": [] }

Resposta:

[
    {
        "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"
    }
]

Envio por email

Campos obrigatórios: receiver_email", "date_shipped.
Campos opcionais: "attachments".

Chamada:

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

Exemplo:

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": [] 
}

Resposta:

[
    {
        "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"
    }
]

Há casos em que a mercadoria ainda não foi postada, mas o vendedor tem a intenção de postar e possui uma data prevista. Nesse caso, ele também pode utilizar esse recurso:

Chamada:

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

Exemplo:

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

Resposta:

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

Nota:

Quando o stage da reclamação estiver como dispute, não é possível utilizar o envio de evidências. Uma vez enviado um tipo de evidência, não é possível trocar, porém, posso completar as informações caso falte alguma, exemplo: anexo.

Histórico do Status e ações tomadas na reclamação

Acesse o histórico dos status e cenários pelos quais a reclamação passou, você também pode ver o histórico das ações realizadas.

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "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"
    }
]

Descrição dos parâmetros

action_id: ID da ação realizada.
action_name: ação realizada.
role: player que realizou a ação.
claim_stage: etapa na qual a ação foi realizada.
claim_status: status da etapa em que a ação foi realizada.
date_created: data em que a ação foi realizada.

Obter detalhe do motivo que levou ao início da reclamação

Chamada:

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

Exemplo:

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

Resposta:

{
   "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"
}

Como identificar se uma reclamação afeta a reputação

O recurso /affects-reputation permite ao integrador identificar se uma determinada reclamação afeta ou não a reputação do vendedor. Para isto, basta realizar a seguinte chamada.

Chamada:

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

Exemplo:

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

Resposta:

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

Campos da resposta:

affects_reputation: mostra se a reclamação afeta a reputação do vendedor. Possiveis valores: affected/not_affected/ not_applies.
has_incentive: nos casos em que a reclamação estiver em aberto, o campo vai ter o resultado true para que o vendedor possa fazer a tratativa da reclamação. Caso esteja encerrado, vai estar como false e o vendedor terá o resultado se impacta ou não na reputação.
due_date: é a data limite para resolver a reclamação.