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 02/06/2025

O que é uma devolução?

Uma devolução é o processo através do qual um comprador pode devolver um produto ao vendedor. Este procedimento pode ser ativado por diversas razões, tais como discrepâncias entre a descrição do produto e o seu estado real, problemas de funcionamento, ou até mesmo uma mudança de opinião por parte do comprador. O bom gerenciamento das devoluções é fundamental para manter a confiança e satisfação do cliente, garantindo que qualquer problema seja resolvido de forma transparente e eficiente.



Nota:

O recurso /post-purchase/v2/claims/$CLAIM_ID/returns é uma ferramenta que permite acessar os detalhes específicos de cada devolução, identificada pelo seu $CLAIM_ID, incluindo seus tipos, subtipos e estados.

No Mercado Livre, gerenciamos vários tipos de devoluções para garantir uma experiência de compra transparente e justa:

  • claim: Devolução iniciada através de uma reclamação do comprador.
  • dispute: Devolução resultante de uma disputa entre o comprador e o vendedor.
  • automatic: Devolução iniciada pelo comprador, processada automaticamente pelo sistema.

Esses diferentes tipos de devoluções nos permitem abordar cada situação de maneira específica, garantindo que tanto compradores quanto vendedores recebam o suporte adequado em cada etapa do processo pós-compra.

Gerenciar uma devolução

Para identificar corretamente uma devolução, fazemos as seguintes recomendações:

  1. Monitorar a notificação da reclamação: Ouça o feed de reclamações (feed claims), que contém as informações do pedido no qual a reclamação se originou.
  2. Consultar o recurso /claims/$CLAIMS para acessar o campo "related_entities", que oferece uma lista de entidades vinculadas à reclamação. Se existir o valor "return" significa que há uma devolução associada a esta reclamação. Agora você pode consultar o recurso de Returns para obter os detalhes da devolução e tomar as medidas necessárias dentro dos prazos estabelecidos.

Para mais informações, consulte a documentação de Gestão de Reclamações.

Returns

Foram feitas melhorias para simplificar e otimizar as informações retornadas, eliminando dados redundantes e adicionando campos essenciais.



Consultar uma devolução

Para consultar uma devolução, realize a chamada para post-purchase/v2/claims/$CLAIM_ID/returns, especificando o $CLAIM_ID. Isso fornecerá informações detalhadas sobre a devolução associada ao respectivo pedido.



Chamada:

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

Resposta:

{
    "id": 57341011,
    "last_updated": "2024-09-10T17:26:41.704+00:00",
    "shipments": [
        {
            "shipment_id": 43810672299,
            "status": "delivered",
            "tracking_number": null,
            "destination": {
                "name": "warehouse",
                "shipping_address": {
                    "address_id": 0,
                    "address_line": "Av. Dr. Antonio Joao Abdalla, 3333",
                    "street_name": "Av. Dr. Antonio Joao Abdalla",
                    "street_number": "3333",
                    "comment": "Mercado Livre",
                    "zip_code": "07750020",
                    "city": {
                        "id": "QlItU1BDYWphbWFy",
                        "name": "Cajamar"
                    },
                    "state": {
                        "id": "BR-SP",
                        "name": "São Paulo"
                    },
                    "country": {
                        "id": "BR",
                        "name": "Brasil"
                    },
                    "neighborhood": {
                        "id": null,
                        "name": "Empresarial Colina"
                    },
                    "municipality": {
                        "id": null,
                        "name": null
                    }
                }
            },
            "type": "return"
        },
        {
            "shipment_id": 43825249694,
            "status": "pending",
            "tracking_number": null,
            "destination": {
                "name": "seller_address",
                "shipping_address": {
                    "address_id": 1351779578,
                    "address_line": "Rua Rio Grande SN",
                    "street_name": "Rua Rio Grande",
                    "street_number": "SN",
                    "comment": "Referência: teste",
                    "zip_code": "09831740",
                    "city": {
                        "id": "BR-SP-39",
                        "name": "São Bernardo do Campo"
                    },
                    "state": {
                        "id": "BR-SP",
                        "name": "São Paulo"
                    },
                    "country": {
                        "id": "BR",
                        "name": "Brasil"
                    },
                    "neighborhood": {
                        "id": null,
                        "name": "Rio Grande"
                    },
                    "municipality": {
                        "id": null,
                        "name": null
                    }
                }
            },
            "type": "return_from_triage"
        }
    ],
    "refund_at": "delivered",
    "date_closed": null,
    "resource_type": "order",
    "date_created": "2024-09-06T16:24:26.636+00:00",
    "claim_id": 5298178312,
    "status_money": "retained",
    "resource_id": 2000009229357366,
    "orders": [
        {
            "order_id": 2000009229357366,
            "item_id": "MLB3840513395",
            "variation_id": null,
            "context_type": "total",
            "total_quantity": "1.0",
            "return_quantity": "1.0"
        }
    ],
    "subtype": "return_total",
    "status": "delivered",
    "related_entities": [
        "reviews"
    ],
    "intermediate_check": true
}

Campos da resposta

Para que compreendam melhor as alterações realizadas no recurso /returns, preparamos uma lista dos campos que foram removidos e os que foram adicionados.

Campo Tipo de atualização Comentários
warehouse_review Removido Agora pode ser obtido através do endpoint de retorno: 
X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' -H 'Authorization: Bearer $ACCESS_TOKEN'
seller_review Removido Agora pode ser obtido através do endpoint de retorno: 
X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' -H 'Authorization: Bearer $ACCESS_TOKEN'
type Removido -
shipping Atualizado Agora é chamado shipments ao invés de shipping e é um array que diferencia os shipments com seu type.
resource Atualizado Agora é chamado resource_type
shipping.origin Removido A partir de agora, não será mais exibido o endereço de origem, apenas o de destino.
status Atualizado Serão retornados mais estados do que antes.
shipping.lead_time Removido -
shipping.status_history Removido Agora pode ser obtido através do endpoint history: 
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPPING_ID/history
id Adicionado Identificador da devolução
shipments.destination.shipping_address Adicionado Agora é exibido o endereço de destino
shipments.id Atualizado Agora é chamado shipment_id
orders Adicionado Lista de pedidos com suas informações
related_entities Adicionado Lista de entidades relacionadas
intermediate_check Adicionado Este campo indica que é um MPT


