O que é um reclamação?

Uma reclamação é uma solicitação formal que os usuários podem apresentar para expressar insatisfação ou problemas relacionados a um processo específico. Essas reclamações são essenciais para resolver problemas, garantir uma experiência positiva para os usuários e manter a integridade do serviço. Existem quatro tipos de reclamações, cada um associado a um aspecto diferente da transação na plataforma. A seguir, detalhamos os tipos de reclamações possíveis:

• Order (Ordem): Reclamações geradas a partir de uma ordem de compra na plataforma Mercado Livre, como discrepâncias no produto, erros na quantidade ou outros problemas. Isso permite que os usuários comuniquem insatisfações e recebam soluções adequadas.
• Shipment (Envio): Reclamações relacionadas ao processo de entrega, incluindo atrasos, produtos danificados ou problemas logísticos. Essas queixas ajudam a resolver rapidamente os problemas, melhorando a experiência do cliente.
• Payment (Pagamento): Reclamações sobre pagamentos feitos através da plataforma, incluindo cobranças incorretas, falhas no processamento ou disputas de transações. Esse mecanismo permite resolver problemas e melhorar a confiabilidade do sistema de pagamentos.
• Purchase (Compra): Reclamações derivadas de uma compra na plataforma, focando em produtos defeituosos ou discrepâncias na descrição. Isso facilita uma rápida resolução e reforça a confiança do cliente na plataforma.

Notificações de reclamações

Na seção "Minhas aplicações", edite sua aplicação e habilite o tópico "Claims" no nosso feed. Isto permitirá receber notificações imediatas sempre que se inicie uma reclamação ou se produza alguma interação relacionada. Mantenha-se informado e a par de todas as atualizações importantes sobre as reclamações. Para mais detalhes, consulte a informação completa sobre as notificações de reclamações.

Possíveis filtros por Tópicos

Consultar uma reclamação

Para consultar a informação sobre uma reclamação, incluindo seu estado atual, é necessário consultar o recurso /claims/$CLAIMS

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.mercadolbre.com/post-purchase/v1/claims/5281510459

Resposta:

{
    "id": 5281510459,
    "resource_id": 2000008659553306,
    "status": "opened",
    "type": "mediations",
    "stage": "claim",
    "parent_id": null,
    "resource": "order",
    "reason_id": "PDD9949",
    "fulfilled": true,
    "quantity_type": "total",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 1550979062,
            "available_actions": []
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 1632279809,
            "available_actions": [
                {
                    "action": "send_message_to_complainant",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "open_dispute",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "return_review_fail",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "return_review_ok",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "refund",
                    "mandatory": false,
                    "due_date": null
                }
            ]
        },
        {
            "role": "mediator",
            "type": "internal",
            "user_id": 46622406,
            "available_actions": []
        }
    ],
    "resolution": null,
    "site_id": "MLA",
    "date_created": "2024-07-01T15:19:11.000-04:00",
    "last_updated": "2024-07-01T15:22:26.000-04:00",
    "related_entities": [
        "return"
    ]
}

Campos da resposta:

A resposta de um GET ao recurso /claims/$CLAIM_ID fornecerá os seguintes parâmetros

• id: ID da reclamação.
• resource_id: ID do recurso sobre o qual a reclamação é criada. Depende do "resource".
• status: estado da reclamação. Pode ter dois valores: opened e closed.
• type: Tipo de reclamação. Pode assumir um dos seguintes valores:
  • meditations: reclamação entre comprador e vendedor.
  • return: devolução do produto. Neste caso, não há mensagens. Para devoluções, siga a documentação de Trabalhar com devoluções.
  • fulfillment: Reclamação entre comprador e Mercado Livre com origem de compra com envio full.
  • ml_case: Cancelamento da compra por parte do comprador devido a envio demorado.
  • cancel_sale: cancelamento da compra por parte do vendedor.
  • cancel_purchase: cancelamento da compra por parte do comprador.
  • change: mudanças de produto. Indica que será realizada uma troca do produto.
  • service: Cancelamento de um serviço ordens bundle.
