Documentação do Mercado Envios

Confira todas as informações necessárias sobre as APIs Mercado Envios.
circulos azuis em degrade

Documentação do

Última atualização em 08/07/2024

Envios Turbo

Importante:
Atualmente, este tipo de logística está disponível apenas para vendedores da Argentina - AMBA.
A partir de 15 de Julho estará também disponível para vendedores do Brasil - São Paulo.

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:


Nota:
- É fundamental respeitar o limite de 1000 RPM em todas as chamadas aos recursos de Flex e Turbo, já que é compartilhado entre estes dois tipos de envios. Manter esse limite garante um uso eficiente e equitativo dos recursos disponíveis.
- O aplicativo de entregas Flex do Mercado Livre é necessário para digitalizar as entregas e planejar as rotas de entrega. No entanto, não está disponível para integrações, o que significa que as empresas logísticas precisarão se adaptar.

Á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)
Brasil São Paulo

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.

Nota:
No contexto das assinaturas, cada uma delas possui um identificador único chamado service_id. Este identificador é fundamental para acessar as configurações da assinatura e fazer alterações nela. Neste caso, o que será usado é o service_id da modalidade 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"
    ]
Nota:
- É importante esclarecer que Turbo não é um tipo de logística em si. Isso significa que, ao interagir com nossos endpoints, o atributo logistic_type continuará retornando o valor self_service e não Turbo.
- Da mesma forma, essa mesma diferença poderá ser encontrada nas tags de:
- https://api.mercadolibre.com/users/$USER_ID/shipping_preferences
- https://api.mercadolibre.com/orders/$ORDER_ID/shipments

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.
Nota:
- Diferente da configuração de intervalos horários de entrega de Flex, os Envios Turbo tem vários intervalos horários. Estes intervalos de horário definem uma janela na qual o vendedor deve realizar os envios associados à venda na hora prevista.
- Os valores de From e To que definem cada intervalo são "filhos" e devem ser tomados da resposta do serviço devolvida ao vendedor na configuração de Turbo, através do atributo configuration.accurate_ranges (não podendo definir intervalos custom).
- Por exemplo: se o intervalo de horário é de 12:00 a 14:00 significa que para as vendas realizadas entre as 11:00 e as 12:00 o vendedor entregar o pacote entre as 12:00 e as 14:00, podendo assim passar um máximo de 3 horas entre a venda e a entrega.
- Os intervalos de horários de entrega estão disponíveis apenas de segunda a sexta-feira indicando desde que hora (from) até que hora (to) se define um intervalo horário de entrega turbo.
- Para garantir a precisão da informação sobre a capacidade de entrega, inclusive se modificada a capacidade de apenas um intervalo de entrega, é necessário enviar todos os intervalos de entrega ativos com a sua capacidade. Caso contrário, se assumirá que os intervalos não enviados não estão ativos.
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
}
Nota:
Neste exemplo, se estabelece que o vendedor tem cobertura de entrega em um raio de 8000 metros. OS raios podem variar desde um mínimo de 1000 metros até um máximo de 8000 metros.

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



Importante:
Antes de anunciar ou editar um item utilizando o Turbo, é importante considerar os seguintes aspectos.
1. Verificar que o vendedor já tenha ativo o tipo de logística Flex.
2. Verificar que o item tenhaFlex ativo.
3. Verificar que o item cumpre com as dimensões estabelecidas:
  • Altura: 70 cm
  • Largura: 70 cm
  • Comprimento: 70 cm
  • Peso: 30000 gr = 30 kg
4. Considerar que se um item cumpre estes requisitos, a ativação é automática, ou seja, Turbo aparecerá de maneira imediata no anúncio.
5. Se não quiser oferecer o item com Turbo, recomendamos desativar ou excluí-lo de Flex.
Estes passos garantem uma gestão adequada dos itens no Mercado Livre e ajudam a oferecer a melhor experiência de compra aos usuários. .