Documentação do Mercado Envios
Confira todas as informações necessárias sobre as APIs Mercado Envios.Documentação do
Envios Turbo
Envios Turbo é um serviço de entrega que se concentra em fornecer entregas rápidas em menos de 3 horas. Ele foi projetado para atender em um raio próximo ao vendedor e se baseia no modelo logístico Flex. Este serviço tem como objetivo oferecer uma opção de entrega extremamente rápida para oferecer um serviço de alta qualidade aos usuários.
Encuentra más información relacionada con Turbo en los siguientes enlaces:
- Envios Flex
- Como calcular os tempos de entrega com Envios Turbo
- Perguntas frequentes sobre envios turbo
- Leve suas vendas a um novo nível com Envios Turbo
- Primeiros passos com Envios Turbo
Áreas de cobertura por países
Para poder oferecer Envios Turbo, o endereço de envio do vendedor deve estar habilitado para uma das áreas de cobertura, de acordo com o país:
País | Cobertura |
---|---|
Argentina | - AMBA (Área Metropolitana de Buenos Aires) |
Configurar um usuário teste
Para configurar a funcionalidade de Envios Turbo para usuários de teste, considere:
1. Inicie seção na conta que deseja habilitar Envio Turbo.
2. Valide que o usuário já tenha ativo Envios Flex, pois é um requisito prévio.
3. Assegure-se de que a conta tenha anúncios ativos em ME2.
4. Verifique que sua conta tenha uma reputação Amarela ou Verde.
5. Assegure-se de ter um endereço de e-mail compatível com a área de cobertura do seu país.
6. Configure o endereço de envio em AMBA.
7. Ative Envios Turbo na conta entrando em "Meu perfil" > "Vendas" > "Preferências de Venda">
Uma vez que tenha completado estes passos, poderá utilizar Envios Turbo como usuário de teste.
Consultar assinatura de um usuário
Este endpoint permite consultar as assinaturas que um usuário possui.
- Se o usuário ativar ambos serviços, Flex e Turbo, ele terá duas assinaturas, já que Flex é um requisito para acessar o Turbo..
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/subscriptions/v1
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/subscriptions/v1
Resposta:
[
{
"id": 111181,
"site_id": "MLA",
"user_id": 1438865529,
"mode": "FLEX",
"configuration_type": {
"coverage": "zone",
"delivery": "custom"
},
"service_id": 736230,
"status": {
"id": "in",
},
"creation_date": "2023-08-02T06:34:40Z"
},
{
"id": 111183,
"site_id": "MLA",
"user_id": 1438865529,
"mode": "TURBO",
"configuration_type": {
"coverage": "radius",
"delivery": "accurate"
},
"service_id": 738216,
"status": {
"id": "in",
},
"creation_date": "2023-08-02T06:35:30Z"
}
]
Parámetros de resposta:
- id ID único da assinatura.
- site_id identificador do país.
- user_id ID do usuário.
- mode tipo de assinatura (TURBO neste caso).
- configuration_type Ttipo de configuração da inscrição (TURBO neste caso).
- configuration_type.coverage tipo de cobertura.
- configuration_type.delivery tipo de entrega.
- service_id ID do serviço associado a assinatura.
- status estado da assinatura.
- status.id: tipos de estados da assinatura:
- in: a assinatura está ativa. Nesse estado, o usuário pode alterar suas configurações e receber pedidos de envio no modo de assinatura.
- out: a assinatura não está ativa. Nesse estado, o usuário não pode alterar as configurações.
- pending: a assinatura está pendente de ativação. Nesse estado, o usuário pode alterar as configurações, embora não vá receber pedidos para realizar entregas.
- creation_date data de criação da assinatura.
Códigos de estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Atualizou corretamente a configuração. | - |
400 - Bad Request | empty site id | O site_id está vazio. | Validar o site_id. |
400 - Bad Request | invalid site_id | Site_id inválido. | Validar se o site_id está habilitado para envios turbo. |
400 - Bad Request | can't access to resource | Site_id inválido. | Validar se o site_id está habilitado para envios turbo. |
404 - Not Found | user not found | O usuário não existe. | Validar o user_id. |
Identificar ordens Turbo
Este endpoint determina se um envio será processado pelo serviço Turbo, permitindo concluir a transação de forma eficaz.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/42469883906
Resposta:
"tags": [
"turbo"
]
Consultar a configuração da assinatura
Este endpoint permite consultar a configuração das assinaturas que tem um usuário para este caso de Turbo.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/configuration/v3
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/configuration/v3
{
"query": "{ configuration(user_id: 1438865529, service_id: 738216) { address { id address_line city { id name } zip_code } subscription { site_id user_id service_id status { id } creation_date training_times { original { value unit } remaining { value unit } activation_date } } delivery_window is_moderated delivery_ranges { week { capacity type processing_time from to et_hour calculated_cutoff } saturday { capacity type processing_time from to et_hour calculated_cutoff } sunday { capacity type processing_time from to et_hour calculated_cutoff } } working_days radius availables { capacity_range { from to } accurate_ranges { from to } radius_range { from to } } disabled_features } }"
}
Resposta:
{
"configuration": {
"address": {
"address_line": "Testing Street 1450",
"city": {
"id": "TUxBQlNBQTM3Mzda",
"name": "Saavedra"
},
"id": "1316123989",
"zip_code": "1430"
},
"availables": {
"capacity_range": {
"from": 1,
"to": 5
},
"accurate_ranges": [
{
"from": 10
"to": 12
},
{
"from": 11
"to": 13
},
{
"from": 12
"to": 14
},
{
"from": 13
"to": 15
},
{
"from": 14
"to": 16
},
{
"from": 15
"to": 17
},
{
"from": 16
"to": 18
}
],
"radius_range" {
"from": 1,
"to": 5
}
},
"delivery_ranges": {
"saturday": null,
"sunday": null,
"week": [
{
"calculated_cutoff": 10,
"capacity": 5,
"et_hour": null,
"from": 10,
"processing_time": 0,
"to": 12,
"type": "etd"
},
{
"calculated_cutoff": 11,
"capacity": 5,
"et_hour": null,
"from": 11,
"processing_time": 0,
"to": 13,
"type": "etd"
},
{
"calculated_cutoff": 12,
"capacity": 5,
"et_hour": null,
"from": 12,
"processing_time": 0,
"to": 14,
"type": "etd"
},
{
"calculated_cutoff": 13,
"capacity": 5,
"et_hour": null,
"from": 13,
"processing_time": 0,
"to": 15,
"type": "etd"
},
{
"calculated_cutoff": 14,
"capacity": 5,
"et_hour": null,
"from": 14,
"processing_time": 0,
"to": 16,
"type": "etd"
},
{
"calculated_cutoff": 15,
"capacity": 5,
"et_hour": null,
"from": 15,
"processing_time": 0,
"to": 17,
"type": "etd"
},
{
"calculated_cutoff": 16,
"capacity": 5,
"et_hour": null,
"from": 16,
"processing_time": 0,
"to": 18,
"type": "cpt"
}
]
},
"delivery_window": "same_day",
"disabled_features": [],
"is_moderated": false,
"subscription": {
"creation_date": "2023-08-02T06:35:30Z",
"service_id": 738216,
"site_id": "MLA",
"status": {
"id": "in"
},
"training_times": null,
"user_id": 1438865529
},
"working_days": [
"week"
],
"radius": 8000
}
}
Parâmetros de resposta:
- address: endereço do usuário.
- aavailables: informações sobre a capacidade, cortes e intervalos disponíveis para o serviço.
- availables.capacity_range: intervalo de valores para capacidade.
- availables.accurate_ranges: intervalos horários de Turbo disponíveis (como mínimo o usuário deve selecionar 3).
- availables.radius_range: intervalo de raios disponíveis em km.
- delivery_ranges: informação sobre a capacidade, cortes e intervalos disponíveis para os diferentes dias da semana.
- delivery_ranges.saturday: intervalos de entrega e capacidade para os sábados (considerar que atualmente Turbo não está disponível para os sábados).
- delivery_ranges.sunday: rntervalos de entrega e capacidade para os domingos (considerar que atualmente Turbo não está disponível para os domingos).
- delivery_ranges.week: intervalos de entrega e capacidade para os dias da semana.
- delivery_window: o tipo de serviço para a entrega. O único valor possível para Turbo é “same_day” (envios no mesmo dia).
- disabled_features: características desabilitadas para o serviço, incluindo, por exemplo: "CUTOFF_BY_ZONE" e "CAPACITY_BY_DAY".
- is_moderated: indica se o serviço está moderado (true/false).
- subscription: informação sobre a assinatura do usuário.
- working_days: dias laborais disponíveis.
- radius: raio de cobertura em metros. A cobertura se define por uma circunferência com o centro e o endereço do vendedor e o raio definido.
Códigos de estado de Resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | A configuração foi atualizada corretamente. | - |
400 - Bad Request | empty site id | O site_id está vazio. | Validar o site_id. |
400 - Bad Request | invalid site_id | Site_id inválido. | Validar se o site_id está habilitado para Envios Turbo. |
400 - Bad Request | can't access to resource | Site_id inválido. | Validar se o site_id está habilitado para Envios Turbo. |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecida. |
400 - Bad Request | failed to create schema in graphql operation | GraphQL inválida para o esquema definido. | Validar o esquema de query estabelecida. |
400 - Bad Request | invalid query | GraphQL inválida para o esquema definido. | Validar o esquema de query estabelecida. |
404 - Not Found | subscriptions not found | Não existe assinatura a Envios Turbo para a combinação de user_id e service_id enviada. | Validar o user_id e service_id nol endpoint. |
404 - Not Found | user not found | No existe el usuario. | Validar o user_id. |
Configurar intervalo de horários de entrega e limite de envios
A través de este endpoint, es posible configurar diferentes aspectos para Envíos Turbo como:
- Intervalos de horários de entrega
- Limite de envios
Chamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/delivery/accurate/v3
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/delivery/accurate/v3
{
"delivery_ranges": {
"week": [
{
"from": 10,
"to": 12,
"capacity": 30
},
{
"from": 11,
"to": 13,
"capacity": 20
},
{
"from": 12,
"to": 14,
"capacity": 10
}
]
}
}
Parâmetros de resposta:
- delivery_ranges.week: informação sobre o intervalo de entrega e limite de envios.
- from: hora de início do intervalo de tempo para a entrega.
- to: hora de finalização do intervalo de tempo para a entrega.
- capacity: capacidade de entrega para o intervalo de tempo dado.
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Configuração atualizada corretamente. | - |
400 - Bad Request | invalid user_id | User_id inválido. | Validar o user_id (deve ser um número inteiro). |
400 - Bad Request | invalid service_id | Service_id inválido. | Validar o service_id (deve ser um número inteiro). |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecido. |
404 - Not Found | can't update delivery custom | Não foi possível realizar a atualização da configuração devido a que não existe assinatura a Envios Turbo para a combinação de user_id e service_id enviada. | Validar o user_id e service_id no endpoint. |
Ampliar área de cobertura Turbo
Este endpoint permite adicionar mais áreas de coberturas para Envios Turbo.
Chamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/coverage/radius/v3
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/coverage/radius/v3
{
"radius": 8000
}
Códigos de estado de respuesta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Configuração atualizada corretamente. | - |
400 - Bad Request | invalid user_id | User_id inválido. | Validar o user_id (deve ser um número inteiro). |
400 - Bad Request | invalid service_id | Service_id inválido. | Validar o service_id (deve ser um número inteiro). |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecido. |
404 - Not Found | can't update delivery custom | Não foi possível realizar a atualização da configuração devido a que não existe assinatura a Envios Turbo para a combinação de user_id e service_id enviada. | Validar o user_id e service_id no endpoint. |
Gestão de itens Turbo
A gestão de itens em Turbo implica a ativação de Turbo para tais itens. Para realizar esta ação, é fundamental considerar o seguinte:
1. Antes de ativar Turbo, é necessário habilitar Flex.
2. Os itens que contam com Flex ativo irão oferecer Turbo quando cumpram com as restrições de dimensões e peso de Envios Turbo.
3. A ativação é automática uma vez que cumpram os requisitos prévios