Referência de ferramentas — Mercado Livre

O conector expõe 43 ferramentas. Classes de cobrança: grátis (meta/status — não contam na cota), leitura, agregação (fan-out computado no servidor) e escrita (auditadas; as arriscadas exigem confirmação).

Agregação (respostas computadas)

`ads_performance`

Performance de Product Ads (api-version 2, ROAS-first; deriva ACoS=(1/ROAS)×100). Janela ≤90 dias.

Parâmetro	Tipo	Obrigatório	Padrão
`date_from`	string	sim
`date_to`	string	sim
`level`	string	não	`account`
`advertiser_id`	string/null	não
`status`	string/null	não
`metrics`	array/null	não
`aggregation_type`	string	não	`sum`
`sort_by`	string/null	não
`limit`	integer	não	`50`
`campaign_ids`	array/null	não

`aggregate_orders`

Agrega pedidos server-side: faturamento (gmv), pedidos, unidades, ticket médio, tarifas, por período/status/agrupamento. 1 chamada = 1 resposta computada (ex.: ‘faturamento pago dos últimos 7 dias’).

Parâmetro	Tipo	Obrigatório	Padrão
`date_from`	string	sim
`date_to`	string	sim
`date_field`	string	não	`closed`
`status`	array/null	não
`group_by`	array/null	não
`metrics`	array/null	não
`top_n`	integer	não	`20`

`claims_open_summary`

Reclamações abertas: total, agrupamentos e as acionáveis com prazo.

Parâmetro	Tipo	Obrigatório	Padrão
`group_by`	array/null	não
`include_actionable`	boolean	não	`True`

`query`

Consulta genérica (DSL) sobre orders, order_items, items, questions, claims — filtros, group_by (com bucket day/week/month) e agregações (sum/count/avg/min/max/count_distinct) computadas no servidor. Use describe_query_schema para o catálogo completo.

Parâmetro	Tipo	Obrigatório
`entity`	string	sim
`select`	array/null	não
`filter`	object/null	não
`group_by`	array/null	não
`aggregate`	array/null	não
`sort`	array/null	não
`limit`	integer/null	não
`budget`	object/null	não

`rank_items`

Ranqueia anúncios por gmv/unidades/visitas/conversão no período.

Parâmetro	Tipo	Obrigatório	Padrão
`date_from`	string	sim
`date_to`	string	sim
`by`	string	não	`gmv`
`status`	array/null	não
`limit`	integer	não	`20`
`direction`	string	não	`desc`
`include`	array/null	não

`reputation_summary`

Reputação enquadrada nos thresholds de cor do site + distância do rebaixamento + reclamações abertas.

Parâmetro	Tipo	Obrigatório	Padrão
`include_open_claims`	boolean	não	`True`

`visits_rollup`

Rollup de visitas (janela ≤150d; contorna a regra 1-id-por-chamada).

Parâmetro	Tipo	Obrigatório	Padrão
`date_from`	string	sim
`date_to`	string	sim
`item_ids`	array/null	não
`group_by`	string/null	não
`top_n`	integer	não	`20`

Leitura

`get_claim`

Reclamação composta (post-purchase v1).

Parâmetro	Tipo	Obrigatório	Padrão
`claim_id`	integer	sim
`include`	array/null	não

`get_item`

Busca 1..N anúncios com projeção de campos (multiget em blocos de 20).

Parâmetro	Tipo	Obrigatório
`item_id`	string/null	não
`item_ids`	array/null	não
`fields`	array/null	não

`get_order`

Busca um pedido do Mercado Livre (normalizado). view=financial inclui descontos.

Parâmetro	Tipo	Obrigatório	Padrão
`order_id`	integer	sim
`view`	string	não	`summary`

`get_question`

Uma pergunta; include_contact usa api_version=4 (dados do comprador).

Parâmetro	Tipo	Obrigatório	Padrão
`question_id`	integer	sim
`include_contact`	boolean	não	`False`

`get_seller_reputation`

Projeção da reputação do vendedor (endpoint /users/id).

`get_shipment`

