Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Frete Dinâmico
Flete Dinâmico é uma funcionalidade do Mercado Envios 1 que agiliza a seleção de preços e prazos de envio para vendedores, fornecendo aos compradores informações precisas sobre os prazos de entrega. Essa configuração verifica em tempo real os preços e condições de envio, mostrando o custo do envio antes da compra, aprimorando a experiência e a eficiência logística. Além disso, para registrar corretamente o desenvolvimento dessa funcionalidade, é necessário passar por um processo de homologação.
Dinâmica de Homologação
A homologação é um processo no qual o Mercado Livre verifica e aprova uma URL externa para que os usuários possam se registrar no Mercado Livre a partir desse site de maneira segura e confiável. Isso envolve testes técnicos, avaliação de segurança e a implementação de medidas necessárias para garantir a autenticidade e proteção dos dados dos usuários. Uma vez aprovada, a URL se torna um canal válido para os usuários do ME1.
Requisitos de Homologação
A continuación, se presentan los requisitos de homologación para asegurar una integración exitosa con nuestra plataforma de flete dinâmico:
- Cumprimento do Contrato
- Tempo de Resposta Ótimo
- Localização da Infraestrutura
- Especificações de Origem e Destino de Dados
- Uso de Cache
- Monitoramento de Erros
- Contingência do Mercado Livre
- A URL não tem uma estrutura específica, proporcionando flexibilidade na configuração.
- Cada solicitação deve conter apenas um item de um vendedor. Isso é fundamental para manter a eficiência na transmissão de dados.
- Utilize o método HTTP GET para acessar o endpoint. Esse método é adequado para solicitar dados e é comumente usado em integrações web.
- Detalhe claramente a fonte de dados (origem) e o sistema de destino. Compreender esses aspectos é fundamental para garantir um fluxo de dados sem problemas e preciso.
- Familiarize-se com a necessidade de manter o tempo de resposta abaixo de 400 ms e compreenda sua importância para uma integração bem-sucedida.
- Antes de ativar o endpoint, submeta-o a uma validação de carga inicial. Isso implica avaliar seu tempo de resposta em condições normais de uso.
- Se o tempo de resposta ultrapassar o limite, são necessárias ações corretivas. Isso pode incluir a revisão e otimização do código e da infraestrutura.
- Se o tempo de resposta atender ao requisito de 400 ms, a integração é aprovada e pode ser ativada para os vendedores.
- Certifique-se de continuar otimizando o tempo de resposta de forma contínua para proporcionar uma experiência de usuário excepcional.
- Considere que a atual infraestrutura de flete dinâmico está localizada na região leste dos Estados Unidos, mais especificamente, em Virginia.
- Avalie se é necessário otimizar sua aplicação ou ajustar a configuração para aproveitar ao máximo a localização da infraestrutura.
Cumprimento do Contrato
A seguir, apresentamos uma abordagem passo a passo ao criar o endpoint para homologação:
Tempo de Resposta Ótimo
Esse enfoque é essencial para garantir uma experiência de usuário eficiente e evitar problemas de integração com os vendedores. Para isso:
Localização da Infraestrutura
Seguindo esses passos, você poderá tomar decisões informadas para melhorar o desempenho de sua aplicação com base na localização da infraestrutura:
Origem e Destino de Dados
Especificações da fonte de dados (origem)
As especificações da fonte de dados fazem parte do protocolo de comunicação ou intercâmbio de dados no processo de homologação:
Exemplo por Zip_Code:
{
"seller_id": 337352780,
"buyer_id": 3123212,
"declared_value": 69.9,
"items": [
{
"id": "MLB1223500643",
"variation_id": 0,
"category_id": "ABC1234",
"price": 69.9,
"quantity": 1,
"sku": "RB-PC890A",
"store_id": 231,
"dimensions": {
"height": 10,
"width": 10,
"length": 31,
"weight": 500
}
}
],
"destination": {
"type": "zipcode",
"value": "88063038"
},
"origin": {
"type": "zipcode",
"value": "88063038"
}
}Exemplo por City:
{
"seller_id": 337352780,
"buyer_id": 3123212,
"declared_value": 69.9,
"items": [
{
"id": "MLB1223500643",
"variation_id": 0,
"category_id": "ABC1234",
"price": 69.9,
"quantity": 1,
"sku": "RB-PC890A",
"store_id": 231,
"dimensions": {
"height": 10,
"width": 10,
"length": 31,
"weight": 500
}
}
],
"destination": {
"type": "city",
"value": "Ñuble/Yungay"
},
"origin": {
"type": "city",
"value": "Metropolitana/Pudahuel"
}
}Parâmetros de resposta:
seller_id (string): obrigatório. É a identificação da conta dentro do Mercado Livre.
buyer_id (string): opcional. É o identificador do usuário que está realizando a compra no Mercado Livre. Está disponível apenas quando o usuário que está fazendo a cotação está logado na plataforma do Mercado Livre.
declared_value (float): opcional. É o valor que será declarado na fatura.
items (array): obrigatório. Informações sobre o item comprado.
- items.id (string): obrigatório. É a identificação do produto registrado no Mercado Livre.
- items.variation_id (string): obrigatório. É a identificação da variante escolhida pelo comprador para a compra, possui dados apenas quando a cotação corresponde a um item com variação.
- items.category_id (string): opcional. É a identificação da categoria do produto dentro do Mercado Livre.
- items.price (float): opcional. É o preço unitário do produto multiplicado pela quantidade de itens escolhidos pelo comprador no momento da cotação.
- items.quantity (int): obrigatório. É a quantidade que será comprada do mesmo produto.
- items.sku (string): obrigatório. É a identificação do produto ao ser comprado.
- items.store_id (string): opcional. É a identificação da loja oficial dentro do Mercado Livre.
- items.dimensions (object): obrigatório. É a lista de medidas de um produto.
- items.dimensions.length (float): obrigatório. É o comprimento do produto (em centímetros).
- items.dimensions.width (float): obrigatório. É a largura do produto (em centímetros).
- items.dimensions.height (float): obrigatório. É a largura do produto (em centímetros).
- items.dimensions.weight (float): obrigatório. É o peso do produto (em gramas).
origin (object): opcional. É a informação do endereço de origem da entrega ou do vendedor.
destination (object): obrigatório. É a informação do endereço onde o produto será entregue. A seguir, os detalhes de acordo com cada país:
| País | Detalhe |
|---|---|
| Brasil | Código Postal |
| Argentina | Código Postal |
| México | Código Postal |
| Chile | Região / Comuna |
| Colômbia | Departamento / Localidade |
| Peru | Departamento / Província ou Distrito |
| Uruguai | Departamento / Localidade |
Especificações do destino dos dados (destino)
As especificações do destino de dados fazem parte do protocolo de comunicação ou intercâmbio de dados no processo de homologação:
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
}
]
}
]
}Parâmetros de resposta:
destinations (array): informação que contém códigos postais ou outras identificações de destinos para os quais os pacotes serão enviados.
packages (array): informação que representa os pacotes criados pelo vendedor.
- packages.dimensions (object): obrigatório. É a lista de medidas do pacote. items (array): obrigatório. Informação sobre o item comprado.
- items.id (string): obrigatório. É a identificação do item registrado no Mercado Livre.
- items.variation_id (string): obrigatório. É a identificação da variante escolhida pelo comprador.
- items.quantity (int): é a quantidade do produto que será enviada.
- items.dimensions (object): obrigatório. É a lista de medidas do item. quotations (array): obrigatório. informações de frete para um produto.
- quotations.price (float): é o preço do frete que será apresentado ao comprador.
- quotations.handling_time (int): é o tempo, em dias úteis, que será utilizado para separar e embalar o produto. Inclui todos os processos anteriores ao envio efetivo do pacote. Caso essa informação não esteja disponível, deve ser devolvido o valor 0.
- quotations.shipping_time (int): é o tempo, em dias úteis, de trânsito do pacote (desde a entrada no caminhão até a entrega ao comprador).
- quotations.promise (int): é a soma dos valores de handling_time e shipping_time.
- quotations.service (int): é o código do serviço/carrier com identificação única, que vai de 0 a 99, atribuído pelo vendedor/integrador.
- Para o código de erro 3 (sem cobertura), o estado HTTP deve ser 400 (Pedido incorreto).
- Para qualquer outro código de erro ou erro interno relacionado com a cotação, o estado HTTP deve ser 500 (Erro interno do servidor).
No caso de ocorrer um erro interno ou se um item estiver relacionado a um erro, a estrutura da resposta deve seguir o seguinte formato:
Exemplo de Resposta:
{
"message": "any message",
"error_code": 1
}Uso de Cache
Neste contexto, será utilizado o RFC IETF 7234, uma especificação amplamente reconhecida que estabelece as melhores práticas para o armazenamento em cache de chamadas HTTP.
Verbo HTTP
Neste contexto, é essencial alinhar a semântica de nossas chamadas com o protocolo HTTP, que sugere que apenas chamadas GET devem ser armazenadas em cache.
Headers
Devem ser incorporados cabeçalhos adicionais nas chamadas e respostas feitas aos integradores. No caso das chamadas, devem ser adicionados os seguintes cabeçalhos:
| Atributo | Descrição |
|---|---|
| If-None-Match | Identificador do recurso (cotação) em questão (cabeçalho ETag). É usado para verificar se a versão do recurso ainda é válida. É válido se o parceiro retornar o status HTTP 304 sem conteúdo. Caso contrário, retorna uma nova versão do recurso e um novo ETag. |
Por outro lado, nas respostas fornecidas pelos integradores, é necessário incluir os seguintes cabeçalhos adicionais:
| Atributo | Descrição |
|---|---|
| Cache-Control | Utilizado para especificar as diretrizes para o cacheamento das respostas. As diretrizes que você deve adaptar são:
|
| Age | Tempo em segundos desde que a versão do recurso se tornou válida. Caso esse controle não exista por parte dos parceiros, você deve enviar o valor zero (0). |
| ETag | Identificador da versão do recurso. É obrigatório usá-lo. |
Buscando otimizar nossas respostas e reduzir o número de chamadas, o atributo chamado destinations conterá uma lista de destinos em formato de strings, indicando todos os lugares onde a cotação pode ser utilizada. Agora, com uma única cotação, é possível evitar várias chamadas, melhorando significativamente a eficiência de nossas APIs.
A seguir, apresentamos um exemplo de como verificar o cabeçalho ETag retornado para determinar se a resposta em cache ainda é válida. Exemplo de chamada com validação de cache:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:private;max-age:1000000 - Age:50000 - ETag:0943dc18-a8d7-4508-97a9-ba9221fa |
304 | No Content |
Para proporcionar um controle mais granular sobre o armazenamento em cache, estamos introduzindo a diretriz no-store no cabeçalho Cache-Control de nossas respostas. Essa diretriz permite que os parceiros indiquem que uma cotação não deve ser armazenada em cache.
Exemplo de resposta sem permitir o cache:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:no-store | 200 | Body da resposta da cotação igual ao exemplo anterior. |
Exemplo de resposta com cache:
| Headers | Estado | Body |
|---|---|---|
| - Cache-Control:private;max-age:1000000 - Age:0 - ETag:0943dc18-a8d7-4508-97a9-ba9221fa |
200 | Body da resposta da cotação igual ao exemplo anterior. |
Monitoreo de errores
A continuación, enumeramos los posibles errores en relación al manejo de Flete Dinâmico:
| Parâmetro | Descrição | Possível Solução |
|---|---|---|
| -1 | Este erro ocorre quando a aplicação do integrador enfrenta problemas internos que impedem seu funcionamento adequado. Como resultado, o comprador receberá uma cotação da calculadora MELI em modo de contingência. | Em caso de um erro interno na aplicação do integrador, é recomendável considerar a Tabela de Contingência como um plano de backup. Quando um erro interno é detectado, a aplicação ativa automaticamente a consulta à Tabela de Contingência. |
| 1 | Este erro ocorre quando o produto selecionado pelo comprador não está disponível no estoque. Como resultado, não é possível calcular uma cotação de envio para um produto que não está em estoque. | Recomenda-se implementar um processo eficaz de gestão de inventário ou considerar mostrar alternativas de produtos similares disponíveis. |
| 2 | Este erro ocorre quando o destino (código postal, comuna, etc.) fornecido pelo comprador não é válido. Como resultado, não é possível calcular uma cotação de envio precisa. | Ao verificar que o destino é inválido, a aplicação deve consultar a Tabela de Contingência. Se a Tabela de Contingência contiver informações válidas para o destino inserido, essas informações devem ser utilizadas para calcular a cotação de envio. |
| 3 | Este erro ocorre quando o produto selecionado pelo comprador não está disponível para entrega no destino especificado. Como resultado, não é possível calcular uma cotação de envio. | Se o produto não estiver disponível na localização original, a Tabela de Contingência pode conter informações sobre produtos alternativos ou locais de entrega alternativos. |
| 4 | Este erro ocorre quando a aplicação não consegue encontrar o produto especificado pelo comprador. Isso impede o cálculo de uma cotação de envio precisa. | Certifique-se de que o banco de dados de produtos esteja atualizado e seja facilmente acessível para a aplicação. |
Contingência do Mercado Livre
A Tabela de Contingência, também conhecida como Tabela Axado, é uma planilha de transportadoras que pode ser carregada diretamente do Mercado Livre. Sua função principal é atuar como um plano de backup caso o endpoint ou URL do integrador falhe. Em outras palavras, é uma ferramenta de segurança projetada para manter as operações dos vendedores em funcionamento mesmo quando surgem problemas inesperados.
A seguir, alguns critérios a serem considerados:
- Requisito Inicial: o Consultor Comercial da MELI solicitará ao vendedor a Tabela de Contingência ao ativar a integração com o integrador de flete dinâmico.
- Responsabilidade do Vendedor: o vendedor deve completar e manter atualizada esta tabela com os valores tanto no integrador quanto na MELI.
- Estabelecer Regras de Frete: recomenda-se que o vendedor estabeleça regras claras de frete, como custos zero para locais próximos, para otimizar a entrega.
- Atualização Fácil: se o vendedor desejar atualizar a tabela, pode fazê-lo a partir da MELI, acessando Meu Perfil -> Vendas -> Preferências de Vendas -> Transportadoras.
Além disso, anexamos um detalhamento por país juntamente com um link de referência para a Tabela de Contingência Modelo:
| País | Detalhe | Link |
|---|---|---|
| Brasil | Código Postal | https://www.mercadolivre.com.br/transportadoras/config |
| Argentina | Código Postal | https://www.mercadolibre.com.ar/transportadoras/config |
| México | Código Postal | https://www.mercadolibre.com.mx/transportadoras/config |
| Chile | Região / Comuna | https://www.mercadolibre.cl/transportadoras/config |
| Colômbia | Departamento / Localidade | https://www.mercadolibre.com.co/transportadoras/config |
| Peru | Departamento / Província ou Distrito | https://www.mercadolibre.com.pe/transportadoras/config |
| Uruguai | Departamento / Localidade | https://www.mercadolibre.com.uy/transportadoras/config |