Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação

Última atualização em 05/12/2023

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

  • Cumprimento do Contrato

    A seguir, apresentamos uma abordagem passo a passo ao criar o endpoint para homologação:

    • 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.
    • Importante:
      Reúne os seguintes elementos necessários:
      • URL ou endpoint que deseja registrar.
      • Headers necessários para a comunicação.
      • Formato do corpo ou JSON request que esteja em conformidade com as especificações.
      • Nome e ID da sua aplicação. (Opcional)

      • Considere criar um vídeo curto que demonstre o desenvolvimento realizado para validar e verificar as especificações do contrato. Isso pode ser útil para documentar o processo e compartilhar sugestões. Lembre-se da importância de ter um consultor comercial que facilite o contato com o Mercado Livre. Para a criação da aplicação, sugerimos revisar a documentação: Registre sua aplicaçã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:

      • 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.

      • 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:

        • 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.

        • 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


          Nota:
          • Quando a quantidade de itens for maior que 1, o Mercado Livre usará um algoritmo para consolidar as dimensões na melhor combinação possível para otimizar o espaço. Neste caso, a integração deve usar os valores enviados na solicitação sem realizar nenhuma multiplicação.
          • A resposta deve incluir a cotação correspondente ao item comprado.
          • É possível enviar várias cotações, cada uma com prazo/promessa de entrega e preço diferentes.
          • Todos os valores de resposta são obrigatórios e devem ser fornecidos.


          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.
          • Nota:
            No caso do atributo quotations.service:
            • Este código é de responsabilidade exclusiva do vendedor/integrador, o Mercado Livre apenas o transmite.
            • Se você enviar apenas um dígito, será automaticamente completado com um 0 à esquerda. Por exemplo, se você enviar 5, será convertido em 05.
            • No caso de enviar mais de 2 dígitos, a informação não será integrada e o código do carrier retornará "00". Por exemplo, se você enviar 123, a resposta será 00.
            • É fundamental incluir pelo menos um objeto dentro do array quotations.


            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:

            • 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).

            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:
            • no-store: (opcional) no-store: (opcional) indica que a resposta não deve ser armazenada em cache. Se usar esta diretriz, as demais não são necessárias.
            • must-revalidate: must-revalidate: você deve verificar se a resposta é válida com o integrador. Este deve retornar o HTTP Status 304 se ainda for válido ou 200 com o novo valor para a cotação. Essa validação é opcional e fica a critério do integrador adotá-la ou não. Se não for adaptada, o max-age será utilizado para definir o TTL da resposta no cache.
            • private: (obligatorio) a resposta não deve ser armazenada por qualquer proxy intermediário.
            • max-age: (obligatorio) tempo máximo em segundos que a resposta é válida.
            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
            Importante:
            Para evitar erros ao carregar a Tabela de Contingência, é importante seguir estas recomendações:
            • Verificar extensão do arquivo: certificar-se de que o arquivo tenha a extensão correta conforme o modelo do Mercado Livre.
            • Manter os nomes das planilhas: não modificar os nomes das planilhas no modelo a ser carregado. Tudo deve coincidir com o modelo original. Além disso, nenhuma planilha deve ser excluída.
            • Preservar os cabeçalhos: não alterar os cabeçalhos no arquivo. Verificar se a estrutura da planilha é mantida de acordo com o modelo.
            • Validar informações: verificar se os códigos postais estão corretos. Prestar atenção às maiúsculas e minúsculas ao se referir a departamentos, cidades, comunidades, etc.