Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
Calcular o custo do frete e o handling time
Atributos da calculadora
Destination (destino): Detalhes do endereço do destinatário
Atributos:
- zip_code (código postal): CEP do destino.
- city (cidade): Informações sobre a cidade de destino.
- state (estado): Informação do estado de destino.
- country (país): Informação do país de destino.
- extended_attributes (atributos estendidos): informações adicionais do endereço de destino.
id: ID da cidade de destino.
name: nome da cidade de destino.
id: ID do estado de destino.
name: nome do estado de destino.
id: ID del país de destino.
name: nome do país de destino.
address (endereço): linha de endereço de destino.
owner_name (nome do proprietário): Proprietário do endereço de destino.
zip_code_type (tipo de código postal): Informações sobre o tipo de código postal de destino.
- type: ID do tipo de código postal de destino.
- Description:(descrição) Nome do tipo de código postal de destino.
city_type (tipo de cidade): ID do tipo de cidade de destino.
city_name (nome da cidade): Nome da cidade de destino.
version: versão interna destes dados na API do código postal.
Options (opções): Cobrança dos custos de envio para cada método de envio disponível.
Atributos:
- id: ID da regra de envio aplicada.
- name: nome do método de envio.
- currency_id (ID da moeda): ID da moeda usada para exibir os custos de envio.
- list_cost (custo de postagem): Custos de envio reais; nenhum frete grátis aplicado.
- cost: Custo final de envio; frete grátis pode ser aplicado.
- tracks_shipments_status (rastreamento do status de envio): indica como este método pode ser rastreado.
- display: ID do método de envio para processamento frontend.
- speed (velocidade): informações de velocidade de entrega.
verified(verificado): pode ser rastreado internamente.
not_verified: As informações de rastreamento devem ser fornecidas pelo vendedor.
no: não é possível rastrear.
always (sempre): O método de envio deve ser mostrado.
optional (opcional): É possível não mostrar o método por ser mais rápido e econômico
shipping (envio): Média de horas de envio.
handling (em manuseio): Média de horas para o vendedor despachar a remessa.
Custos de envio de acordo com o item e zip code
Calcule os custos de envio de um item enviando apenas os parâmetros Item_id e zip_code (CP o CEP).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/shipping_options?zip_code=$ZIP_CODE
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB2997181655/shipping_options?zip_code=06233903
Resposta:
{
"destination": {
"zip_code": "06233903",
"city": {
"id": "BR-SP-31",
"name": "Osasco"
},
"state": {
"id": "BR-SP",
"name": "São Paulo"
},
"country": {
"id": "BR",
"name": "Brasil"
},
"extended_attributes": {
"address": "Avenida das Nações Unidas 3003",
"zip_code_type": {
"type": "GU",
"description": "Grande Usuario"
},
"city_type": "CI",
"city_name": "Osasco",
"neighborhood": "Bonfim",
"status": "active"
}
},
"buyer": {
"id": 0,
"loyalty_level": 1,
"shipping_level": "1"
},
"options": [
{
"id": 1423196752,
"option_hash": "ae1bd0a2dbfe1358ec28585f4e432cae",
"name": "Expresso",
"currency_id": "BRL",
"base_cost": 13.5,
"cost": 0,
"list_cost": 22.74,
"display": "recommended",
"shipping_method_id": 511948,
"shipping_method_type": "sedex",
"shipping_option_type": "address",
"estimated_delivery_time": {
"type": "known_frame",
"date": "2022-12-01T00:00:00-03:00",
"unit": "hour",
"offset": {
"date": "2022-12-05T00:00:00-03:00",
"shipping": 48
},
"time_frame": {
"from": null,
"to": null
},
"pay_before": "2022-11-29T00:00:00-03:00",
"shipping": 24,
"handling": 48,
"schedule": null
},
"discount": {
"promoted_amount": 13.5,
"rate": 1,
"type": "ratio",
"show_loyal_benefit": false
}
}
],
"custom_message": {
"display_mode": null,
"reason": ""
},
"app_version": "2.1"
}
Custos de envio de acordo com item e cidade em MCO
Calcule os custos de envio de um item enviando apenas os parâmetros Item_id e City_to.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MCO415774919/shipping_options?city_to=Q08tRENCb2dvdA
Resposta:
{
"destination": {
"zip_code": null,
"city": {
"id": "Q08tRENCb2dvdA",
"name": "Bogotá"
},
"state": {
"id": "CO-DC",
"name": "Bogota D.C."
},
"country": {
"id": "CO",
"name": "Colombia"
}
},
"options": [
{
"id": 523835933,
"name": "Servientrega Normal",
"shipping_method_id": 501745,
"currency_id": "COP",
"list_cost": 5000,
"cost": 0,
"tracks_shipments_status": "verified",
"display": "recommended",
"speed": {
"shipping": 24,
"handling": 72
},
"estimated_delivery": {
"date": "2015-06-22T00:00:00.000-05:00",
"pay_before": null,
"time_from": null,
"time_to": null
},
"discount": {
"rate": 0,
"type": "none",
"promoted_amount": 0
}
}
]
}
Descrições dos atributos
Type: tipo de promessa de entrega.
Date: data de entrega estimada. Em caso de classificação: é a data inferior da classificação.
Shipping: tempo que a transportadora leva para entregar o pedido. Se for um intervalo: é o limite inferior do intervalo.
Handling: tempo que o vendedor leva para despachar o pedido.
Unit: unidade de tempo para os atributos de shipping, handling e offset.shipping.
Offset: aplicável apenas para intervalos.
Date: data superior do intervalo.
Shipping: Amplitude do intervalo de dias.
time_frame: horário limite de entrega
pay_before: prazo limite para efetuar o pagamento.
{
"estimated_delivery_time": {
"type": "known|known_frame|unknown_frame",
"date": 2015-09-10T00: 00: 00: 000-03: 00,
"shipping": 72,
"handling": 24,
"unit": "hour",
"offset": {
"date": null,
"shipping": null
},
"time_frame": {
"from": "12: 00",
"to": "15: 00"
},
"pay_before": null
}
}
Tipos de promessa de entrega
Para conhecer os diferentes tipos de promessa de entrega você deve fazer o seguinte GET:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/lead_time
known: no caso de ser uma data exata e com handling time conhecido.
[...]
"estimated_delivery_time": {
"type": "known",
"date": "2015-09-10T00:00:00:000-03:00",
"shipping": 72,
"handling": 24,
"unit": "hour",
"offset": {
"date": null,
"shipping": null
},
"time_frame": {
"from":"12:00",
"to": "15:00"
},
"pay_before": null
},
[...]
Unknown: no caso de ser uma data exata, desconsiderando o handling time, expresso em dias úteis.
[...]
"estimated_delivery_time": {
"type": "unknown",
"date": null,
"shipping": 72,
"handling": null,
"unit": "hour",
"offset": {
"date": null,
"shipping": null
},
"time_frame": {
"from":"null",
"to": "null"
},
"pay_before": null
},
[...]
known_frame: no caso de ser um intervalo de datas específicas, o handling time é conhecido.
[...]
"estimated_delivery_time": {
"type": "known_frame",
"date": "2015-09-10T00:00:00:000-03:00",
"shipping": 72,
"handling": 24,
"unit": "hour",
"offset": {
"date": "2015-09-12T00:00:00:000-03:00",
"shipping": 48
},
"time_frame": {
"from":"12:00",
"to": "15:00"
},
"pay_before": null
},
[...]
unknown_frame: no caso de intervalo de dias úteis, desconhecendo o handling time.
[...]
"estimated_delivery_time": {
"type": "unknown_frame",
"date": "null",
"shipping": 72,
"handling": null,
"unit": "hour",
"offset": {
"date": "null",
"shipping": 48
},
"time_frame": {
"from":"null",
"to": "null"
},
"pay_before": null
},
[...]
Considerações
- O intervalo de dias úteis é definido pelos limites ["shipping", "shipping" + "offset.shipping"]. Ex: Sim "shipping": 96 e "offset.shipping": 48, então o intervalo de entrega estimado será de 4 a 6 dias úteis, inclusive.
- As datas estimadas de entrega ("date" e "offset.date") são sempre dias úteis e só terão valores se o tempo de despacho(handling) é conhecido.
- "time_frame" só se aplica a operadoras que lidam com intervalos de tempo bem definidos.
- "pay_before" só se aplica a transportadoras em que a promessa de entrega esteja condicionada à data e hora em que o pagamento é feito.
- Essas mudanças afetarão da mesma maneira em GET de Shipments.
Próximo: Frete grátis.