Trabalhar com Devoluções

O novo recurso / returns permite obter os detalhes de uma Devolução de produto, conhecer seus motivos e status.
No Mercado Livre trabalhamos com 2 tipos de devoluções:

As chamadas "express", que dependem 100% da decisão do comprador.
As geradas através de uma reclamação.

Nota: Por enquanto, este recurso permitirá consultar as do tipo "express" e gerenciá-las de maneira simples. A partir do mesmo recurso, em breve, será possível acessar aquelas que provêm de uma reclamação.

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  
https://api.mercadolibre.com/v1/claims/{claim_id}/returns?access_token=$ACCESS_TOKEN”

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 efetiviza 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: (Expres)
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?access_token=APP_USR-1505-112714-9e75ec9d61d116d6510b2385f8be31fb-379926",
    "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