Trabalhar com Devoluções
Como identificar uma Devolução
- Ouvindo a notificação da reclamação que foi criada associada a uma ordem (feed claims).
- Consultando a reclamação (recurso / claims).
- Validando se o type da reclamação é "return" (recurso / claims).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/v1/claims/$CLAIM_ID/returns
Resposta:
{
"last_updated": "2019-01-04T22:51:47.459-04:00",
"shipping": {
"id": "27768896524",
"status": "cancelled",
"tracking_number": null,
"lead_time": {
"estimated_delivery_time": {
"date": "2018-12-28T00:00:00.000-03:00"
}
},
"status_history": [
{
"status": "handling",
"substatus": null,
"date": "2018-12-20T08:31:14.000-04:00"
},
{
"status": "ready_to_ship",
"substatus": "ready_to_print",
"date": "2018-12-20T08:31:14.000-04:00"
},
{
"status": "cancelled",
"substatus": "return_expired",
"date": "2019-01-04T22:47:01.000-04:00"
}
],
"origin": {
"type": "selling_address",
"sender_id": 388146803,
"shipping_address": {
"address_id": 1018791372,
"address_line": "Testing Street 1450",
"street_name": "Testing Street",
"street_number": "1450",
"comment": "Referencia: The Testing Cavern",
"zip_code": "1430",
"city": {
"id": "TUxBQlNBQTM3Mzda",
"name": "Saavedra"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"country": {
"id": "AR",
"name": "Argentina"
},
"neighborhood": {
"id": null,
"name": "The Neighborhood"
},
"municipality": {
"id": null,
"name": null
},
"types": [
"billing",
"default_buying_address",
"default_selling_address",
"shipping"
],
"latitude": -34.554242,
"longitude": -58.491549,
"geolocation_type": "APPROXIMATE"
}
}
},
"refund_at": "delivered",
"date_closed": null,
"resource": "order",
"date_created": "2018-12-20T08:31:13.813-04:00",
"claim_id": 1028414216,
"status_money": "available",
"resource_id": 1893698454,
"type": "express",
"status": "expired"
}
Descrição de parâmetros
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 da identificação do envio.
- status: status em que o envio se encontra.
- tracking_number: número de acompanhamento do envio da devolução.
- estimated_delivery_time: tempo estimado de chegada do envio da devolução.
status_history: representa o histórico dos status pelos quais o envio da Devolução foi passando.
status: são os 4 status pelos que o returns pode passar:
handling: quando a etiqueta é gerada
ready_to_ship: etiqueta pronta para envio
shipped: enviado
delivered: entregue
- substatus
- date
origin: informação do Endereço do Seller, onde a Devolução é enviada
refund_at: quando o dinheiro é reembolsado ao buyer
values: [‘shipped’|‘delivered’]
‘shipped’: quando o buyer efetiva o envio da devolução
‘delivered’: 3 dias após o seller receber o envio.
date_closed: data em que a devolução é fechada.
resource: nome do recurso associado à devolução.
date_created: data em que a devolução é criada.
claim_id: o ID da reclamação associado à devolução.
status_money: status do Dinheiro da devolução.
- values: [‘RETAINED’|‘REFUNDED’, ‘AVAILABLE’]
RETAINED: dinheiro em conta, mas indisponível, retido.
REFUNDED: dinheiro reembolsado para o buyer.
AVAILABLE: dinheiro em conta disponível.
resource_id: ID do recurso.
type: express.
status: tipo de Devolução, atualmente só há express.
Status de uma Devolução
Opened: Quando o buyer inicia o processo de devolução e ainda não enviou o produto.
Shipped: Momento em que o buyer já enviou o produto e está a caminho do seller.
Closed: Devolução finalizada. Dinheiro reembolsado para o buyer.
Delivered: Somente para as devoluções com "refund_at" = "delivered". Quando o produto está em mãos do seller mas ainda não se passaram os 3 dias úteis de revisão para a realização do refund do dinheiro para o buyer.
Cancelled: Devolução cancelada pelo buyer.
Expired: Devolução expirada, o buyer não fez o envio do produto no tempo disponível.
Tratamento de Erros
Estrutura do erro
{
"error":Error Type,
"code":Error code,
"message":error message,
"cause":list of error cause
}
Exemplo invalid claim_id
{
"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": []
}
Exemplo invalid_param
{
"error": "BAD_REQUEST",
"code": 400,
"message": "key: parameter claim_id must be a number, status_code:400",
"cause": [
400,
"Invalid Param claim_id :aa"
]
}
Exemplo invalid access_token
{
"error": "ACCESS_TOKEN_VERIFICACION_FAILS",
"code": 401,
"message": "Error validating access token, status_code:401",
"cause": [
"ACCESS_TOKEN_VERIFICACION_FAILS",
"Error validating access token",
401
]
}
