Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação do

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 20/09/2024

Gestão Mercado Envios

Importante:
Atualmente, esta modalidade de envio está disponível para vendedores da Argentina, Brasil, México, Chile, Colômbia, Uruguai, Peru e Equador.

Mercado Envios é uma rede de serviços do Mercado Livre que proporciona soluções logísticas para melhorar a experiência de vendedores e compradores. Além de coordenar com diversos operadores da indústria, a rede logística do Mercado Envios inclui centros de armazenamento e distribuição próprios, agências, e uma frota terrestre e aérea em constante crescimento. Saiba mais sobre envios para vendedores e assista ao nosso webinar para se integrar:




Modalidades de Envios

Mercado Envios se divide nas seguintes modalidades:

  • Mercado Envios 1 (ME1): é uma modalidade de envio que permite aos vendedores vender através do Mercado Livre, utilizando sua própria logística ou serviços de terceiros.
  • Mercado Envios 2 (ME2): é a modalidade de envio do Mercado Livre, onde se gerencia toda a logística utilizando diversos meios como correios, agências, entre outros. Esta modalidade se divide, por sua vez, nos seguintes tipos de logística:
  • Custom: é uma modalidade de envio onde o vendedor carrega uma tabela com os preços de envio por cada região e se encarrega da logística.
  • Not Specified: é uma modalidade de envio onde o vendedor não especifica nenhum preço de envio para suas publicações e deve entrar em contato com o comprador para coordenar o envio.

Preferências de envio de um item

Para estabelecer as preferências de envio de um item no Mercado Livre de maneira adequada, é crucial ter em conta os seguintes pontos:



A gestão de itens no Mercado Livre, seja por meio de publicação, edição ou migração, está estreitamente vinculada às preferências de envio ativas tanto do usuário quanto do item em questão. Essas preferências determinam quais modalidades de envio estão disponíveis e devem ser revisadas cuidadosamente.


Serviços de Envio disponíveis por país

Para estabelecer as preferências de envio de um item no Mercado Livre de maneira adequada, é crucial ter em conta os seguintes pontos:


Chamada:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping_methods

Resposta:

	
    {
      {
        "id": 73328,
        "name": "Normal a domicilio",
        "type": "standard",
        "deliver_to": "address",
        "status": "active",
        "site_id": "MLA",
        "free_options": [
          "country"
        ],
        "shipping_modes": [
          "me2"
        ],
        "company_id": 17500240,
        "company_name": "OCA",
        "min_time": 72,
        "max_time": null,
        "currency_id": "ARS"
      },
    ...
    }


Parâmetros de resposta:

  • id: é um identificador único para o tipo de envio.
  • name: nome descritivo do serviço de envio.
  • type: define o tipo de serviço de envio.
  • deliver_to: Especifica o destino do envio. "address" indica que o pacote será entregue em um endereço físico.
  • status: indica o estado atual do serviço de envio. "active" significa que o serviço está atualmente disponível e operacional.
  • site_id: país ao qual se aplica este serviço de envio.
  • free_options: lista de opções em que o serviço de envio pode ser gratuito. Neste caso, "country" indica que o envio pode ser gratuito a nível nacional.
  • shipping_modes: indica os modos de envio compatíveis.
  • company_id: identificador único da empresa de logística que fornece o serviço de envio.
  • company_name: nome da empresa de logística que gerencia o envio.
  • min_time: o tempo mínimo estimado de entrega do envio em horas.
  • max_time: o tempo máximo estimado de entrega do envio em horas.
  • currency_id: identificador da moeda utilizada para qualquer tarifa aplicável ao serviço de envio.

Códigos de Estado de resposta:

Código Mensagem Descrição Recomendação
200 - OK - A configuração atual foi obtida corretamente. -
401 - Unauthorized invalid access token Access token inválido. Validar o access_token.
404 - Not Found invalid_site_id O site_id não existe. Validar o site_id.

Preferências de envio de um usuário

Este endpoint permite conhecer as preferências de envio ativas para um usuário e com isso validar previamente que o vendedor pode publicar ou editar um item para os tipos de envio segundo sua conta.


Chamada:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/shipping_preferences

Exemplo:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/12345678/shipping_preferences

Resposta:

	
    
