Referência de tools

As ferramentas que valem em todos os marketplaces conectados. O marketplace vem da conta que você indicar.

Quais marketplaces oferecem cada uma está na matriz de disponibilidade.

As ferramentas se dividem em quatro 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).

Em Retorno, chave? só aparece em certas condições, [] é lista e o que vem marcado como ML é dado do Mercado Livre repassado sem transformação.

Agregação (respostas computadas)

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

Exemplo de pedido ao agente: “Qual foi meu faturamento de pedidos pagos nos últimos 7 dias, dia a dia?”

Disponível em: Mercado Livre

Retorno

{ range{from, to, field}, status_filter[],
  totals{…métricas pedidas: count, gmv, units, avg_ticket, sale_fee_total, net,
         cancelled_rate},
  currency, _pages_scanned, _truncated?,
  groups[]?{key, …métricas pedidas, share}, group_by? }
 · groups e group_by só aparecem quando group_by é informado (usa a primeira dimensão; groups limitado a top_n)

claims_open_summary

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

Exemplo de pedido ao agente: “Resuma minhas reclamações abertas por motivo e por etapa.”

Disponível em: Mercado Livre

Retorno

{ total_open, by_<dimensão>{<valor>: contagem}, actionable[]?{claim_id, type, stage, mandatory_action, due_date}, soonest_due_date? }
 · uma chave by_<dimensão> por item de group_by (type, stage, reason_id, status; padrão: by_type e by_stage) · actionable e soonest_due_date só com include_actionable=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.

Exemplo de pedido ao agente: “Agrupe meus pedidos pagos do trimestre por status e some o valor de cada grupo.”

Disponível em: Mercado Livre

Retorno

{ entity, rows[]{…}, _meta{upstream_calls, rows_scanned, truncated, returned} }
 · sem aggregate: cada linha tem os campos de select (padrão: todos os campos da entidade) · com aggregate: cada linha tem os campos de group_by + uma chave por agregação (nome em "as", ou <op>_<field>, ou <op>)

rank_items

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

Exemplo de pedido ao agente: “Quais são meus melhores anúncios por faturamento no mês, e quais convertem pior?”

Disponível em: Mercado Livre

Retorno

{ ranked[]{item_id, title, gmv, units, sale_fee, price, available_quantity, health,
           permalink, visits?, conversion?, revenue_per_visit?, _error?, value},
  basis, range{from, to}, _pages_scanned, _truncated? }
 · visits, conversion e revenue_per_visit só quando by é visits, conversion ou revenue_per_visit · _error na linha quando a leitura de visitas daquele anúncio falhou

reputation_summary

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

distance_to_downgrade é medida sobre a taxa de reclamações (claims_rate) até o teto da faixa green; a métrica e o limite vêm da enum reputation_thresholds do adaptador do marketplace, não da API do marketplace, e podem mudar sem aviso. É uma conta sobre as suas próprias métricas, não uma previsão.

Exemplo de pedido ao agente: “Estou perto de perder o nível de reputação? Compare com os limites da plataforma.”

Disponível em: Mercado Livre

Retorno

{ level_id, power_seller_status, transactions<objeto ML>, metrics<objeto ML>, claims_rate,
  distance_to_downgrade, protected, real_level, protection_end_date, open_claims? }
 · open_claims só com include_open_claims=true (null se a leitura falhar)

visits_rollup

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

Exemplo de pedido ao agente: “Some as visitas dos meus anúncios de janeiro e mostre os que mais atraíram público.”

Disponível em: Mercado Livre

Retorno

{ range{from, to}, total_visits, by_day[]?<lista ML>, by_item[]?{item_id, visits, _error?}, _items_scanned }
 · by_day só com group_by="day" sem item_ids · by_item só quando item_ids é informado (limitado a top_n) · sem nenhum dos dois: só range, total_visits e _items_scanned

Leitura

get_claim

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

Exemplo de pedido ao agente: “Mostre os detalhes da reclamação 5200012345.”

Disponível em: Mercado Livre

Retorno

{ …<objeto ML> (GET /post-purchase/v1/claims/{claim_id}), actions_history?, status_history?, affects_reputation?, messages? }
 · cada chave de include carrega a resposta do ML daquele recurso, ou {_error} se a leitura falhar · include="detail" não acrescenta chave

get_item

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

Exemplo de pedido ao agente: “Me mostre o anúncio MLB3456789012 com preço, estoque e status.”

Disponível em: Mercado Livre

Retorno

{ items[]<objeto ML>, _error? }
 · fields projeta cada anúncio para os campos pedidos (aceita caminho com 1 ponto) · sem item_id/item_ids: { items[] vazio, _error }

get_order

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

Exemplo de pedido ao agente: “Mostre os detalhes do pedido 2000012345678 da minha conta principal.”

Disponível em: Mercado Livre

Retorno

