O que é uma devolução?

Uma devolução é um processo crucial na experiência de compra em nossa plataforma, por meio do qual um comprador pode devolver um item ao vendedor. Este procedimento pode ser ativado por diversas razões, como discrepâncias entre a descrição do produto e seu estado real, problemas de funcionamento, ou até mesmo uma mudança de opinião por parte do comprador. Gerenciar 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: Escute o feed de reclamações (feed claims), que contém as informações do pedido no qual a reclamação foi originada.
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 a 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

Resposta:

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

Campos da resposta

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

• id: identificador da devolução (return_id).
• last_updated: data da última atualização.
• shipments: lista de envios associados à devolução.
  • shipment_id: identificador do envio.
  • status: status em que se encontra o envio. Valores possíveis:
    • pending: quando o envio é gerado.
    • ready_to_ship: etiqueta pronta para despacho.
    • shipped: enviado.
    • not_delivered: não entregue.
    • delivered: entregue.
    • cancelled: envio cancelado.
  • tracking_number: número de rastreamento do envio da devolução.
  • destination: informações do destino do envio.
    • name: nome do destino. Valores possíveis:
      • seller_address: destino vendedor.
      • warehouse: destino depósito do Mercado Livre.
    • shipping_address: endereço de envio.
      • address_id: identificador do endereço.
      • address_line: endereço completo.
      • street_name: nome da rua.
      • street_number: número da rua.
      • comment: comentário adicional.
      • zip_code: CEP.
      • city: cidade (objeto com id e name).
      • state: estado (objeto com id e name).
      • country: país (objeto com id e name).
      • neighborhood: bairro (objeto com id e name).
      • municipality: município (objeto com id e name).
  • type: tipo de envio. Valores possíveis:
    • return: envio com destino seller ou warehouse.
    • return_from_triage: envio do warehouse para uma revisão intermediária.
• refund_at: quando o dinheiro é devolvido ao comprador. Valores possíveis:
  • shipped: quando o comprador realiza o despacho do envio da devolução.
  • delivered: 3 dias após o vendedor receber o envio.
  • n/a: para casos low cost que não geram uma devolução.
• date_closed: data em que a devolução é encerrada.
• resource_type: nome do recurso ao qual a devolução está associada. Valores possíveis:
  • order
  • claim
  • shipment
  • other
• date_created: data de criação da devolução.
• claim_id: ID da reclamação à qual a devolução está associada.
• status_money: status do dinheiro. Valores possíveis:
  • retained: dinheiro na conta mas retido.
  • refunded: dinheiro devolvido ao comprador.
  • available: dinheiro disponível.
• resource_id: identificador do recurso associado.
• orders: lista de pedidos associados.
  • order_id: identificador do pedido.
  • item_id: identificador do item.
  • variation_id: identificador da variação.
  • context_type: contexto do item. Valores possíveis:
    • total: reclamada por todo o pedido.
    • partial: reclamada por quantidade parcial.
    • incomplete: unidades não recebidas, não podem ser devolvidas.
  • total_quantity: quantidade total de itens.
  • return_quantity: quantidade de itens a devolver.
• subtype: subtipo de devolução. Valores possíveis:
  • low_cost: devolução automática do tipo low cost.
  • return_partial: devolução parcial.
  • return_total: devolução total.
• status: status atual da devolução. Valores possíveis:
  • pending_cancel: em processo de cancelamento.
  • pending: devolução criada e inicializando o shipment.
  • failed: não foi possível criar e/ou inicializar o shipment.
  • shipped: devolução enviada, dinheiro retido.
  • pending_delivered: em processo de passar para delivered.
  • return_to_buyer: devolução retornando ao comprador.
  • pending_expiration: em processo de expiração.
  • scheduled: programada para retirada.
  • pending_failure: em processo de falha.
  • label_generated: devolução pronta para ser enviada.
  • cancelled: devolução cancelada, dinheiro disponível.
  • not_delivered: devolução não entregue.
  • expired: devolução expirada.
  • delivered: devolução nas mãos do vendedor.
