# Receitas — Mercado Livre

Perguntas prontas para mandar ao seu agente, a chamada que ele deve fazer e o
que conferir na resposta. As datas são de exemplo: o servidor não entende
"semana passada", quem calcula o intervalo (`AAAA-MM-DD`) é o agente.

## Quanto faturei nos últimos 7 dias?

**Peça assim**

> Qual foi meu faturamento de pedidos pagos nos últimos 7 dias no Mercado
> Livre? Diga se o resultado veio parcial.

**O que o agente chama**

```json
{
  "tool": "aggregate_orders",
  "date_from": "2026-08-17",
  "date_to": "2026-08-23",
  "date_field": "closed",
  "status": ["paid"],
  "metrics": ["gmv", "count", "units", "avg_ticket", "sale_fee_total", "net"]
}
```

**O que volta:** `gmv` (faturamento bruto), `count` (pedidos), `units`
(unidades), `avg_ticket` (ticket médio), `sale_fee_total` (tarifas de venda do
Mercado Livre) e `net`.

**Cuidados**

- `net` é o faturamento menos **apenas as tarifas de venda** do Mercado Livre.
  Não desconta frete, impostos, devoluções, anúncios nem custo do produto.
  **Não é lucro.**
- `date_field` vem como `closed`: conta pedidos *fechados* no período, não
  criados. As alternativas são `created` e `updated`.
- `status` vem como `["paid"]`. Para incluir cancelados, passe `status`
  explicitamente.
- A varredura para em 2000 pedidos. Quando isso acontece a resposta traz
  `_truncated: true` e o número é um piso, não o total. Reduza o período e some.

## Quais são meus 10 anúncios que mais vendem?

**Peça assim**

> Liste meus 10 anúncios com maior faturamento neste mês e avise se a lista
> cobre todos os pedidos do período.

**O que o agente chama**

```json
{
  "tool": "rank_items",
  "date_from": "2026-08-01",
  "date_to": "2026-08-23",
  "by": "gmv",
  "limit": 10,
  "direction": "desc"
}
```

**Cuidados**

- `by` aceita exatamente `gmv`, `units`, `visits`, `conversion`,
  `revenue_per_visit` e `sale_fee`. "Mais vendem" em dinheiro é `gmv`; em
  quantidade é `units`. São rankings diferentes.
- `limit` vai até 50. `direction: "asc"` mostra os piores, que costuma ser a
  pergunta mais útil.
- O mesmo teto de 2000 pedidos vale aqui, com o mesmo aviso `_truncated`.
- Ranking por `visits`, `conversion` ou `revenue_per_visit` só considera os 50
  primeiros anúncios por volume de pedidos, **e esse corte não tem aviso na
  resposta**. Peça ao agente para dizer isso.
- Conversão em anúncio com pouco volume é ruído: 1 visita e 1 venda dá 100%.

## Minha publicidade está valendo a pena?

**Peça assim**

> Mostre o ACoS de cada campanha de Product Ads neste mês, da pior para a
> melhor.

**O que o agente chama**

```json
{
  "tool": "ml_ads_performance",
  "date_from": "2026-08-01",
  "date_to": "2026-08-23",
  "level": "campaign",
  "aggregation_type": "campaign",
  "limit": 50
}
```

**Cuidados**

- Ads é **somente leitura**. O agente relata; pausar ou criar campanha continua
  sendo no painel do Mercado Livre.
- Conta sem nenhuma campanha não é erro: a resposta vem vazia com uma nota
  explicando. O agente deve dizer "esta conta não tem campanhas".
- Não existe `_truncated` nesta tool. Se o número de linhas for igual ao
  `limit` enviado (máximo 100), existem mais campanhas.
- ACoS usa a receita **atribuída aos anúncios**, que vem na própria resposta.
  Dividir o gasto pelo `gmv` de `aggregate_orders` dá um número que parece
  ACoS e não é.
- Use `aggregation_type: "DAILY"` quando quiser tendência em vez de total.

## Tenho reclamação para responder hoje?

**Peça assim**

> Tenho reclamações abertas no Mercado Livre? Ordene pelas que têm prazo mais
> próximo e não responda nada sem me perguntar.

**O que o agente chama**

```json
{
  "tool": "claims_open_summary",
  "group_by": ["type", "stage"],
  "include_actionable": true
}
```

**Cuidados**

- Esta tool **não recebe datas**: "reclamação aberta" é estado atual, não
  período. `group_by` aceita `type`, `stage`, `reason_id` e `status`.
- A varredura para em 500 reclamações e **não há aviso** na resposta. Total
  igual ou perto de 500 é resumo parcial.
- Achar uma reclamação acionável não é permissão para resolvê-la.
  `resolve_claim` sempre exige confirmação — veja
  [Segurança e controle](/seguranca).
- Nada de resposta-modelo: o Mercado Livre bloqueia mensagens automáticas ou
  padronizadas no pós-venda, e isso põe sua conta em risco. O agente pode
  ajudar a pensar **uma** resposta para **uma** reclamação.