{
    "local_pick_up": false,
    "modes": [
      "custom",
      "not_specified",
      "me2",
      "me1"
    ],
    "trusted_user": false,
    "bulky": false,
    "custom_calculator": "Axado",
    "picking_type": null,
    "thermal_printer": null,
    "option": "in",
    "tags": [
      "optional_me1_allowed",
      "turbo",
      "flex2_migration"
    ],
    "me2_enablers": [],
    "carrier_pickup": false,
    "items_combination": "enabled",
    "services": [
      153,
      154,
      251,
      422,
      431,
      742746,
      742748
    ],
    "logistics": [
      {
        "mode": "me1",
        "types": [
          {
            "type": "default",
            "carrier_pickup": [],
            "services": [
              251,
              153,
              154
            ],
            "default": true,
            "status": "active"
          }
        ]
      },
      {
        "mode": "me2",
        "types": [
          {
            "type": "drop_off",
            "carrier_pickup": [],
            "services": [
              422,
              431
            ],
            "default": true,
            "status": "active"
          },
          {
            "type": "self_service",
            "carrier_pickup": [],
            "services": [
              742746,
              742748
            ],
            "default": false,
            "status": "active"
          }
        ]
      },
      {
        "mode": "custom",
        "types": [
          {
            "type": "custom",
            "carrier_pickup": [],
            "services": null,
            "default": true,
            "status": "active"
          }
        ]
      },
      {
        "mode": "not_specified",
        "types": [
          {
            "type": "not_specified",
            "carrier_pickup": [],
            "services": null,
            "default": true,
            "status": "active"
          }
        ]
      }
    ],
    "label": {
      "print_danfe": false,
      "print_browser": false,
      "print_voucher": false,
      "print_summary": true,
      "thermal_printer": null,
      "page_size": "a4",
      "page_format": "pdf"
    },
    "content_declaration_disabled": false,
    "conciliation": {
      "type": null
    },
    "mandatory_invoice_data": false,
    "site_id": "MLA",
    "free_configurations": [
      {
        "condition": {
          "value": null,
          "type": "all"
        },
        "rule": {
          "default": true,
          "free_mode": "country",
          "value": null
        }
      }
    ],
    "mandatory_settings": {}
  }  


  • local_pick_up: indica se o comprador tem a opção de retirar o pacote no endereço do vendedor. Os valores possíveis são:
    • true: permite a retirada.
    • false: não permite a retirada.
  • modes: lista de modos de envio configurados para o usuário. Os valores possíveis são:
    • custom
    • not_specified
    • me2
    • me1
  • trusted_user: indica se o usuário é considerado confiável para vender em domínios restritos. Os valores possíveis são:
    • true
    • false
  • custom_calculator: indica se o usuário possui uma tabela de contingência no Mercado Livre. Os valores possíveis são:
    • Axado: tem ME1 ativo com tabela de contingência.
    • true: tem ME1 ativo sem tabela de contingência.
    • false: não tem ME1 ativo.
    • CBT: usuário CBT.
  • thermal_printer: indica se utiliza uma impressora térmica.
  • option: opção de configuração de envio do usuário. Os valores possíveis são:
    • in: usuário tem Mercado Envios 2 ativo para todas as suas publicações.
    • out: usuário anteriormente tinha habilitada a opção de Mercado Envios 2. No entanto, esta funcionalidade já não está ativa para sua conta.
    • trial: usuário tem Mercado Envios 2 ativo para algumas publicações.
    • null: usuário nunca teve Mercado Envios 2 ativo.
  • tags: lista de etiquetas adicionais relacionadas com a configuração de envio do usuário. Os valores possíveis são:
    • optional_me1_allowed: me2 é a opção mandatória, e me1 é a preferência de envio opcional.
    • optional_me2_allowed: me1 é a opção padrão, e me2 é a preferência de envio opcional.
    • turbo: logística turbo ativa para o usuário.
  • me2_enablers: indica os habilitadores configurados para o vendedor. Os valores possíveis são:
    • bulky_fulfilllment
    • bulky_cross_docking
    • bulky_drop_off
    • pharma
    • cbt_fulfillment
    • entre outros.
  • carrier_pickup: indica se tem habilitado um carrier para coletas.
  • items_combination: indica se permite combinação no carrinho.
  • services: lista de identificadores de serviços disponíveis.
  • logistics: configurações logísticas detalhadas para diferentes modos de envio, cada uma com tipos específicos e seus atributos.
  • label: configurações para a impressão de etiquetas, incluindo opções de impressão e tamanho/formato da página.
  • site_id: identificador do país do usuário no Mercado Livre.

Códigos de Estado de resposta:

Código Mensagem Descrição Recomendação
200 - OK - A configuração atual foi obtida corretamente. -
401 - Unauthorized authorization value not present Falta informar o access token Informe um access token válido
401 - Unauthorized invalid access token O access token informado é inválido ou expirado Informe um access token válido

