Frete Dinâmico

Importante:

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

A funcionalidade de frete dinâmico tem como objetivo dinamizar e democratizar a seleção de preços e prazos de frete para sellers que utilizam a modalidade ME1, visando melhorar a experiência do comprador, através do fornecimento mais preciso dos prazos de frete praticados por cada lojista.
Também é objetivo proporcionar ao vendedor um aumento do catálogo para aqueles que possuem mais de um centro de distribuição, esperando assim um aumento das vendas e de GMV.

Nota:

Em um primeiro momento, só estará disponível para vendedores do Brasil.

Conteúdos

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

Dinâmica de integração

Esse projeto possui uma dinâmica diferente de toda API do Mercado Livre. Pois, neste caso, o seller/integrador deverá disponibilizar um endpoint, no qual o Mercado Livre fará o request para obter as informações de frete que serão exibidas na plataforma no momento da compra.
A disponibilização do endpoint poderá ser através do vendedor (desenvolvimento inhouse), integrador ou parceiro que possui integração com transportadoras.

Tempo de resposta

Um ponto muito importante neste projeto é o tempo de resposta do endpoint, que 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, pois, caso ultrapasse o tempo limite, a integração não será aprovada e não poderá ser ativada para os sellers.

Nota:

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

Contingência

No início do frete dinâmico utilizaremos a solução atual de ME1 como contingência mas conforme a solução se consolide em produção, a contingência passa a ser responsabilidade do integrador/lojista.
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

Request 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.
O request possibilita o envio de mais de um produto mesmo que sejam de lojas diferentes (mas garantindo que pertença à mesma integração).
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. Pode ser enviado em qualquer formatação desde que respeite os 8 dígitos.
buyer_id (int64): opcional. É o identificador do usuário que está comprando no Mercado Livre. Só está disponível quando o usuário realizando a cotação está logado na plataforma Mercado Livre.
items (array): obrigatório. É uma lista com a relação de itens que estão sendo comprados.

seller_id (string): obrigatório. É a identificação da conta dentro do Mercado Livre.
item_id (string): opcional. É a identificação do item cadastrado no Mercado Livre.
store_id (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): opcional. É a relação de dimensões de um produto.

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.

length (float): obrigatório se houver dimensions. É o comprimento do produto (em centímetros).

width (float): obrigatório se houver dimensions. É a largura do produto (em centímetros).

height (float): obrigatório se houver d imensions. É a altura do produto (em centímetros).

weight (float): obrigatório se houver dimensions. É o peso do produto (em quilogramas).

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

Resposta: A resposta deve retornar as cotações para os itens comprados, separados por “pacotes”. Este tipo de resposta permite que lojistas que possuam mais de um centro de distribuição possam enviar cotações de frete a partir dos CDs onde cada um dos produtos se encontram.
A criação de mais de um “pacote” fica a critério de cada lojista porém é esperado no mínimo um com todos os produtos que foram enviados através do request.
Devem existir no máximo 2 (duas) cotações por pacote, tendo como caption os nomes Normal ou Expresso.
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.

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.

quantity (int): É a quantidade do produto que será enviado no pacote. Pode acontecer por questões de disponibilidade em estoque que uma parcela do produto seja enviado a partir de um CD e a outra parte de outro CD (portanto dois “pacotes” distintos). -

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.

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 á esqueda. 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

Como mencionado anteriormente, os erros acontecem individualmente por item. O objetivo desta abordagem é 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 inesperado (utilizar somente em casos muito específicos).
0	Sem erro.
1	Quantidade não disponível em estoque.
2	CEP de destino inválido.
3	Produto não disponível para o CEP de destino.
4	Produto escolhido não existe.

Nota:

Quando retornar o erro -1, será considerado um erro interno na aplicação do integrador e automaticamente será direcionado para a contingência.