• stage: Etapa da reclamação. Pode assumir um dos seguintes valores:
  • claim: etapa da reclamação onde intervêm o comprador e o vendedor.
  • dispute: Etapa de mediação onde intervém um representante do Mercado Livre.
  • recontact: etapa em que uma das partes entra em contato após o fechamento da reclamação/disputa.
  • none: não se aplica.
  • stale: Etapa da reclamação onde intervêm o comprador e Mercado Livre para reclamações do tipo ml_case.
• 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
• reason_id: Razão/motivo pelo qual a reclamação foi criada. Interfere diretamente com as soluções que podem ser propostas
  • PNR: Produto Não Recebido
  • PDD: Produto Diferente ou Defeituoso
  • CS: Compra Cancelada
• fulfilled: Indica se a reclamação é iniciada por um produto entregue ou não. Pode ter dois valores: false | true.
• quantity_type: informa se a reclamação é parcial ou não
  • partial: indica que é uma reclamação parcial
  • total: indica que é uma reclamação completa
• players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
  • role: papel dentro da reclamação. Pode ser:
    • complainant: pessoa que reclama.
    • respondent: pessoa a quem se reclama.
    • mediator: pessoa que intervém para ajudar a resolver o problema.
    • purchase: comprador - Mercado Livre.
  • type: papel que a pessoa ocupa sobre a operação que está sendo reclamada. Pode variar de acordo com o recurso.
    • Payment: comprador ou coletor.
    • Order: comprador ou vendedor.
    • Shipment: receptor ou remetente.
  • user_id: ID do usuário no ML que cumpre o papel.
  • available_actions: lista de ações que podem ser executadas por cada uma das partes intervenientes:
    • 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 anexos).
      • send_message_to_mediator: enviar mensagem para o mediador (com ou sem anexos).
      • recontact(não disponível ainda): reabrir uma reclamação já encerrada, por meio de uma interação, como uma mensagem.
      • refund: devolver o dinheiro do comprador.
      • open_dispute: iniciar uma mediação.
      • send_potential_shipping: enviar uma promessa de envio, uma data.
      • add_shipping_evidence: publicar uma evidência de que o produto foi enviado.
      • send_attachments: enviar mensagem com anexos.
      • allow_return: gerar etiqueta de devolução.
      • allow_return_label: gerar etiqueta de devolução.
      • allow_partial_refund: devolução parcial do dinheiro do comprador para reclamações do tipo PDD.
      • send_tracking_number: enviar o número de rastreamento do envio (tracking number).
      • return_review_fail: realizar a revisão não ok de uma devolução.(tracking number).
      • return_review_ok: realizar a revisão ok de uma devolução.(tracking number).
    • mandatory: campo do tipo true onde a ação é obrigatória e deve ser cumprida antes do tempo limite.
    • due_date: tempo limite para realizar a ação.
