Desenvolvedores

Assistentes de IA (MCP)

Conecte o Claude, o ChatGPT ou o Cursor à sua conta NinjaBuy e pergunte com as suas palavras: onde está um pedido, o que há na sua prateleira, se vale a pena vender um anúncio, e coloque-o na sua loja.

Nesta página

1Conectar
2Login e acesso
3Nada aqui gasta dinheiro
4Ferramentas
5O que perguntar

Conectar

Um endereço de servidor para todos os assistentes. Você entra com a sua conta NinjaBuy; não há chave para colar.

https://www.ninjabuy.com/mcp

Claude

Abra Settings › Connectors e escolha Add custom connector.
Cole o endereço acima e adicione.
Entre com o seu número de celular da NinjaBuy e depois escolha Permitir acesso.

ChatGPT

Ative o modo desenvolvedor em Settings e depois adicione um servidor MCP personalizado.
Cole o endereço acima e escolha OAuth como login.
Entre com o seu número de celular da NinjaBuy e depois escolha Permitir acesso.

Cursor

Adicione o servidor em Cursor Settings › MCP, ou em ~/.cursor/mcp.json. Na primeira vez, o Cursor abre o login da NinjaBuy no seu navegador.

~/.cursor/mcp.json

{
  "mcpServers": {
    "ninjabuy": {
      "url": "https://www.ninjabuy.com/mcp"
    }
  }
}

Claude Code e outros assistentes de linha de comando

Terminal

claude mcp add --transport http ninjabuy https://www.ninjabuy.com/mcp

Os nomes dos menus mudam conforme os assistentes são atualizados; procure “custom connector” ou “custom MCP server”.

O assistente faz login com OAuth 2.1: ele se registra, envia você ao ninjabuy.com, e você o aprova na nossa própria tela, que mostra o nome do app e para onde ele vai levar você de volta. Só permita um app que você acabou de pedir para conectar. Você aprova cada app uma vez.

Ele age como a sua conta: as ferramentas não recebem um id de conta e só veem os seus pedidos, a sua prateleira e os seus produtos.
O acesso dura uma hora e é renovado por sete dias; depois o assistente pede que você entre de novo.
Remova o conector no seu assistente para desconectá-lo.
As ferramentas que leem um marketplace (product, analyze_product, import_product, push_to_shopify) compartilham a janela de 30 por minuto da API: Limites de requisições.

Nada aqui gasta dinheiro

Nenhuma ferramenta paga, cria um envio ou gasta o seu saldo. Quando algo precisa ser pago, a resposta indica a página onde fazer isso: o checkout pelo carrinho, o envio pela página do seu armazém. push_to_shopify anuncia um produto como rascunho, então nada entra à venda até você publicar.

Ferramentas

Toda resposta traz requestId (informe-o quando nos escrever) e warnings, coisas que vale saber e que não interromperam a chamada. Uma resposta longa é cortada em cerca de 6.000 tokens com truncated: true; as listas então usam um limite menor.

Ferramenta	O que faz
list_orders	Listar os meus pedidos da NinjaBuy
order	Um pedido da NinjaBuy
warehouse	O meu armazém na NinjaBuy
product	Ler as variantes de um produto
add_to_cart	Adicionar ao meu carrinho da NinjaBuy
search_products	Pesquisar produtos
analyze_product	Analisar um produto
import_product	Importar um produto
push_to_shopify	Enviar para a Shopify
list_synced_products	Listar os meus produtos sincronizados
set_sync_rule	Definir uma regra de sincronização

`list_orders`somente leitura

Os pedidos da conta, dos mais recentes aos mais antigos: status, status do pagamento, o que ainda está pendente, os itens e a página de cada pedido. Siga cursor enquanto has_more for true.

cursorstring?: Da resposta anterior; omita na primeira página.
limitnumber?: De 1 a 25. 25 se omitido.

list_orders responde

