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.

Llamada:

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

Respuesta:

{
    "paging": {
        "offset": 0,
        "limit": 30,
        "total": 170
    },
    "data": [
        {
            "id": 2342342432,
            "type": "mediations",
            "stage": "dispute",
            "status": "closed",
            "parent_id": null,
            "client_id": null,
            "resource_id": 234342342,
            "resource": "order",
            "reason_id": "PDD316",
            "quantity_type": "total",
            "players": [
                {
                    "role": "complainant",
                    "type": "buyer",
                    "user_id": 44234343,
                    "available_actions": [
                        {
                            "action": "recontact",
                            "due_date": "2018-09-29T07:37:16.656-04:00",
                            "mandatory": null
                        }
                    ]
                },
                {
                    "role": "respondent",
                    "type": "seller",
                    "user_id": 2343424,
                    "available_actions": [
                        {
                            "action": "recontact",
                            "due_date": "2018-09-29T07:37:16.656-04:00",
                            "mandatory": null
                        }
                    ]
                },
                {
                    "role": "mediator",
                    "type": "internal",
                    "user_id": 432434324,
                    "available_actions": []
                }
            ],
            "resolution": {
                "reason": "payment_refunded",
                "date_created": "2018-08-30T07:37:16.656-04:00",
                "benefited": [
                    "complainant"
                ],
                "closed_by": "mediator"
            },
            "labels": [],
            "site_id": "MLM",
            "date_created": "2018-08-25T15:57:55.588-04:00",
            "last_updated": "2018-08-30T07:37:16.839-04:00"
        } 
]}

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
- players.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?stage=dispute&status=opened

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?stage=dispute&status=opened&sort=last_updated:asc

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: dPara 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: mudanças no produto. Indica que uma mudança de produto será feita.
  

• 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: respondent: pessoa de quem reclamam.
  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.
• labels: rótulos da reclamação, por exemplo, indica se a reclamação afeta ou não a reputaçã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.

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.

filename: nome do arquivo em anexo hasheado.
original_filename: nome real do anexo.
size: tamanho do arquivo em Bytes.
type: tipo de arquivo.
date_created: data de carga do anexo.

• stage: etapa em que a mensagem foi enviada.
• 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.
• message: texto da mensagem.



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": 950700111,
    "type": "mediations",
    "stage": "claim",
    "status": "closed",
    "parent_id": null,
    "client_id": null,
    "resource_id": 1656223086,
    "resource": "order",
    "reason_id": "PDD-0",
    "quantity_type": "total"
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 271942703,
            "available_actions": [
                {
                    "action": "recontact",
                    "due_date": "2018-04-07T10:35:29.000-0400",
                    "mandatory": false
                }
            ]
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 271959653,
            "available_actions": [
                {
                    "action": "recontact",
                    "due_date": "2018-04-07T10:35:29.000-0400",
                    "mandatory": false
                }
            ]
        }
    ],
    "resolution": {
        "reason": "item_returned",
        "date_created": "2018-03-08T10:35:29.269-0400",
        "decision": [
            "complainant",
            "respondent"
        ],
        "closed_by": "mediator"
    },
    "coverages": [
        {
            "type": "bpp",
            "benefited": "complainant",
            "amount": 194.99,
            "resource": "bpp",
            "resource_id": 224635193,
            "date_created": "2018-03-08T10:35:30.000-0400",
            "costs": [
                {
                    "role": "respondent",
                    "amount": 194.99,
                    "date_created": "2018-03-08T10:35:30.000-0400"
                }
            ]
        },
        {
            "type": "return_label",
            "benefited": "complainant",
            "amount": 144.99,
            "resource": "bpp",
            "resource_id": 224635218,
            "date_created": "2018-03-08T10:38:28.000-0400",
            "costs": [
                {
                    "role": "mediator",
                    "amount": 144.99,
                    "date_created": "2018-03-08T10:38:28.000-0400"
                },
                {
                    "role": "respondent",
                    "amount": 0,
                    "date_created": "2018-03-08T10:38:28.000-0400"
                }
            ]
        }
    ],
    "labels": [
        {
            "name": "reputation",
            "value": "avoid",
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        },
        {
            "name": "return_label",
            "value": "charged",
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T09:56:00.078-0400"
        }
    ],
    "site_id": "MLA",
    "date_created": "2018-03-08T09:56:00.078-0400",
    "last_updated": "2018-03-08T10:38:27.999-0400"
}




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/950463475/messages