• resolution: forma de resolução da reclamação.
  • reason: forma de resolução da reclamação
    • already_shipped: Produto a caminho
    • buyer_claim_opened: Encerramento da devolução por abertura de outra reclamação
    • buyer_dispute_opened: Encerramento da devolução por abertura de outra reclamação em disputa (com mediação do Mercado Livre)
    • charged_back: Encerramento por contracargo
    • coverage_decision: Disputa encerrada com cobertura pelo ML
    • found_missing_parts: Comprador encontrou as partes faltantes
    • item_returned: Produto devolvido
    • no_bpp: Encerramento sem cobertura por parte do ML
    • not_delivered: Produto não entregue
    • opened_claim_by_mistake: Comprador criou a reclamação por engano
    • partial_refunded: Reembolso parcial do pagamento concedido ao comprador
    • payment_refunded: Pagamento devolvido ao comprador
    • prefered_to_keep_product: Comprador preferiu ficar com o produto
    • product_delivered: Falha de um representante do Mercado Livre
    • reimbursed: Reembolso
    • rep_resolution: Falha de um representante do Mercado Livre
    • respondent_timeout: Vendedor não responde
    • return_canceled: Devolução cancelada pelo comprador
    • return_expired: Devolução vencida sem alteração de status no envio
    • seller_asked_to_close_claim: Vendedor pediu ao comprador que encerrasse a reclamação
    • seller_did_not_help: Comprador conseguiu resolver o problema sem a ajuda do vendedor
    • seller_explained_functions: Vendedor explicou como funcionava o item
    • seller_sent_product: Vendedor enviou o produto
    • timeout: Encerramento por timeout de ação ao comprador
    • warehouse_decision: Encerramento por demora na revisão do produto no Warehouse
    • warehouse_timeout: Encerramento por demora na revisão do produto no Warehouse
    • worked_out_with_seller: Comprador resolveu com o vendedor fora do ML
    • low_cost: Encerramento porque o custo do envio é maior que o do produto
    • item_changed: Encerramento porque a troca foi feita com sucesso
    • change_expired: A troca não foi realizada e o tempo permitido expirou
    • change_cancelled_buyer: Encerramento proativo de uma troca pelo comprador
    • change_cancelled_seller: Encerramento proativo de uma troca pelo vendedor
    • change_cancelled_meli: Encerramento de uma troca pelo Meli
    • shipment_not_stopped: Encerramento porque o envio não conseguiu ser interrompido
    • cancel_installation: Cancelamento de serviço de instalação
  • data_created: Data de resolução/encerramento da reclamação
  • benefited: Beneficiários da resolução (complainant**|**respondent**|**)
  • closed_by: Ator que encerrou a reclamação (mediator | buyer)
  • applied_coverage: Cobre a reclamação (false | true)
  • site_id: ID do site onde a reclamação se desenvolve
  • created_date: Data de criação/abertura da reclamação
  • last_updated: Data da última atualização sobre a reclamação
  • related_entities: Contém uma lista de entidades relacionadas à reclamação. Caso não haja devoluções, os IDs terão vda.
  • return: Indica que a reclamação tem uma devolução atribuída

Detalhes de uma reclamação

Para acessar informações detalhadas sobre uma reclamação, incluindo seu estado atual, é necessário consultar o recurso /claims/$CLAIMS/detail

Chamada:

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

Exemplo:

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

Resposta:

{
    "due_date": "2023-07-19T22:33:00.000-04:00",
    "action_responsible": "mediator",
    "title": "Devolución en mediación con Mercado Libre",
    "description": "Intervinimos para ayudar. Te escribiremos antes del miércoles 19 de julio.",
    "problem": "Nos dijiste que el producto llegó dañado"
}

Campos da resposta

A resposta de um GET ao recurso /claims/detail fornecerá os seguintes campos:

• due_date: Data limite para solucionar a reclamação
• action_responsible: Responsável pela ação. Pode ter dois valores: seller | buyer | mediator
• title: Título que detalha o estado da reclamação
• description: Descrição detalhada do estado em que se encontra a reclamação
• problem: Problema pelo qual a reclamação foi gerada

Buscar reclamações

A busca de reclamações fornece uma visão completa de todas as reclamações associadas a um vendedor específico. Esta ferramenta ajuda a monitorar e gerenciar as incidências relatadas.

Parâmetros:

Você pode consultar uma reclamação realizando uma busca no recurso de reclamações utilizando diversos parâmetros:

Chamada:

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

Resposta:

