Pular para o conteúdo principal

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.

FerramentaO que fazTipoAPIEscopo
seller_ads_list_campaignsLista as campanhas do Magalu Ads do seller, com orçamento, lance, datas e statusLeituraListar campanhasopen:ads-campaign-seller:read
seller_ads_get_campaignConsulta uma campanha: orçamento, estratégia de lance, datas e statusLeituraConsultar campanhaopen:ads-campaign-seller:read
seller_ads_list_adsLista os anúncios (um por SKU) de uma campanha, com o status de cada umLeituraListar anúncios da campanhaopen:ads-campaign-seller:read
seller_ads_get_adConsulta um anúncio de uma campanha: SKU e statusLeituraConsultar anúncioopen:ads-campaign-seller:read
seller_ads_get_balanceConsulta o saldo do seller no Magalu Ads, em centavos (ex.: 5000 = R$ 50,00)LeituraConsultar saldoopen:ads-financial-seller:read
seller_ads_create_campaignCria e publica uma campanha de Produto Patrocinado, que passa a gastar o saldo do Magalu AdsEscritaCriar campanha de Produto Patrocinadoopen:ads-campaign-seller:write
seller_ads_add_adsAdiciona anúncios (um por SKU) a uma campanha, todos ou nenhumEscritaAdicionar anúncios em lote à campanhaopen:ads-campaign-seller:write
seller_ads_pause_campaignPausa uma campanha ativa: ela para de veicular e de gastar até ser retomadaEscritaPausar campanhaopen:ads-campaign-seller:write
seller_ads_resume_campaignRetoma uma campanha pausada: ela volta a veicular e a gastar o saldoEscritaRetomar campanhaopen:ads-campaign-seller:write
seller_ads_extend_campaignTroca a data de término da campanha; com mais dias, a campanha gasta por mais tempoEscritaEstender campanhaopen:ads-campaign-seller:write
seller_ads_reschedule_campaignTroca a data de início de uma campanha que ainda não começouEscritaReagendar campanhaopen:ads-campaign-seller:write
seller_ads_finalize_campaignEncerra de vez a veiculação de uma campanha; não dá para retomar depoisEscritaFinalizar campanhaopen:ads-campaign-seller:write
seller_ads_update_budgetTroca o orçamento da campanha, que define quanto ela pode gastarEscritaAtualizar orçamento da campanhaopen:ads-campaign-seller:write
seller_ads_update_default_bidTroca o lance por clique de uma campanha manual_cpcEscritaAtualizar lance padrão da campanhaopen:ads-campaign-seller:write
seller_ads_update_target_roasTroca o ROAS alvo (retorno sobre o gasto) de uma campanha target_roasEscritaAtualizar ROAS alvo da campanhaopen:ads-campaign-seller:write
seller_ads_pause_adPausa um anúncio da campanha: o produto deixa de ser patrocinado até ser retomadoEscritaPausar anúncioopen:ads-campaign-seller:write
seller_ads_resume_adRetoma um anúncio pausado da campanha: o produto volta a ser patrocinadoEscritaRetomar anúncioopen:ads-campaign-seller:write
seller_ads_delete_campaignExclui de vez uma campanha, com todos os anúnciosEscritaExcluir campanhaopen:ads-campaign-seller:write
seller_ads_delete_adExclui de vez um anúncio da campanhaEscritaExcluir anúncioopen:ads-campaign-seller:write

seller:ads_metrics​

Métricas de desempenho das campanhas do Magalu Ads.

