Calcular o custo do frete e o handling time

Os vendedores poderão usar a calculadora de envio na página de descrição do item e os compradores saberão o custo de remessa e o handling time.

Conteúdos:

→Atributos da calculadora
→Calcular o frete de acordo com o CEP e as dimensões do item
→Calcular o frete de acordo com o usuário e CEP
↳Calcule o envio em MCO (Colômbia)
↳Custos de envio por usuário, cidade e dimensões em MCO (Colômbia)
→Descrições dos atributos
→Tipos de promessa de entrega
→Considerações

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.

id: ID da cidade de destino.
name: nome da cidade de destino.

state (estado): Informação do estado de destino.

id: ID do estado de destino.
name: nome do estado de destino.

country (país): Informação do país de destino.

id: ID del país de destino.
name: nome do país de destino.

extended_attributes (atributos estendidos): informações adicionais do endereço 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.

verified(verificado): pode ser rastreado internamente.
not_verified: As informações de rastreamento devem ser fornecidas pelo vendedor.
no: não é possível rastrear.

display: ID do método de envio para processamento frontend.

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

speed (velocidade): informações de velocidade de entrega.

shipping (envio): Média de horas de envio.
handling (em manuseio): Média de horas para o vendedor despachar a remessa.

Calcule o frete de acordo com o CEP e as dimensões do item

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping_options?zip_code_from=$ZIP_CODE_FROM&zip_code_to=$ZIP_CODE_TO&dimensions=$DIMENSIONS

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping_options?zip_code_from=01310909&zip_code_to=01310909&dimensions=16x16x16,1500

Resposta:

{
  "destination": {
	"zip_code": "01310909",
	"city": {
  	"id": "BR-SP-44",
  	"name": "São Paulo"
	},
	"state": {
  	"id": "BR-SP",
  	"name": "São Paulo"
	},
	"country": {
  	"id": "BR",
  	"name": "Brasil"
	},
	"extended_attributes": {
  	"address": "Avenida Paulista, 688",
  	"owner_name": "Edifício Santa Filippa",
  	"zip_code_type": {
    	"type": "LO",
    	"description": "Logradouro"
  	},
  	"city_type": "CI",
  	"city_name": "São Paulo",
  	"neighborhood": "Bela Vista",
  	"status": "active"
	}
  },
  "options": [
	{
  	"id": 27554373,
  	"name": "Normal",
  	"shipping_method_id": 100009,
  	"currency_id": "BRL",
  	"list_cost": 9.66,
  	"cost": 9.66,
  	"tracks_shipments_status": "not_verified",
  	"display": "recommended",
  	"speed": {
    	"shipping": 96,
    	"handling": 48
  	},
  	"estimated_delivery": {
    	"date": "2016-02-26T00:00:00.000-02:00",
    	"pay_before": null,
    	"time_from": null,
    	"time_to": null
  	},
  	"estimated_delivery_time": {
    	"type": "known_frame",
    	"date": "2016-02-24T00:00:00.000-02:00",
    	"shipping": 48,
    	"handling": 48,
        "unit": "hour",
    	"offset": {
      	"date": "2016-02-26T00:00:00.000-02:00",
      	"shipping": 48
    	},
    	"time_frame": {
      	"from": null,
      	"to": null
    	},
    	"pay_before": null
  	},
  	"discount": {
    	"rate": 0,
    	"type": "none",
    	"promoted_amount": 0
  	}
	},
	{
  	"id": 27551043,
  	"name": "Expresso",
  	"shipping_method_id": 182,
  	"currency_id": "BRL",
  	"list_cost": 9.83,
  	"cost": 9.83,
  	"tracks_shipments_status": "not_verified",
  	"display": "always",
  	"speed": {
    	"shipping": 48,
    	"handling": 48
  	},
  	"estimated_delivery": {
    	"date": "2016-02-24T00:00:00.000-02:00",
    	"pay_before": null,
    	"time_from": null,
    	"time_to": null
  	},
  	"estimated_delivery_time": {
    	"type": "known_frame",
    	"date": "2016-02-23T00:00:00.000-02:00",
    	"shipping": 24,
    	"handling": 48,
    	"unit": "hour",
    	"offset": {
      	"date": "2016-02-24T00:00:00.000-02:00",
      	"shipping": 24
    	},
    	"time_frame": {
      	"from": null,
      	"to": null
    	},
    	"pay_before": null
  	},
  	"discount": {
    	"rate": 0,
        "type": "none",
    	"promoted_amount": 0
  	}
	}
  ]
}

Calcule o frete de acordo com o usuário e o CEP

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_options?zip_code=$ZIP_CODE&dimensions=$DIMENSIONS

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/190990642/shipping_options?zip_code=01310909&dimensions=16x16x16,1500

Resposta:

{
  "destination": {
	"zip_code": "01310909",
	"city": {
  	"id": "BR-SP-44",
  	"name": "São Paulo"
	},
	"state": {
  	"id": "BR-SP",
  	"name": "São Paulo"
	},
	"country": {
  	"id": "BR",
  	"name": "Brasil"
	},
	"extended_attributes": {
  	"address": "Avenida Paulista, 688",
  	"owner_name": "Edifício Santa Filippa",
  	"zip_code_type": {
    	"type": "LO",
    	"description": "Logradouro"
  	},
  	"city_type": "CI",
  	"city_name": "São Paulo",
  	"neighborhood": "Bela Vista",
  	"status": "active"
	}
  },
  "options": [
	{
  	"id": 27555383,
  	"name": "Normal",
  	"shipping_method_id": 100009,
  	"currency_id": "BRL",
  	"list_cost": 11.86,
  	"cost": 11.86,
  	"tracks_shipments_status": "not_verified",
  	"display": "recommended",
  	"speed": {
    	"shipping": 96,
    	"handling": 48
  	},
  	"estimated_delivery": {
    	"date": "2016-03-01T00:00:00.000-02:00",
    	"pay_before": null,
    	"time_from": null,
    	"time_to": null
  	},
  	"estimated_delivery_time": {
    	"type": "known_frame",
    	"date": "2016-02-26T00:00:00.000-02:00",
    	"shipping": 48,
    	"handling": 48,
    	"unit": "hour",
    	"offset": {
          "date": "2016-03-01T00:00:00.000-02:00",
      	"shipping": 48
    	},
    	"time_frame": {
      	"from": null,
      	"to": null
    	},
    	"pay_before": null
  	},
  	"discount": {
    	"rate": 0,
    	"type": "none",
    	"promoted_amount": 0
  	}
	},
	{
  	"id": 27843879,
  	"name": "Expresso",
  	"shipping_method_id": 182,
  	"currency_id": "BRL",
  	"list_cost": 16.48,
  	"cost": 16.48,
  	"tracks_shipments_status": "not_verified",
  	"display": "always",
  	"speed": {
    	"shipping": 48,
    	"handling": 48
  	},
  	"estimated_delivery": {
    	"date": "2016-02-26T00:00:00.000-02:00",
    	"pay_before": null,
    	"time_from": null,
    	"time_to": null
  	},
  	"estimated_delivery_time": {
    	"type": "known_frame",
    	"date": "2016-02-25T00:00:00.000-02:00",
    	"shipping": 24,
    	"handling": 48,
    	"unit": "hour",
    	"offset": {
      	"date": "2016-02-26T00:00:00.000-02:00",
      	"shipping": 24
    	},
    	"time_frame": {
      	"from": null,
      	"to": null
    	},
    	"pay_before": null
  	},
  	"discount": {
    	"rate": 0,
    	"type": "none",
    	"promoted_amount": 0
  	}
	}
  ]
}

Calcule de acordo com a cidade e dimensões em MCO (Colômbia)

Você pode calcular os custos de envio para um site específico. O MCO é diferente de outros sites porque o cálculo é realizado de acordo com os parâmetros city_from, city_to e dimensões. Como pode ver no exemplo a seguir, este recurso permite multiget. Você deve vincular os códigos das cidades um por um.

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MCO/shipping_options?city_from=Q08tRENCb2dvdA&city_to=TUNPQ0NBUjcwNTYz,TUNPQ01FRGRjNjc4&dimensions=10x10x10,1000

