Devoluções

Identificar uma Devolução

Para identificar corretamente uma devolução fizemos as seguintes recomendações:

• Ouça a notificação da reclamação (feed claims) que contém a informação da ordem que a originou.
• Consulte a APi de reclamações no recurso /v1/claims/search, validando se o type és “return”.
• Validando se o type da reclamação é "return" (recurso / claims).

Consulte uma devolução

Para consultar uma devolução você deve fazer a chamada a /v2/claims/$CLAIM_ID/returns, especificando o $CLAIM_ID:

Exemplo de chamada:

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

Resposta:

{
  "last_updated": "2023-05-30T16:06:08.207-04:00",
  "shipping": {
      "id": 42313159782,
      "status": "delivered",
      "tracking_number": "10101015808",
      "lead_time": {
          "estimated_delivery_time": {
              "date": "2023-06-06T00:00:00.000-05:00"
          }
      },
      "status_history": [
          {
              "status": "handling",
              "substatus": null,
              "date": "2023-05-30T15:52:05.206-04:00"
          },
          {
              "status": "ready_to_ship",
              "substatus": "ready_to_print",
              "date": "2023-05-30T15:52:09.736-04:00"
          },
          {
              "status": "shipped",
              "substatus": null,
              "date": "2023-05-30T16:04:00.689-04:00"
          },
          {
              "status": "delivered",
              "substatus": null,
              "date": "2023-05-30T16:06:07.644-04:00"
          }
      ],
      "origin": {
          "type": "selling_address",
          "sender_id": 1206328181,
          "shipping_address": {
              "address_id": 1303663780,
              "address_line": "Calle 3 #01-22",
              "street_name": "Calle 3",
              "street_number": "#01-22",
              "comment": "Referencia: casa",
              "zip_code": "252201",
              "city": {
                  "id": "TUNPQ1BBUzQ4NjY4",
                  "name": "Pasca"
              },
              "state": {
                  "id": "CO-CUN",
                  "name": "Cundinamarca"
              },
              "country": {
                  "id": "CO",
                  "name": "Colombia"
              },
              "neighborhood": {
                  "id": null,
                  "name": "Paca"
              },
              "municipality": {
                  "id": null,
                  "name": null
              },
              "types": [],
              "latitude": 4.307708,
              "longitude": -74.301528,
              "geolocation_type": "ROOFTOP"
          }
      }
  },
  "refund_at": "shipped",
  "date_closed": "2023-05-30T16:04:01.763-04:00",
  "resource": "order",
  "date_created": "2023-05-30T15:52:04.476-04:00",
  "claim_id": 5195217090,
  "status_money": "refunded",
  "resource_id": 2000005748875612,
  "type": "claim",
  "subtype": null,
  "status": "closed"
}

Descrição dos parâmetros da resposta

A resposta de um GET ao recurso / returns dá como resultado os seguintes parâmetros:

• 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 seguimento do envio da devolução.
• lead_time:

• estimated_delivery_time: tempo estimado da chegada do envio da devolução.

• date: data estimada da 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 returns:

• Se o tipo de devolução é Devex (deprecado 30/11/2023) os possíveis estados são:

• handling: quando a etiqueta é gerada.
• ready_to_ship: etiqueta pronta para despachar.
• shipped: enviado.
• delivered: entregue.

• Para Devos v2.0 os possíveis estados são:

• pending: quando o envio é gerado.
• 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 da devolução.

• type: tipo de endereço.
• sender_id: código do comprador (buyer_id).
• shipping_address: detalhe do endereço.

• destination: informação do destino de devolução.

• seller_address: endereço do vendedor.
• warehouse: endereço do depósito do Mercado Livre.

• refund_at: quando o dinheiro é devolvido ao comprador.

• shipped: quando o comprador realiza o despacho do envio da devolução.
• delivered: 3 dias depois do vendedor receber o envio.
• n/a: para casos low cost que não é gerada uma devolução.