{
  "orders": [
    {
      "id": "j57a9x2b",
      "number": 1012,
      "kind": "procurement",
      "total": "¥57.00",
      "orderStatus": { "status": "ordered" },
      "paymentStatus": { "status": "paid" },
      "amountDue": null,
      "itemCount": 1,
      "items": [
        {
          "id": "P1012-1",
          "title": "Heavyweight washed hoodie",
          "quantity": 1,
          "options": ["Black", "M"],
          "status": "ordered"
        }
      ],
      "url": "https://www.ninjabuy.com/me/orders/j57a9x2b"
    }
  ],
  "cursor": "eyJvIjoyNX0",
  "has_more": true,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`order`somente leitura

Um pedido por id: as linhas e os preços, o status de cada item e quantos chegaram, e o envio com rastreio. order é null para um id que não é desta conta.

idstringobrigatório: Um id de list_orders.

order responde

{
  "order": {
    "id": "j57c4k1m",
    "number": 1019,
    "kind": "shipout",
    "orderStatus": { "status": "ready" },
    "paymentStatus": { "status": "paid" },
    "shipment": {
      "state": "shipped",
      "destinationCountry": "US",
      "weightGrams": 176,
      "trackingNumbers": ["YT2630812345678"],
      "shippedAt": 1793685600000
    },
    "url": "https://www.ninjabuy.com/me/orders/j57c4k1m"
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`warehouse`somente leitura

Tudo o que chegou ao nosso armazém: fotos, quantos chegaram, quantos podem ser enviados ou estão em um envio, peso, valor declarado, se está pago e quando termina a armazenagem grátis.

Sem parâmetros.

warehouse responde

{
  "items": [
    {
      "id": "P1012-1",
      "order": 1012,
      "title": "Heavyweight washed hoodie",
      "photos": [
        {
          "type": "image",
          "url": "https://media.ninjabuy.com/qc/P1012-1/1.webp"
        }
      ],
      "received": 1,
      "availableToShip": 1,
      "inShipment": 0,
      "unitWeightGrams": 176,
      "declaredUnitValue": "¥38.00",
      "paid": true,
      "freeStorageUntil": "2026-12-02T03:20:11.000Z"
    }
  ],
  "warehouseUrl": "https://www.ninjabuy.com/me/warehouse",
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`product`somente leitura

Lê um anúncio a partir de qualquer link de produto (Taobao, Tmall, Weidian, 1688, o link ou link curto de outro agente de compras, ou uma página de produto da NinjaBuy): título, imagens, vendedor e cada variante com skuId, rótulo, preço em CN¥ e estoque.

linkstringobrigatório: Um link de produto, com até 2.048 caracteres.

product responde

{
  "product": {
    "handle": "weidian-7750970856",
    "title": "重磅水洗连帽卫衣",
    "seller": "Ruoyi Studio",
    "variants": [
      {
        "skuId": "5187209554",
        "label": "Black / M",
        "priceMinor": 3800,
        "price": "¥38.00",
        "inStock": true
      },
      {
        "skuId": "5187209555",
        "label": "Black / L",
        "priceMinor": 3800,
        "price": "¥38.00",
        "inStock": false
      }
    ],
    "url": "https://www.ninjabuy.com/products/weidian-7750970856"
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`add_to_cart`escrita

Coloca variantes de um anúncio no carrinho, para comprar antecipadamente e guardar na sua prateleira. Nada é comprado: a resposta é a página do carrinho, onde você faz o checkout.

handlestringobrigatório: De product.
lines{ skuId, quantity }[]obrigatório: De 1 a 100 linhas; quantidade de 1 a 9.999. Uma variante que já está no carrinho é somada.

add_to_cart responde

{
  "added": 1,
  "cartUrl": "https://www.ninjabuy.com/cart",
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`search_products`somente leitura

Busca por palavra-chave na Taobao ou na 1688, a mesma busca do ninjabuy.com. Um link colado responde com esse produto.

querystringobrigatório: De 2 a 120 caracteres, ou um link.
providerstring?: taobao ou 1688. taobao se omitido.
pagenumber?: De 0 a 20.

search_products responde

{
  "kind": "products",
  "products": [
    {
      "handle": "taobao-781204556120",
      "title": "Heavyweight cotton hoodie, washed",
      "price": { "amount": "45.00", "currency": "CNY" },
      "marketplace": "taobao",
      "url": "https://www.ninjabuy.com/products/taobao-781204556120"
    }
  ],
  "page": 0,
  "totalCount": 1840,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`analyze_product`somente leitura

Quanto custa uma venda de cada variante entregue na porta do comprador, e o preço que mantém a sua margem no seu marketplace. Nada é salvo. Os mesmos valores de a análise de importação.

linkstringobrigatório: Um link de produto.
weight_gnumberobrigatório: Peso embalado de uma unidade, em gramas.
ship_tostring?: País de duas letras. US se omitido.
lanestring?: saver ou fast.
marketplacestring?: ebay, shopify, amazon ou tiktok.
margin_percentnumber?: A margem para o cálculo do preço. 30 se omitido.

analyze_product responde

{
  "title": "重磅水洗连帽卫衣",
  "shipTo": "US",
  "marketplace": "ebay",
  "brandHint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "inStock": true,
      "procurement": "57.00",
      "parcel": "134.52",
      "landedUsd": "27.71",
      "suggestedPrice": "49.99",
      "marginPercent": "30.16"
    }
  ],
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`import_product`escrita

Importa um anúncio com a análise, como na API de importações. Grátis. Responde com a importação para enviar ou precificar de novo.

linkstringobrigatório: Um link de produto ou uma planilha de achados.
weight_gnumberobrigatório: Peso embalado de uma unidade, em gramas.
ship_tostring?: País de duas letras. US se omitido.
lanestring?: saver ou fast.
marketplacestring?: ebay, shopify, amazon ou tiktok.
margin_percentnumber?: A margem para o cálculo do preço. 30 se omitido.

import_product responde

{
  "import": {
    "id": "imp_2c9d",
    "status": "ready",
    "title": "重磅水洗连帽卫衣",
    "variants": 6,
    "inStock": 5
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`push_to_shopify`escrita

Salva uma importação como produto e a anuncia na sua loja Shopify como rascunho, com estoque no local Fulfilled by NinjaBuy. Enviar de novo atualiza. As mesmas regras de Enviar para a Shopify.

import_idstringobrigatório: De import_product.
variants{ sku, price }[]?: Quais manter e por qual preço em US$. Se omitido, os que estão em estoque pelo preço sugerido.
titlestring?: O seu título.
shopstring?: Necessário quando há várias lojas vinculadas.

push_to_shopify responde

{
  "product": "prd_8f2k",
  "shopify": {
    "status": "draft",
    "variants": 5,
    "adminUrl": "https://admin.shopify.com/store/acme-goods/products/8812042"
  },
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`list_synced_products`somente leitura

Os seus produtos com a última verificação, as mudanças de custo e o estoque, para você ver o que mudou.

statusstring?: active ou paused.
changed_sincestring?: Uma data: só os produtos cujo custo ou estoque mudou desde então.
cursorstring?: Da resposta anterior; omita na primeira página.
limitnumber?: De 1 a 25. 25 se omitido.

list_synced_products responde

{
  "products": [
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "lastCheckedAt": "2026-11-04T02:10:00Z",
      "costChange": {
        "from": "¥42.00",
        "to": "¥48.00",
        "action": "repriced",
        "price": { "from": "$18.99", "to": "$20.99" }
      }
    }
  ],
  "cursor": null,
  "has_more": false,
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

`set_sync_rule`escrita

O que fazer quando um vendedor aumenta um preço: reajustar para manter uma margem, pausar ou só avisar você. Para todos os produtos, ou para um. Os mesmos campos de Regras de sincronização.

applies_tostringobrigatório: all, ou um id de produto.
on_cost_increasestringobrigatório: reprice, pause ou notify.
keep_margin_percentnumber?: Com reprice.
max_increase_percentnumber?: Com reprice: acima disso, pausar.

set_sync_rule responde

{
  "rule": {
    "id": "rule_default",
    "appliesTo": "all",
    "onCostIncrease": {
      "action": "reprice",
      "keepMarginPercent": 40,
      "maxIncreasePercent": 15
    }
  },
  "requestId": "5f7c2a1e-3b8d-4c61-9a0f-2e4d6b8c1a37",
  "warnings": []
}

O que perguntar

Quais dos meus pedidos ainda estão esperando um vendedor?

list_orders

Dois: #1012 (o moletom estonado, comprado em 1º de nov.) e #1015 (duas ecobags de lona). Os dois estão pagos e pedidos ao vendedor; nenhum chegou ao armazém ainda.

Vale a pena vender este moletom no eBay? weidian.com/item.html?itemID=7750970856, cerca de 180 g embalado.

analyze_product

Uma venda para os EUA custa CN¥ 191,52 com tudo incluído, cerca de $27.71. A $49.99, o eBay fica com cerca de $7.20 e sobram $15.08 para você, uma margem de 30%. Black / L está esgotado. Nenhuma palavra de marca no título.

Ótimo. Coloque Black / M na minha Shopify a $49.99, com o título “Heavyweight Washed Hoodie”.

import_productpush_to_shopify

Pronto: é um rascunho em acme-goods.myshopify.com com 1 variante, com estoque em Fulfilled by NinjaBuy. Confira as fotos e publique na Shopify.

Mantenha uma margem de 40% em tudo, mas nunca aumente um preço mais de 15% de uma vez.

set_sync_rule

Definida para todos os produtos. Um aumento acima de 15% pausa o produto em vez disso, e vou ver em list_synced_products.

Conectar#

Claude

ChatGPT

Cursor

Claude Code e outros assistentes de linha de comando

Login e acesso#

Nada aqui gasta dinheiro#

Ferramentas#

list_orderssomente leitura

ordersomente leitura

warehousesomente leitura

productsomente leitura

add_to_cartescrita

search_productssomente leitura

analyze_productsomente leitura

import_productescrita

push_to_shopifyescrita

list_synced_productssomente leitura

set_sync_ruleescrita

O que perguntar#