Considerações:

  • A configuração padrão de um usuário com ME2 e ME1 ativos é com optional_me1_allowed. Isso significa que ME1 está habilitado como um modo de envio opcional, e ME2 é mandatório.
  • Se desejar realizar qualquer modificação nesta configuração, é necessário que o vendedor entre em contato com seu consultor comercial, justificando a alteração requerida.
  • É fundamental validar os modos de envio ativos para cada usuário, pois isso impacta diretamente em como serão gerenciadas as publicações de seus produtos. Os atributos chave a considerar são optional_me1_allowed e optional_me2_allowed.
  • Lembrar que todos os vendedores têm habilitado custom e not_specified por padrão.

Consultar modos de envios de uma categoria

Este endpoint permite consultar as preferências de envio disponíveis para a categoria e serve para identificar previamente as opções de envio.


Chamada:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/$CATEGORY_ID/shipping_preferences

Exemplo:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLA418448/shipping_preferences

Resposta:

	
    {
        "dimensions": {
          "height": 5,
          "width": 18,
          "length": 25,
          "weight": 650
        },
        "logistics": [
          {
            "types": [
              "default"
            ],
            "mode": "me1"
          },
          {
            "types": [
              "drop_off",
              "xd_drop_off",
              "self_service",
              "cross_docking",
              "fulfillment"
            ],
            "mode": "me2"
          },
          {
            "types": [
              "not_specified"
            ],
            "mode": "not_specified"
          },
          {
            "types": [
              "custom"
            ],
            "mode": "custom"
          }
        ],
        "me2_restrictions": null,
        "restricted": false,
        "source": {
          "origin": "categories",
          "identifier": "MLA418448"
        },
        "date_created": null,
        "last_modified": null,
        "category_id": "MLA418448"
      }


Parâmetros de resposta:

  • dimensions: são as dimensões base (default) dos produtos desta categoria.
  • logistics: mostra os tipos logísticos (mode e type) habilitados para a categoria.
  • me2_restrictions: caso haja alguma restrição que não permita me2, estará identificado. Valores possíveis:
    • fbm_non_totable
    • flex_ne
    • cbt_fulfillment
    • bulky_drop_off
    • farma
    • fragile
    • bulky_cross_docking
    • bulky_fulfillment
  • restricted: caso haja restrição de me2, estará identificado com true, caso contrário, é false.

Códigos de estado de resposta:

Código Mensagem Descrição Recomendação
200 - OK - A configuração atual foi obtida corretamente. -
404 - Not Found Category not found A categoria não existe. Validar o category_id.

Consultar atributos de shipping por domínio

Este endpoint permite consultar os atributos de preferências de envio por domínio, para identificar os atributos requeridos para as regras de envios a ME2.

Nota:
Verifique que o domain_id pode ser obtido tanto em /categories quanto na publicação em /items.

Chamada:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/catalog_domains/$DOMAIN_ID/shipping_attributes

Exemplo:

	curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_domains/MLA-AUTOMOTIVE_TIRES/shipping_attributes

Resposta:

	
    
{
    "domain_id": "MLA-AUTOMOTIVE_TIRES",
    "attributes": [
      {
        "id": "RIM_DIAMETER",
        "type": "NUMBER_UNIT",
        "unit": "\"",
        "index": 1,
        "ranges": null
      },
      {
        "id": "TIRES_NUMBER",
        "type": "INTEGER",
        "unit": "",
        "index": 2,
        "ranges": null
      },
      {
        "id": "SECTION_WIDTH",
        "type": "NUMBER_UNIT",
        "unit": "mm",
        "index": 3,
        "ranges": null
      }
    ],
    "client_id": app_id,
    "date_created": "2018-11-09T15:31:02.040-03:00",
    "last_modified": "2023-09-11T15:59:30.175-03:00"
  }  


Parâmetros de resposta:

  • domain_id: ID do domínio consultado.
  • attributes: atributos que determinam a preferência de envio de um item.

Códigos de estado de resposta:

Código Mensagem Descrição Recomendação
200 - OK - A configuração atual foi obtida corretamente. -
404 - Not Found Domain does not exist Não existe o domínio. Validar o domain_id.

Consultar modos de envios de um item para o usuário

Como passo extra, é possível realizar uma validação antes de executar o POST do Item para identificar se a API permite o modo de envio que você está tentando atualizar. Para isso, deve enviar as informações abaixo, focando nos atributos da publicação. Lembre-se de observar o recurso de catalog_domaing/$ID/shipping_attributes para testar com os atributos que se apontam como necessários para atualização a ME2.

Chamada:


	curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 'x-multichannel: true' 'X-Format-New: true' -H 'Content-Type: application/json' -d https://api.mercadolibre.com/users/$USER_ID/shipping_modes

