Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
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.
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.