Frete dinâmico

Importante:

Antes de começar o desenvolvimento da ferramenta, é necessário a aprovação do Mercado Livre.

Frete dinâmico tem como objetivo agilizar a seleção de preços e condições de frete para os vendedores com o Mercado Envios 1 e melhorar a experiência do comprador, fornecendo informações mais precisas sobre as condições de frete aplicadas por cada vendedor. Além disso, amplia o catálogo de vendedores que possuem mais de um centro de distribuição, gerando aumento nas vendas.

Conteúdos

→Dinâmica de integração
→Tempo de resposta
→Contingência
→Contrato da API
→Tratativa de erros

Dinâmica de integração

Para integrar esta funcionalidade, é necessário disponibilizar um endpoint, no qual o Mercado Livre fará uma chamada para obter as informações do frete que são exibidas na plataforma no momento da compra.

Tempo de resposta

O tempo de resposta do endpoint não poderá ultrapassar 400ms. Antes da ativação do endpoint, teremos várias validações, entre elas validação de carga para avaliar o tempo de resposta e o resultado será compartilhado com o integrador. Caso ultrapasse o tempo limite, a integração não será aprovada e não poderá ser ativada para os vendedores.

Nota:

A atual infraestrutura frete dinâmico está situada na região leste dos EUA (Virgínia).

Contingência

Para os casos em que a integração falhe ou não responda a tempo, para que o comprador não fique sem resposta, utilizaremos como contingência a calculadora MELI. Nesta ferramenta interna o vendedor carrega suas tabelas de frete com o apoio do assessor comercial. A contingência atual será ativada nas situações abaixo:

erros/indisponibilidade do integrador.
taxa de timeouts muito alta (caso ultrapasse os 400 ms).
quando retornar -1 para o error_code no response.

Contrato da API

Para a criação do endpoint, devem ser seguidas algumas regras do contrato, conforme segue:

O nome do end-point ficará a cargo do integrador, bastando respeitar o “contrato” definido para os requests e responses.
Na requisição enviaremos apenas um item de um determinado vendedor.

Abaixo segue a descrição de cada um dos itens suportados no payload:

destination (string): obrigatório. É o CEP do comprador, onde os produtos serão entregues.

Para Brasil, Argentina e México o código postal será informado.
Para Chile, região/cidade, separado por uma "/".
Para Colômbia, região/cidade.
Para Uruguai, região/cidade.

buyer_id opcional. É o identificador do usuário que está comprando no Mercado Livre. Só está disponível quando o usuário está logado na plataforma Mercado Livre no momento em que realiza a cotação.
seller_id (string): obrigatório. É a identificação da conta dentro do Mercado Livre.
item_id (string): (string): obrigatório. É a identificação do item cadastrado no Mercado Livre.
store_id (string): (string): opcional. É a identificação da loja dentro do Mercado Livre. Essa informação só está disponível para aqueles que possuem mais de uma loja embaixo de uma mesma conta.
sku (string): obrigatório. É a identificação do produto a ser comprado.
quantity (int): obrigatório. É a quantidade a ser comprada de um mesmo item.
origin (string): obrigatório. É o CEP de cadastro do lojista. Pode ser enviado em qualquer formatação desde que respeite os 8 dígitos.
price (float): opcional. É o preço unitário do produto multiplicado pela quantidade selecionada pelo comprador, no momento de realizar a cotação.
dimensions (object): obrigatório. É a relação de dimensões de um produto.

length (float): obrigatório. É o comprimento do produto (em centímetros).
width (float): obrigatório. É a largura do produto (em centímetros).
height (float): obrigatório. É a altura do produto (em centímetros).
weight(float): obrigatório. É o peso do produto (em quilogramas).

Importante:

Quando a quantidade de itens é maior que 1, há um algoritmo no marketplace que consolida os volumes na melhor combinação de dimensões, para minimizar a cubagem. Neste caso, a integração deve sempre considerar os valores enviados no POST e não fazer mais nenhuma multiplicação.

