Sviluppatori

Assistenti IA (MCP)

Collega Claude, ChatGPT o Cursor al tuo account NinjaBuy e chiedi con parole tue: dov’è un ordine, cosa c’è sul tuo scaffale, se vale la pena vendere un’inserzione, e mettila nel tuo negozio.

In questa pagina

1Collega
2Accesso e autorizzazioni
3Qui nulla spende denaro
4Strumenti
5Cosa chiedere

Collega

Un solo indirizzo server per ogni assistente. Accedi con il tuo account NinjaBuy; nessuna chiave da incollare.

https://www.ninjabuy.com/mcp

Claude

Apri Settings › Connectors e scegli Add custom connector.
Incolla l’indirizzo qui sopra e aggiungilo.
Accedi con il numero di telefono del tuo account NinjaBuy, poi scegli Allow access.

ChatGPT

Attiva la modalità sviluppatore nelle impostazioni, poi aggiungi un server MCP personalizzato.
Incolla l’indirizzo qui sopra e scegli OAuth come metodo di accesso.
Accedi con il numero di telefono del tuo account NinjaBuy, poi scegli Allow access.

Cursor

Aggiungi il server in Cursor Settings › MCP, o in ~/.cursor/mcp.json. La prima volta Cursor apre l’accesso a NinjaBuy nel browser.

~/.cursor/mcp.json

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

Claude Code e altri assistenti da riga di comando

Terminale

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

I nomi dei menu cambiano con gli aggiornamenti degli assistenti; cerca “custom connector” o “custom MCP server”.

L’assistente accede con OAuth 2.1: si registra, ti manda su ninjabuy.com e tu lo approvi sulla nostra schermata, che indica l’app e dove ti rimanderà. Autorizza solo un’app che hai appena chiesto di collegare. Approvi ogni app una volta sola.

Agisce come il tuo account: gli strumenti non accettano un ID account e vedono solo i tuoi ordini, il tuo scaffale e i tuoi prodotti.
L’accesso dura un’ora e si rinnova per sette giorni; poi l’assistente ti chiede di accedere di nuovo.
Rimuovi il connettore nel tuo assistente per scollegarlo.
Gli strumenti che leggono un marketplace (product, analyze_product, import_product, push_to_shopify) condividono la finestra di 30 al minuto dell’API: Limiti di frequenza.

Qui nulla spende denaro

Nessuno strumento paga, crea una spedizione o spende il tuo saldo. Quando qualcosa va pagato, la risposta indica la pagina dove farlo: il pagamento dal carrello, la spedizione dalla pagina del tuo magazzino. push_to_shopify pubblica un prodotto come bozza, quindi nulla va in vendita finché non lo pubblichi.

Strumenti

Ogni risposta contiene requestId (citalo quando ci scrivi) e warnings, cose utili da sapere che non hanno bloccato la chiamata. Una risposta lunga viene troncata a circa 6.000 token con truncated: true; gli elenchi usano allora un limite più piccolo.

Strumento	Cosa fa
list_orders	Elenca i miei ordini NinjaBuy
order	Un ordine NinjaBuy
warehouse	Il mio magazzino NinjaBuy
product	Leggi le varianti di un prodotto
add_to_cart	Aggiungi al mio carrello NinjaBuy
search_products	Cerca prodotti
analyze_product	Analizza un prodotto
import_product	Importa un prodotto
push_to_shopify	Push to Shopify
list_synced_products	Elenca i miei prodotti sincronizzati
set_sync_rule	Imposta una regola di sincronizzazione

`list_orders`sola lettura

Gli ordini dell’account, dal più recente: stato, stato del pagamento, quanto resta da pagare, gli articoli e la pagina di ogni ordine. Segui cursor finché has_more è true.

cursorstring?: Dalla risposta precedente; omettilo per la prima pagina.
limitnumber?: Da 1 a 25. 25 se omesso.

list_orders risponde