FerramentaO que fazTipoAPIEscopo
seller_ads_metrics_get_summaryConsolida o desempenho de todas as campanhas do seller no período (datas inclusivas)LeituraConsultar métricas do selleropen:ads-metrics-seller:read
seller_ads_metrics_list_dailyLista, dia a dia, o desempenho de todas as campanhas do seller no períodoLeituraConsultar métricas diárias do selleropen:ads-metrics-seller:read
seller_ads_metrics_get_campaignConsolida o desempenho de uma campanha no período (datas inclusivas)LeituraConsultar métricas da campanhaopen:ads-metrics-seller:read
seller_ads_metrics_list_campaign_dailyLista, dia a dia, o desempenho de uma campanha no períodoLeituraConsultar métricas diárias da campanhaopen:ads-metrics-seller:read
seller_ads_metrics_list_campaign_productsLista o desempenho de cada produto anunciado numa campanha no períodoLeituraConsultar métricas dos produtos da campanhaopen:ads-metrics-seller:read
seller_ads_metrics_get_campaign_productConsolida o desempenho de um produto dentro de uma campanha no períodoLeituraConsultar métricas de um produto da campanhaopen:ads-metrics-seller:read
seller_ads_metrics_list_campaign_product_dailyLista, dia a dia, o desempenho de um produto dentro de uma campanha no períodoLeituraConsultar métricas diárias de um produto da campanhaopen:ads-metrics-seller:read

seller:categories​

Categorias, atributos e ficha técnica do catálogo.

FerramentaO que fazTipoAPIEscopo
seller_categories_searchBusca categorias do catálogo pelo nome ou IDLeituraConsultar categoriaopen:portfolio-categories-seller:read
seller_categories_get_hierarchyNavega a árvore de categorias: raízes, filhas de uma categoria ou o caminho até elaLeituraConsultar hierarquia de categoriaopen:portfolio-categories-seller:read
seller_categories_list_attributesLista os atributos (ex.: cor, voltagem) que um SKU da categoria pode ou deve terLeituraConsultar atributos de uma categoriaopen:portfolio-categories-seller:read
seller_categories_list_datasheetLista os campos da ficha técnica de uma categoriaLeituraConsultar atributos de ficha técnica de uma categoriaopen:portfolio-categories-seller:read
seller_categories_get_sku_templateMonta o template de cadastro de SKU de uma categoria: atributos e ficha técnicaLeituraConsultar atributos de uma categoriaopen:portfolio-categories-seller:read

seller:chat​

Chat com Cliente: conversas do seller com compradores.

FerramentaO que fazTipoAPIEscopo
seller_chat_list_conversationsLista as conversas de compradores com o seller no Chat com ClienteLeituraBuscar conversasservices:conversations-seller:read
seller_chat_get_conversationConsulta uma conversa: comprador, status, contexto (pedido ou produto) e última mensagemLeituraBuscar conversa por IDservices:conversations-seller:read
seller_chat_list_messagesLista as mensagens de uma conversa, do comprador e do sellerLeituraBuscar mensagensservices:conversations-seller:read
seller_chat_get_messageConsulta uma mensagem de uma conversaLeituraBuscar mensagem por IDsservices:conversations-seller:read
seller_chat_send_messageEnvia uma mensagem do seller ao comprador na conversa; o comprador recebe na horaEscritaResponder mensagemservices:conversations-seller:write
seller_chat_mark_as_readMarca como lidas pelo seller as mensagens de uma conversaEscritaRegistrar leituraservices:conversations-seller:write

seller:customer_service​

Atendimento ao consumidor (SAC) do seller.

