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 03/07/2024

Que é um reclamação?

Um reclamação é uma solicitação formal que os usuários podem apresentar para expressar insatisfação ou problemas relacionados com um processo específico. Estes reclamos são essenciais para resolver problemas, garantir uma experiência positiva para os usuários e manter a integridade do serviço. Só quatro tipos de recursos podem gerar reclamos, cada um associado a um aspecto diferente da transação na plataforma. A continuação, se detalham os recursos possíveis:

  • Order (Ordem): Este tipo de reclamação se gera a partir de uma ordem de compra realizada na plataforma de Mercado Livre. Os usuários podem apresentar um reclamação se experimentam problemas com a ordem, como discrepâncias no produto recebido, erros na quantidade, ou qualquer outro inconveniente relacionado com a ordem. Isto assegura que os usuários possam comunicar qualquer insatisfação e receber uma solução adequada, mantendo assim a confiança e a integridade do serviço.
  • Shipment (Envio): Os reclamos do tipo Shipment se originam a partir do processo de envio de uma compra na plataforma de Mercado Livre. Os usuários podem gerar um reclamação se enfrentam problemas com a entrega do produto, como atrasos, produtos danificados durante o envio ou problemas logísticos. Estes reclamos permitem resolver rapidamente as incidências, melhorando a experiência do cliente.
  • Payment (Pagamento): Este tipo de reclamação se cria em relação com um pagamento realizado através da plataforma de Mercado Livre. Os usuários podem apresentar um reclamação tanto por pagamentos associados a compras na plataforma como por qualquer outro tipo de transação realizada mediante o sistema de pagamentos de Mercado Livre. Os problemas que podem motivar estes reclamos incluem encargos incorretos, falhas no processamento do pagamento, ou disputas relacionadas com a transação. Este mecanismo não só permite aos usuários resolver rapidamente seus problemas, mas também ajuda a plataforma a identificar e corrigir possíveis falhas no seu sistema de pagamentos, melhorando a confiabilidade e a satisfação do cliente.
  • Purchase (Compra): Os reclamos do tipo Purchase se originam a partir de uma compra realizada na plataforma de Mercado Livre. Estes reclamos se centram na transação de compra e abordam problemas como produtos defeituosos, discrepâncias entre a descrição do produto e o recebido, entre outros inconvenientes. Ao permitir que os usuários apresentem estes reclamos, se melhora a transparência e se facilita uma rápida resolução, o que não só reforça a confiança do cliente na plataforma, mas também ajuda a identificar e solucionar falhas no processo de compra.

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

Filtro Type Value Detalhe value
fulfilled Boolean true - false Indica basicamente se a reclamação é PDD (true) ou PNR (false)
event_type String insert, update Tipo de operação realizada na reclamação
stage String claim, dispute, recontact, stale, none Etapa da reclamação
resource String payment, order, shipment, purchase Recurso sobre o qual a reclamação é criada
site_id String mlb, mlm, mla, mlu, mco, mlc, mpe, mlv, mec, mcr, mbo, mrd, mpa, mgt, mpy, msv Site de procedência
type String mediations, returns, ml_case, cancel_sale, fulfillment, cancel_purchase Tipo de reclamação
parent_id
test_claim Boolean true - false Indica se a reclamação é de teste (true) ou não (false)
status Boolean opened - closed Indica o estado da reclamação seja (opened) ou (closed)

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/detail 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. Deve ser realizado pelo front do Mercado Livre ou Mercado Pago.
        • 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: Oferecer reembolso parcial do dinheiro ao comprador. Deve ser realizado pelo front do Mercado Livre.
        • send_tracking_number: enviar o número de rastreamento do envio (tracking number).
        • return_review_fail: realizar una revisión fallida de una devolución.
        • return_review_ok: realizar una revisión ok de una devolución.
      • 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 parâmetros:

  • 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 é essencial para monitorar e gerenciar eficientemente as incidências relatadas.

Parâmetros:

Você pode recuperar uma reclamação realizando uma busca no sistema de reclamações utilizando diversos parâmetros. Os parâmetros de busca disponíveis são os seguintes:

Query params Type Values Detalhe value
date_created date (yyyy-MM-dd'T'HH:mm:ss.SS SZ) Data de criação da reclamação. Ex.: 2018-05-01T00:00:00.000-0400
id Long {claimId} ID da reclamação
last_updated date (yyyy-MM-dd'T'HH:mm:ss.SS SZ) Data da última atualização da reclamação. Ex.: 2018-05-01T00:00:00.000-0400
order_id Long {orderId} Reclamação cujo recurso pode ou não ser um pedido, mas tal recurso está relacionado ao pedido do order_id inserido
player_role String {userId} ID do usuário interveniente na reclamação
player_user_id String {userId} ID do usuário interveniente na reclamação
reason_id Long {reasonId} Razão/motivo pelo qual a reclamação foi criada
resource String shipment, payment, order, purchase Recurso sobre o qual a reclamação foi criada
resource_id Long {ID do recurso} ID do recurso sobre o qual a reclamação foi criada
site_id String {enabledSites} ID do site onde a reclamação é desenvolvida
stage String claim, dispute, recontact, stale, none Etapa da reclamação
status String mediations, returns, ml_case, cancel_sale, cancel_purchase, fulfillment, change Tipo de reclamação
labels.name String test_claim, claim_version, reason_flow, reputation, forward_label, etc... Este é o nome do label que faz parte de uma reclamação, conforme aplicável. Por exemplo, se o label tiver como nome test_claim, então corresponderá a uma reclamação especificamente designada como teste. Outros valores também podem ser usados aqui para identificar diferentes labels nas reclamações conforme necessário.
Nota:
Com o recurso de busca de reclamações, você poderá considerar certos filtros para obter resultados mais específicos conforme necessário.

