O que é uma devolução?

Uma devolução é um processo crucial na experiência de compra em nossa plataforma, através do qual um comprador pode devolver um artigo 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. Gerir eficazmente as devoluções é fundamental para manter a confiança e satisfação do cliente, garantindo que qualquer problema seja resolvido de forma transparente e eficiente.

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.

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