Envio composto: colapsa até 8 endpoints /shipments/* (busca só o pedido).

Parâmetro	Tipo	Obrigatório	Padrão
`shipment_id`	integer	sim
`include`	array/null	não

`get_stock`

Estoque multi-origem; devolve x_version (necessário para escrita).

Parâmetro	Tipo	Obrigatório	Padrão
`user_product_id`	string	sim

`get_visits`

Visitas (user ou item). Janela ≤150 dias; 1 id por chamada (regra ML).

Parâmetro	Tipo	Obrigatório	Padrão
`scope`	string	sim
`id`	string/null	não
`date_from`	string/null	não
`date_to`	string/null	não
`mode`	string	não	`total`
`last`	integer/null	não
`unit`	string	não	`day`

`list_pack_messages`

Mensagens pós-venda de um pacote/pedido (pack-cêntrico; aceita ambos).

Parâmetro	Tipo	Obrigatório	Padrão
`pack_id`	integer/null	não
`order_id`	integer/null	não
`mark_as_read`	boolean	não	`False`
`cursor`	string/null	não
`limit`	integer	não	`50`

`list_received_questions`

Perguntas recebidas (pré-venda).

Parâmetro	Tipo	Obrigatório	Padrão
`status`	string/null	não
`item_id`	string/null	não
`from_user`	integer/null	não
`sort`	string/null	não
`cursor`	string/null	não
`limit`	integer	não	`50`

`list_warehouses`

Depósitos (stock locations) do vendedor.

`search_claims`

Busca reclamações. Auto-injeta players.user_id+role=respondent quando não há filtro real (ML devolve 400 em busca só com paginação).

Parâmetro	Tipo	Obrigatório	Padrão
`status`	string/null	não
`type`	string/null	não
`stage`	string/null	não
`order_id`	integer/null	não
`pack_id`	integer/null	não
`resource`	string/null	não
`resource_id`	integer/null	não
`reason_id`	string/null	não
`range_from`	string/null	não
`range_to`	string/null	não
`sort`	string/null	não
`cursor`	string/null	não
`limit`	integer	não	`30`

`search_orders`

Busca pedidos do vendedor (/orders/search) com paginação normalizada (cursor).

Parâmetro	Tipo	Obrigatório	Padrão
`status`	string/null	não
`q`	string/null	não
`item`	string/null	não
`tags`	array/null	não
`date_field`	string	não	`created`
`date_from`	string/null	não
`date_to`	string/null	não
`sort`	string/null	não
`cursor`	string/null	não
`limit`	integer	não	`50`

`search_seller_items`

Lista IDs de anúncios do vendedor; muda para scan/scroll_id além de 1000.

Parâmetro	Tipo	Obrigatório	Padrão
`status`	string/null	não
`listing_type`	string/null	não
`sku`	string/null	não
`cursor`	string/null	não
`limit`	integer	não	`100`

Escrita (auditadas)

`add_order_note`

Adiciona nota interna a um pedido (visível só para o vendedor).

Parâmetro	Tipo	Obrigatório	Padrão
`order_id`	integer	sim
`note`	string	sim
`confirm`	boolean	não	`False`

`answer_question`

Responde uma pergunta de pré-venda.

Parâmetro	Tipo	Obrigatório	Padrão
`question_id`	integer	sim
`text`	string	sim
`confirm`	boolean	não	`False`

`delete_question` ⚠️ destrutiva

Exclui uma pergunta. SEMPRE exige confirm=true.

Parâmetro	Tipo	Obrigatório	Padrão
`question_id`	integer	sim
`confirm`	boolean	não	`False`

`print_shipping_labels`

Obtém etiquetas de envio OFICIAIS do ML (o template nunca é alterado).

Parâmetro	Tipo	Obrigatório	Padrão
`shipment_ids`	array	sim
`format`	string	não	`pdf`
`confirm`	boolean	não	`False`

`resolve_claim` ⚠️ destrutiva

Resolve uma reclamação. Valida action ∈ available_actions do claim. SEMPRE exige confirm=true (ação de alto risco).

Parâmetro	Tipo	Obrigatório	Padrão
`claim_id`	integer	sim
`action`	string	sim
`payload`	object/null	não
`confirm`	boolean	não	`False`

`send_claim_message`

Envia mensagem na reclamação (para o reclamante ou mediador).

Parâmetro	Tipo	Obrigatório	Padrão
`claim_id`	integer	sim
`to`	string	sim
`text`	string	sim
`attachment_ids`	array/null	não
`confirm`	boolean	não	`False`

`send_message`

Envia UMA mensagem pós-venda no pacote/pedido. Regras ML: só conversas iniciadas pelo comprador, janela de 48h úteis, pedido não cancelado. PROIBIDO uso automático/template/repetitivo (bloqueado pelo ML e arrisca a conta do vendedor) — apenas os motivos oficiais.

Parâmetro	Tipo	Obrigatório	Padrão
`text`	string	sim
`pack_id`	integer/null	não
`order_id`	integer/null	não
`attachment_ids`	array/null	não
`confirm`	boolean	não	`False`

`split_shipment` ⚠️ destrutiva

Divide um envio em pacotes. SEMPRE exige confirm=true.

Parâmetro	Tipo	Obrigatório	Padrão
`shipment_id`	integer	sim
`reason`	string	sim
`packs`	array	sim
`confirm`	boolean	não	`False`

`update_item` ⚠️ destrutiva

Atualiza um anúncio (preço, estoque, status). Guardas: rejeita variação de preço >±50%, estoque negativo; deleted encadeia closed→delete.

Parâmetro	Tipo	Obrigatório	Padrão
`item_id`	string	sim
`price`	number/null	não
`available_quantity`	integer/null	não
`status`	string/null	não
`deleted`	boolean	não	`False`
`other_fields`	object/null	não
`confirm`	boolean	não	`False`

`update_order_note`

Atualiza uma nota interna de pedido.

Parâmetro	Tipo	Obrigatório	Padrão
`order_id`	integer	sim
`note_id`	string	sim
`note`	string	sim
`confirm`	boolean	não	`False`

`update_stock_multiwarehouse` ⚠️ destrutiva

Atualiza estoque multi-origem (busca x-version e envia PUT com lock otimista).

Parâmetro	Tipo	Obrigatório	Padrão
`user_product_id`	string	sim
`locations`	array	sim
`confirm`	boolean	não	`False`

`upload_message_attachment`

Sobe um anexo de mensagem (≤25MB; JPG/PNG/PDF/TXT).

Parâmetro	Tipo	Obrigatório	Padrão
`file_base64`	string	sim
`filename`	string	sim
`confirm`	boolean	não	`False`

Meta (grátis)

`connection_status`

Status da conexão: conta, validade do token, escopos. Gratuito.

`describe_query_schema`

Catálogo do DSL query: entidades, campos, operadores, regras de budget. Gratuito.

`describe_schemas`

Schemas dos objetos ML (para o agente montar consultas). Gratuito.

Parâmetro	Tipo	Obrigatório	Padrão
`entity`	string/null	não

`get_app_limits`

Limites do app ML (max_requests_per_hour, escopos). Gratuito.

`get_claim_reasons`

Motivos de reclamação (todos ou um específico). Gratuito.

Parâmetro	Tipo	Obrigatório	Padrão
`reason_id`	string/null	não

`list_shipment_statuses`

Catálogo de status de envio (cacheável). Gratuito.

`list_sites`

Sites do ML (site_id ↔ moeda). Gratuito.

`open_support_ticket`

Abre um chamado de suporte do mcplace sem sair do chat. Use quando o usuário pedir, ou OFEREÇA quando houver erro repetido de ferramenta, falha de permissão/auth sem solução, ou limitação do conector. Sempre pergunte ao usuário antes de abrir. Gratuito (não conta na cota).

Parâmetro	Tipo	Obrigatório	Padrão
`subject`	string	sim
`body`	string	sim
`severity`	string/null	não
`category`	string	não	`question`
`context`	object/null	não

`suggest_improvement`

Registra uma sugestão de melhoria do mcplace (ex.: ‘essa ação ainda não existe no conector’). Pergunte ao usuário antes. Gratuito.

Parâmetro	Tipo	Obrigatório	Padrão
`text`	string	sim
`area`	string/null	não

`whoami`

Conta conectada: id, nickname, site, tags (inclui multiwarehouse), status.

Início rápido Consulta genérica (query)

Referência de ferramentas — Mercado Livre

Agregação (respostas computadas)

ads_performance

aggregate_orders

claims_open_summary

query

rank_items

reputation_summary

visits_rollup

Leitura

get_claim

get_item

get_order

get_question

get_seller_reputation

get_shipment

get_stock

get_visits

list_pack_messages

list_received_questions

list_warehouses

search_claims

search_orders

search_seller_items

Escrita (auditadas)

add_order_note

answer_question

delete_question ⚠️ destrutiva

print_shipping_labels

resolve_claim ⚠️ destrutiva

send_claim_message

send_message

split_shipment ⚠️ destrutiva

update_item ⚠️ destrutiva

update_order_note

update_stock_multiwarehouse ⚠️ destrutiva

upload_message_attachment