{ id, status, date_created, date_closed, total_amount, paid_amount, currency_id,
  buyer{id, nickname}, items[]{item_id, title, qty, unit_price, gross_price, sale_fee},
  shipping_id, pack_id, tags, cancel_detail, _missing?, discounts?, payments? }
 · view="financial" acrescenta discounts (<objeto ML> ou null) e payments (<lista ML>) · view="full" devolve o pedido ML completo (GET /orders/{order_id})

get_question

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

Exemplo de pedido ao agente: “Abra a pergunta 13000045678 e me mostre o anúncio a que ela se refere.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (GET /questions/{question_id})

get_seller_reputation

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

Exemplo de pedido ao agente: “Como está minha reputação hoje?”

Disponível em: Mercado Livre

Retorno

{ user_id, nickname, seller_reputation<objeto ML> }

get_shipment

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

Exemplo de pedido ao agente: “Qual é o status do envio do pedido 2000012345678?”

Disponível em: Mercado Livre

Retorno

{ …<objeto ML> (GET /shipments/{shipment_id}), costs?, sla?, history?, carrier?, lead_time?, items?, delays? }
 · cada chave de include carrega a resposta do ML daquele recurso, ou {_error} se a leitura falhar · delays sem atraso (404): {delayed: false}

get_stock

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

Exemplo de pedido ao agente: “Quanto tenho em estoque do anúncio MLB3456789012?”

Disponível em: Mercado Livre

Retorno

{ locations[]<lista ML>, x_version }

get_visits

Visitas (user ou item). mode=total exige date_from+date_to, janela ≤150 dias; scope=item exige id e só aceita unit=day; 1 id por chamada.

Exemplo de pedido ao agente: “Quantas visitas o anúncio MLB3456789012 teve nos últimos 30 dias?”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (mode="total": GET /users/{target}/items_visits ou GET /items/visits; mode="timeseries": GET /users/{target}/items_visits/time_window ou GET /items/{target}/visits/time_window)

list_messages

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

Exemplo de pedido ao agente: “Mostre a conversa com o comprador do pedido 2000012345678.”

Disponível em: Mercado Livre

Retorno

{ conversation_status<objeto ML>, messages[]<lista ML>, seller_max_message_length, paging }
 · sem pack_id/order_id: { _error }

list_received_questions

Perguntas recebidas (pré-venda).

Exemplo de pedido ao agente: “Quais perguntas dos compradores estão sem resposta?”

Disponível em: Mercado Livre

Retorno

{ questions[]<lista ML>, total, cursor }

list_warehouses

Depósitos (stock locations) do vendedor.

Exemplo de pedido ao agente: “Em quais depósitos eu tenho estoque cadastrado?”

Disponível em: Mercado Livre

Retorno

{ stores<lista ML> }

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). range_from/range_to aceitam AAAA-MM-DD e são ancorados à meia-noite (-0300), então range_to exclui o dia informado.

Exemplo de pedido ao agente: “Liste as reclamações abertas de março, ainda na etapa de reclamação, das mais recentes para as mais antigas.”

Disponível em: Mercado Livre

Retorno

{ data[]<lista ML>, paging, cursor }

search_orders

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

Exemplo de pedido ao agente: “Liste os pedidos pagos de ontem que ainda não foram despachados.”

Disponível em: Mercado Livre

Retorno

{ results[]{id, status, date_created, date_closed, total_amount, paid_amount, currency_id,
            buyer{id, nickname}, items[]{item_id, title, qty, unit_price, gross_price, sale_fee},
            shipping_id, pack_id, tags, cancel_detail, _missing?},
  paging, cursor }

search_seller_items

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

Exemplo de pedido ao agente: “Quais dos meus anúncios ativos estão com estoque zerado?”

Disponível em: Mercado Livre

Retorno

{ item_ids[], paging, cursor }

Escrita (auditadas)

add_order_note

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

Exemplo de pedido ao agente: “Anote no pedido 2000012345678 que o cliente pediu embalagem para presente.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /orders/{order_id}/notes)

answer_question

Responde uma pergunta de pré-venda (máx. 2.000 caracteres).

Exemplo de pedido ao agente: “Responda a pergunta 13000045678 dizendo que o produto tem garantia de um ano.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /answers)

delete_question · destrutiva

Exclui uma pergunta. SEMPRE exige confirm=true.

Exemplo de pedido ao agente: “Exclua a pergunta 13000045678, ela é ofensiva.”

Disponível em: Mercado Livre

Retorno

{ deleted, message }

print_shipping_labels

Obtém etiquetas de envio OFICIAIS do ML (o template nunca é alterado). Máx. 50 envios por chamada, conforme o teto publicado.

Exemplo de pedido ao agente: “Gere as etiquetas dos envios prontos para despachar hoje.”

Disponível em: Mercado Livre

Retorno

{ format, content_base64, shipment_ids[] }

resolve_claim · destrutiva

Resolve uma reclamação pela rota publicada da ação. A ação é validada contra players[].available_actions[] do claim: reclamação sem ação disponível é RECUSADA. SEMPRE exige confirm=true (alto risco).