Ao buscar por pack_id e order_id, você obterá todas as reclamações relacionadas indiretamente ao ID inserido. Por exemplo, ao inserir um pack_id, a busca retornará todas as reclamações vinculadas a esse pack por meio de seus pedidos, remessas e pagamentos. Da mesma forma, ao buscar por order_id, serão mostradas todas as reclamações associadas a esse pedido específico. Essa capacidade permite que você gerencie e resolva incidentes de maneira mais eficaz.

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"
       }
…
    ]
}
Nota:
1. Tipificação de reclamações: Cada tipificação de reclamações está associada a um conjunto específico de razões. Para obter detalhes sobre o motivo do início de uma reclamação, é necessário consultar a API de reasons.

2. Tipos de papéis dentro da reclamação: Os papéis dos players estão estritamente definidos e não podem ser outros. O player mediator intervém no claim apenas quando se encontra nas etapas de disputa ou recontact. Cada player pode ter uma lista de ações, mas na reclamação, apenas um player tem a ação obrigatória em todo o processo.

Personalizar a busca de reclamações

A busca de reclamações através do serviço de buscas 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:

Query params Type Values Detalhe value
offset Integer Nível de deslocamento no conjunto de dados resultado da busca
limit Integer Quantidade limite de resultados que deseja que retorne a busca. Por padrão são 30 resultados e como máximo são 100 resultados
sort String field: date_asc, date_desc, qualquer campo da reclamação Ordenação dos resultados da busca
range (field) :after: "yyyy-MM-dd'T'HH:mm:ss.SSZ" before: "yyyy-MM-dd'T'HH:mm:ss.SSZ" String field: Qualquer data da reclamação Busca entre/por intervalo de datas

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 para realizar buscas mais eficazes.

Parâmetros:

Query params Type Values Detalhe value
flow string cancel_sale, distant_agencies, fulfillment_delivered, fulfillment_undelivered, label_unavailable, mediations, mediations_delivered, mediations_undelivered, no_shipping_options, reservation, returns, unification_delivered Permite obter reasons PDD ou PNR
delivered string true, false Permite obter reasons PDD ou PNR
deep boolean true, false Permite obter a árvore de dependências da reason consultada
name string wrong_shipment_cost, wrong_seller_address, wrong_buyer_address, unavailable_pick_up, unknown_buyer, unknown_seller, unknown_shipment_policy, unavailable_incorrect_shipping, shipment_type_not_allowed_daft, unavailable_correct_shipping, unavailable_product, unavailable_payment_method, unavailable_buyer_item_report, alignment_prices_taxes, alignment_discounts, safe_review, safety_notifications, seller_rate_modification, unauthorized_transference, seller_address_not_allowed, return_request_return, represent_buyer_claim, represent_buyer_dispute, alignment_packaging, improper_tracking, improper_package_weight, payment_method_fraud, no_agreed_delivery, not_expected_quality_offer, not_expected_quality_item, wrong_warranty, misleading_promotion, returned_service, finished_return_automatic, finished_return_with_request, return_claim_not_accept, return_claim_accept, return_claim_cancel, return_claim_item_restock, return_claim_item_refurbished, return_claim_item_lost, wrong_pack_service, wrong_pack_service_transport, buyer_return_pack_service, seller_return_pack_service, wrong_pack_service_provider, wrong_pack_service_time, wrong_pack_service_repack, wrong_pack_service_delivery, buyer_dispute_delivery, buyer_dispute_delivery_not_show, buyer_dispute_delivery_not_contact, buyer_dispute_delivery_not_receive, buyer_dispute_delivery_no_show, buyer_dispute_delivery_no_call, wrong_pack_service_failed, buyer_dispute_buyer_claim_delivery, delivery_wrong_seller, delivery_wrong_buyer, delivery_same_state, delivery_same_city, delivery_same_zip_code, delivery_wrong_shipping, delivery_lost, delivery_damaged, delivery_delayed, delivery_wrong_address, delivery_wrong_city, delivery_wrong_state, delivery_wrong_zip_code, delivery_wrong_country, delivery_wrong_date, delivery_wrong_time, delivery_wrong_shipping_service, delivery_wrong_pack_service, wrong_pack_service_full, wrong_pack_service_partial, wrong_pack_service_product_wrong, wrong_pack_service_product_changed, wrong_pack_service_restock, wrong_pack_service_no_restock, wrong_pack_service_refurbished, wrong_pack_service_lost, wrong_pack_service_failed, wrong_pack_service_provider, wrong_pack_service_time, wrong_pack_service_repack, buyer_dispute_buyer_claim_delivery

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 parâmetros:

  • 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 preciso e estratégico 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 parâmetros:

  • 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, permitindo um acompanhamento preciso e estratégico do processo

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 facilita aos integradores a capacidade de determinar se uma reclamação específica impacta a reputação do vendedor, mediante a execução da chamada correspondente

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 parâmetros:

  • affects_reputation: Informa se a reclamação afeta a reputação do vendedor. Pode assumir um dos seguintes valores:
    • affected: Afeta reputação (Só consideramos que afetou quando a reclamação está fechada)
    • not_affected: Não afeta a reputação
    • not_applies: Não se aplica
  • 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