Pular para conteúdo

Catálogo de tools

O servidor tem 22 tools: 16 de consulta, descritas nesta página, e 6 de alteração (preço, estoque, produto, anúncio, etiquetas e nota fiscal), que funcionam em dois passos e estão em Alterações pelo MCP. A fonte de verdade é a resposta de tools/list no próprio servidor — esta página descreve o mesmo catálogo em prosa, com as armadilhas que a descrição de cada tool não tem espaço para explicar.

Convenções

Valem para todas as tools.

  • Nomes de argumento são camelCase: startDate, marketplaceId, includeCustomerData.
  • Argumento não declarado é recusado, com a lista dos nomes não reconhecidos. Nada é ignorado em silêncio.
  • Paginação: limit (padrão 10, teto 50) e page (começa em 0). A resposta informa o total e como pedir o restante.
  • Datas: AAAA-MM-DD, inclusivas, interpretadas no fuso do lojista (America/Sao_Paulo). As datas devolvidas saem no mesmo fuso.
  • Códigos de canal: use list_channels para descobrir os aceitos. Escrever um código que o lojista não tem não devolve dado de outro canal.
  • O lojista é o do token. Nenhuma tool aceita identificador de lojista.

Catálogo de produtos

Tool O que responde Argumentos
search_products Lista produtos do catálogo por título, EAN, SKU, marca, categoria ou situação. Sem critério nenhum, lista o catálogo paginado — é a resposta para "quais produtos eu tenho?" query, name, sku, ean, brand, category, status, limit, page
get_product O produto completo em uma chamada: nome, situação, categoria, marca, atributos, e por variação o SKU, os EANs (o principal e os demais), os atributos e as imagens productId (obrigatório)

brand e category recebem o nome, não o identificador interno — a tool resolve o nome antes de buscar. get_product exige o productId: se você só tem nome, EAN ou SKU, chame search_products antes para descobri-lo.

Uma variação pode ter mais de um EAN (a lista eans da API, com um principal). O filtro ean de search_products casa com qualquer EAN de qualquer variação do produto; a linha do resultado mostra só o EAN principal e, quando há outros, a quantidade (+2 EANs). get_product mostra o principal e lista os demais em "outros EANs".

get_product não traz estoque por armazém nem preço por canal

O produto traz o cadastro. A posição de estoque por armazém vem de get_stock e o preço por canal, de get_prices.

Anúncios

Tool O que responde Argumentos
search_ads Anúncios do lojista num canal, com o adId de cada um channel (obrigatório), sku, marketplaceId, name, ean, status, limit, page
get_ad O anúncio completo: canal, situação, link, preço padrão e promocionais, estoque por armazém, categoria, EANs (o principal e os demais), atributos e variações adId (obrigatório)
export_ads Os anúncios de um canal em formato de planilha: uma linha por anúncio com SKU, nome, situação, preço, estoque, id no marketplace e link channel (obrigatório), limit, page
get_catalog_status Se o anúncio está em catálogo no canal, se está pendente de match, ou se não foi possível saber adId (obrigatório)

status aqui é a situação no Gubee, não no canal: ACTIVE, INACTIVE, PAUSED ou FINISHED.

Todos os filtros de anúncio (sku, marketplaceId, ean, name e status) consultam o catálogo inteiro e devolvem o mesmo total que a tela de anúncios do painel.

O anúncio também pode ter mais de um EAN: o filtro ean de search_ads casa com qualquer um deles, e get_ad mostra o principal em "EAN" e os demais em "Outros EANs".

Em get_ad, situação de integração ausente não é situação limpa

A situação de integração no canal é consultada em tempo real, numa chamada separada, e pode falhar (permissão insuficiente na credencial, ou canal fora do ar). Quando falha, a resposta declara que não foi possível consultar. Isso nunca deve ser lido como "sem erros".

Três identificadores diferentes convivem aqui: o adId é o identificador Gubee do anúncio (o que get_ad exige), o marketplaceId é o código no canal (MLB5183719235, o que aparece no link do anúncio), e o sku é o código da variação escrito pelo lojista.

Estoque e preço

Tool O que responde Argumentos
get_stock Posição de estoque de um SKU por armazém: total, reservado e disponível em cada um, mais o disponível consolidado sku (obrigatório)
get_prices O preço de/por de um SKU. Sem channel, uma visão por plataforma; com channel, o preço padrão, o promocional vigente e as promoções agendadas com datas sku (obrigatório), channel

O sku das duas é o código cadastrado pelo lojista — não é o productId, não é o skuId interno e não é o EAN.