FerramentaO que fazTipoAPIEscopo
seller_customer_service_list_ticketsLista os protocolos de atendimento (SAC) abertos por consumidores, pelo canal ou pelo sellerLeituraConsultaropen:tickets-seller:read
seller_customer_service_get_ticketConsulta um protocolo de atendimento: pedido, itens, motivo, status e prazo de respostaLeituraConsultar por IDopen:tickets-seller:read
seller_customer_service_create_ticketAbre um protocolo de atendimento do seller sobre uma entrega, visível ao canal e ao consumidorEscritaCriaropen:tickets-seller:write
seller_customer_service_list_ticket_eventsLista os eventos de devolução registrados num protocolo (envio, reversa, recebimento, reembolso)LeituraConsultaropen:ticket-events-seller:read
seller_customer_service_create_ticket_eventRegistra uma etapa da devolução; authorize_refund libera o reembolso ao consumidor e não pode ser desfeitoEscritaCriaropen:ticket-events-seller:write
seller_customer_service_list_messagesLista a conversa de um protocolo: mensagens do consumidor, do canal e do seller, com anexosLeituraConsultaropen:ticket-messages-seller:read
seller_customer_service_get_messageConsulta uma mensagem de um protocolo, com remetente, destinatário, moderação e anexosLeituraConsultar por IDopen:ticket-messages-seller:read
seller_customer_service_send_messageEnvia uma mensagem no protocolo ao consumidor ou ao canal, com um anexo opcional (JPG, PNG ou PDF até 25 MB)EscritaCriaropen:ticket-messages-seller:write
seller_customer_service_list_returnsLista as remessas reversas (devoluções) solicitadas num protocolo, com o código de postagemLeituraConsultaropen:ticket-returns-seller:read
seller_customer_service_get_returnConsulta uma remessa reversa de um protocolo, com o código de postagemLeituraConsultar por IDopen:ticket-returns-seller:read
seller_customer_service_create_returnSolicita a remessa reversa de um protocolo: gera o código de postagem para o consumidor devolver o produtoEscritaCriaropen:ticket-returns-seller:write
seller_customer_service_list_transactionsLista as transações de SAC do seller num período: o andamento das aberturas, mensagens, eventos e reversasLeituraLista transações com filtros e paginaçãoopen:sac-transaction-seller:read
seller_customer_service_get_transactionConsulta o resultado de uma escrita de SAC (abertura, mensagem, evento ou reversa) pelo transaction_idLeituraBuscar transaçãoopen:sac-transaction-seller:read

seller:financial​

Análise financeira dos pedidos do seller.

FerramentaO que fazTipoAPIEscopo
seller_financial_list_ordersLista a análise financeira dos pedidos: valor vendido, comissão, frete e repasseLeituraConsultaropen:order-financial-report-seller:read
seller_financial_get_orderConsulta o demonstrativo financeiro de um pedidoLeituraConsultar por Pedidoopen:order-financial-report-seller:read

seller:orders​

Pedidos do seller no Marketplace Magalu.

FerramentaO que fazTipoAPIEscopo
seller_orders_searchBusca pedidos do seller aplicando filtros avançadosLeituraConsultaropen:order-order-seller:read
seller_orders_getConsulta os detalhes de um pedido específicoLeituraConsultar por códigoopen:order-order-seller:read
seller_orders_list_deliveriesLista as entregas do seller. Cada pedido pode ter uma ou mais entregasLeituraConsultaropen:order-order-seller:read
seller_orders_get_deliveryConsulta os detalhes de uma entregaLeituraConsultar por IDopen:order-order-seller:read
seller_orders_list_delivery_historyLista o histórico de mudanças de status de uma entregaLeituraConsultar históricoopen:order-order-seller:read
seller_orders_finish_deliveryMarca uma entrega como entregue ao cliente (status delivered). A ação não pode ser desfeitaEscritaMarcar entrega finalizadaopen:order-delivery-seller:write
seller_orders_ship_deliveryMarca uma entrega como despachada (status shipped), com rastreio e previsão de entregaEscritaMarcar entrega enviadaopen:order-delivery-seller:write
seller_orders_list_delivery_invoicesLista as notas fiscais (NF-e) enviadas para uma entregaLeituraBuscar NF-esopen:order-delivery-seller:read
seller_orders_create_delivery_invoiceEnvia a nota fiscal (NF-e) de uma entrega aprovada; a entrega passa a invoicedEscritaEnviar NF-e de entregaopen:order-delivery-seller:write
seller_orders_update_delivery_invoiceSubstitui os dados de uma NF-e já enviada para a entregaEscritaAtualizar NF-e de entregaopen:order-delivery-seller:write
seller_orders_list_fulfillment_invoicesGera o link para baixar as notas fiscais emitidas pela Magalu nas vendas com fulfillmentLeituraBuscar NF-e de fulfillmentopen:order-invoice-seller:read
seller_orders_create_shipping_labelsGera as etiquetas de envio de uma ou mais entregasEscritaGerar etiquetasopen:order-logistics-seller:write