A resposta de um GET ao recurso /v2/claims/$CLAIM_ID/returns fornecerá os seguintes campos:

  • shipments: lista de envios associados à devolução.
    • shipment_id: identificador do envio.
    • status: estado em que o envio se encontra. Possíveis valores:
      • pending: quando o envio é gerado.
      • ready_to_ship: etiqueta pronta para envio.
      • shipped: enviado.
      • not_delivered: não entregue.
      • delivered: entregue.
      • cancelled: envio cancelado.
    • tracking_number: número de rastreamento do envio da devolução.
    • destination: informações do destino do envio.
      • name: nome do destino. Possíveis valores:
        • seller_address: endereço do vendedor.
        • warehouse: depósito do Mercado Livre.
        • shipping_address: endereço de envio.
          • address_id: identificador do endereço.
          • address_line: endereço completo.
          • street_name: nome da rua.
          • street_number: número da rua.
          • comment: comentário adicional.
          • zip_code: código postal.
          • city: cidade (objeto com id e name).
          • state: estado (objeto com id e name).
          • country: país (objeto com id e name).
          • neighborhood: bairro (objeto com id e name).
          • municipality: município (objeto com id e name).
    • type: tipo de envio. Possíveis valores:
      • return: envio com destino ao vendedor.
      • return_from_triage: envio com destino ao depósito para revisão intermediária.
    • refund_at: quando o dinheiro é devolvido ao comprador. Possíveis valores:
      • shipped: quando o comprador realiza o envio da devolução.
      • delivered: 3 dias após o vendedor receber o envio.
      • n/a: para casos de baixo custo que não geram devolução.
  • date_closed: data em que a devolução foi encerrada.
  • resource_type: nome do recurso associado à devolução. Possíveis valores:
    • order
    • claim
    • shipment
    • other
  • date_created: data de criação da devolução.
  • claim_id: ID da reclamação associada à devolução.
  • status_money: status do dinheiro. Possíveis valores:
    • retained: dinheiro na conta, mas retido.
    • refunded: dinheiro devolvido ao comprador.
    • available: dinheiro disponível.
  • resource_id: identificador do recurso associado.
  • orders: lista de pedidos associados.
    • order_id: identificador do pedido.
    • item_id: identificador do item.
    • variation_id: identificador da variação.
    • context_type: contexto do item. Possíveis valores:
      • total: devolução de todo o pedido.
      • partial: devolução parcial.
      • incomplete: unidades não recebidas, não podem ser devolvidas.
    • total_quantity: quantidade total de itens.
    • return_quantity: quantidade de itens a serem devolvidos.
  • subtype: subtipo da devolução. Possíveis valores:
    • low_cost: devolução automática de baixo custo.
    • return_partial: devolução parcial.
    • return_total: devolução total.
  • status: status atual da devolução. Possíveis valores:
    • pending_cancel: em processo de cancelamento
    • pending: devolução criada e envio sendo iniciado
    • failed: não foi possível criar e/ou iniciar o envio
    • shipped: devolução enviada, dinheiro retido
    • pending_delivered: em processo de entrega
    • return_to_buyer: devolução retornando ao comprador
    • pending_expiration: em processo de expiração
    • scheduled: agendada para retirada
    • pending_failure: em processo de falha
    • label_generated: devolução pronta para envio
    • cancelled: devolução cancelada, dinheiro disponível
    • not_delivered: devolução não entregue
    • expired: devolução expirada
    • delivered: devolução recebida pelo vendedor
  • related_entities: entidades relacionadas. Exemplo: ["reviews"]
  • intermediate_check: indica se houve verificação intermediária. Possíveis valores:
    • true
    • false
Nota:
Lembre-se de que o recurso /shipments/$SHIPMENT_ID/costs devolve os custos do envio que o usuário deve enfrentar.

Reviews

O recurso /reviews fornece informações sobre a revisão de devoluções, seja de MELI (armazém), do vendedor ou apelações. Para identificar as devoluções que têm revisões, é necessário consultar o campo “related_entities”, que conterá o item "reviews".


Importante:
Atualmente não é possível realizar apelações através da API.

O que são as apelações?

As apelações ocorrem quando uma devolução foi revisada pela equipe de triage, e o vendedor pode contestar a decisão.

Qual é a diferença entre apelações e revisão fallida de devoluções?

Uma revisão fallida de devolução ocorre quando não há revisão por parte da triage, e o vendedor é responsável por essa revisão, indicando que o produto chegou com algum problema.


Chamada:

  
    curl -L -X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews' \
    -H 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:

  
    curl -L -X GET 'https://api.mercadolibre.com/post-purchase/v1/returns/57341011/reviews' \
       -H 'Authorization: Bearer $ACCESS_TOKEN'

Resposta:

  
    {
   "reviews": [
       {
           "resource": "order",
           "resource_id": 2000008958860420,
           "method": "triage",
           "resource_reviews": [
               {
                   "stage": "",
                   "status": "success",
                   "product_condition": "unsaleable",
                   "product_destination": "seller",
                   "reason_id": "accepted",
                   "benefited": "buyer",
                   "seller_status": "failed",
                   "seller_reason": "SRF2",
                   "benefited_type": null,
		           "benefited_reason": null,
		           "missing_quantity": 1
               }
           ],
           "date_created": "2024-08-27T14:58:21.978Z",
           "last_updated": "2024-08-27T14:58:21.978Z"
       }
   ]
}

Campos da resposta

reviews (lista): Lista das revisões finalizadas pelo processo de triage e pelo vendedor.

resource (string): Tipo de recurso que estará relacionado com a revisão. Para o carrinho, será "order". Nos casos diferentes do carrinho, o recurso também será "order".

resource_id (string): ID do recurso indicado em "resource".

method (string): Indica qual é o método de revisão da devolução. Valores possíveis:

  • none: revisão do vendedor.
  • triage: revisão realizada pela triage do MELI.

date_created (string): Data de criação da revisão.

last_updated (string): Data de atualização da revisão.

resource_reviews (lista): Lista de revisões realizadas sobre o recurso.

stage (string): De acordo com este campo, é possível identificar os casos que podem ter apelações do vendedor e os de timeout. Valores possíveis:

  • closed: a revisão foi finalizada, seja por uma triage que pode incluir uma apelação do vendedor ou uma revisão de devolução fallida.
  • pending: a revisçao de devolução fallida está pendente de resolução.
  • seller_review_pending: revisão de triage que pode ter uma apelação do vendedor e está pendente.
  • timeout: o tempo para que a triag analise o produto expirou.

status (string): Estado da revisão realizada pela triage. Valores possíveis:

  • success: revisão realizada e o produto está OK.
  • failed: indica que o operador detectou que o produto tem algum problema. O campo "product_condition" detalha essa condição do produto.
  • "" não há uma revisão da triage.
  • null: é uma revisão realizada pelo vendedor.

