> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bulkroute.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectando o Mercado Livre

> Importe vendas do Mercado Livre e sincronize o tracking de volta.

O [Mercado Livre](https://www.mercadolivre.com.br) é o maior marketplace da América Latina. A integração usa OAuth 2.0 e importa vendas pagas como shipments.

## Conectando

### 1. Autorizar OAuth

1. Acesse **Integrações** > **Mercado Livre**
2. Clique em **Conectar Mercado Livre**
3. Você será redirecionado para o ML — faça login e autorize
4. O ML retorna para o BulkRoute com o token de acesso

### 2. Mapear carriers

O Mercado Livre usa o campo `shipping_option.name` para identificar o carrier. Mapeie:

| Shipping option ML | Carrier no BulkRoute      |
| :----------------- | :------------------------ |
| "Correios Sedex"   | `CORREIOS`                |
| "Correios PAC"     | `CORREIOS`                |
| "Jadlog"           | `JADLOG`                  |
| "Mercado Envios"   | `MERCADOLIVRE` (fallback) |

### 3. Ativar sincronização

Ative a sincronização automática (padrão: 30 minutos).

## O que é importado

| Campo do ML                    | Campo no BulkRoute    |
| :----------------------------- | :-------------------- |
| `id`                           | `external_order_id`   |
| `buyer.first_name + last_name` | `recipient.name`      |
| `buyer.phone`                  | `recipient.phone`     |
| `shipping.address.zip_code`    | `destination_zip`     |
| `order_items[].item.title`     | `items[].description` |
| `order_items[].unit_price`     | `items[].value`       |

### Cubagem

O Mercado Livre não envia dimensões por item. O BulkRoute usa **cubagem padrão por categoria** do ML:

* Eletrônicos pequenos: 20×15×10 cm, 1 kg
* Eletrodomésticos: 50×40×30 cm, 8 kg
* Móveis: 100×60×40 cm, 15 kg
* Outros: 30×30×30 cm, 3 kg

Você pode ajustar esses valores em **Integrações** > **Mercado Livre** > **Mapeamento de categorias**.

## Sincronização de tracking

O BulkRoute envia o tracking code para o ML via `POST /shipments/:id/tracking`. O cliente final vê o tracking dentro do ML ou pelo link do BulkRoute.

## Mercado Envios vs frete próprio

<Warning>
  Se você usa **Mercado Envios** (frete gerenciado pelo próprio ML), o ML já gera o tracking e despacha. Nesse caso, o BulkRoute apenas importa o pedido para centralização — não despacha nem gera etiqueta.

  Se você usa **frete próprio** no ML (envio combinado), o BulkRoute despacha normalmente e sincroniza o tracking de volta.
</Warning>

## Troubleshooting

| Problema              | Causa                             | Solução                    |
| :-------------------- | :-------------------------------- | :------------------------- |
| Token expirado        | OAuth token tem validade limitada | Reconectar ML              |
| Rate limit (HTTP 429) | ML limita requisições             | Aumentar intervalo de sync |
| Categoria sem cubagem | Categoria não mapeada             | Adicionar mapeamento       |
| Pedido sem CEP        | Comprador não informou CEP        | Verificar no ML            |