Resposta:

{
  "TUNPQ01FRGRjNjc4": {
	"destination": {
  	"zip_code": null,
  	"city": {
    	"id": "TUNPQ01FRGRjNjc4",
    	"name": "Medellín"
  	},
  	"state": {
    	"id": "CO-ANT",
    	"name": "Antioquia"
  	},
  	"country": {
    	"id": "CO",
    	"name": "Colombia"
  	}
	},
	"options": [
  	{
    	"id": 523836053,
    	"name": "Servientrega Normal",
    	"shipping_method_id": 501745,
    	"currency_id": "COP",
    	"list_cost": 7500,
    	"cost": 7500,
    	"tracks_shipments_status": "not_verified",
    	"display": "recommended",
    	"speed": {
      	"shipping": 24,
      	"handling": 72
    	},
    	"estimated_delivery": {
      	"date": "2016-02-26T00:00:00.000-05:00",
      	"pay_before": null,
      	"time_from": null,
      	"time_to": null
    	},
    	"estimated_delivery_time": {
      	"type": "known",
      	"date": "2016-02-26T00:00:00.000-05:00",
      	"shipping": 24,
      	"handling": 72,
      	"unit": "hour",
      	"offset": {
        	"date": null,
        	"shipping": null
      	},
      	"time_frame": {
        	"from": null,
        	"to": null
      	},
      	"pay_before": null
    	},
    	"discount": {
      	"rate": 0,
      	"type": "none",
      	"promoted_amount": 0
    	}
  	}
	]
  },
  "TUNPQ0NBUjcwNTYz": {
	"destination": {
  	"zip_code": null,
  	"city": {
    	"id": "TUNPQ0NBUjcwNTYz",
    	"name": "Cartagena De Indias"
  	},
  	"state": {
    	"id": "CO-BOL",
    	"name": "Bolivar"
  	},
  	"country": {
    	"id": "CO",
    	"name": "Colombia"
  	}
	},
	"options": [
  	{
    	"id": 523835977,
    	"name": "Servientrega Normal",
    	"shipping_method_id": 501745,
    	"currency_id": "COP",
    	"list_cost": 7500,
    	"cost": 7500,
    	"tracks_shipments_status": "not_verified",
    	"display": "recommended",
    	"speed": {
      	"shipping": 48,
      	"handling": 72
    	},
    	"estimated_delivery": {
      	"date": "2016-02-29T00:00:00.000-05:00",
      	"pay_before": null,
      	"time_from": null,
      	"time_to": null
    	},
    	"estimated_delivery_time": {
      	"type": "known",
      	"date": "2016-02-29T00:00:00.000-05:00",
      	"shipping": 48,
      	"handling": 72,
      	"unit": "hour",
      	"offset": {
        	"date": null,
        	"shipping": null
      	},
      	"time_frame": {
        	"from": null,
        	"to": null
      	},
      	"pay_before": null
    	},
    	"discount": {
      	"rate": 0,
      	"type": "none",
      	"promoted_amount": 0
    	}
  	}
	]
  }
}

Custos de envio por usuário, cidade e dimensões em MCO (Colômbia)

Se desejar, você pode calcular os custos de envio para um usuário específico, uma cidade e dimensões específicas. Como pode ver no exemplo a seguir, este recurso permite multiget. Você deve concatenar os códigos das cidades um por um.

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/454271894/shipping_options?city_to=Q08tRENCb2dvdA,TUNPQ01FRGRjNjc4&dimensions=15x15x15,650

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": 11110,
        	"name": "Servientrega Estandar",
            "shipping_method_id": 501745,
        	"currency_id": "COP",
        	"list_cost": 7.5,
        	"cost": 7.5,
            "tracks_shipments_status": "verified",
        	"display": "recommended",
        	"speed": {
            	"shipping": 48,
            	"handling": null
        	},
            "estimated_delivery": {
            	"date": null,
            	"pay_before": null,
            	"time_from": null,
            	"time_to": null
        	},
        	"discount": {
            	"rate": 0
        	}
    	}
	],
	"settings": {
    	"allow_add_cost": null
	}
}

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.