product_condition (string): Condição do produto. Valores possíveis:

  • saleable: o produto está em boas condições para venda.
  • discard: o produto foi descartado.
  • unsaleable: o produto não está apto para venda.
  • missing: o produto não chegou para revisão.
  • "" ou null: quando não há uma revisão.

product_destination (string): Destino do produto após a análise da revisão. Valores possíveis:

  • meli: o produto vai para o Mercado Livre.
  • buyer: o produto vai para o comprador.
  • seller: o produto vai para o vendedor.
  • "" nos casos de "missing", o valor deste campo está vazio.
  • null: quando não há uma revisão.

reason_id (string): Tipificação selecionada no processo de revisão. Valores possíveis:

  • accepted: o produto foi aceito.
  • different_product: produto diferente.
  • discard: produto descartado.
  • misused: produto mal usado.
  • not_working: o produto não funciona.
  • incomplete: produto incompleto.
  • blocked: produto bloqueado.
  • open_box: produto de caixa aberta.
  • missing: produto não encontrado.
  • default: nos casos em que a revisão não pôde ser gerada.
  • null: quando não há uma revisão.

benefited (string): Indica quem foi o beneficiário da revisão de triage. Valores possíveis:

  • both: o beneficiário é tanto o comprador quanto o vendedor.
  • buyer: o beneficiário é o comprador.
  • seller: o beneficiário é o vendedor.
  • null: não há revisão.

seller_status (string): Status da revisão do vendedor, se aplicável. Valores possíveis:

  • pending: o vendedor está revisando o produto.
  • success: o vendedor indicou que o produto está em boas condições.
  • failed: o vendedor indicou que o produto tem problemas.
  • claimed: o vendedor reclamou o produto.
  • "" não é necessária revisão pelo vendedor.
  • null: o vendedor não recebeu o produto ou não precisa revisá-lo.

seller_reason (string): Identifica o motivo alegado pelo vendedor se a revisão não for bem-sucedida. Valores possíveis:

  • "SRF2"
  • "SRF3"
  • "SRF6"
  • "SRF7"
  • null: quando não foi indicado um motivo.

missing_quantity (long): Utilizado para identificar a quantidade de itens que não foram revisados, pois o produto não chegou para avaliação.


Possíveis erros

404 Not Found:

{
    "code": 404,
    "error": "not_found_error",
    "message": "return review not found",
    "cause": null
}

Revisão OK de uma devolução

Quando uma devolução chega ao vendedor, ele tem a possibilidade de revisar a mesma, indicando se o produto chegou nas condições esperadas ou se há algum problema com ele.

Para realizar uma revisão OK de uma devolução, confirmando que o produto chegou nas condições esperadas, o recurso /claims/$CLAIM_ID/actions/return-review-ok foi habilitado.

Para saber se o vendedor já tem habilitada a opção de fazer uma revisão ok de uma devolução, pode-se utilizar o recurso /claims/$CLAIM_ID. Dentro do array de “players”, buscamos o player “type”: “seller” e validamos que em suas "available_actions" exista "action": "return_review_ok"

Chamada:

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

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -d 
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-ok

Resposta:

{
   "id":5255026166,
   "resource_id": 2000007760636316,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9949",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": true,
                   "due_date": "2024-06-03T22:43:00.000-04:00"
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46122402,
           "available_actions": []
       }
   ],
   "resolution": {
       "reason": "item_returned",
       "date_created": "",
       "benefited": [
           "complainant"
       ],
       "closed_by": "mediator",
       "applied_coverage": true
   },
   "site_id": "MLA",
   "date_created": "2024-05-29T23:48:32.000-04:00",
   "last_updated": "2024-05-29T23:51:26.370-04:00"
}

Campos da resposta

A resposta bem-sucedida de um GET ao recurso /actions/return-review-ok retornará um status code 201 e os seguintes campos:

  • id: ID da reclamação
  • resource: ID do recurso sobre o qual a reclamação é criada. Depende do “resource”
  • status: Status da reclamação
    • opened
    • closed
  • type: Tipo de reclamação
    • mediations: reclamação entre comprador e vendedor.
    • return: Devolução de produto.
    • 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 de compra por parte do vendedor. Sempre em status: "closed" e stage: "none". O rol complainant sempre vai ser do tipo seller, collector ou sender dependendo do recurso da reclamação.
    • cancel_purchase: cancelamento de compra por parte do comprador
    • change: Troca de Produto.
    • service: Cancelamento de um serviço ordens bundle.
  • stage: Etapa da reclamação
    • claim: etapa de 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 na qual uma das partes entra em contato após a reclamação/disputa ser encerrada
    • none: não se aplica
    • stale: Etapa de reclamação onde intervêm o comprador e o 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. Interfere nos atores da reclamação
    • payment: Pagamento
    • order: Ordem
    • shipment: Envio
    • purchase: Compra
  • reason_id: Razão/motivo pelo qual a reclamação foi criada. Interfere diretamente nas 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 foi iniciada por um produto entregue ou não
  • quantity_type: informa se a reclamação é parcial ou não
    • partial: indica que é uma reclamação parcial
    • total: indica que é uma reclamação total
  • players: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
    • role: papel na reclamação
      • complainant: pessoa que reclama.
      • respondent: pessoa a quem é dirigida a reclamação.
      • mediator: pessoa que intervém para ajudar a resolver o problema.
      • warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
    • type: papel que a pessoa ocupa na operação que está sendo reclamada
      • payment: comprador - collector.
      • order: comprador - vendedor.
      • shipment: receptor - remetente.
      • purchase: comprador - Mercado Livre
    • user_id: ID do usuário no ML que desempenha o papel
    • available_actions: Lista de ações que cada uma das partes envolvidas pode executar
      • players: lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis.
        • action: Nome da açã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 (ainda não disponível): 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_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 (tracking number).
          • return_review_fail: realizar uma revisão de falhas de uma devolução.
          • return_review_ok: realizar uma revisão ok de uma devolução.
          • mandatory: tipo de ação
            • respondent: pessoa a quem é dirigida a reclamação.
            • warehouse_dispatcher: pessoa encarregada de revisar o produto nas devoluções ao warehouse.
  • resolution: Lista dos atores que participam da reclamação com suas respectivas ações e tempos disponíveis
    • reason: Motivo de resolução/fechamento
      • already_shipped: Produto a caminho
      • buyer_claim_opened: Fechamento da devolução por abertura de outra reclamação
      • buyer_dispute_opened: Fechamento da devolução por abertura de outra reclamação em disputa (com mediação do Mercado Livre)
      • charged_back: Fechamento por chargeback
      • coverage_decision: Disputa fechada com cobertura do ML
      • found_missing_parts: Comprador encontrou as partes faltantes
      • item_returned: Produto devolvido
      • no_bg: Fechamento sem cobertura do ML
      • not_delivered: Produto não entregue
      • opened_claim_by_mistake: Comprador criou a reclamação por engano
      • other: Outro caso
      • partial_refunded: Reembolso parcial do pagamento ao comprador
      • payment_refunded: Pagamento devolvido ao comprador
      • preferred_to_keep_product: Comprador preferiu ficar com o produto
      • product_delivered: Decisão de um representante do MercadoLibre
      • reimbursed: Reembolso
      • rep_resolution: Decisão de um representante do MercadoLibre
      • respondent_timeout: Vendedor não responde
      • return_cancelled: Devolução cancelada pelo comprador
      • return_expired: Devolução vencida sem troca ou sem envio
      • seller_asked_to_close_claim: Vendedor pediu ao comprador que fechasse a reclamação
      • seller_did_not_help: Comprador conseguiu resolver o problema sem a ajuda do vendedor
      • seller_explained_functions: Vendedor explicou como o item funcionava
      • seller_sent_product: Vendedor enviou o produto
      • timeout: Fechamento por tempo limite de ação ao comprador
      • warehouse_decision: Fechamento por revisão de produto no Warehouse
      • warehouse_timeout: Fechamento por demora na revisão de produto no Warehouse
      • worked_out_with_seller: Comprador resolveu com o vendedor fora do ML
      • low_cost: Fechamento porque o custo do envio é maior que o do produto
      • item_changed: Fechamento porque a troca foi feita internamente
      • change_expired: A troca não foi realizada e o tempo permitido foi cumprido
      • change_cancelled_buyer: Fechamento de uma troca pelo comprador
      • change_cancelled_seller: Fechamento proativo de uma troca pelo vendedor
      • change_cancelled_meli: Fechamento de uma troca pela Meli
      • shipment_not_stopped: Fechamento porque o envio não pôde ser interrompido
      • cancel_installation: Cancelamento de serviço de instalação
    • created: Data de resolução/fechamento da reclamação
    • benefited: Beneficiários da resolução
      • respondent
    • closed_by: Ator que fechou a reclamação
      • mediator
      • buyer
      • respondent
      • false
    • applied_coverage: Pagamento ao comprador
    • site_id: ID do site onde a reclamação foi desenvolvida
    • date_created: Data de criação/abertura da reclamação
    • last_updated: Data da última atualização da reclamação