{
  "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`sola lettura

Un ordine per ID: righe e prezzi, lo stato di ogni articolo e quanti sono arrivati, e la spedizione con il tracciamento. order è null per un ID che non appartiene a questo account.

idstringobbligatorio: Un ID da list_orders.

order risponde

{
  "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`sola lettura

Tutto ciò che è arrivato nel nostro magazzino: foto, quanti pezzi sono arrivati, spedibili o in una spedizione, peso, valore dichiarato, se è pagato e quando finisce lo stoccaggio gratuito.

Nessun input.

warehouse risponde

{
  "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`sola lettura

Legge un’inserzione da qualsiasi link di prodotto (Taobao, Tmall, Weidian, 1688, il link o link breve di un altro agente di acquisto, o una pagina prodotto NinjaBuy): titolo, immagini, venditore e ogni variante con skuId, etichetta, prezzo in CN¥ e stock.

linkstringobbligatorio: Un link di prodotto, fino a 2.048 caratteri.

product risponde

{
  "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`scrittura

Mette nel carrello varianti di un’inserzione, da acquistare in anticipo e tenere sul tuo scaffale. Non si acquista nulla: la risposta è la pagina del carrello, dove fai il checkout.

handlestringobbligatorio: Da product.
lines{ skuId, quantity }[]obbligatorio: Da 1 a 100 righe; quantità da 1 a 9.999. Una variante già nel carrello si somma.

add_to_cart risponde

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

`search_products`sola lettura

Ricerca per parole chiave su Taobao o 1688, la stessa di ninjabuy.com. Un link incollato restituisce quel prodotto.

querystringobbligatorio: Da 2 a 120 caratteri, o un link.
providerstring?: taobao o 1688. taobao se omesso.
pagenumber?: Da 0 a 20.

search_products risponde

{
  "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`sola lettura

Quanto costa una vendita di ogni variante consegnata alla porta dell’acquirente, e il prezzo che mantiene il tuo margine sul tuo marketplace. Nulla viene salvato. Stesse cifre dell’analisi di importazione.

linkstringobbligatorio: Un link di prodotto.
weight_gnumberobbligatorio: Peso imballato di un’unità, in grammi.
ship_tostring?: Paese a due lettere. US se omesso.
lanestring?: saver o fast.
marketplacestring?: ebay, shopify, amazon o tiktok.
margin_percentnumber?: Il margine su cui calcolare il prezzo. 30 se omesso.

analyze_product risponde

{
  "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`scrittura

Importa un’inserzione con la sua analisi, come l’API Imports. Gratis. Restituisce l’importazione per inviarla o ricalcolarne il prezzo.

linkstringobbligatorio: Un link di prodotto o un foglio di scoperte.
weight_gnumberobbligatorio: Peso imballato di un’unità, in grammi.
ship_tostring?: Paese a due lettere. US se omesso.
lanestring?: saver o fast.
marketplacestring?: ebay, shopify, amazon o tiktok.
margin_percentnumber?: Il margine su cui calcolare il prezzo. 30 se omesso.

import_product risponde

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

`push_to_shopify`scrittura

Salva un’importazione come prodotto e la pubblica come bozza sul tuo negozio Shopify, a stock nella sede Fulfilled by NinjaBuy. Un nuovo invio la aggiorna. Stesse regole di Push to Shopify.

import_idstringobbligatorio: Da import_product.
variants{ sku, price }[]?: Quali tenere e a quale prezzo in US$. Se omesso, quelle disponibili al prezzo suggerito.
titlestring?: Il tuo titolo.
shopstring?: Necessario quando sono collegati più negozi.

push_to_shopify risponde

{
  "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`sola lettura

I tuoi prodotti con l’ultimo controllo, le variazioni di costo e lo stock, così vedi cosa si è mosso.

statusstring?: active o paused.
changed_sincestring?: Una data: solo i prodotti il cui costo o stock è cambiato da allora.
cursorstring?: Dalla risposta precedente; omettilo per la prima pagina.
limitnumber?: Da 1 a 25. 25 se omesso.

list_synced_products risponde

{
  "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`scrittura

Cosa fare quando un venditore alza un prezzo: ricalcolare per mantenere un margine, mettere in pausa o solo avvisarti. Per tutti i prodotti, o uno. Stessi campi di Regole di sincronizzazione.

applies_tostringobbligatorio: all, o un ID prodotto.
on_cost_increasestringobbligatorio: reprice, pause o notify.
keep_margin_percentnumber?: Con reprice.
max_increase_percentnumber?: Con reprice: oltre questo, pausa.

set_sync_rule risponde

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

Cosa chiedere

Quali dei miei ordini aspettano ancora un venditore?

list_orders

Due: #1012 (la felpa slavata, acquistata il 1° nov.) e #1015 (due tote bag in tela). Entrambi sono pagati e ordinati al venditore; nessuno è ancora arrivato in magazzino.

Vale la pena vendere questa felpa su eBay? weidian.com/item.html?itemID=7750970856, circa 180 g imballata.

analyze_product

Una vendita negli USA costa 191,52 CN¥ finale, circa $27.71. A $49.99 eBay trattiene circa $7.20 e a te restano $15.08, un margine del 30%. Black / L è esaurito. Nessuna parola di marchio nel titolo.

Bene. Metti Black / M sul mio Shopify a $49.99, titolo “Heavyweight Washed Hoodie”.

import_productpush_to_shopify

Fatto: è una bozza su acme-goods.myshopify.com con 1 variante, a stock presso Fulfilled by NinjaBuy. Controlla le foto, poi pubblicalo in Shopify.

Tieni un margine del 40% su tutto, ma non alzare mai un prezzo più del 15% in una volta.

set_sync_rule

Imposta per tutti i prodotti. Un aumento oltre il 15% mette invece in pausa il prodotto, e lo vedrò in list_synced_products.

Collega#

Claude

ChatGPT

Cursor

Claude Code e altri assistenti da riga di comando

Accesso e autorizzazioni#

Qui nulla spende denaro#

Strumenti#

list_orderssola lettura

ordersola lettura

warehousesola lettura

productsola lettura

add_to_cartscrittura

search_productssola lettura

analyze_productsola lettura

import_productscrittura

push_to_shopifyscrittura

list_synced_productssola lettura

set_sync_rulescrittura

Cosa chiedere#