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

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 automática do tipo return partial.
  • 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
    • status
      • pending: Pode aparecer em duas situações, nas devoluções ao seller e também nas devoluções ao warehouse:
        • Devolução ao seller: a devolução está pendente de revisão.
        • Devolução ao warehouse: foi feita a revisão e o julgamento do triage disse que o seller tem que retirar o produto. (Sendo vendedores que vendem através de integradores, não sei se têm a possibilidade de retirar o produto).
      • claimed
        • Devolução ao seller: o seller revisa o produto e decide que o produto não está em condições.
        • Devolução ao warehouse: o triage decide que o seller tem que retirar o produto. Uma vez que o retira, pode apelar a revisão feita pelo warehouse para que a decisão seja alterada. Quando apela, este status é definido.
      • failed: Pode aparecer em duas situações, nas devoluções ao seller e também nas devoluções ao warehouse:
        • Nas devoluções ao warehouse, após a apelação, um representante de CX decide sobre a reclamação do seller. Se decidir que a reclamação do seller é válida (o seller também se torna beneficiário), o status passa a failed. (o status anterior é claimed).
        • Devolução ao seller: o responsável de CX decide que o seller é beneficiário. (o status anterior é claimed).
      • success: Pode aparecer em duas situações, nas devoluções ao seller e também nas devoluções ao warehouse:
        • Devolução ao seller: o seller aceita a devolução e a marca como ok.
        • Nas devoluções ao warehouse, após a apelação do seller, um representante de CX decide sobre a reclamação. Se decidir manter a decisão do warehouse (com o beneficiário sendo o buyer), o status passa a success. (o status anterior é claimed).
      • 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.

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