Frete Dinâmico

Flete Dinâmico é uma funcionalidade do Mercado Envios 1 que agiliza a seleção de preços e prazos de envio para vendedores, fornecendo aos compradores informações precisas sobre os prazos de entrega. Essa configuração verifica em tempo real os preços e condições de envio, mostrando o custo do envio antes da compra, aprimorando a experiência e a eficiência logística. Além disso, para registrar corretamente o desenvolvimento dessa funcionalidade, é necessário passar por um processo de homologação.

Dinâmica de Homologação

A homologação é um processo no qual o Mercado Livre verifica e aprova uma URL externa para que os usuários possam se registrar no Mercado Livre a partir desse site de maneira segura e confiável. Isso envolve testes técnicos, avaliação de segurança e a implementação de medidas necessárias para garantir a autenticidade e proteção dos dados dos usuários. Uma vez aprovada, a URL se torna um canal válido para os usuários do ME1.

Requisitos de Homologação

A continuación, se presentan los requisitos de homologación para asegurar una integración exitosa con nuestra plataforma de flete dinâmico:

• Cumprimento do Contrato
• Tempo de Resposta Ótimo
• Localização da Infraestrutura
• Especificações de Origem e Destino de Dados
• Uso de Cache
• Monitoramento de Erros
• Contingência do Mercado Livre

Cumprimento do Contrato

A seguir, apresentamos uma abordagem passo a passo ao criar o endpoint para homologação:

• A URL não tem uma estrutura específica, proporcionando flexibilidade na configuração.
• Cada solicitação deve conter apenas um item de um vendedor. Isso é fundamental para manter a eficiência na transmissão de dados.
• Utilize o método HTTP GET para acessar o endpoint. Esse método é adequado para solicitar dados e é comumente usado em integrações web.
• Detalhe claramente a fonte de dados (origem) e o sistema de destino. Compreender esses aspectos é fundamental para garantir um fluxo de dados sem problemas e preciso.

Tempo de Resposta Ótimo

Esse enfoque é essencial para garantir uma experiência de usuário eficiente e evitar problemas de integração com os vendedores. Para isso:

• Familiarize-se com a necessidade de manter o tempo de resposta abaixo de 400 ms e compreenda sua importância para uma integração bem-sucedida.
• Antes de ativar o endpoint, submeta-o a uma validação de carga inicial. Isso implica avaliar seu tempo de resposta em condições normais de uso.
• Se o tempo de resposta ultrapassar o limite, são necessárias ações corretivas. Isso pode incluir a revisão e otimização do código e da infraestrutura.
• Se o tempo de resposta atender ao requisito de 400 ms, a integração é aprovada e pode ser ativada para os vendedores.
• Certifique-se de continuar otimizando o tempo de resposta de forma contínua para proporcionar uma experiência de usuário excepcional.

Localização da Infraestrutura

Seguindo esses passos, você poderá tomar decisões informadas para melhorar o desempenho de sua aplicação com base na localização da infraestrutura:

• Considere que a atual infraestrutura de flete dinâmico está localizada na região leste dos Estados Unidos, mais especificamente, em Virginia.
• Avalie se é necessário otimizar sua aplicação ou ajustar a configuração para aproveitar ao máximo a localização da infraestrutura.

Origem e Destino de Dados

Especificações da fonte de dados (origem)

As especificações da fonte de dados fazem parte do protocolo de comunicação ou intercâmbio de dados no processo de homologação:

Exemplo por Zip_Code:

{
  "seller_id": 337352780,
  "buyer_id": 3123212,
  "declared_value": 69.9,
  "items": [
    {
      "id": "MLB1223500643",
      "variation_id": 0,
      "category_id": "ABC1234",
      "price": 69.9,
      "quantity": 1,
      "sku": "RB-PC890A",
      "store_id": 231,
      "dimensions": {
        "height": 10,
        "width": 10,
        "length": 31,
        "weight": 500
      }
    }
  ],
  "destination": {
    "type": "zipcode",
    "value": "88063038"
  },
  "origin": {
    "type": "zipcode",
    "value": "88063038"
  }
}

Exemplo por City:

{
  "seller_id": 337352780,
  "buyer_id": 3123212,
  "declared_value": 69.9,
  "items": [
    {
      "id": "MLB1223500643",
      "variation_id": 0,
      "category_id": "ABC1234",
      "price": 69.9,
      "quantity": 1,
      "sku": "RB-PC890A",
      "store_id": 231,
      "dimensions": {
        "height": 10,
        "width": 10,
        "length": 31,
        "weight": 500
      }
    }
  ],
"destination": {
    "type": "city",
    "value": "Ñuble/Yungay"
  },
  "origin": {
    "type": "city",
    "value": "Metropolitana/Pudahuel"
   }
}

Parâmetros de resposta:

• seller_id (string)​​: obrigatório. É a identificação da conta dentro do Mercado Livre.
• buyer_id (string): opcional. É o identificador do usuário que está realizando a compra no Mercado Livre. Está disponível apenas quando o usuário que está fazendo a cotação está logado na plataforma do Mercado Livre.
• declared_value (float)​​: opcional. É o valor que será declarado na fatura.
• items (array): obrigatório. Informações sobre o item comprado.
• items.id (string): obrigatório. É a identificação do produto registrado no Mercado Livre.
• items.variation_id (string): obrigatório. É a identificação da variante escolhida pelo comprador para a compra, possui dados apenas quando a cotação corresponde a um item com variação.
• items.category_id (string)​​: opcional. É a identificação da categoria do produto dentro do Mercado Livre.
• items.price (float)​​: opcional. É o preço unitário do produto multiplicado pela quantidade de itens escolhidos pelo comprador no momento da cotação.
• items.quantity (int)​​: obrigatório. É a quantidade que será comprada do mesmo produto.
• items.sku (string)​​: obrigatório. É a identificação do produto ao ser comprado.
• items.store_id (string)​​: opcional. É a identificação da loja oficial dentro do Mercado Livre.
• items.dimensions (object)​​: obrigatório. É a lista de medidas de um produto.
• items.dimensions.length (int)​​: obrigatório. É o comprimento do produto (em centímetros)
• items.dimensions.width (int)​​: obrigatório. É a largura do produto (em centímetros).
• items.dimensions.height (int)​​: obrigatório. É a largura do produto (em centímetros).
• items.dimensions.weight (int)​​: obrigatório. É o peso do produto (em gramas).
  
• origin (object)​​: opcional. É a informação do endereço de origem da entrega ou do vendedor.
• destination (object)​: obrigatório. É a informação do endereço onde o produto será entregue. A seguir, os detalhes de acordo com cada país:

Especificações do destino dos dados (destino)

As especificações do destino de dados fazem parte do protocolo de comunicação ou intercâmbio de dados no processo de homologação:

Exemplo:

{
   "destinations":[
      "88063038"
   ],
   "packages":[
      {
         "dimensions":{
            "height":10,
            "width":10,
            "length":15,
            "weight":500
         },
         "items":[
            {
               "id":"MLB1223500643",
               "variation_id":3123212,
               "quantity":1,
               "dimensions":{
                  "height":10,
                  "width":10,
                  "length":15,
                  "weight":500
               }
            }
         ],
         "quotations":[
            {
               "price":119.88,
               "handling_time":0,
               "shipping_time":4,
               "promise":4,
               "service":99
            },
            {
               "price":0,
               "handling_time":0,
               "shipping_time":6,
               "promise":6,
               "service":99
            }
         ]
      }
   ]
}

Parâmetros de resposta:

• destinations (array)​​: informação que contém códigos postais ou outras identificações de destinos para os quais os pacotes serão enviados.
• packages (array)​​: informação que representa os pacotes criados pelo vendedor.
• packages.dimensions (object): obrigatório. É a lista de medidas do pacote.
• items (array): obrigatório. Informação sobre o item comprado.
• items.id (string): obrigatório. É a identificação do item registrado no Mercado Livre.
• items.variation_id (string): obrigatório. É a identificação da variante escolhida pelo comprador.
• items.quantity (int)​​: é a quantidade do produto que será enviada.
• items.dimensions (object)​​: obrigatório. É a lista de medidas do item.
• quotations (array)​​: obrigatório. informações de frete para um produto.
• quotations.price (float)​​: é o preço do frete que será apresentado ao comprador.
• quotations.handling_time (int)​​: é o tempo, em dias úteis, que será utilizado para separar e embalar o produto. Inclui todos os processos anteriores ao envio efetivo do pacote. Caso essa informação não esteja disponível, deve ser devolvido o valor 0.
• quotations.shipping_time (int)​​: é o tempo, em dias úteis, de trânsito do pacote (desde a entrada no caminhão até a entrega ao comprador).
• quotations.promise (int)​​: é a soma dos valores de handling_time e shipping_time.
• quotations.service (int): é o código do serviço/carrier com identificação única, que vai de 0 a 99, atribuído pelo vendedor/integrador.

No caso de ocorrer um erro interno ou se um item estiver relacionado a um erro, a estrutura da resposta deve seguir o seguinte formato:

• Para o código de erro 3 (sem cobertura), o estado HTTP deve ser 400 (Pedido incorreto).
• Para qualquer outro código de erro ou erro interno relacionado com a cotação, o estado HTTP deve ser 500 (Erro interno do servidor).

Exemplo de Resposta:

{
   "message": "any message",
   "error_code": 1
}

Uso de Cache

Neste contexto, será utilizado o RFC IETF 7234, uma especificação amplamente reconhecida que estabelece as melhores práticas para o armazenamento em cache de chamadas HTTP.

Verbo HTTP

Neste contexto, é essencial alinhar a semântica de nossas chamadas com o protocolo HTTP, que sugere que apenas chamadas GET devem ser armazenadas em cache.

Headers

Devem ser incorporados cabeçalhos adicionais nas chamadas e respostas feitas aos integradores. No caso das chamadas, devem ser adicionados os seguintes cabeçalhos:

Por outro lado, nas respostas fornecidas pelos integradores, é necessário incluir os seguintes cabeçalhos adicionais:

Buscando otimizar nossas respostas e reduzir o número de chamadas, o atributo chamado destinations conterá uma lista de destinos em formato de strings, indicando todos os lugares onde a cotação pode ser utilizada. Agora, com uma única cotação, é possível evitar várias chamadas, melhorando significativamente a eficiência de nossas APIs.
A seguir, apresentamos um exemplo de como verificar o cabeçalho ETag retornado para determinar se a resposta em cache ainda é válida. Exemplo de chamada com validação de cache:

Para proporcionar um controle mais granular sobre o armazenamento em cache, estamos introduzindo a diretriz no-store no cabeçalho Cache-Control de nossas respostas. Essa diretriz permite que os parceiros indiquem que uma cotação não deve ser armazenada em cache.

Exemplo de resposta sem permitir o cache:

Exemplo de resposta com cache:

Monitoreo de errores

A continuación, enumeramos los posibles errores en relación al manejo de Flete Dinâmico:

Contingência do Mercado Livre

A Tabela de Contingência, também conhecida como Tabela Axado, é uma planilha de transportadoras que pode ser carregada diretamente do Mercado Livre. Sua função principal é atuar como um plano de backup caso o endpoint ou URL do integrador falhe. Em outras palavras, é uma ferramenta de segurança projetada para manter as operações dos vendedores em funcionamento mesmo quando surgem problemas inesperados.
A seguir, alguns critérios a serem considerados:

• Requisito Inicial: o Consultor Comercial da MELI solicitará ao vendedor a Tabela de Contingência ao ativar a integração com o integrador de flete dinâmico.
• Responsabilidade do Vendedor: o vendedor deve completar e manter atualizada esta tabela com os valores tanto no integrador quanto na MELI.
• Estabelecer Regras de Frete: recomenda-se que o vendedor estabeleça regras claras de frete, como custos zero para locais próximos, para otimizar a entrega.
• Atualização Fácil: se o vendedor desejar atualizar a tabela, pode fazê-lo a partir da MELI, acessando Meu Perfil -> Vendas -> Preferências de Vendas -> Transportadoras.

Além disso, anexamos um detalhamento por país juntamente com um link de referência para a Tabela de Contingência Modelo: