Frete dinâmico

Importante:
Esta funcionalidade só estará disponível para os integradores certificados. Para conseguir aprovação para desenvolver a funcionalidade, você deve entrar em contato com seu Partner Development.

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. Veja as novas atualizações:



Conteúdos

→Dinâmica de integração
→Tempo de resposta
→Contingência
→Contrato da API
→Usar cache
→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 ou 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 (object)​: 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 (int) 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 (int)​​: obrigatório. É a identificação da conta dentro do Mercado Livre.
declared_value (float)​​: opcional. É o valor que vai ser declarado na nota fiscal.
item_id (string): (string): obrigatório. É a identificação do item cadastrado no Mercado Livre.
variation_id (int): obligatorio. É a identificação da variante escolhida pelo comprador para a compra, possui dados somente quando a cotação corresponde a um item com variação.
category_id (string)​​: opcional. É a identificação da categoria do ítem no Mercado Livre.
store_id (string)​​: (string)​​: opcional. É a identificação da loja dentro do Mercado Livre.
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 (object)​​: 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 gramas).
  • 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 request e não fazer mais nenhuma multiplicação.

    Exemplo:

    {
       "seller_id": 123333,
       "buyer_id": 432123,
       "declared_value": 95.99,
       "items": [
           {
               "id": "MLB1223500643",
               "variation_id": 3123212,
               "category_id": "MLB1234",
               "price": 15.5,
               "quantity": 1,
               "SKU": "ITXEV8URJCPUN0UP",
               "store_id": 231,
               "dimensions": {
                   "height": 10,
                   "width": 10,
                   "length": 15,
                   "weight": 500
               }
           }
       ],
       "destination": {
           "type": "zipcode",
           "value": "88063038"
       },
       "origin": {
           "type": "zipcode",
           "value": "88063038"
       }
    }
    Notas:
    - A resposta​ deve retornar a cotação para o item comprado.
    - Podem ser enviados várias cotações, todos com distinção de prazo/promessa de entrega e preço.
    - 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.
    item_id (string): obrigatório. É a identificação do item cadastrado no Mercado Livre.
    variation_id (int): obrigatório. É a identificação da variante escolhida pelo comprador.

    • quantity (int)​​: é a quantidade do produto que será enviado no pacote.
    • 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 na chamada.

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

    • price(float)​​: é o preço de ​frete​​ que será apresentado para o comprador.
    • 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​
    • service (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:

    {
       "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
                }
             ]
          }
       ]
    }

    No caso de ocorrer algum erro interno ou algum item estiver associado a um error code, a estrutura da resposta deverá ser conforme é apresentado abaixo. Para o error code 3 (sem cobertura), o HTTP Status deve ser 400 (bad request) e para qualquer outro error code ou erro interno associado a cotação, deve ser 500 (internal server error).


    Resposta:

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

    Usar cache

    Importante:
    As atualizações para a adaptação mínima (parcial) deverão ser desenvolvidas até 31 de agosto de 2021.

    Para a implementação do cacheamento das respostas, será utilizado a RFC IETF 7234 (leitura sugerida). Essa RFC foi definida pela comunidade e reúne as melhores práticas de cacheamento de chamadas HTTP.


    Verbo HTTP

    Para a implementação da mesma, será alterado o verbo HTTP dos endpoints de cotação de frete de POST para GET. Isso será necessário para que a semântica dos endpoints seja adequada ao protocolo HTTP, na qual, é sugerido que apenas chamadas GET devem ser cacheadas.


    Headers

    Além disso, será adicionado header nas requisições e respostas das chamadas aos partners.
    Para as requisições, serão adicionados os headers:

    Atributo Valor
    If-None-Match Chave identificadora do recurso (cotação) em questão (header ETag). É utilizada para verificar se a versão do recurso ainda é válida. Se válido for, o partner deve retornar o HTTP status 304 sem conteúdo. Caso contrário, retorna uma nova versão do recurso e uma nova ETag.

    Por sua vez, para as respostas dos integradores, será necessário adicionar os headers:

    Atributo Valor
    Cache-Control Utilizado para especificar as diretivas para cacheamento das respostas. As diretivas que pretende-se adotar são:
    1. no-store: indica que a resposta não deve ser cacheada. É opcional. Se utilizar essa diretiva, as demais não são necessárias;
    2. must-revalidate: deve-se verificar se a resposta ainda é válida com o integrador. Este deve retornar o HTTP Status 304 se ainda for válida ou 200 com o novo valor para a cotação. Essa validação é opcional e fica a critério do integrador adotá-la. Se não for adotado, será utilizado o max-age para definir o TTL da resposta no cache.
    3. private: indica que a resposta não deve ser armazenada por qualquer proxy intermediário. É obrigatório.
    4. max-age: tempo máximo em segundos que a resposta é válida. É obrigatório.
    Age Tempo em segundos desde que a versão do recurso passou a ser válida. Se não existir esse controle por parte dos partners, deve ser enviado o valor zero (0).
    ETag Chave identificadora da versão do recurso. É obrigatório a sua utilização.


    Contrato da resposta

    Será adicionado um novo atributo destinations na resposta das chamadas aos partners e deve conter todos os destinos que a cotação pode ser utilizada. Este atributo será uma lista de strings e pode conter apenas o destino para qual a cotação foi solicitada. Com isso, com uma única cotação, pode-se evitar N outras requisições.
    O quadro abaixo apresenta um exemplo de resposta onde é verificado o header ETag sendo retornado que a resposta cacheada ainda é válida.
    Exemplo de requisição com validação de cache.

    Headers Status Body
    - Cache-Control:private;max-age:1000000
    - Age:50000
    - ETag:0943dc18-a8d7-4508-97a9-ba9221fa
    304 No content

    Por fim, o quadro a seguir apresenta um exemplo de resposta onde o partner indica que a cotação não deve ser armazenada em nenhum cache. Esta deve conter a diretiva no-store no header Cache-Control.

    Exemplo de resposta sem permitir o cacheamento.

    Headers Status Body
    - Cache-Control:no-store 200 Body igual da resposta da cotação

    Exemplo de resposta com cache:

    Headers Status Body
    Cache-Control:private;max-age:1000000
    - Age:0
    - ETag:0943dc18-a8d7-4508-97a9-ba9221fa
    200 Body igual da resposta da cotação

    Tratativa de erros

    Importante:
    O error code 1 direciona a cotação para contingência.

    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 sem cobertura de envio para o CEP destino.

    Próximo: Convivência

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