• date_closed: data em que termina a devolução.
• resource: nome do recurso ao qual se associa a devolução.
• date_created: data em que se cria a devolução.
• claim_id: o ID da reclamação ao qual está associado a devolução.
• status_money: estado no qual se encontra o dinheiro da devolução.

• retained: dinheiro em conta, mas não disponível, retido.
• refunded: dinheiro devolvido ao comprador.
• available: dinheiro disponível em conta.

• resource_id: ID do recurso.
• type: tipo de devolução;

• express: express: devoluções v1.0 (deprecado 30/11/2023).
• 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 de tipo low cost.
• return_partial: devolução automática de tipo return partial.

• status: estados pelos quais pode passar uma devolução.

• Estados de uma devolução.

• Se o tipo de devolução é Devex (deprecado 30/11/2023) os possíveis estados são:

• opened: quando o comprador inicia uma reclamação ao Mercado Libre por uma devolução.
• shipped: devolução enviada, dinheiro retido.
• closed: estado final da devolução no término da mesma e do claim_id associado. Este estado dispara a devolução do dinheiro ao comprador.
• delivered: envio em mãos ao vendedor mas ainda NÃO passaram os 3 dias para revisar.
• cancelled: devolução cancelada, dinheiro disponível.
• expired: evolução expirada, dinheiro disponível.

• Para Devos v2.0 os possíveis estados são:

• opened: quando o comprador inicia uma reclamação ao Mercado Libre por uma devolução.
• shipped: devolução enviada, dinheiro retido.
• closed: estado final da devolução no término da mesma e do claim_id associado.
• delivered: envio em mãos ao vendedor.
• not_delivered: devolução não entregue.
• cancelled: devolução cancelada, dinheiro disponível.
• failed: devolução falha.
• expired: devolução expirada.

• warehouse_review resultado do processo de triagem que é feito no depósito (revisão do produto), este array tem informação apenas se o atributo “destination” é igual warehouse, do contrário será 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 ao que o comprador obteve da transação e deveria devolver, por exemplo, uma pedra.

• product_destination: pode ser “buyer”, “seller” ou “meli”.
• benefited:
• true: o dinheiro da venda é devolvido ao vendedor.
• false: o dinheiro da venda é devolvido ao comprador.
Nota:
Lembre-se que o recurso /shipments/$SHIPMENT_ID/costs retorna os custos de envio que o usuário terá que arcar.




Gestão de Erros

A continuación se detalla los mensajes de error que el recurso puede responder, y que esperan una acción correctiva:

1. Error cuando se envía un $CLAIM_ID al que no se tiene acceso usando ese access token:

{
    "error": "Can’t obtain data with id: 18",
    "code": 403,
    "message": "Cant get data with id: 18, status_code: 403 , response: {'error':'not_owned_order','status':403,'message':'The user has not access to the order.','cause':[]}, url: https://api.mercadolibre.com/v1/claims/10284142/returns",
    "cause": []
}

2. Error cuando se envía un $CLAIM_ID que no es de tipo numérico.

{
    "error": "BAD_REQUEST",
    "code": 400,
    "message": "key: parameter claim_id must be a number, status_code:400",
    "cause": [
        400,
        "Invalid Param claim_id :aa"
    ]
}

3. Error si el $CLAIM_ID enviado no existe:

{
    "message": "Error executing GET [client:claims]",
    "error": "rest_client_error",
    "status": 404,
    "cause": [
        "{\"status\":404,\"error\":\"not_found\",\"message\":\"Claim not found. claimId: xxxx\"}"
    ]
}

4. Error si el $CLAIM_ID enviado es vacío o invalido.

{
    "message": "key: parameter claim_id is invalid or empty, status_code: 400",
    "error": "bad_request",
    "status": 400,
    "cause": [
        "bad_request",
        "Invalid Param claim_id",
        400
    ]
}

5. A partir del 30 de novembro de 2023 al consultar la v1 se recibirá un código de error 503, ya que está versión se depreca.