Revisão de falhas de uma devolução

Quando uma devolução chega ao vendedor, este tem a possibilidade de fazer uma revisão da mesma indicando se o produto chegou nas condições esperadas ou se há algum problema com o mesmo.

Para saber se o vendedor já tem habilitada a opção de fazer uma revisão falhada, podemos consultar o recurso /claims/$CLAIM_ID. Dentro do array de “players”, buscamos o player “type”: “seller” e validamos que em suas "available_actions" exista "action": "return_review_fail"

Para realizar uma revisão de falhas de uma devolução, indicando que o produto chegou com algum problema, utilizam-se três recursos que se descrevem a seguir:

Obter razões para criar uma revisão de falhas de uma devolução

Para criar uma revisão falhada terás que conhecer a razão pela qual o vendedor identifica que o produto não chegou nas condições esperadas.

A lista das possíveis razões que o vendedor pode selecionar se obtêm no recurso returns/reasons/return-fail.

Chamada:

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

Exemplo:

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

Resposta:

[
   {
       "id": "SRF2",
       "name": "product_damaged",
       "detail": "El producto llegó dañado",
       "position": 1
   },
   {
       "id": "SRF3",
       "name": "return_incomplete",
       "detail": "La devolución está incompleta",
       "position": 2
   },
   {
       "id": "SRF4",
       "name": "returned_product_different",
       "detail": "Devolvieron un producto distinto al que envié",
       "position": 3
   },
   {
       "id": "SRF5",
       "name": "product_not_in_package",
       "detail": "El producto no está en el paquete",
       "position": 4
   },
   {
       "id": "SRF6",
       "name": "another_failure_with_product",
       "detail": "Reportar otra falla en el producto",
       "position": 5
   },
   {
       "id": "SRF7",
       "name": "return_has_not_arrived",
       "detail": "Aún no me llegó",
       "position": 6
   }
]

Campos da resposta

A resposta bem-sucedida de um GET ao recurso /returns/reasons/return-fail retornará um status code 200 e os seguintes campos:

  • id: Identificador da reason. Este valor é o que deve ser enviado ao criar uma revisão falhada.
  • name: Código da reason
  • detail: Motivo da devolução falhada para dar contexto ao vendedor ao escolher a reason
    • return_product
  • position: Posição recomendada da reason ao mostrar todas as reasons ao vendedor

Obter nome das evidências a anexar na revisão de falhas de uma devolução

Ao criar uma revisão falhada, também se habilita o envio de evidências, com o objetivo de fornecer mais informações ao caso. Portanto, você poderá utilizar o recurso de /claims/$CLAIM_ID/returns/attachments para o upload de arquivos.

Como resultado, será obtido o nome do arquivo que será enviado como evidência na revisão..

Este recurso deve ser utilizado para cada evidência que se queira anexar a uma revisão falhada.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/returns/attachments
-F 'file=@"/Users/usuer/Downloads/file.png'

Resposta:

{
    "user_id": 1277895049,
    "file_name": "1277895049_9d6b8d38-a2c2-4d17-a68b-f0845bc35fd1.png"
}

Campos da resposta

A resposta bem-sucedida de um GET ao recurso /claims/$CLAIM_ID/returns/attachments retornará um status code 200 e os seguintes campos:

  • user_id: identificador do usuário
  • file_name: nome do arquivo que poderá ser utilizado ao criar uma revisão falhada

Criar revisão de falhas de uma devolução

Para criar a revisão de falhas de uma devolução, indicando que o produto chegou com algum problema, foi habilitado o recurso /claims/$CLAIM_ID/actions/return-review-fail

Parâmetros

params Type Values Detalhe value
claim_id Integer Identificador único da reclamação para a qual se deseja indicar a revisão falhada da devolução (obrigatório)
reson String Identificador único da razão pela qual o vendedor indica que o produto não chegou como esperado (obrigatório).
Os possíveis valores deste campo são obtidos do recurso returns/reasons
message String Mensagem inserida pelo vendedor indicando o motivo da revisão falhada (obrigatório)
attachments Array[String] Nomes das evidências a serem anexadas na revisão.
Os valores deste campo são obtidos do recurso returns/attachments
(obrigatório para as reason_id SRF2 e SRF4)

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "reason" : $REASON_ID,	
    "message": $MESSAGE,
    "attachments": [$ATTACHMENTS]
}
https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-fail

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "reason" : "SRF2",	
    "message": "Me enviaron el sweater con una mancha",
    "attachments": ["1277895049_4d421a16-31ba-444d-hbbf-68b373ed2g32.png"]
}
https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/actions/return-review-fail

