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 17/01/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.

Consultar uma devolução

Para consultar uma devolução, faça uma solicitação para post-purchase/v2/claims/$CLAIM_ID/returns, especificando o $CLAIM_ID. Isso fornecerá informações detalhadas sobre a devolução associada à reclamação correspondente.

Chamada:

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

Exemplo:

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

Resposta:

{
   "last_updated": "2023-02-25T00:02:22.575-04:00",
   "shipping": {
       "id": 42049162337,
       "status": "cancelled",
       "tracking_number": "MEL42049162337FMDOR01",
       "lead_time": {
           "estimated_delivery_time": {
               "date": "2023-02-20T00:00:00.000-06:00"
           }
       },
       "status_history": [
           {
               "status": "handling",
               "substatus": null,
               "date": "2023-02-15T15:43:14.944-04:00"
           },
           {
               "status": "ready_to_ship",
               "substatus": "ready_to_print",
               "date": "2023-02-15T15:43:18.377-04:00"
           },
           {
               "status": "cancelled",
               "substatus": "return_expired",
               "date": "2023-02-25T00:02:20.394-04:00"
           }
       ],
       "origin": {
           "type": "selling_address",
           "sender_id": 1299347553,
           "shipping_address": {
               "address_id": 1280687101,
               "address_line": "Calle Transportes 234",
               "street_name": "Calle Transportes",
               "street_number": "234",
               "comment": "Referencia: NA",
               "zip_code": "03940",
               "city": {
                   "id": "TUxNQ0JFTjM2MjQ",
                   "name": "Benito juárez"
               },
               "state": {
                   "id": "MX-DIF",
                   "name": "Distrito Federal"
               },
               "country": {
                   "id": "MX",
                   "name": "Mexico"
               },
               "neighborhood": {
                   "id": null,
                   "name": "Crédito Constructor"
               },
               "municipality": {
                   "id": null,
                   "name": null
               },
               "types": [
                   "default_buying_address"
               ],
               "latitude": 19.365558,
               "longitude": -99.179523,
               "geolocation_type": "GEOMETRIC_CENTER"
           }
       },
       "destination": {
           "name": "seller_address"
       }
   },
   "refund_at": "delivered",
   "date_closed": null,
   "resource": "order",
   "date_created": "2023-02-15T15:43:14.694-04:00",
   "claim_id": 5255026166,
   "status_money": "retained",
   "resource_id": 2000007760636316,
   "type": "dispute",
   "subtype": null,
   "status": "opened",
   "warehouse_review": {
       "product_condition": "",
       "product_destination": "",
       "benefited": false
   },
   "seller_review": {
       "status": "",
       "reason_id": null
   }
}