payload por ação — allow_partial_refund: {“percentage”: N} (um dos valores de /claims/{id}/partial-refund/available-offers; 100% não é permitido aqui, use ‘refund’); send_potential_shipping: {“handling_date”: “AAAA-MM-DD”}; add_shipping_evidence: {“type”, “shipping_method”, …campos condicionais}; return_review: omitido = devolução aprovada, lista [{“reason”,“message”,“attachments”?}] = reprovada. refund/allow_return/open_dispute não levam body.

Exemplo de pedido ao agente: “Reembolse integralmente a reclamação 5200012345.”

Disponível em: Mercado Livre

Retorno

{ claim_id, action, result<resposta ML> }

send_claim_message

Envia mensagem na reclamação (para o reclamante ou mediador). Valida send_message_to_<destinatário> em players[].available_actions[]; em mediação (stage=dispute) só o canal do mediador é permitido.

Exemplo de pedido ao agente: “Responda ao comprador da reclamação 5200012345 pedindo uma foto do defeito.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /post-purchase/v1/claims/{claim_id}/actions/send-message)

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.

Exemplo de pedido ao agente: “Responda o comprador do pedido 2000012345678, que perguntou do prazo: o envio sai amanhã.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /messages/packs/{pack_id}/sellers/{seller_id})

split_shipment · destrutiva

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

Exemplo de pedido ao agente: “Divida o envio 45000067890 em dois pacotes, os itens são frágeis.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /shipments/{shipment_id}/split)

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.

Exemplo de pedido ao agente: “Reduza em dez por cento o preço do anúncio MLB3456789012.”

Disponível em: Mercado Livre

Retorno

{ update?<objeto ML>, deleted?<objeto ML> }
 · update: resposta do PUT /items/{item_id} quando há campo a alterar · deleted: resposta do PUT final quando deleted=true

update_order_note

Atualiza uma nota interna de pedido.

Exemplo de pedido ao agente: “Corrija a nota do pedido 2000012345678: o cliente retira na loja.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (PUT /orders/{order_id}/notes/{note_id})

update_stock · destrutiva

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

Exemplo de pedido ao agente: “Ajuste o estoque do anúncio MLB3456789012 para 40 unidades no depósito principal.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (PUT /user-products/{user_product_id}/stock/type/seller_warehouse)

upload_message_attachment

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

Exemplo de pedido ao agente: “Anexe a nota fiscal em PDF à conversa do pedido 2000012345678.”

Disponível em: Mercado Livre

Retorno

resposta do Mercado Livre sem transformação (POST /messages/attachments)

Meta (grátis)

connection_status

Contas conectadas: apelido, estado, tools bloqueadas. Gratuito.

Sem argumentos lista todas as contas que você alcança — inclusive nenhuma. Com account (ou connector_id) devolve o detalhe de uma conta.

Exemplo de pedido ao agente: “Minhas contas estão conectadas e autorizadas a escrever?”

Disponível em: plataforma (não depende de marketplace)

Retorno

{ status, connector_id, seller_id, site_id, token_expires_at, read_only, require_confirm, plan }
 · status = "ok" | "reconnect_required"

describe_query_schema

Catálogo do DSL query: entidades, campos, operadores, regras de budget. Com entity filtra uma entidade; com marketplace (ex.: ml) acrescenta enums e campos nativos. Gratuito.

Exemplo de pedido ao agente: “Que campos e filtros posso usar na consulta livre de pedidos?”

Disponível em: plataforma (não depende de marketplace)

Retorno

{ query, entities{orders[], order_items[], items[], questions[], claims[]}, filter, aggregate, group_by, budget, rules[], native?{enums{<nome>[]}, fields{…}} }
 · entity informado: entities traz só essa entidade · marketplace informado: native acrescenta enums e campos do marketplace

describe_statuses

Status normalizados: valores canônicos e os nativos de cada marketplace. Sem chamada ao marketplace. Gratuito.

Exemplo de pedido ao agente: “Quais status canônicos existem para pedidos e quais valores nativos do marketplace correspondem a cada um?”

Disponível em: plataforma (não depende de marketplace)

Retorno

{ entities{<entidade>{canonical[], native{<marketplace>{<canônico>: [<nativos>]}}}} }

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

Exemplo de pedido ao agente: “Abra um chamado de suporte: minha conta parou de sincronizar ontem à noite.”

Disponível em: plataforma (não depende de marketplace)

Retorno

{ ticket_id, status, deduped, message }

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.

Exemplo de pedido ao agente: “Sugira ao time do mcplace um filtro de pedidos por transportadora.”

Disponível em: plataforma (não depende de marketplace)

Retorno

{ ticket_id, deduped, message }

whoami

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

Exemplo de pedido ao agente: “Qual conta e qual vendedor é esta conexão?”

Disponível em: Mercado Livre

Retorno

{ id, nickname, site_id, tags, status, connector_id }

página gerada por mcplace_server.docgen · não edite à mão