seller:products​

SKUs, preços, estoques e vídeos do seller.

FerramentaO que fazTipoAPIEscopo
seller_products_get_seller_infoRetorna as informações do seller (lojista) autenticadoLeituraConsultar informações do selleropen:portfolio-skus-seller:read
seller_products_list_skusLista os SKUs (produtos) do catálogo do seller com paginaçãoLeituraConsultaropen:portfolio-skus-seller:read
seller_products_create_skuCria um novo SKU no catálogo do sellerEscritaCriaropen:portfolio-skus-seller:write
seller_products_update_skuAtualiza completamente um SKU existente (PUT — substitui todos os campos)EscritaAtualizaropen:portfolio-skus-seller:write
seller_products_get_sku_validation_infoConsulta o último bloqueio ou alerta da política de publicação de um SKULeituraConsultar eventos de políticas de SKUopen:portfolio-skus-seller:read
seller_products_get_priceConsulta o preço atual de um SKULeituraConsultaropen:portfolio-prices-seller:read
seller_products_update_priceAtualiza o preço de um SKU que já tem preço cadastrado. Para o primeiro preço, use seller_products_create_priceEscritaAtualizaropen:portfolio-prices-seller:write
seller_products_get_stockConsulta o estoque atual de um SKULeituraConsultaropen:portfolio-stocks-seller:read
seller_products_create_stockCria o registro de estoque inicial de um SKU em um canalEscritaCriaropen:portfolio-stocks-seller:write
seller_products_update_stockAltera a quantidade à venda de um SKU no marketplace; com 0, o SKU deixa de ser vendido no canalEscritaAtualizaropen:portfolio-stocks-seller:write
seller_products_list_videosLista os vídeos associados a um SKULeituraConsultar vídeos de um produto específicoopen:portfolio-skus-seller:read
seller_products_request_video_uploadInicia o processo de upload de vídeo para um SKUEscritaIniciar processo de upload de vídeoopen:portfolio-skus-seller:write
seller_products_confirm_video_uploadConfirma que o upload do vídeo foi concluído e inicia a validaçãoEscritaConfirmar o upload de um vídeoopen:portfolio-skus-seller:write
seller_products_get_videoConsulta os detalhes e status de um vídeo específicoLeituraConsultar detalhes de um vídeo específicoopen:portfolio-skus-seller:read
seller_products_get_skuConsulta todos os dados cadastrados de um SKULeituraConsultar pelo SKUopen:portfolio-skus-seller:read
seller_products_patch_skuAtualiza só os campos informados de um SKU, sem reenviar o cadastro inteiroEscritaAtualizar (parcial)open:portfolio-skus-seller:write
seller_products_create_priceCadastra o primeiro preço de um SKU em um canal. Para alterar depois, use seller_products_update_priceEscritaCriaropen:portfolio-prices-seller:write
seller_products_list_all_videosLista os vídeos de todo o portfólio do seller, com filtrosLeituraConsultar todos os vídeos do portfólioopen:portfolio-skus-seller:read
seller_products_request_bulk_video_uploadInicia o upload de um vídeo associado a vários SKUs de uma vezEscritaIniciar processo de múltiplos uploads de vídeosopen:portfolio-skus-seller:write
seller_products_list_scoresLista a nota de qualidade do cadastro dos produtos em um canalLeituraConsultaropen:portfolio-scores-seller:read

seller:promotions​

Promoções do seller no Marketplace Magalu.