Campos da resposta:

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

  • last_updated: última atualização da devolução.
  • shipping: detalhe do envio da devolução.
    • id: número de identificação do envio.
    • status: estado em que se encontra o envio.
    • tracking_number: número de rastreamento do envio da devolução.
    • lead_time
    • estimated_delivery_time: tempo estimado de chegada do envio da devolução.
    • date: tempo estimado de chegada do envio da devolução.
  • status_history: representa o histórico dos estados pelos quais foi passando o envio da devolução.
    • status: são os estados pelos quais pode passar o retorno:
      • pending: quando se gera o envio.
      • ready_to_ship: etiqueta pronta para despachar.
      • shipped: enviado.
      • not_delivered: não entregue.
      • delivered: entregue.
      • cancelled: envio cancelado.
    • substatus: null
    • date: data do estado.
  • origin: endereço de origem do envio de devolução.
    • type: tipo de endereço.
    • sender_id: código do comprador (buyer_id).
    • shipping_address: detalhe do endereço.
      • address_id:
      • address_line:
      • street_name:
      • street_number:
      • comment:
      • zip_code:
      • city:
      • state:
      • country:
      • neighborhood:
      • municipality:
      • types:
      • latitude:
      • longitude:
      • geolocation_type:
  • destination: informação do destino da devolução.
    • name
      • seller_address: destino vendedor.
      • warehouse: destino depósito do Mercado Livre.
  • refund_at: quando se devolve o dinheiro ao comprador.
    • shipped: quando o comprador realiza o despacho do envio da devolução.
    • delivered: 3 dias depois de o vendedor receber o envio.
    • n/a: para casos low cost que não geram uma devolução.
  • date_closed: data em que se fecha a devolução.
  • resource: nome do recurso ao qual se associa a devolução.
  • date_created: data em que se criou a devolução.
  • claim_id: o id da reclamação à qual está associada a devolução.
  • status_money: estado em que se encontra o dinheiro da devolução.
    • retained: dinheiro na conta, mas não disponível, retido.
    • refunded: dinheiro devolvido ao comprador.
    • available: dinheiro na conta disponível.
  • resource_id: ID do recurso.
  • type: tipo de devolução.
    • claim: devolução por reclamação.
    • dispute: devolução por mediação.
    • automatic: devolução automática.
  • subtype: o subtipo de devolução.
    • low_cost: devolução automática do tipo low cost.
    • return_partial: devolução parcial.
    • return_total: devolução total.
  • status: estados pelos quais pode passar uma devolução.
    • opened: quando o comprador inicia uma reclamação no Mercado Livre por uma devolução.
    • shipped: devolução enviada, dinheiro retido.
    • closed: estado final da devolução ao encerramento da mesma e do claim_id associado.
    • delivered: envio em mãos do vendedor.
    • not_delivered: devolução não entregue.
    • cancelled: devolução cancelada, dinheiro disponível.
    • failed: devolução falhada.
    • expired: devolução expirada.
  • warehouse_review: resultado do processo do triage que é feito no depósito (revisão do produto), este array tem informação unicamente se o atributo “destination” é igual warehouse, do contrário se mostra nulo.
    • product_condition
      • saleable: significa que o produto está apto para voltar a ser vendido e é feito o restock automaticamente.
      • unsaleable: o produto não está em condições para a venda.
      • discard: o produto é descartado porque é diferente do que o comprador obteve na transação e devia devolver, por exemplo uma pedra.
    • product_destination
      • buyer
      • seller
      • meli
    • benefited
      • true: se reintegra o dinheiro da venda ao vendedor.
      • false: se reintegra o dinheiro da transação ao comprador.
  • seller_review: fornece informações sobre a revisão realizada pelo vendedor.
    • status: estado da revisão. Pode assumir um dos seguintes valores:
      • pending: a devolução está pendente de revisão pelo vendedor.
      • claimed: o vendedor revisou o produto e decidiu que ele não está nas condições esperadas.
      • failed: o responsável de CX decide que o vendedor é beneficiário (o status anterior é claimed).
      • success: o vendedor revisou a devolução e indicou que chegou nas condições esperadas.
    • reason_id: Identificador da razão pela qual o vendedor indicou um problema com o produto. Os valores possíveis são os retornados pelo recurso reasons/return-fail. Atualmente, os valores possíveis são:
      • null: Quando nenhuma razão é especificada. Este campo é sempre null, exceto quando o status é 'claimed'.
      • SRF2: O produto chegou danificado.
      • SRF3: A devolução está incompleta.
      • SRF4: Foi devolvido um produto diferente do enviado.
      • SRF5: O produto não está no pacote.
      • SRF6: Reportar outra falha no produto.
      • SRF7: Ainda não recebeu o produto.
Nota:
Lembre-se de que o recurso /shipments/$SHIPMENT_ID/costs devolve os custos do envio que o usuário deve enfrentar.

Returns - Nova versão a partir de 20/03/2025

Importante:
Haverá uma nova versão produtiva que substituirá a atual a partir de 20/03/2025. Estamos disponibilizando para que possam se familiarizar com as mudanças e realizarem os ajustes necessários. Tenha em mente que uma das mudanças na nova versão é que já não traz informações de reviews. Haverá um novo endpoint para isso que também estará disponível em 20/03/2025, portanto, será necessário utilizá-lo para obter informações das reviews.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/reviews

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, faça uma solicitação 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

Nota:
Recordando que esta versão ainda não está produtiva, por isso, seguirá recebendo as mesmas respostas da versão atual.

Reviews - Disponível a partir de 20/03/2025

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 falhada 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 falhada 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 falhada 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 falhada 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 falhada 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

Revisão falhada de devolução

Para criar a revisão falhada 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:

  • 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 com falha 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

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