Resposta:

[{
        "sender_role": "respondent",
        "receiver_role": "complainant",
        "attachments": [{
            "filename": "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg",
            "original_filename": "camiseta promocional 6555 rosa.jpg",
            "size": 5434,
            "type": "image/jpeg",
            "date_created": "2018-03-08T16:59:25.936-0400"
        }],
        "status": "moderated",
        "moderation": {
            "status": "rejected",
            "reason": "OUT_OF_PLACE_LANGUAGE",
            "source": "online",
            "date_moderated": "2020-12-05T20:01:46.000Z"
        },
        "stage": "claim",
        "date_created": "2018-03-08T16:59:25.936-0400",
        "message": "Este es un mensaje de test del respondent al complainant"
    },
    {
        "sender_role": "complainant",
        "receiver_role": "respondent",
        "attachments": [],
        "status": "available",
        "moderation": {
            "status": "clean",
            "reason": "",
            "source": "online",
            "date_moderated": "2020-12-05T20:01:46.000Z"
        },
        "stage": "claim",
        "date_created": "2018-03-08T10:40:02.602-0400",
        "message": "Test pdd"
    }
]

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.




Campos da resposta

• 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 "https://api.mercadolibre.com/post-purchase/v1/claims/{claim_id}/actions/message?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID"

Nota:
Na lista de anexos serão mostrados todos os retornados no POST anterior, associados à mensagem separados por vírgula.

Exemplo:

curl -X POST "https://api.mercadolibre.com/post-purchase/v1/claims/950463475/actions/message?access_token=$ACCESS_TOKEN&application_id=$APPLICATION_ID" -H 'Content-Type: application/json'  \
 -d '{ \
  "receiver_role": "complainant", \
  "message": "Este es un mensaje de test del respondent al complainant", \
  "attachments": [ \
    "fa8d559e-b6c9-4a9d-9824-aba4607bd869_271959653.jpg" \
  ] \
}'

Resposta:

{"id":1817133310}

Enviar mensagens sem anexos

Chamada:

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

Exemplo:

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

Resposta:

{
  "execution_response": {
      "id": 0
  },
"new_state": {
  "name": "pdd_opened",
  "modifiers": {
      "send_message_turn":"complainant",
      "optional_refund": "denied",
      "partial_refund": "denied",
      "return_condition": "allowable"
  }
}
}




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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/1022718940/attachments/0f2d81a2-c489-435e-96af-59688ad3d8f4_305860144.jpeg/download

Resposta: a imagem do anexo.



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 -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/1022718940/attachments/0f2d81a2-c489-435e-96af-59688ad3d8f4_305860144.jpeg

Resposta:

{
    "filename": "0f2d81a2-c489-435e-96af-59688ad3d8f4_305860144.jpeg",
    "original_filename": "casa.jpeg",
    "size": 10080,
    "date_created": "2018-07-30T12:25:18.133-04:00",
    "type": "image/jpeg"
}




Solicitar mediação

Chamada:

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

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/950463475  -H 'Content-Type: application/json' -d '{"stage":"dispute"}'

Resposta:

{
    "id": 950463475,
    "type": "mediations",
    "stage": "dispute",
    "status": "opened",
    "parent_id": null,
    "client_id": null,
    "resource_id": 1656273684,
    "resource": "order",
    "reason_id": "PDD-0",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "id": 271942703,
            "available_actions": []
        }
    ],
    "resolution": null,
    "coverages": [],
    "labels": [
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T10:40:02.390-0400"
        },
        {
            "name": null,
            "value": null,
            "comments": null,
            "admin_id": null,
            "date_created": "2018-03-08T10:40:02.390-0400"
        }
    ],
    "site_id": "MLA",
    "date_created": "2018-03-08T10:40:02.390-0400",
    "last_updated": "2018-03-12T09:17:56.844-0400"
}

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/messages

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/1036274835/messages'  -H 'Content-Type: application/json' -d '{"receiver_role": "mediator", "message": "Teste de resposta"}'

Resposta:

{"id": 1914089028}




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": 271942703,
        "expected_resolution": "return",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "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.