Resposta:

{
   "id": 5255026166,
   "resource_id": 2000007760636316,
   "status": "closed",
   "type": "mediations",
   "stage": "claim",
   "parent_id": null,
   "resource": "order",
   "reason_id": "PDD9949",
   "fulfilled": true,
   "quantity_type": "total",
   "players": [
       {
           "role": "complainant",
           "type": "buyer",
           "user_id": 1277895049,
           "available_actions": []
       },
       {
           "role": "respondent",
           "type": "seller",
           "user_id": 1582937623,
           "available_actions": [
               {
                   "action": "return_review_fail",
                   "mandatory": false,
                   "due_date": null
               },
               {
                   "action": "return_review_ok",
                   "mandatory": true,
                   "due_date": "2024-06-03T22:43:00.000-04:00"
               }
           ]
       },
       {
           "role": "mediator",
           "type": "internal",
           "user_id": 46122402,
           "available_actions": []
       }
   ],
   "resolution": {
       "reason": "item_returned",
       "date_created": "",
       "benefited": [
           "complainant"
       ],
       "closed_by": "mediator",
       "applied_coverage": true
   },
   "site_id": "MLA",
   "date_created": "2024-05-29T23:48:32.000-04:00",
   "last_updated": "2024-05-29T23:51:26.370-04:00"
}

Campos da resposta

A resposta bem-sucedida de um POST ao recurso /claims/$CLAIM_ID/actions/return-review-fail retornará um status code 201 e os seguintes campos:

Parâmetros de resposta:

  • id: ID da reclamação.
  • resource_id: ID do recurso sobre o qual a reclamação foi criada. Depende do “resource”.
  • status: status 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. Nesse caso, não há mensagens. Para trabalhar com devoluções, siga a documentação de Devoluções.
    • fulfillment: reclamação entre comprador e Mercado Livre em compras com envio full.
    • ml_case: cancelamento da compra por parte do comprador devido a atraso no envio.
    • cancel_sale: cancelamento da compra pelo vendedor.
    • cancel_purchase: cancelamento da compra pelo comprador.
    • change: troca de produto. Indica que será realizada uma troca.
    • service: cancelamento de um serviço ordens bundle.
  • stage: etapa da reclamação. Pode assumir os seguintes valores:
    • claim: etapa em que o comprador e o vendedor interagem.
    • dispute: etapa de mediação com um representante do Mercado Livre.
    • recontact: etapa em que uma das partes entra em contato após o encerramento da disputa.
    • none: não aplicável.
    • stale: etapa em que o comprador e o Mercado Livre interagem para reclamações do tipo ml_case.
  • claim_version: versão da reclamação. Exemplo: 1.0, 1.5, 2.0.
  • claimed_quantity: quantidade de itens associados à reclamação.
  • parent_id: ID da reclamação da qual esta depende.
  • resource: identificador do recurso ao qual se refere a reclamação. Pode ser:
    • payment
    • order
    • shipment
    • purchase
  • reason_id: motivo da reclamação. Influencia diretamente nas soluções possíveis:
    • PNR: Produto Não Recebido
    • PDD: Produto Diferente ou Defeituoso
    • CS: Compra Cancelada
  • fulfilled: indica se o produto foi entregue. Valores possíveis: true | false.
  • quantity_type: informa se a reclamação é parcial ou total.
    • partial: reclamação parcial
    • total: reclamação total
  • players: lista dos atores envolvidos na reclamação:
    • role:
      • complainant: pessoa que reclama.
      • respondent: pessoa contra quem se reclama.
      • mediator: pessoa que intervém para solucionar o problema.
      • purchase: comprador - Mercado Livre.
    • type: depende do recurso (payment, order, shipment).
    • user_id: ID do usuário.
    • available_actions:
      • action: ação possível
      • mandatory: true se for obrigatória
      • due_date: data limite
  • resolution: forma de resolução da reclamação.
    • reason:
      • already_shipped: Produto a caminho
      • buyer_claim_opened: Devolução encerrada por nova reclamação
      • buyer_dispute_opened: Devolução encerrada por nova disputa com mediação do Mercado Livre
      • charged_back: Encerramento por chargeback
      • coverage_decision: Disputa encerrada com cobertura do ML
      • found_missing_parts: Comprador encontrou peças faltantes
      • item_returned: Produto devolvido
      • no_bpp: Encerramento sem cobertura do ML
      • not_delivered: Produto não entregue
      • opened_claim_by_mistake: Reclamação aberta por engano
      • partial_refunded: Reembolso parcial concedido
      • payment_refunded: Pagamento reembolsado
      • prefered_to_keep_product: Comprador preferiu ficar com o produto
      • product_delivered: Decisão do representante do Mercado Livre
      • reimbursed: Reembolsado
      • rep_resolution: Decisão do representante do Mercado Livre
      • respondent_timeout: Vendedor não respondeu
      • return_canceled: Devolução cancelada pelo comprador
      • return_expired: Devolução expirada sem atualização de status
      • seller_asked_to_close_claim: Vendedor pediu para fechar a reclamação
      • seller_did_not_help: Comprador resolveu o problema sem ajuda do vendedor
      • seller_explained_functions: Vendedor explicou o funcionamento do item
      • seller_sent_product: Vendedor enviou o produto
      • timeout: Reclamação encerrada por inatividade do comprador
      • warehouse_decision: Encerramento por demora na análise no depósito
      • warehouse_timeout: Encerramento por expiração de tempo de análise no depósito
      • worked_out_with_seller: Resolvido diretamente com o vendedor
      • low_cost: Custo de envio maior que o valor do produto
      • item_changed: Troca concluída com sucesso
      • change_expired: Troca não realizada dentro do prazo
      • change_cancelled_buyer: Troca cancelada proativamente pelo comprador
      • change_cancelled_seller: Troca cancelada proativamente pelo vendedor
      • change_cancelled_meli: Troca cancelada pelo Mercado Livre
      • shipment_not_stopped: Envio não foi interrompido
      • cancel_installation: Cancelamento de serviço de instalação
  • data_created: Data da resolução/encerramento da reclamação.
  • benefited: Beneficiário da resolução (complainant | respondent).
  • closed_by: Parte que encerrou a reclamação (mediator | buyer).
  • applied_coverage: Reclamação com cobertura (false | true).
  • site_id: ID do site onde a reclamação foi criada.
  • created_date: Data de criação/abertura da reclamação.
  • last_updated: Data da última atualização da reclamação.
  • related_entities: Lista de entidades relacionadas à reclamação.
  • return: Indica se a reclamação possui uma devolução vinculada.

