Referência de ferramentas
Esta página lista as ferramentas que o servidor MCP oferece para sellers, agrupadas por toolset. Para cada uma, você encontra:
- Tipo: se a ferramenta só consulta dados (Leitura) ou se altera dados na loja (Escrita);
- API: a operação da API que a ferramenta chama, com link para a referência completa (parâmetros, respostas e erros);
- Escopo: a permissão do ID Magalu que a ferramenta exige. Se o token não tiver esse escopo, a ferramenta não aparece para o assistente.
O nome de cada toolset indica a visão e o assunto: seller:orders reúne as ferramentas de pedidos para quem vende.
Ferramentas para sellers
seller:ads
Campanhas, anúncios e saldo do Magalu Ads.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_ads_list_campaigns | Lista as campanhas do Magalu Ads do seller, com orçamento, lance, datas e status | Leitura | Listar campanhas | open:ads-campaign-seller:read |
seller_ads_get_campaign | Consulta uma campanha: orçamento, estratégia de lance, datas e status | Leitura | Consultar campanha | open:ads-campaign-seller:read |
seller_ads_list_ads | Lista os anúncios (um por SKU) de uma campanha, com o status de cada um | Leitura | Listar anúncios da campanha | open:ads-campaign-seller:read |
seller_ads_get_ad | Consulta um anúncio de uma campanha: SKU e status | Leitura | Consultar anúncio | open:ads-campaign-seller:read |
seller_ads_get_balance | Consulta o saldo do seller no Magalu Ads, em centavos (ex.: 5000 = R$ 50,00) | Leitura | Consultar saldo | open:ads-financial-seller:read |
seller_ads_create_campaign | Cria e publica uma campanha de Produto Patrocinado, que passa a gastar o saldo do Magalu Ads | Escrita | Criar campanha de Produto Patrocinado | open:ads-campaign-seller:write |
seller_ads_add_ads | Adiciona anúncios (um por SKU) a uma campanha, todos ou nenhum | Escrita | Adicionar anúncios em lote à campanha | open:ads-campaign-seller:write |
seller_ads_pause_campaign | Pausa uma campanha ativa: ela para de veicular e de gastar até ser retomada | Escrita | Pausar campanha | open:ads-campaign-seller:write |
seller_ads_resume_campaign | Retoma uma campanha pausada: ela volta a veicular e a gastar o saldo | Escrita | Retomar campanha | open:ads-campaign-seller:write |
seller_ads_extend_campaign | Troca a data de término da campanha; com mais dias, a campanha gasta por mais tempo | Escrita | Estender campanha | open:ads-campaign-seller:write |
seller_ads_reschedule_campaign | Troca a data de início de uma campanha que ainda não começou | Escrita | Reagendar campanha | open:ads-campaign-seller:write |
seller_ads_finalize_campaign | Encerra de vez a veiculação de uma campanha; não dá para retomar depois | Escrita | Finalizar campanha | open:ads-campaign-seller:write |
seller_ads_update_budget | Troca o orçamento da campanha, que define quanto ela pode gastar | Escrita | Atualizar orçamento da campanha | open:ads-campaign-seller:write |
seller_ads_update_default_bid | Troca o lance por clique de uma campanha manual_cpc | Escrita | Atualizar lance padrão da campanha | open:ads-campaign-seller:write |
seller_ads_update_target_roas | Troca o ROAS alvo (retorno sobre o gasto) de uma campanha target_roas | Escrita | Atualizar ROAS alvo da campanha | open:ads-campaign-seller:write |
seller_ads_pause_ad | Pausa um anúncio da campanha: o produto deixa de ser patrocinado até ser retomado | Escrita | Pausar anúncio | open:ads-campaign-seller:write |
seller_ads_resume_ad | Retoma um anúncio pausado da campanha: o produto volta a ser patrocinado | Escrita | Retomar anúncio | open:ads-campaign-seller:write |
seller_ads_delete_campaign | Exclui de vez uma campanha, com todos os anúncios | Escrita | Excluir campanha | open:ads-campaign-seller:write |
seller_ads_delete_ad | Exclui de vez um anúncio da campanha | Escrita | Excluir anúncio | open:ads-campaign-seller:write |
seller:ads_metrics
Métricas de desempenho das campanhas do Magalu Ads.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_ads_metrics_get_summary | Consolida o desempenho de todas as campanhas do seller no período (datas inclusivas) | Leitura | Consultar métricas do seller | open:ads-metrics-seller:read |
seller_ads_metrics_list_daily | Lista, dia a dia, o desempenho de todas as campanhas do seller no período | Leitura | Consultar métricas diárias do seller | open:ads-metrics-seller:read |
seller_ads_metrics_get_campaign | Consolida o desempenho de uma campanha no período (datas inclusivas) | Leitura | Consultar métricas da campanha | open:ads-metrics-seller:read |
seller_ads_metrics_list_campaign_daily | Lista, dia a dia, o desempenho de uma campanha no período | Leitura | Consultar métricas diárias da campanha | open:ads-metrics-seller:read |
seller_ads_metrics_list_campaign_products | Lista o desempenho de cada produto anunciado numa campanha no período | Leitura | Consultar métricas dos produtos da campanha | open:ads-metrics-seller:read |
seller_ads_metrics_get_campaign_product | Consolida o desempenho de um produto dentro de uma campanha no período | Leitura | Consultar métricas de um produto da campanha | open:ads-metrics-seller:read |
seller_ads_metrics_list_campaign_product_daily | Lista, dia a dia, o desempenho de um produto dentro de uma campanha no período | Leitura | Consultar métricas diárias de um produto da campanha | open:ads-metrics-seller:read |
seller:categories
Categorias, atributos e ficha técnica do catálogo.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_categories_search | Busca categorias do catálogo pelo nome ou ID | Leitura | Consultar categoria | open:portfolio-categories-seller:read |
seller_categories_get_hierarchy | Navega a árvore de categorias: raízes, filhas de uma categoria ou o caminho até ela | Leitura | Consultar hierarquia de categoria | open:portfolio-categories-seller:read |
seller_categories_list_attributes | Lista os atributos (ex.: cor, voltagem) que um SKU da categoria pode ou deve ter | Leitura | Consultar atributos de uma categoria | open:portfolio-categories-seller:read |
seller_categories_list_datasheet | Lista os campos da ficha técnica de uma categoria | Leitura | Consultar atributos de ficha técnica de uma categoria | open:portfolio-categories-seller:read |
seller_categories_get_sku_template | Monta o template de cadastro de SKU de uma categoria: atributos e ficha técnica | Leitura | Consultar atributos de uma categoria | open:portfolio-categories-seller:read |
seller:chat
Chat com Cliente: conversas do seller com compradores.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_chat_list_conversations | Lista as conversas de compradores com o seller no Chat com Cliente | Leitura | Buscar conversas | services:conversations-seller:read |
seller_chat_get_conversation | Consulta uma conversa: comprador, status, contexto (pedido ou produto) e última mensagem | Leitura | Buscar conversa por ID | services:conversations-seller:read |
seller_chat_list_messages | Lista as mensagens de uma conversa, do comprador e do seller | Leitura | Buscar mensagens | services:conversations-seller:read |
seller_chat_get_message | Consulta uma mensagem de uma conversa | Leitura | Buscar mensagem por IDs | services:conversations-seller:read |
seller_chat_send_message | Envia uma mensagem do seller ao comprador na conversa; o comprador recebe na hora | Escrita | Responder mensagem | services:conversations-seller:write |
seller_chat_mark_as_read | Marca como lidas pelo seller as mensagens de uma conversa | Escrita | Registrar leitura | services:conversations-seller:write |
seller:customer_service
Atendimento ao consumidor (SAC) do seller.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_customer_service_list_tickets | Lista os protocolos de atendimento (SAC) abertos por consumidores, pelo canal ou pelo seller | Leitura | Consultar | open:tickets-seller:read |
seller_customer_service_get_ticket | Consulta um protocolo de atendimento: pedido, itens, motivo, status e prazo de resposta | Leitura | Consultar por ID | open:tickets-seller:read |
seller_customer_service_create_ticket | Abre um protocolo de atendimento do seller sobre uma entrega, visível ao canal e ao consumidor | Escrita | Criar | open:tickets-seller:write |
seller_customer_service_list_ticket_events | Lista os eventos de devolução registrados num protocolo (envio, reversa, recebimento, reembolso) | Leitura | Consultar | open:ticket-events-seller:read |
seller_customer_service_create_ticket_event | Registra uma etapa da devolução; authorize_refund libera o reembolso ao consumidor e não pode ser desfeito | Escrita | Criar | open:ticket-events-seller:write |
seller_customer_service_list_messages | Lista a conversa de um protocolo: mensagens do consumidor, do canal e do seller, com anexos | Leitura | Consultar | open:ticket-messages-seller:read |
seller_customer_service_get_message | Consulta uma mensagem de um protocolo, com remetente, destinatário, moderação e anexos | Leitura | Consultar por ID | open:ticket-messages-seller:read |
seller_customer_service_send_message | Envia uma mensagem no protocolo ao consumidor ou ao canal, com um anexo opcional (JPG, PNG ou PDF até 25 MB) | Escrita | Criar | open:ticket-messages-seller:write |
seller_customer_service_list_returns | Lista as remessas reversas (devoluções) solicitadas num protocolo, com o código de postagem | Leitura | Consultar | open:ticket-returns-seller:read |
seller_customer_service_get_return | Consulta uma remessa reversa de um protocolo, com o código de postagem | Leitura | Consultar por ID | open:ticket-returns-seller:read |
seller_customer_service_create_return | Solicita a remessa reversa de um protocolo: gera o código de postagem para o consumidor devolver o produto | Escrita | Criar | open:ticket-returns-seller:write |
seller_customer_service_list_transactions | Lista as transações de SAC do seller num período: o andamento das aberturas, mensagens, eventos e reversas | Leitura | Lista transações com filtros e paginação | open:sac-transaction-seller:read |
seller_customer_service_get_transaction | Consulta o resultado de uma escrita de SAC (abertura, mensagem, evento ou reversa) pelo transaction_id | Leitura | Buscar transação | open:sac-transaction-seller:read |
seller:financial
Análise financeira dos pedidos do seller.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_financial_list_orders | Lista a análise financeira dos pedidos: valor vendido, comissão, frete e repasse | Leitura | Consultar | open:order-financial-report-seller:read |
seller_financial_get_order | Consulta o demonstrativo financeiro de um pedido | Leitura | Consultar por Pedido | open:order-financial-report-seller:read |
seller:orders
Pedidos do seller no Marketplace Magalu.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_orders_search | Busca pedidos do seller aplicando filtros avançados | Leitura | Consultar | open:order-order-seller:read |
seller_orders_get | Consulta os detalhes de um pedido específico | Leitura | Consultar por código | open:order-order-seller:read |
seller_orders_list_deliveries | Lista as entregas do seller. Cada pedido pode ter uma ou mais entregas | Leitura | Consultar | open:order-order-seller:read |
seller_orders_get_delivery | Consulta os detalhes de uma entrega | Leitura | Consultar por ID | open:order-order-seller:read |
seller_orders_list_delivery_history | Lista o histórico de mudanças de status de uma entrega | Leitura | Consultar histórico | open:order-order-seller:read |
seller_orders_finish_delivery | Marca uma entrega como entregue ao cliente (status delivered). A ação não pode ser desfeita | Escrita | Marcar entrega finalizada | open:order-delivery-seller:write |
seller_orders_ship_delivery | Marca uma entrega como despachada (status shipped), com rastreio e previsão de entrega | Escrita | Marcar entrega enviada | open:order-delivery-seller:write |
seller_orders_list_delivery_invoices | Lista as notas fiscais (NF-e) enviadas para uma entrega | Leitura | Buscar NF-es | open:order-delivery-seller:read |
seller_orders_create_delivery_invoice | Envia a nota fiscal (NF-e) de uma entrega aprovada; a entrega passa a invoiced | Escrita | Enviar NF-e de entrega | open:order-delivery-seller:write |
seller_orders_update_delivery_invoice | Substitui os dados de uma NF-e já enviada para a entrega | Escrita | Atualizar NF-e de entrega | open:order-delivery-seller:write |
seller_orders_list_fulfillment_invoices | Gera o link para baixar as notas fiscais emitidas pela Magalu nas vendas com fulfillment | Leitura | Buscar NF-e de fulfillment | open:order-invoice-seller:read |
seller_orders_create_shipping_labels | Gera as etiquetas de envio de uma ou mais entregas | Escrita | Gerar etiquetas | open:order-logistics-seller:write |
seller:products
SKUs, preços, estoques e vídeos do seller.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_products_get_seller_info | Retorna as informações do seller (lojista) autenticado | Leitura | Consultar informações do seller | open:portfolio-skus-seller:read |
seller_products_list_skus | Lista os SKUs (produtos) do catálogo do seller com paginação | Leitura | Consultar | open:portfolio-skus-seller:read |
seller_products_create_sku | Cria um novo SKU no catálogo do seller | Escrita | Criar | open:portfolio-skus-seller:write |
seller_products_update_sku | Atualiza completamente um SKU existente (PUT — substitui todos os campos) | Escrita | Atualizar | open:portfolio-skus-seller:write |
seller_products_get_sku_validation_info | Consulta o último bloqueio ou alerta da política de publicação de um SKU | Leitura | Consultar eventos de políticas de SKU | open:portfolio-skus-seller:read |
seller_products_get_price | Consulta o preço atual de um SKU | Leitura | Consultar | open:portfolio-prices-seller:read |
seller_products_update_price | Atualiza o preço de um SKU que já tem preço cadastrado. Para o primeiro preço, use seller_products_create_price | Escrita | Atualizar | open:portfolio-prices-seller:write |
seller_products_get_stock | Consulta o estoque atual de um SKU | Leitura | Consultar | open:portfolio-stocks-seller:read |
seller_products_create_stock | Cria o registro de estoque inicial de um SKU em um canal | Escrita | Criar | open:portfolio-stocks-seller:write |
seller_products_update_stock | Altera a quantidade à venda de um SKU no marketplace; com 0, o SKU deixa de ser vendido no canal | Escrita | Atualizar | open:portfolio-stocks-seller:write |
seller_products_list_videos | Lista os vídeos associados a um SKU | Leitura | Consultar vídeos de um produto específico | open:portfolio-skus-seller:read |
seller_products_request_video_upload | Inicia o processo de upload de vídeo para um SKU | Escrita | Iniciar processo de upload de vídeo | open:portfolio-skus-seller:write |
seller_products_confirm_video_upload | Confirma que o upload do vídeo foi concluído e inicia a validação | Escrita | Confirmar o upload de um vídeo | open:portfolio-skus-seller:write |
seller_products_get_video | Consulta os detalhes e status de um vídeo específico | Leitura | Consultar detalhes de um vídeo específico | open:portfolio-skus-seller:read |
seller_products_get_sku | Consulta todos os dados cadastrados de um SKU | Leitura | Consultar pelo SKU | open:portfolio-skus-seller:read |
seller_products_patch_sku | Atualiza só os campos informados de um SKU, sem reenviar o cadastro inteiro | Escrita | Atualizar (parcial) | open:portfolio-skus-seller:write |
seller_products_create_price | Cadastra o primeiro preço de um SKU em um canal. Para alterar depois, use seller_products_update_price | Escrita | Criar | open:portfolio-prices-seller:write |
seller_products_list_all_videos | Lista os vídeos de todo o portfólio do seller, com filtros | Leitura | Consultar todos os vídeos do portfólio | open:portfolio-skus-seller:read |
seller_products_request_bulk_video_upload | Inicia o upload de um vídeo associado a vários SKUs de uma vez | Escrita | Iniciar processo de múltiplos uploads de vídeos | open:portfolio-skus-seller:write |
seller_products_list_scores | Lista a nota de qualidade do cadastro dos produtos em um canal | Leitura | Consultar | open:portfolio-scores-seller:read |
seller:promotions
Promoções do seller no Marketplace Magalu.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_promotions_list | Lista as promoções do seller, com filtro opcional por status (ex.: ["available"]) | Leitura | Consultar promoções elegíveis | open:promotion-promotions-seller:read |
seller_promotions_create | Cria uma promoção do próprio seller (self service) | Escrita | Criar promoção | open:promotion-promotions-seller:write |
seller_promotions_get | Consulta os detalhes de uma promoção | Leitura | Consultar detalhes de uma promoção | open:promotion-promotions-seller:read |
seller_promotions_apply | Efetiva as alterações pendentes de SKUs (inclusões, preços e remoções) de uma promoção, com efeito imediato | Escrita | Aplicar alterações pendentes de uma promoção | open:promotion-skus-seller:write |
seller_promotions_get_performance | Consulta vendas, investimento e uso de uma promoção | Leitura | Consultar performance de uma promoção | open:promotion-promotions-seller:read |
seller_promotions_list_skus | Lista os SKUs do seller que participam de uma promoção | Leitura | Consultar SKUs de uma promoção | open:promotion-skus-seller:read |
seller_promotions_list_by_sku | Lista, para um SKU, as promoções em que ele já está e as disponíveis para adesão | Leitura | Consultar promoções de um SKU | open:promotion-skus-seller:read |
seller_promotions_get_sku | Consulta um SKU dentro de uma promoção | Leitura | Consultar SKU de uma promoção por ID | open:promotion-skus-seller:read |
seller_promotions_update_sku | Inclui um SKU na promoção ou altera o preço promocional ou o limite de unidades dele | Escrita | Atualizar dados de um SKU de uma promoção | open:promotion-skus-seller:write |
seller_promotions_remove_sku | Remove um SKU de uma promoção | Escrita | Remover SKU de uma promoção | open:promotion-skus-seller:write |
seller_promotions_subscribe | Inscreve o seller em uma promoção do canal | Escrita | Inscrever-se em uma promoção | open:promotion-subscriptions-seller:write |
seller_promotions_unsubscribe | Cancela a inscrição do seller em uma promoção | Escrita | Cancelar inscrição em uma promoção | open:promotion-subscriptions-seller:write |
seller:questions
Perguntas dos compradores nos anúncios do seller.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_questions_list | Lista as perguntas feitas pelos compradores nos anúncios do seller, com a resposta, se houver | Leitura | Consultar | services:questions-seller:read |
seller_questions_get | Consulta uma pergunta: produto, texto, status, resposta e resultado da moderação | Leitura | Consultar por ID | services:questions-seller:read |
seller_questions_answer | Responde uma pergunta de comprador; depois da moderação, a resposta fica pública no anúncio | Escrita | Responder pergunta | services:questions-seller:write |
seller:vehicles
Compatibilidade de autopeças com veículos.
| Ferramenta | O que faz | Tipo | API | Escopo |
|---|---|---|---|---|
seller_vehicles_list_manufacturers | Lista os fabricantes de veículos. Primeiro passo para chegar à versão do veículo | Leitura | Consultar fabricantes | open:portfolio-vehicles-seller:read |
seller_vehicles_list_models | Lista os modelos de um fabricante | Leitura | Consultar modelos | open:portfolio-vehicles-seller:read |
seller_vehicles_list_years | Lista os anos disponíveis de um modelo | Leitura | Consultar anos do modelo | open:portfolio-vehicles-seller:read |
seller_vehicles_list_versions | Lista as versões de um modelo em um ano. O ID da versão é o que entra na compatibilidade | Leitura | Consultar versões | open:portfolio-vehicles-seller:read |
seller_vehicles_add_compatibilities | Adiciona versões de veículos compatíveis com uma autopeça (SKU) | Escrita | Criar compatibilidades | open:portfolio-vehicles-compatibility-seller:write |
seller_vehicles_replace_compatibilities | Substitui toda a lista de veículos compatíveis de uma autopeça (SKU) | Escrita | Atualizar compatibilidades | open:portfolio-vehicles-compatibility-seller:write |
seller_vehicles_remove_compatibilities | Remove todas as compatibilidades de veículos de uma autopeça (SKU) | Escrita | Remover compatibilidades | open:portfolio-vehicles-compatibility-seller:write |
Ferramentas do servidor
Estas aparecem para qualquer conta e não chamam APIs da loja.
| Ferramenta | O que faz |
|---|---|
magalu_list_modules | Lista os toolsets que o token permite usar |
magalu_list_channels | Lista os canais de venda da loja, com o ID que o assistente usa em preço, estoque, cadastro e promoções. Só no servidor de sellers |
list_toolsets, get_toolset_tools, enable_toolset | Descoberta de toolsets no modo dinâmico. Veja Para desenvolvedores |