Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 22/02/2024

Reclamações

Importante:
Se você tiver alguma dúvida como comprador ou vendedor, pode entrar em contato no canal de ajuda do Mercado Livre. Você também encontrará informações sobre pagamentos, publicações, vendas, envios e muito mais.

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.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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"
        } 
]}
Nota:
O campo “quantity_type” inicialmente exibirá apenas o valor “total” e futuramente exibirá o valor “parcial”. Indica se uma devolução corresponde a todos os produtos da orden ou apenas a alguns.

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/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/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/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/v1/claims/{claim_id}

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/{claim_id}/messages

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/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/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/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/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/v1/claims/$CLAIM_ID/messages

      Exemplo:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/{claim_id}/attachments/{attach_id}/download

      Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID/attachments/$ATTACH_ID

      Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID

      Exemplo:

      curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID/messages

      Exemplo:

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

      Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID/expected_resolutions

      Exemplo:

      curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID/expected_resolutions'

      Exemplo:

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

      Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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/v1/claims/{claim_id}/actions/evidences?access_token=$ACCESS_TOKEN"

      Exemplo:

      curl -X POST "https://api.mercadolibre.com/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/v1/claims/$CLAIM_ID/evidences

      Exemplo:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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",
                      "file_url": "/mediations/claims/attachments/render/193294183"
                  }
              ],
              "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/v1/claims/$CLAIM_ID/evidences

      Exemplo:

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

      Exemplo:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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",
                      "file_url": "/mediations/claims/attachments/render/193294183"
                  }
              ],
              "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/v1/claims/$CLAIM_ID/evidences

      Exemplo:

      curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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",
                      "file_url": "/mediations/claims/attachments/render/193294183"
                  }
              ],
              "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/v1/claims/$CLAIM_ID/evidences

      Exemplo:

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

      Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/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.