Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 03/09/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:

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.
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:

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