• related_entities: entidades relacionadas. Exemplo: ["reviews"]
• intermediate_check: indica se foi realizada verificação intermediária. Valores possíveis:
  • true
  • false
• resources: lista de recursos (claims) associados à devolução.

Obter detalhes das revisões de uma devolução

Como identificar a possibilidade de consultar a API de GET Reviews?

A API de GET Returns retornará o campo related_entities, que deve conter o item "reviews" para indicar que existe uma revisão para essa devolução.

O que são as apelações?

É quando uma devolução tem uma revisão por parte do processo de triagem e o vendedor pode questionar ou disputar a decisão tomada.

Qual é a diferença entre apelações e devolução com falha?

• Devolução com falha: Ocorre quando não há uma revisão por parte da triagem e o vendedor é o responsável por realizar essa revisão, podendo indicar se o produto chegou com algum problema.
• Apelação: É a resposta do vendedor a uma decisão já tomada pela triagem.

Chamada:

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

Parâmetros de consulta

Exemplo:

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

Resposta:

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

Parâmetros de resposta:

Campos de resource_reviews:

Erros

404 Not Found

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

A review para a devolução não foi encontrada. Verifique se o campo related_entities no recurso /post-purchase/v2/claims/$CLAIM_ID/returns contém o elemento "reviews" para indicar que existe uma review para a devolução.

Revisão de uma devolução

Quando uma devolução chega ao vendedor, ele 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 ele.

Como obter o return_id

Para realizar uma revisão de devolução, primeiro você precisa obter o return_id. Siga estes passos:

1. Consulte o recurso /post-purchase/v2/claims/$CLAIM_ID/returns para obter os detalhes da devolução.
2. Extraia o return_id da resposta (é retornado como id no objeto de devolução).
3. Use este return_id para realizar a revisão.

Verificar se a revisão está disponível

Para saber se o vendedor tem habilitada a opção de fazer uma revisão, consulte o recurso /claims/$CLAIM_ID. Dentro do array de "players", procure o player "type": "seller" e valide que em suas "available_actions" exista:

• "action": "return_review_ok" - para aprovar a devolução
• "action": "return_review_fail" - para reportar um problema

Realizar uma revisão

Use o endpoint unificado para enviar sua revisão de devolução. O body da solicitação determina se é uma revisão bem-sucedida (OK) ou uma revisão com falha.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
https://api.mercadolibre.com/post-purchase/v1/returns/$RETURN_ID/return-review \
-d '$REQUEST_BODY'

Revisão OK (produto chegou como esperado)

Para confirmar que o produto chegou nas condições esperadas, envie um body vazio:

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
https://api.mercadolibre.com/post-purchase/v1/returns/267582953/return-review \
-d '{}'

Obter razões para criar uma revisão com falha

Para criar uma revisão com falha, você precisará conhecer a razão pela qual o vendedor identifica que o produto não chegou nas condições esperadas.

Chamada:

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

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/post-purchase/v1/returns/reasons?flow=seller_return_failed&claim_id=5555555'

É necessário enviar:

• flow: Indicando as reasons de qual fluxo queremos obter (por enquanto só é válido o valor seller_return_failed)
• claim_id: Identificador único da reclamação.

Resposta:

[
    {
        "id": "SRF2",
        "name": "product_damaged",
        "detail": "O produto chegou danificado",
        "position": 1,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF3",
        "name": "return_incomplete",
        "detail": "A devolução está incompleta",
        "position": 2,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF4",
        "name": "returned_product_different",
        "detail": "Devolveram um produto diferente do que enviei",
        "position": 3,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF5",
        "name": "product_not_in_package",
        "detail": "O produto não está no pacote",
        "position": 4,
        "apply": [
            "order",
            "package"
        ]
    },
    {
        "id": "SRF6",
        "name": "another_failure_with_product",
        "detail": "Reportar outra falha no produto",
        "position": 5,
        "apply": [
            "order"
        ]
    },
    {
        "id": "SRF7",
        "name": "return_has_not_arrived",
        "detail": "Ainda não chegou",
        "position": 6,
        "apply": [
            "package"
        ]
    }
]