{
   "paging": {
       "total": 316,
       "offset": 0,
       "limit": 30
   },
   "data": [
       {
           "id": 5187110991,
           "resource_id": 2000005489080336,
           "status": "opened",
           "type": "mediations",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9528",
           "fulfilled": true,
           "quantity_type": null,
           "players": [
               {
                   "role": "complainant",
                   "type": "buyer",
                   "user_id": 1354382565,
                   "available_actions": []
               },
               {
                   "role": "respondent",
                   "type": "seller",
                   "user_id": 1295357671,
                   "available_actions": [
                       {
                           "action": "send_message_to_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2023-04-18T12:06:48.000-04:00",
           "last_updated": "2023-04-18T12:07:25.000-04:00"
       },
       {
           "id": 5173473377,
           "resource_id": 2000005051445424,
           "status": "opened",
           "type": "returns",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9502",
           "fulfilled": true,
           "quantity_type": null,
           "players": [
               {
                   "role": "complainant",
                   "type": "buyer",
                   "user_id": 1299347553,
                   "available_actions": []
               },
               {
                   "role": "respondent",
                   "type": "seller",
                   "user_id": 1295357671,
                   "available_actions": [
                       {
                           "action": "send_message_to_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2023-02-03T16:25:40.000-04:00",
           "last_updated": "2023-03-13T22:41:49.000-04:00"
       }
…
    ]
}

Personalizar a busca de reclamações

A busca de reclamações pode gerar uma ampla variedade de resultados, dependendo dos parâmetros utilizados. Para otimizar esse processo, são oferecidas diversas opções que melhoram a eficiência da busca.

Parâmetros:

Chamada:

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

Resposta:

{
   "paging": {
       "total": 125,
       "offset": 0,
       "limit": 30
   },
   "data": [
       {
           "id": 5172740586,
           "resource_id": 2000005028386014,
           "status": "opened",
           "type": "returns",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9502",
           "fulfilled": true,
           "quantity_type": null,
           "players": [
               {
                   "role": "complainant",
                   "type": "buyer",
                   "user_id": 1298667949,
                   "available_actions": []
               },
               {
                   "role": "respondent",
                   "type": "seller",
                   "user_id": 1295357671,
                   "available_actions": [
                       {
                           "action": "send_message_to_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2023-01-31T09:18:01.000-04:00",
           "last_updated": "2023-02-13T23:57:02.000-04:00",
           "return": null
       },
       {
           "id": 5175655066,
           "resource_id": 2000005121967322,
           "status": "opened",
           "type": "mediations",
           "stage": "dispute",
           "parent_id": null,
           "resource": "order",
           "reason_id": "PDD9553",
           "fulfilled": true,
           "quantity_type": null,
           "players": [
               {
                   "role": "complainant",
                   "type": "buyer",
                   "user_id": 1310908303,
                   "available_actions": []
               },
               {
                   "role": "respondent",
                   "type": "seller",
                   "user_id": 1295357671,
                   "available_actions": [
                       {
                           "action": "send_message_to_mediator",
                           "mandatory": false,
                           "due_date": null
                       }
                   ]
               }
           ],
           "resolution": null,
           "site_id": "MLM",
           "date_created": "2023-02-15T08:59:41.000-04:00",
           "last_updated": "2023-02-15T09:00:21.000-04:00",
           "return": null
       }
   ]
}

Obter detalhes do motivo pelo qual a reclamação foi iniciada

Para obter detalhes sobre o motivo do início de uma reclamação, deve-se consultar o recurso /claims/reasons/$REASON_ID. Este acesso fornece informações detalhadas e permite o uso de parâmetros específicos.

Parâmetros:

Chamada:

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

Exemplo:

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

Resposta:

{
    "id": "PDD9939",
    "flow": "post_purchase_delivered",
    "name": "repentant_buyer",
    "detail": "Llegó lo que compré en buenas condiciones pero no lo quiero",
    "position": 10,
    "filter": {
        "group": [
            "generic",
            "fashion",
            "installable_autoparts",
            "expiring_food",
            "expiring_health"
        ],
        "site_id": [
            "MLC",
            "MCO",
            "MLU",
            "MPE",
            "MLM",
            "MLA",
            "MLB",
            "MEC",
            "CBT"
        ]
    },
    "settings": {
        "allowed_flows": [
            "returns"
        ],
        "expected_resolutions": [
            "change_product",
            "return_product"
        ],
        "rules_engine_triage": [
            "repentant"
        ]
    },
    "parent_id": null,
    "children_title": null,
    "status": "active",
    "date_created": "2024-01-15T18:07:42.632-04:00",
    "last_updated": "2024-03-12T20:20:21.795-04:00"
}

Campos da resposta

A resposta de um GET ao recurso /claims/reasons/$REASON_ID fornecerá os seguintes campos:

• id: ID da reclamação
• flow: Fluxo da reclamação
• name: Nome da reason
• detail: Detalhe da reason
• position: Funciona como sort_by, mas por padrão. Sem sort_by, o sistema ordena as razões por posição ascendente.
• group: O group indica a vertical do item. Pode assumir um dos seguintes valores:
  • generic
  • fashion
  • installable_autoparts
  • expiring_food
  • expiring_health
• site_id: ID do site onde a reclamação é desenvolvida
• settings: Pode assumir um dos seguintes valores:
  • allowed_flows: Indica em quais fluxos podemos visualizar esta reason
  • expected_resolutions: Possíveis resoluções esperadas por quem reclama
    • product
    • refund
    • other
  • rules_engine_triage: Este item define o tag para a categorização de triage, com valores como:
    • repentant
    • defective
    • incomplete
    • different
    • not_working
• parent_id: Reason pai
• children_title: Este valor é usado para tipificar em pós-compra, atribuindo o título a razões filhas daquelas que contêm este atributo. Apenas razões têm este atributo.
• status: Estado da reason
• date_created: Data de criação da reason
• last_updated: Data da última atualização da reason

Histórico de ações da reclamação

O histórico de ações de uma reclamação detalha as ações realizadas, quem as executa e quando, permitindo um acompanhamento do processo.

Chamada:

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

Exemplo:

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

Resposta:

[
    {
        "action_name": "send_message_to_mediator",
        "player_role": "complainant",
        "action_reason_id": "",
        "claim_stage": "dispute",
        "claim_status": "opened",
        "date_created": "2023-02-15T15:44:42.000-04:00"
    },
    {
        "action_name": "open_dispute",
        "player_role": "complainant",
        "action_reason_id": "",
        "claim_stage": "claim",
        "claim_status": "opened",
        "date_created": "2023-02-15T15:44:42.000-04:00"
    },
    {
        "action_name": "generate_return",
        "player_role": "complainant",
        "action_reason_id": null,
        "claim_stage": "claim",
        "claim_status": "opened",
        "date_created": "2023-02-15T15:43:15.000-04:00"
    },
    {
        "action_name": "allow_return",
        "player_role": "respondent",
        "action_reason_id": null,
        "claim_stage": "claim",
        "claim_status": "opened",
        "date_created": "2023-02-15T15:40:15.000-04:00"
    },
    {
        "action_name": "open_claim",
        "player_role": "complainant",
        "action_reason_id": null,
        "claim_stage": null,
        "claim_status": null,
        "date_created": "2023-02-15T15:35:04.000-04:00"
    }
]

Campos da resposta

A resposta de um GET ao recurso /claims/actions-history fornecerá os seguintes campos:

• action_name: Nome da ação realizada
• player_role: Player que realiza a ação
• action_reason_id: ID da ação realizada
• claim_stage: Etapa em que 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

Histórico de estados da reclamação

O histórico de estados de uma reclamação fornece informações sobre a etapa e o estado da reclamação no momento de cada ação.

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/5175748308/status-history

Resposta:

[
    {
        "stage": "dispute",
        "status": "opened",
        "date": "2023-02-15T15:44:42.000-04:00",
        "change_by": "complainant"
    },
    {
        "stage": "claim",
        "status": "opened",
        "date": "2023-02-15T15:35:04.000-04:00",
        "change_by": "complainant"
    }
]

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

O recurso /affects-reputation permite aos integradores identificar se uma reclamação específica impacta a reputação do vendedor, mediante a execução da 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": "not_applies",
    "has_incentive": false,
    "due_date": null
}

Campos da resposta

A resposta de um GET ao recurso /claims/affects-reputation fornecerá os seguintes campos:

• affects_reputation: Informa se a reclamação afeta a reputação do vendedor. Pode assumir um dos seguintes valores:
  • affected: Afeta reputação.
  • not_affected: Não afeta a reputação.
  • not_applies: Pagamentos não vinculados a pedidos do marketplace ou Shops.
• has_incentive: Quando este campo devolve true, se o vendedor responder satisfatoriamente dentro das primeiras 48 horas, não afetará sua reputação. Se for false, o vendedor ainda tem as mesmas 48 horas, mas não garantimos que a reputação do vendedor não seja afetada
• due_date: Data limite para resolver a reclamação

Seguinte: Gerenciar mensagens de uma reclamação