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 /post-purchase/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 /post-purchase/v2/claims/$CLAIM_ID/returns, especificando o $CLAIM_ID:

Exemplo de chamada:

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

Resposta:

{
    {
        "last_updated": "2024-01-11T16:03:22.2+00:00",
        "shipping": {
            "id": 42998970748,
            "status": "delivered",
            "tracking_number": "101010622106990",
            "lead_time": {
                "estimated_delivery_time": {
                    "date": "2024-01-17T00:00:00.000-03:00"
                }
            },
            "status_history": [
                {
                    "status": "handling",
                    "substatus": null,
                    "date": "2024-01-11T12:01:35.576-04:00"
                },
                {
                    "status": "ready_to_ship",
                    "substatus": "ready_to_print",
                    "date": "2024-01-11T12:02:06.839-04:00"
                },
                {
                    "status": "shipped",
                    "substatus": null,
                    "date": "2024-01-11T12:02:10.839-04:00"
                },
                {
                    "status": "delivered",
                    "substatus": null,
                    "date": "2024-01-11T12:02:14.280-04:00"
                }
            ],
            "origin": {
                "type": "selling_address",
                "sender_id": 1632520187,
                "shipping_address": {
                    "address_id": 1350834413,
                    "address_line": "Calle 34 123",
                    "street_name": "Calle 34",
                    "street_number": "123",
                    "comment": "23  Entre: 67 y 54",
                    "zip_code": "5000",
                    "city": {
                        "id": "TUxBQ0NBUGNiZGQx",
                        "name": "Córdoba"
                    },
                    "state": {
                        "id": "AR-X",
                        "name": "Córdoba"
                    },
                    "country": {
                        "id": "AR",
                        "name": "Argentina"
                    },
                    "neighborhood": {
                        "id": null,
                        "name": null
                    },
                    "municipality": {
                        "id": null,
                        "name": null
                    },
                    "types": [
                        "default_buying_address"
                    ],
                    "latitude": -31.010405,
                    "longitude": -64.075891,
                    "geolocation_type": "APPROXIMATE"
                }
            },
            "destination": {
                "name": "seller_address"
            }
        },
        "refund_at": "delivered",
        "date_closed": "2024-01-11T12:03:22.464-04:00",
        "resource": "order",
        "date_created": "2024-01-11T16:01:34.936+00:00",
        "claim_id": 5243352643,
        "status_money": "refunded",
        "resource_id": 2000007357691104,
        "type": "automatic",
        "subtype": null,
        "status": "closed",
        "warehouse_review": {
            "product_condition": "saleable",
            "product_destination": "buyer",
            "benefited": false
        }
     }
     
}

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:

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

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

• 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. Erro quando o pedido não existe:

{
        {
            "code": 404,
            "error": "not_found_error",
            "message": "Error executing GET [client:claims]",
            "cause": null
         }         

2. Erro quando não se tem permissão para acessar o recurso. (unauthorized_request_error):

{
        {
            "code": 401,
            "error": "unauthorized_request_error",
            "message": "{\"message\":\"key: parameter caller.id unauthorized owner, status_code:401\",\"error\":\"access_token_verification_fails\",\"status\":401,\"cause\":[\"access_token_verification_fails\",\"Error validating access token, caller.id is not owner\",401]}",
            "cause": null
         }         

3. Erro de autenticação -token- (unauthorized_request_error):

{
        {
            "code": 401,
            "error": "unauthorized_request_error",
            "message": "Invalid caller.id",
            "cause": null
         }