Erros:

Claim inexistente:

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

Flow inválido:

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

Atualmente só é válido o flow seller_return_failed. Qualquer outro valor retornará este erro.

Campos da resposta

• id: Identificador da reason. Este valor é o que deverá ser enviado ao criar uma revisão com falha.
• name: Código da reason.
• detail: Motivo da devolução com falha para dar contexto ao vendedor na hora de escolher a reason.
• position: Posição recomendada da reason na hora de mostrar todas as reasons ao vendedor.
• apply: Indica para que a reason pode ser utilizada. Em devoluções carrinho (que incluem vários pedidos), há reasons que se aplicam apenas a todo o pacote, outras aos pedidos de forma individual e outras para ambos os casos. Valores possíveis: package e order.

Obter nome das evidências a anexar na revisão com falha

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

Como resultado, você obterá o nome do arquivo que será enviado como evidência na revisão. Este recurso deve ser utilizado para cada evidência que você queira anexar a uma revisão com falha.

Chamada:

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

Exemplo:

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

Resposta:

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

Erros:

Claim inexistente:

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

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

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

Invalid key:

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

Campos da resposta

• user_id: identificador do usuário
• file_name: nome do arquivo que poderá ser utilizado na hora de criar uma revisão com falha

Revisão com falha (produto chegou com problemas)

Para indicar que o produto tem problemas, você deve fornecer a razão, uma mensagem e opcionalmente evidências.

Parâmetros

Exemplo - Revisão de pedido individual:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
https://api.mercadolibre.com/post-purchase/v1/returns/267582953/return-review \
-d '[
  {
    "reason": "SRF2",
    "message": "O produto chegou com dano visível na tela",
    "attachments": ["1277895049_9d6b8d38-a2c2-4d17-a68b-f0845bc35fd1.png"]
  }
]'

Exemplo - Caso carrinho com múltiplos pedidos:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
https://api.mercadolibre.com/post-purchase/v1/returns/267582953/return-review \
-d '[
  {
    "reason": "SRF2",
    "message": "Produto danificado",
    "attachments": ["1277895049_9d6b8d38-a2c2-4d17-a68b-f0845bc35fd1.png"],
    "order_id": 2000011248679992
  },
  {
    "reason": "SRF4",
    "message": "Produto diferente recebido",
    "attachments": ["1117895119_abc123-a1c7-4f1f-a68b-xyz789.png"],
    "order_id": 2000011248679993
  }
]'

Exemplo - Razão a nível de pacote (ex. pacote não recebido):

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
https://api.mercadolibre.com/post-purchase/v1/returns/267582953/return-review \
-d '[
  {
    "reason": "SRF7",
    "message": "O pacote de devolução ainda não chegou"
  }
]'

Custo de envio de devoluções e trocas

Com o objetivo de melhorar a experiência que oferecemos aos nossos vendedores, criamos esta funcionalidade para permitir que você obtenha as informações de custo de envio de devoluções e trocas.

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

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/charges/return-cost'

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

Exemplo com parâmetro calculate_amount_usd=true

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/charges/return-cost?calculate_amount_usd=true'

Resposta:

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

Exemplo sem parâmetro calculate_amount_usd

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
'https://api.mercadolibre.com/post-purchase/v1/claims/$CLAIM_ID/charges/return-cost'

Resposta:

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

Campos da resposta

Erros

A seguir, são detalhadas as possíveis mensagens de erro que os recursos podem gerar:

Se a reclamação não pertence ao vendedor:

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

Se a reclamação não existe:

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

Se o token não é 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 está incorreto:

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

Se o vendedor não está habilitado para fazer uma revisão de 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 é válido:

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

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

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

Se o campo "file" não é 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 é enviado:

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

Ir: Gerenciar reclamações