Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.Documentação do
Reclamações
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"
}
]
}
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.
- 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
Como filtrar?
Os parâmetros disponíveis para os filtros são:
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
}
]
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
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
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.
Opções para resolver reclamação
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.
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"
}
]
Devolução do produto
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
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.
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"
}
]
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.