FerramentaO que fazTipoAPIEscopo
seller_promotions_listLista as promoções do seller, com filtro opcional por status (ex.: ["available"])LeituraConsultar promoções elegíveisopen:promotion-promotions-seller:read
seller_promotions_createCria uma promoção do próprio seller (self service)EscritaCriar promoçãoopen:promotion-promotions-seller:write
seller_promotions_getConsulta os detalhes de uma promoçãoLeituraConsultar detalhes de uma promoçãoopen:promotion-promotions-seller:read
seller_promotions_applyEfetiva as alterações pendentes de SKUs (inclusões, preços e remoções) de uma promoção, com efeito imediatoEscritaAplicar alterações pendentes de uma promoçãoopen:promotion-skus-seller:write
seller_promotions_get_performanceConsulta vendas, investimento e uso de uma promoçãoLeituraConsultar performance de uma promoçãoopen:promotion-promotions-seller:read
seller_promotions_list_skusLista os SKUs do seller que participam de uma promoçãoLeituraConsultar SKUs de uma promoçãoopen:promotion-skus-seller:read
seller_promotions_list_by_skuLista, para um SKU, as promoções em que ele já está e as disponíveis para adesãoLeituraConsultar promoções de um SKUopen:promotion-skus-seller:read
seller_promotions_get_skuConsulta um SKU dentro de uma promoçãoLeituraConsultar SKU de uma promoção por IDopen:promotion-skus-seller:read
seller_promotions_update_skuInclui um SKU na promoção ou altera o preço promocional ou o limite de unidades deleEscritaAtualizar dados de um SKU de uma promoçãoopen:promotion-skus-seller:write
seller_promotions_remove_skuRemove um SKU de uma promoçãoEscritaRemover SKU de uma promoçãoopen:promotion-skus-seller:write
seller_promotions_subscribeInscreve o seller em uma promoção do canalEscritaInscrever-se em uma promoçãoopen:promotion-subscriptions-seller:write
seller_promotions_unsubscribeCancela a inscrição do seller em uma promoçãoEscritaCancelar inscrição em uma promoçãoopen:promotion-subscriptions-seller:write

seller:questions​

Perguntas dos compradores nos anúncios do seller.

FerramentaO que fazTipoAPIEscopo
seller_questions_listLista as perguntas feitas pelos compradores nos anúncios do seller, com a resposta, se houverLeituraConsultarservices:questions-seller:read
seller_questions_getConsulta uma pergunta: produto, texto, status, resposta e resultado da moderaçãoLeituraConsultar por IDservices:questions-seller:read
seller_questions_answerResponde uma pergunta de comprador; depois da moderação, a resposta fica pública no anúncioEscritaResponder perguntaservices:questions-seller:write

seller:vehicles​

Compatibilidade de autopeças com veículos.

FerramentaO que fazTipoAPIEscopo
seller_vehicles_list_manufacturersLista os fabricantes de veículos. Primeiro passo para chegar à versão do veículoLeituraConsultar fabricantesopen:portfolio-vehicles-seller:read
seller_vehicles_list_modelsLista os modelos de um fabricanteLeituraConsultar modelosopen:portfolio-vehicles-seller:read
seller_vehicles_list_yearsLista os anos disponíveis de um modeloLeituraConsultar anos do modeloopen:portfolio-vehicles-seller:read
seller_vehicles_list_versionsLista as versões de um modelo em um ano. O ID da versão é o que entra na compatibilidadeLeituraConsultar versõesopen:portfolio-vehicles-seller:read
seller_vehicles_add_compatibilitiesAdiciona versões de veículos compatíveis com uma autopeça (SKU)EscritaCriar compatibilidadesopen:portfolio-vehicles-compatibility-seller:write
seller_vehicles_replace_compatibilitiesSubstitui toda a lista de veículos compatíveis de uma autopeça (SKU)EscritaAtualizar compatibilidadesopen:portfolio-vehicles-compatibility-seller:write
seller_vehicles_remove_compatibilitiesRemove todas as compatibilidades de veículos de uma autopeça (SKU)EscritaRemover compatibilidadesopen:portfolio-vehicles-compatibility-seller:write

Ferramentas do servidor​

Estas aparecem para qualquer conta e não chamam APIs da loja.

FerramentaO que faz
magalu_list_modulesLista os toolsets que o token permite usar
magalu_list_channelsLista 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_toolsetDescoberta de toolsets no modo dinâmico. Veja Para desenvolvedores