• 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.



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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5225721252/expected_resolutions - d 
{
  "expected_resolution": "allow_partial_refund",
  "detail": {
    "key": "percentage",
    "value": "50.0"
  }
}

Resposta:

[
    {
        "player_role": "complainant",
        "user_id": 710928120,
        "expected_resolution": "return_product",
        "detail": [],
        "date_created": "2022-11-04T12:23:44.000-05:00",
        "last_updated": "2022-11-04T12:23:44.000-05:00",
        "status": "rejected"
    },
    {
        "player_role": "respondent",
        "user_id": 823876519,
        "expected_resolution": "partial_refund",
        "detail": [
            {
                "key": "percentage",
                "value": "50.0"
            },
            {
                "key": "seller_amount",
                "value": "114.52"
            },
            {
                "key": "seller_currency",
                "value": "R$"
            }
        ],
        "date_created": "2022-11-04T12:43:06.000-05:00",
        "last_updated": "2022-11-04T12:43:06.000-05:00",
        "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/5224172034/expected-resolutions/refund

Resposta:

{
        "player_role": "complainant",
        "user_id": 1234,
        "expected_resolution": "refund",
        "detail": [],
        "date_created": "2022-11-04T12:43:06.000-05:00",
        "last_updated": "2022-11-04T12:43:06.000-05:00",
        "status": "accepted"
}




Aceitar a resolução do player

Chamada:

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

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/950463475/expected_resolutions d '{"status":"accepted"}'

Resposta:

[
    {
        "player_role": "complainant",
        "user_id": 271942703,
        "expected_resolution": "change_product",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "accepted"
    }
]

Notas:
- Caso o "respondent" aceite a resolução do "complainant".
- Nos casos pertinentes, Mercado Livre dará ao comprador um rótulo para retornar o produto.
- A resolução a ser aceita é sempre a que fica pendente pela contraparte.



Carregar uma nova resolução

Chamada:

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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/950463475/expected_resolutions d '{"expected_resolution":"return_product"}'

Resposta:

[
    {
        "player_role": "complainant",
        "user_id": 271942703,
        "expected_resolution": "change_product",
        "date_created": "2018-03-07T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "rejected"
    },
{
        "player_role": "respondent",
        "user_id": 271944560,
        "expected_resolution": "return_product",
        "date_created": "2018-03-08T11:40:02.489-0300",
        "last_updated": "2018-03-08T11:40:02.489-0300",
        "status": "accepted"
    }
]

Nota:
No exemplo, o vendedor se recusa a trocar o produto que o comprador deseja, mas aceita que o produto seja retornado e que o dinheiro, seja devolvido para o comprador.

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/949903015/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

Chamada:

curl -X POST "https://api.mercadolibre.com/post-purchase/v1/claims/{claim_id}/actions/evidences?access_token=$ACCESS_TOKEN"

Exemplo:

curl -X POST "https://api.mercadolibre.com/post-purchase/v1/claims/949903015/actions/evidences?access_token=$ACCESS_TOKEN" -d {"attachments": [],"type": "shipping_evidence", "date_shipped": "2018-03-07T05:00:01.858-03:00", "shipping_company_name": "servientrega", "shipping_method": "mail" } 

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.

 

Campos del recurso

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. 

Notes:
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. Ej: 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/evidences

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/949903015/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/evidences

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/949903016/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/evidences

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/949903017/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/evidences

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/949903018/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/950463475/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/sites/$SITE_ID/v2/reasons/$REASON_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/sites/MLB/v2/reasons/PDD9502

Resposta:

{
 "id": "PDD9502",
 "flow": "unification_delivered",
 "name": "repentant_buyer",
 "detail": "Me arrependi da compra",
 "position": 101,
   "filter": {
    "group": [
      "expiring_food",
      "expiring_health"
    ],
    "site_id": [
      "MLB"
    ]
  },
  "settings": {
    "allowed_flows": [
      "returns"
    ],
    "expected_resolutions": [
      "change_product",
      "return_product"
    ],
    "rules_engine_triage": [
      "repentant"
    ]
  },
  "parent_id": "PDD9501",
  "children_title": null,
  "status": "active",
  "date_created": "2022-01-04T17:09:50.793Z",
  "last_updated": "2022-01-04T17:09:50.793Z"
}

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.