Exemplo:

{  
   "destination":"13295000",
   "items":[  
      {  
         "seller_id":"89540000",
         "sku":"0001166000",
         "quantity":1,
         "origin":"02611-000",
         "price":316,
         "dimensions":{  
            "length":1,
            "height":1,
            "width":1,
            "weight":1
         }
      }
   ]
}

A resposta deve retornar a cotação para o item comprado. Devem existir no máximo 2 (duas) cotações por pacote, caption com a legenda Normal ou Express.
Todos os valores da resposta são obrigatórios.
Abaixo segue a descrição de cada um dos itens suportados no payload:

packages (array): É a lista de pacotes criados pelo lojista.
items (array): É a lista de itens dentro de um mesmo pacote.

sku (string): É a identificação do item a ser comprado.
seller_id (string): É a identificação do conta que está vendendo o produto. Geralmente é uma cópia de informação já passada no request.
quantity (int): É a quantidade do produto que será enviado no pacote
stock (int): É a disponibilidade do produto em estoque por CD. No caso de indisponibilidade dessa informação deve-se retornar o valor -1.
error_code (int): É o código que irá identificar o tipo de erro em relação ao produto. A listagem dos códigos suportados será apresentada nas seções seguintes.
store_id (string): opcional. É a identificação da loja que está vendendo o produto. Geralmente é uma cópia de informação já passada no request.

quotations (array): É a lista de cotação de frete para um pacote.

cost(float): É o custo real do frete. No caso de indisponibilidade dessa informação deve-se retornar o mesmo valor de price.
price(float): É o preço de frete que será apresentado para o comprador. Esta informação se difere de cost pois há a possibilidade do frete ser subsidiado parcial ou completamente (frete grátis).
handling_time (int): É o tempo, em dias úteis, que será gasto para separação e empacotamento do produto. Abrange todos os processos anteriores ao envio efetivo do pacote. No caso de indisponibilidade dessa informação deve-se retornar o valor 0.
shipping_time (int): É o tempo, em dias úteis, de trânsito do pacote (da entrada no caminhão até a entrega para o comprador).
promise (int): É a soma dos valores de handling_time e shipping_time
caption (string): É o nome dado à cotação. A opções válida são Normal e Expresso.
service_id (int) : É o código que identifica um serviço/transportadora dentro do contexto do seller. Valores válidos vão de 0 à 99. Esse código é única e exclusivamente de responsabilidade do seller/integrador, sendo responsabilidade do Mercado Livre apenas repassar este valor.

Importante:

Caso seja enviado somente 1 dígito, será completado automaticamente com 0 à esquerda. Já no caso de ser enviado mais de 2 dígitos, a informação não será integrada e retornará 00 no código da transportadora.

Exemplo:

{
    "packages": [
        {
            "items": [
                {
                    "sku": "00266983118",
                    "seller_id": "207740981",
                    "quantity": 1,
                    "stock": -1,
                    "error_code": 0,
                    "store_id": null
                }
            ],
            "quotations": [
                {
                    "cost": 66.6,
                    "price": 66.6,
                    "handling_time": 0,
                    "shipping_time": 39,
                    "promise": 39,
                    "caption": "Normal",
                    "service_id": 01
                }
            ]
        }
    ]
}

Tratativa de erros

Importante:

A partir do dia 26 de abril o error code 1 vai direcionar a cotação para contingência.

Os erros acontecem individualmente por item e o objetivo não é invalidar a cotação/compra dos demais itens quando apenas parte deles apresentarem algum tipo de problema. A taxa de conversão tende a ser maior do que se invalidarmos todos os itens.
Abaixo segue a listagem dos códigos de erros válidos:

Parâmetro	Descrição
-1	Erro interno na aplicação do integrador e automaticamente será direcionado para a contingência.
0	Sem erro.
2	CEP de destino inválido.
3	Produto não disponível para o CEP de destino.
4	Produto escolhido não existe.

Próximo: Convivência