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
→Contingê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).

Contingê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 contingência atual será 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 ficará 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 descrição de cada um dos itens suportados no payload:


destination (string)​: obrigatório. É o CEP do comprador, onde os produtos serã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)​​: obrigatório. É a identificação da conta dentro do Mercado Livre.
item_id (string): (string): obrigatório. É a identificação do item cadastrado no Mercado Livre.
store_id (string)​​: (string)​​: opcional. É a identificação da loja dentro do Mercado Livre. Essa informação só está disponível para aqueles que possuem mais de uma loja embaixo de uma mesma conta.
sku (string)​​: obrigatório. É a identificação do produto a ser comprado.
quantity (int)​​: obrigatório. É a quantidade a ser comprada de um mesmo item.
origin (string)​​: obrigatório. É o CEP de cadastro do lojista. Pode ser enviado em qualquer formatação desde que respeite os 8 dígitos.
price (float)​​: opcional. É o preço unitário do produto multiplicado pela quantidade selecionada pelo comprador, no momento de realizar a cotação.
dimensions (object)​​: obrigatório. É a relação de dimensões de um produto.

  • length (float)​​: obrigatório​​. É o comprimento do produto (em centímetros).
  • width (float)​​: obrigatório​​. É a largura do produto (em centímetros).
  • height (float)​​: obrigatório​​. É a altura do produto (em centímetros).
  • weight(float)​​: obrigatório​​. É 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 cotação para o item comprado. Devem existir no máximo 2 (duas) cotações por pacote, caption com a legenda Normal ou Express.
    Todos os valores da resposta são obrigatórios​​.
    Abaixo segue a descrição de cada um dos itens suportados no payload:


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

    • sku (string)​​: É a identificação do item a ser comprado.
    • seller_id (string)​​: É a identificação do conta que está vendendo o produto. Geralmente é uma cópia de informação já passada no request.
    • quantity (int)​​: É a quantidade do produto que será enviado no pacote
    • stock (int)​​: É a disponibilidade do produto em estoque por CD. No caso de indisponibilidade dessa informação deve-se retornar o valor -1.
    • error_code (int)​​: É o código que irá identificar o tipo de erro em relação ao produto. A listagem dos códigos suportados será apresentada nas seções seguintes.
    • store_id (string)​​: opcional. É a identificação da loja que está vendendo o produto. Geralmente é uma cópia de informação já passada no request.

    quotations (array)​​: É a lista de cotação de frete para um pacote.

    • cost(float)​​: É o custo real do ​frete.​​ No caso de indisponibilidade dessa informação deve-se retornar o mesmo valor de ​price​​.
    • price(float)​​: É o preço de ​frete​​ que será apresentado para o comprador. Esta informação se difere de ​cost​​ pois há a possibilidade do frete ser subsidiado parcial ou completamente (frete grátis).
    • handling_time (int)​​: É o tempo, em dias úteis, que será gasto para separação e empacotamento do produto. Abrange todos os processos anteriores ao envio efetivo do pacote. No caso de indisponibilidade dessa informação deve-se retornar o valor 0.
    • shipping_time (int)​​: É o tempo, em dias úteis, de trânsito do pacote (da entrada no caminhão até a entrega para o comprador).
    • promise (int)​​: É a soma dos valores de ​handling_time​​ e shipping_time​
    • caption (string)​​: É o nome dado à cotação. A opções vá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 não é invalidar a cotação/compra dos demais itens quando apenas parte deles apresentarem algum tipo de problema. A taxa de conversão tende a ser maior do que se invalidarmos todos os itens.
    Abaixo segue a listagem dos códigos de erros vá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

ou registre-se para receber as últimas notícias sobre nossa API