Revisão de falhas de uma devolução - Nova versão disponível a partir de 21/07/2025

Importante:
A partir de 21 de julho, a versão antiga dos recursos de revisão falha de uma devolução será descontinuada. Uma nova versão será implementada e já está disponível para integradores certificados. Recomendamos que atualizem suas integrações para esta nova versão para garantir a continuidade do serviço.

Quando uma devolução chega ao vendedor, este tem a possibilidade de fazer uma revisão da mesma indicando se o produto chegou nas condições esperadas ou se há algum problema com o mesmo.

Para saber se o vendedor já tem habilitada a opção de fazer uma revisão falhada, podemos consultar o recurso /claims/$CLAIM_ID. Dentro do array de “players”, buscamos o player “type”: “seller” e validamos que em suas "available_actions" exista "action": "return_review_fail"

Para realizar uma revisão de falhas de uma devolução, indicando que o produto chegou com algum problema, utilizam-se três recursos que se descrevem a seguir:

Obter razões para criar uma revisão de falhas de uma devolução

Para criar uma revisão falhada terás que conhecer a razão pela qual o vendedor identifica que o produto não chegou nas condições esperadas.

A lista das possíveis razões que o vendedor pode selecionar se obtêm dessa maneira:

Chamada:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/returns/reasons?flow=$FLOW&claim_id=$CLAIM_ID' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/returns/reasons?flow=seller_return_failed&claim_id=55555' \
    --header 'Authorization: Bearer $ACCESS_TOKEN'

É necessário enviar:

  • flow: Indicando as razões de qual fluxo queremos obter (por enquanto, apenas é válido o valor seller_return_failed)
  • claim_id: Identificador único da reclamação.

Resposta:

[
    {
        "id": "SRF2",
        "name": "product_damaged",
        "detail": "El producto llegó dañado",
        "position": 1,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF3",
        "name": "return_incomplete",
        "detail": "La devolución está incompleta",
        "position": 2,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF4",
        "name": "returned_product_different",
        "detail": "Devolvieron un producto distinto al que envié",
        "position": 3,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF5",
        "name": "product_not_in_package",
        "detail": "El producto no está en el paquete",
        "position": 4,
        "apply": [
            "order",
         "package"
        ]
    },
    {
        "id": "SRF6",
        "name": "another_failure_with_product",
        "detail": "Reportar otra falla en el producto",
        "position": 5,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF7",
        "name": "return_has_not_arrived",
        "detail": "Aún no me llegó",
        "position": 6,
        "apply": [
         "package"
        ]
    }
 ]

Erros:

Claim inexistente

{
   "code": 404,
   "error": "not_found_error",
   "message": "claim_Not Found",
   "cause": null
 }

Flow inválido:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "flow: invalid_flow does not exist. claimId: 5358155244",
   "cause": null
 }

Atualmente, apenas o flow seller_return_failed é válido. Qualquer outro valor retornará este erro

Campos da resposta

A resposta bem-sucedida de um GET ao recurso /returns/reasons/return-fail retornará um status code 200 e os seguintes campos:

  • id: Identificador da reason. Este valor é o que deve ser enviado ao criar uma revisão falhada.
  • name: Código da reason
  • detail: Motivo da devolução falhada para dar contexto ao vendedor ao escolher a reason
    • return_product
  • position: Posição recomendada da reason ao mostrar todas as reasons ao vendedor
  • apply: Nos indica para que se pode utilizar a reason. Isso é porque agora poderemos realizar revisões de devoluções de carrinho (que incluem vários pedidos), de modo que há reasons que se aplicam somente ao pacote inteiro, outras que se aplicam aos pedidos de maneira individual e outras que podem ser utilizadas para ambos os casos. Os valores possíveis deste campo para casos de carrinho são: package e order e para os casos não carrinho é somente order.

Obter nome das evidências a anexar na revisão de falhas de uma devolução

Ao criar uma revisão falhada, também se habilita o envio de evidências, com o objetivo de fornecer mais informações ao caso. Portanto, você poderá utilizar o recurso de /claims/$CLAIM_ID/returns/attachments para o upload de arquivos.

Como resultado, será obtido o nome do arquivo que será enviado como evidência na revisão..

Este recurso deve ser utilizado para cada evidência que se queira anexar a uma revisão falhada.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 
    https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/returns/attachments
    -F 'file=@"/Users/usuer/Downloads/file.png'

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/post-purchase/v1/claims/5255026166/returns/attachments
    -F 'file=@"/Users/usuer/Downloads/file.png'

Resposta:

{
    "user_id": 1277895049,
    "file_name": "1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"
}

Erros:

Claim inexistente

{
    "code": 404,
    "error": "not_found_error",
    "message": "Claim not found. claimId: 5255026166",
    "cause": null
 }

Erro com o body (por exemplo, não foi enviada uma imagem)

{
    "code": "bad_request",
    "message": "Error retrieving uploaded file. claim_id: 5356116886. caller_id: 1985874106"
}

Invalid key

{
    "code": "not_found",
    "message": "Request error: [{\"status\":404,\"error\":\"not_found\",\"message\":\"Can not get attachment\"}]"
}

Campos da resposta

A resposta bem-sucedida de um GET ao recurso /claims/$CLAIM_ID/returns/attachments retornará um status code 200 e os seguintes campos:

  • user_id: identificador do usuário
  • file_name: nome do arquivo que poderá ser utilizado ao criar uma revisão falhada

Criar revisão de falhas de uma devolução - Nova versão disponível a partir de 21/07/2025

Para criar a revisão de falhas de uma devolução, indicando que o produto chegou com algum problema, foi habilitado o recurso /claims/$CLAIM_ID/actions/return-review-fail

Parâmetros

params Type Values Detalhe value
claim_id Integer Identificador único da reclamação para a qual se deseja indicar a revisão falhada da devolução (obrigatório)
reson String Identificador único da razão pela qual o vendedor indica que o produto não chegou como esperado (obrigatório).
Os possíveis valores deste campo são obtidos do recurso returns/reasons
message String Mensagem inserida pelo vendedor indicando o motivo da revisão falhada (obrigatório)
attachments Array[String] Nomes das evidências a serem anexadas na revisão.
Os valores deste campo são obtidos do recurso returns/attachments
(obrigatório para as reason_id SRF2 e SRF4)
order_id Integer Identificador único do pedido. Este valor deve ser utilizado apenas para casos de carrinho em que queremos realizar a revisão para um pedido específico. No caso de se tratar de uma revisão de um caso que não seja de carrinho ou de carrinho completo, este parâmetro não deve ser enviado.

Chamada:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : $REASON_ID,
    "message": $MESSAGE,
    "attachments": [$ATTACHMENTS],
    "order_id": $ORDER_ID
  }
]'

Agora o endpoint para criação de revisões falhas de devoluções aceita uma lista de reviews. Isso ocorre porque agora é possível realizar revisões por carrinho. Vamos ver um exemplo de uso. Se eu tenho um caso com 5 produtos e quero devolver apenas 2, devemos indicar para cada um desses 2 a razão, a mensagem, imagens se necessário e o order_id.

Exemplo:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF2",
    "message": "Olá",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
    "order_id":2000011248679992
  },
  {
    "reason" : "SRF4",
    "message": "Olá",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
    "order_id":2000011248679992
  }
]'

Devemos levar em consideração que existem reasons que se aplicam ao pacote inteiro, então não devemos enviar o order_id e devemos enviar apenas uma review. Por exemplo, se eu tiver 5 produtos e eles ainda não chegaram, então o reason seria SRF7, que conforme observamos no nosso GET de reasons, se aplica a todo o pacote. Nesse caso, devemos utilizar o endpoint da seguinte forma:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF7",
    "message": "Não chegou",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"]
  }
]'

Por fim, para os casos que não envolvem carrinho, devemos enviar apenas uma review sem o order_id:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/555555555/actions/return-review-fail' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data '[
  {
    "reason" : "SRF7",
    "message": "Não chegou",
    "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"]
  }
]'

Response:

{
    "id": 5255026166,
    "resource_id": 2000007760636316,
    "status": "closed",
    "type": "mediations",
    "stage": "claim",
    "parent_id": null,
    "resource": "order",
    "reason_id": "PDD9949",
    "fulfilled": true,
    "quantity_type": "total",
    "players": [
        {
            "role": "complainant",
            "type": "buyer",
            "user_id": 1277895049,
            "available_actions": []
        },
        {
            "role": "respondent",
            "type": "seller",
            "user_id": 1582937623,
            "available_actions": [
                {
                    "action": "return_review_fail",
                    "mandatory": false,
                    "due_date": null
                },
                {
                    "action": "return_review_ok",
                    "mandatory": true,
                    "due_date": "2024-06-03T22:43:00.000-04:00"
                }
            ]
        },
        {
            "role": "mediator",
            "type": "internal",
            "user_id": 46122402,
            "available_actions": []
        }
    ],
    "resolution": {
        "reason": "item_returned",
        "date_created": "",
        "benefited": [
            "complainant"
        ],
        "closed_by": "mediator",
        "applied_coverage": true
    },
    "site_id": "MLA",
    "date_created": "2024-05-29T23:48:32.000-04:00",
    "last_updated": "2024-05-29T23:51:26.370-04:00"
 }

Campos da resposta

A resposta bem-sucedida de um POST ao recurso /claims/$CLAIM_ID/actions/return-review-fail retornará um status code 201 e os seguintes campos:

Parâmetros de resposta:

  • id: ID da reclamação.
  • resource_id: ID do recurso sobre o qual a reclamação foi criada. Depende do “resource”.
  • status: status 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. Nesse caso, não há mensagens. Para trabalhar com devoluções, siga a documentação de Devoluções.
    • fulfillment: reclamação entre comprador e Mercado Livre em compras com envio full.
    • ml_case: cancelamento da compra por parte do comprador devido a atraso no envio.
    • cancel_sale: cancelamento da compra pelo vendedor.
    • cancel_purchase: cancelamento da compra pelo comprador.
    • change: troca de produto. Indica que será realizada uma troca.
    • service: cancelamento de um serviço ordens bundle.
  • stage: etapa da reclamação. Pode assumir os seguintes valores:
    • claim: etapa em que o comprador e o vendedor interagem.
    • dispute: etapa de mediação com um representante do Mercado Livre.
    • recontact: etapa em que uma das partes entra em contato após o encerramento da disputa.
    • none: não aplicável.
    • stale: etapa em que o comprador e o Mercado Livre interagem para reclamações do tipo ml_case.
  • claim_version: versão da reclamação. Exemplo: 1.0, 1.5, 2.0.
  • claimed_quantity: quantidade de itens associados à reclamação.
  • parent_id: ID da reclamação da qual esta depende.
  • resource: identificador do recurso ao qual se refere a reclamação. Pode ser:
    • payment
    • order
    • shipment
    • purchase
  • reason_id: motivo da reclamação. Influencia diretamente nas soluções possíveis:
    • PNR: Produto Não Recebido
    • PDD: Produto Diferente ou Defeituoso
    • CS: Compra Cancelada
  • fulfilled: indica se o produto foi entregue. Valores possíveis: true | false.
  • quantity_type: informa se a reclamação é parcial ou total.
    • partial: reclamação parcial
    • total: reclamação total
  • players: lista dos atores envolvidos na reclamação:
    • role:
      • complainant: pessoa que reclama.
      • respondent: pessoa contra quem se reclama.
      • mediator: pessoa que intervém para solucionar o problema.
      • purchase: comprador - Mercado Livre.
    • type: depende do recurso (payment, order, shipment).
    • user_id: ID do usuário.
    • available_actions:
      • action: ação possível
      • mandatory: true se for obrigatória
      • due_date: data limite
  • resolution: forma de resolução da reclamação.
    • reason:
      • already_shipped: Produto a caminho
      • buyer_claim_opened: Devolução encerrada por nova reclamação
      • buyer_dispute_opened: Devolução encerrada por nova disputa com mediação do Mercado Livre
      • charged_back: Encerramento por chargeback
      • coverage_decision: Disputa encerrada com cobertura do ML
      • found_missing_parts: Comprador encontrou peças faltantes
      • item_returned: Produto devolvido
      • no_bpp: Encerramento sem cobertura do ML
      • not_delivered: Produto não entregue
      • opened_claim_by_mistake: Reclamação aberta por engano
      • partial_refunded: Reembolso parcial concedido
      • payment_refunded: Pagamento reembolsado
      • prefered_to_keep_product: Comprador preferiu ficar com o produto
      • product_delivered: Decisão do representante do Mercado Livre
      • reimbursed: Reembolsado
      • rep_resolution: Decisão do representante do Mercado Livre
      • respondent_timeout: Vendedor não respondeu
      • return_canceled: Devolução cancelada pelo comprador
      • return_expired: Devolução expirada sem atualização de status
      • seller_asked_to_close_claim: Vendedor pediu para fechar a reclamação
      • seller_did_not_help: Comprador resolveu o problema sem ajuda do vendedor
      • seller_explained_functions: Vendedor explicou o funcionamento do item
      • seller_sent_product: Vendedor enviou o produto
      • timeout: Reclamação encerrada por inatividade do comprador
      • warehouse_decision: Encerramento por demora na análise no depósito
      • warehouse_timeout: Encerramento por expiração de tempo de análise no depósito
      • worked_out_with_seller: Resolvido diretamente com o vendedor
      • low_cost: Custo de envio maior que o valor do produto
      • item_changed: Troca concluída com sucesso
      • change_expired: Troca não realizada dentro do prazo
      • change_cancelled_buyer: Troca cancelada proativamente pelo comprador
      • change_cancelled_seller: Troca cancelada proativamente pelo vendedor
      • change_cancelled_meli: Troca cancelada pelo Mercado Livre
      • shipment_not_stopped: Envio não foi interrompido
      • cancel_installation: Cancelamento de serviço de instalação
  • data_created: Data da resolução/encerramento da reclamação.
  • benefited: Beneficiário da resolução (complainant | respondent).
  • closed_by: Parte que encerrou a reclamação (mediator | buyer).
  • applied_coverage: Reclamação com cobertura (false | true).
  • site_id: ID do site onde a reclamação foi criada.
  • created_date: Data de criação/abertura da reclamação.
  • last_updated: Data da última atualização da reclamação.
  • related_entities: Lista de entidades relacionadas à reclamação.
  • return: Indica se a reclamação possui uma devolução vinculada.

Erros

Claim inexistente:

{
   "code": 404,
   "error": "not_found_error",
   "message": "Claim not found. claimId: 4444444",
   "cause": null
}

Se não for enviada uma mensagem:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Required request body is missing or incorrect, please see the documentation.",
   "cause": null
}

Se não for enviada uma reason:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Required request body is missing or incorrect, please see the documentation.",
   "cause": null
}

O vendedor não tem a action habilitada:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Not valid action return_review_fail for player role respondent",
   "cause": null
}

Mais de uma review com uma reason que se aplica ao pacote inteiro:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "only one review is allowed for package-wide reasons.",
   "cause": null
}

Quando for utilizada uma reason que se aplica a todo o pacote, apenas uma review deve ser enviada. Caso contrário, retornará este erro.

Exemplo do que não deve ser feito:

[
    {
        "reason" : "SRF7",
        "message": "Olá",
        "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
        "order_id": 2000011248679992
    },
    {
        "reason" : "SRF4",
        "message": "Olá",
        "attachments": ["1117895119_9d6zaaz8-a1c7-4f1f-a68b-fz0z0135gd6.png"],
        "order_id": 2000011248679992
    }
]

Order_id não enviado:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "You must provide an order_id for each review.",
   "cause": null
}

Para casos de carrinho, devemos enviar um order_id em cada review, a menos que a review contenha uma reason que se aplique a todo o pacote. Caso contrário, este erro será retornado.

Se nenhuma review for enviada em casos de carrinho:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "at least one review is required.",
   "cause": null
}

Reason inválida:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "The provided reason 'SRF33' is not valid.",
   "cause": null
}

Mais de uma review em casos não carrinho:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "only one review is allowed for non-cart cases.",
   "cause": null
}

Se nenhuma review for enviada em casos não carrinho:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "one review is required.",
   "cause": null
}

Custo de envio de devoluções e trocas

Visando melhorar a experiência que oferecemos aos nossos sellers, criamos essa funcionalidade para permitir que possa obter as informações de custo de envio de devoluções e trocas.

Para obter a informação do custo de envio de devoluções e trocas, faça uma solicitação GET para:

 /post-purchase/v1/claims/{claim_id}/charges/return-cost

especificando o $CLAIM_ID. Isso fornecerá informações detalhadas sobre o valor associado ao envio de devoluções e trocas da reclamação correspondente.


Nota:
O parâmetro calculate_amount_usd é um query parameter que, por padrão, tem o valor false. Isso significa que, caso você não envie esse parâmetro na requisição, ele será tratado automaticamente como false. Quando o parâmetro for enviado com o valor true, a aplicação realizará o cálculo do valor em dólares (USD). Se não for enviado ou se enviado com o valor false, o cálculo não será feito.

Exemplo com parâmetro calculate_amount_usd=true

Chamada:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/charges/return-cost?calculate_amount_usd=true'

Resposta:

{
    "currency_id": "BRL",
    "amount": 42.90,
    "amount_usd": 7.517
}

Exemplo sem parâmetro calculate_amount_usd

Chamada:

curl --location 'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/charges/return-cost'

Resposta:

{
    "currency_id": "BRL",
    "amount": 42.90
}

Campos da resposta

Nome Tipo Descrição Exemplo
claim_id long id do claim 123456789
calculate_amount_usd boolean retorna o valor em dólar se true true
amount BigDecimal Valor a ser cobrado ao seller pela devolução 42.90
amount_usd BigDecimal Valor acima porém em dólar 7.517
currency_id String ID da moeda à qual o campo amount se refere BRL

Erros

A seguir, detalham-se as possíveis mensagens de erro que o recurso pode gerar:

Se o claim não pertence ao vendedor:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid roleId :12343234 in claim :123454323",
   "cause": null
}

Se o claim não existe:

{
   "code": 404,
   "error": "not_found_error",
   "message": "claim id: 5255026166 not found",
   "cause": null
}

Se o token não for enviado:

{
   "code": 401,
   "error": "unauthorized_request_error",
   "message": "Invalid caller.id",
   "cause": null
}

Se o token expirou ou é inválido:

{
   "message": "invalid_token",
   "error": "not_found",
   "status": 401,
   "cause": []
}

Se o token estiver incorreto:

{
   "message": "{\"message\":\"Malformed access_token: toke n\",\"error\":\"bad_request\",\"status\":400,\"cause\":[]}",
   "error": "",
   "status": 400,
   "cause": []
}

Se o vendedor não tiver habilitado a revisão de uma devolução:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Not valid action return_review_ok for player role respondent",
   "cause": null
}

Se o formato do arquivo que se deseja anexar não for válido:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid mime_type",
   "cause": null
}

Se o nome do arquivo não for válido:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Invalid file_name: ",
   "cause": null
}

Se o campo "file" não for enviado:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Current request is not a multipart request",
   "cause": null
}

Se algum dos campos obrigatórios não for passado:

{
   "code": 400,
   "error": "bad_request_error",
   "message": "Required request body is missing or incorrect, please see the documentation.",
   "cause": null
}

Ir: Gerenciar reclamações