Exemplo:

	curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 'x-multichannel: true' 'X-Format-New: true' -H 'Content-Type: application/json' -d https://api.mercadolibre.com/users/123456789/shipping_modes
	{
    "site_id": "MLB",
    "item_id": "MLB1234",
    "seller_id": 123456789,
    "title": "Título de teste",
    "item_price": 500,
    "item_currency": "BRL",
    "category_id": "MLB1626",
    "sale_terms": [],
    "listing_type_id": "gold_pro",
    "buying_mode": "buy_it_now",
    "condition": "new",
    "dimensions": null,
    "local_pick_up": false,
    "channels": [
        {
            "id": "marketplace"
        }
    ],
    "new_format": true,
    "verbose": false
}
    

Resposta:

	{
    "channels": {
        "marketplace": {
            "available_modes": [
                {
                    "mode": "custom",
                    "logistic_types": [
                        {
                            "type": "custom",
                            "default": true,
                            "attributes": {
                                "dimensions": "optional",
                                "costs": "required",
                                "adoption": "not_required",
                                "free_shipping": "not_allowed",
                                "local_pick_up": "optional",
                                "tags": []
                            }
                        }
                    ],
                    "shipping_attributes": {
                        "dimensions": "optional",
                        "costs": "required",
                        "adoption": "not_required",
                        "free_shipping": "not_allowed",
                        "local_pick_up": "optional",
                        "tags": []
                    }
                },
                {
                    "mode": "not_specified",
                    "logistic_types": [
                        {
                            "type": "not_specified",
                            "default": true,
                            "attributes": {
                                "dimensions": "optional",
                                "costs": "not_allowed",
                                "adoption": "not_required",
                                "free_shipping": "optional",
                                "local_pick_up": "optional",
                                "tags": []
                            }
                        }
                    ],
                    "shipping_attributes": {
                        "dimensions": "optional",
                        "costs": "not_allowed",
                        "adoption": "not_required",
                        "free_shipping": "optional",
                        "local_pick_up": "optional",
                        "tags": []
                    }
                },
                {
                    "mode": "me2",
                    "logistic_types": [
                        {
                            "type": "self_service",
                            "default": true,
                            "attributes": {
                                "dimensions": "clear",
                                "costs": "not_allowed",
                                "adoption": "not_required",
                                "free_shipping": "mandatory",
                                "local_pick_up": "optional",
                                "tags": []
                            }
                        }
                    ],
                    "shipping_attributes": {
                        "dimensions": "clear",
                        "costs": "not_allowed",
                        "adoption": "not_required",
                        "free_shipping": "mandatory",
                        "local_pick_up": "optional",
                        "tags": []
                    }
                }
            ],
            "warnings": null,
            "channel_id": "marketplace"
        }
    }
}


Parâmetros de resposta:

  • mode: modos de envios permitidos.
  • logistic_types
    • type: tipos de logística de acordo com cada modo de envio.
    • default: se o tipo de logística é definido como padrão.
    • attributes:
      • dimensions: caso haja uma dimensão padrão, será preenchida.
      • costs: regras relacionadas ao custo de envio.
      • adoption: indica a configuração sobre ativar me2 na publicação
      • free_shipping: se a configuração de frete grátis é padrão.
      • local_pick_up: indica a configuração sobre retirada em mãos
      • tags: tags internas relacionadas às características de cada tipo de logística.

    Nota:
    Caso deseje validar um item existente, é necessário enviar o atributo item_id. Se este não estiver presente, as regras serão validadas de maneira genérica. Portanto, recomenda-se utilizar pelo menos os seguintes atributos para obter uma resposta mais precisa: item_id, seller_id, category_id, channels, attributes, new_format e verbose.

    Consultar um item

    Também é possível validar certas informações relacionadas ao envio da publicação consultando seu detalhe pela API /Items.


    Chamada:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID
    

    Exemplo:

      curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1718222111
    

    Resposta

      
            
    {
        "id": "MLA1718222111",
        "site_id": "MLA",
        "title": "Silla Director Coleman Sillon Plegable Acero Resistente 136k Color Rojo",
        "seller_id": 309720111,
        "category_id": "MLA79227",
        "user_product_id": "MLAU255412797",
        "official_store_id": 66111,
        "price": 105622,
        "base_price": 105622,
        "original_price": 126900,
        "currency_id": "ARS",
        "initial_quantity": 4,
        "available_quantity": 2,
        "sold_quantity": 2,
      ...
        "shipping": {
          "mode": "me2",
          "methods": [],
          "tags": [
            "self_service_out",
            "mandatory_free_shipping"
          ],
          "dimensions": null,
          "local_pick_up": true,
          "free_shipping": true,
          "logistic_type": "cross_docking",
          "store_pick_up": false
        },
      ...
        }  
        
    

    Agora que você já sabe como validar previamente as informações do seu vendedor, revise a documentação a seguir para saber como gerenciar as publicações: