Frete Dinâmico
Conteúdos
→Dinâmica de integração →Tempo de resposta →Contingê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.
Contingência
No início do frete dinâmico utilizaremos a solução atual de ME1 como contingência mas conforme a solução se consolide em produção, a contingência passa a ser responsabilidade do integrador/lojista.
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
Request 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.
O request possibilita o envio de mais de um produto mesmo que sejam de lojas diferentes (mas garantindo que pertença à mesma integração).
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. Pode ser enviado em qualquer formatação desde que respeite os 8 dí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): obrigatório. É uma lista com a relação de itens que estão sendo comprados.
- seller_id (string): obrigatório. É a identificação da conta dentro do Mercado Livre.
- item_id (string): opcional. É a identificação do item cadastrado no Mercado Livre.
- store_id (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): opcional. É a relação de dimensões de um produto.
length (float): obrigatório se houver dimensions. É o comprimento do produto (em centímetros).
width (float): obrigatório se houver dimensions. É a largura do produto (em centímetros).
height (float): obrigatório se houver d imensions. É a altura do produto (em centímetros).
weight (float): obrigatório se houver dimensions. É 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 cotações para os itens comprados, separados por “pacotes”. Este tipo de resposta permite que lojistas que possuam mais de um centro de distribuição possam enviar cotações de frete a partir dos CDs onde cada um dos produtos se encontram.
A criação de mais de um “pacote” fica a critério de cada lojista porém é esperado no mínimo um com todos os produtos que foram enviados através do request.
Devem existir no máximo 2 (duas) cotações por pacote, tendo como caption os nomes Normal ou Expresso.
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.
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.
quantity (int): É a quantidade do produto que será enviado no pacote. Pode acontecer por questõ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): É 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.
- 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.
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 é 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 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. |