get_ad já traz o preço padrão e os promocionais do anúncio. Use get_prices quando precisar do de/por por canal, inclusive as promoções agendadas.

Pedidos

Tool O que responde Argumentos
search_orders Pedidos do lojista, do mais recente para o mais antigo, com o identificador de cada um status, channel, sku, startDate, endDate, limit, page
get_order O pedido completo: identificação, canal, situação atual e anterior, datas, itens, totais, envio, remessas com rastreio, linha do tempo e notas fiscais orderId (obrigatório), includeCustomerData
export_orders Pedidos em formato de planilha: número, canal, data, situação, valor, quantidade e destino (cidade/UF) channel, status, startDate, endDate, limit, page

Situações aceitas em status: CREATED, PAYED, INVOICED, SHIPPED, DELIVERED, CONCLUDED, RETURNED, CANCELED e SHIPMENT_EXCEPTION.

orderId é o identificador interno, não o número do pedido no marketplace

get_order aceita o identificador que search_orders devolve. Não existe endpoint para resolver o número do canal para o identificador interno — se o lojista só tem o número do marketplace, busque por período ou canal e localize o pedido na lista.

Dados do comprador

Por padrão get_order devolve o nome do comprador reduzido, documento e contato mascarados e o endereço só com cidade e UF. includeCustomerData traz o dado completo e cada uso fica registrado em auditoria. Ligue apenas quando o lojista pedir explicitamente o dado do consumidor final. A partir de 26/12/2026, o dado completo exige que a conexão tenha a permissão de dados do comprador (Permissões dos apps); sem ela, a resposta vem mascarada e diz o motivo.

search_orders não devolve dado do comprador em nenhuma hipótese.

Notas fiscais

Tool O que responde Argumentos
get_invoices A situação de cada nota fiscal de um pedido: tipo, plataforma, data de emissão e a situação mais recente, com as mensagens de erro quando houver orderId (obrigatório), includeDownloadLink

get_order já lista as notas associadas ao pedido. Use get_invoices quando precisar da situação detalhada de uma nota ou do link de download.

O conceito e o ciclo de vida da nota estão em Notas Fiscais e DANFE.

Canais e campanhas

Tool O que responde Argumentos
list_channels Em quais canais o lojista realmente vende. Os códigos devolvidos são exatamente os aceitos no argumento channel das outras tools channel
list_campaigns Campanhas e promoções de um canal das quais o lojista participa ou pode participar: nome, situação, tipo e período channel (obrigatório), status, limit, page

Informe o canal quando já souber qual

list_channels com channel custa uma consulta. Sem argumento, consulta todos os canais suportados de uma vez — mais lento e mais caro.

Promoções e ajustes de preço estão detalhados em Promoções / Ajustes de Preço.

Diagnóstico

Tool O que responde Argumentos
list_integration_issues Por que os produtos do lojista não estão publicados em cada canal: a situação de integração por canal e os erros que o marketplace reportou channel, includeHealthy, limit, page
list_import_errors Por que uma importação de anúncios de um canal não trouxe tudo channel, importId, limit, page

list_integration_issues é o ponto de partida para "por que meu produto não subiu?". Por padrão mostra apenas o que tem problema; includeHealthy inclui também os canais sem pendência.

Alteração

As tools abaixo alteram a conta do lojista. Nenhuma escreve na primeira chamada: a primeira devolve o antes → depois e um código confirmation, e só a segunda chamada, com o código e depois da aprovação do lojista, aplica. O fluxo, as recusas e os erros estão em Alterações pelo MCP.

Tool O que altera Argumentos Permissão
update_price O preço padrão (o "de") de um anúncio. Não altera preço promocional adId, price, confirmation price:edit
update_stock A quantidade total de um SKU num armazém, por movimentação sku, quantity, warehouseId, confirmation stock:edit
update_product Nome, descrição e valores de atributos de um produto. Preço e estoque não mudam productId, name, description, attributes, confirmation product:edit
update_ad Título e descrição de um anúncio, só naquele canal e conta adId, title, description, confirmation ad:edit
manage_ad_tags Adiciona ou remove etiquetas de um anúncio; reenvia o anúncio ao canal adId, operation, tags, confirmation ad:edit
issue_invoice Emite a NF-e de venda de um pedido pago orderId, confirmation invoice:issue

Nenhuma tool de alteração edita EAN: update_product e update_ad não têm argumento ean nem eans, e a lista de EANs do produto fica como estava depois de um update_product.

Próximos passos