Desarrolladores

Asistentes de IA (MCP)

Conecta Claude, ChatGPT o Cursor a tu cuenta de NinjaBuy y pregunta con tus propias palabras: dónde está un pedido, qué hay en tu estante, si vale la pena vender una publicación, y súbela a tu tienda.

En esta página

1Conectar
2Inicio de sesión y acceso
3Nada aquí gasta dinero
4Herramientas
5Qué preguntar

Conectar

Una sola dirección de servidor para todos los asistentes. Inicias sesión con tu cuenta de NinjaBuy; no hay ninguna clave que pegar.

https://www.ninjabuy.com/mcp

Claude

Abre Settings › Connectors y elige Add custom connector.
Pega la dirección de arriba y agrégala.
Inicia sesión con tu número de celular de NinjaBuy y luego elige Permitir acceso.

ChatGPT

Activa el modo desarrollador en Settings y luego agrega un servidor MCP personalizado.
Pega la dirección de arriba y elige OAuth como método de inicio de sesión.
Inicia sesión con tu número de celular de NinjaBuy y luego elige Permitir acceso.

Cursor

Agrega el servidor en Cursor Settings › MCP, o en ~/.cursor/mcp.json. Cursor abre el inicio de sesión de NinjaBuy en tu navegador la primera vez.

~/.cursor/mcp.json

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

Claude Code y otros asistentes de línea de comandos

Terminal

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

Los nombres de los menús cambian cuando se actualizan los asistentes; busca “conector personalizado” o “servidor MCP personalizado”.

El asistente inicia sesión con OAuth 2.1: se registra, te envía a ninjabuy.com y lo apruebas en nuestra propia pantalla, que muestra el nombre de la app y adónde te devolverá. Solo permite una app que acabas de pedir conectar. Apruebas cada app una vez.

Actúa como tu cuenta: las herramientas no reciben un id de cuenta y solo ven tus pedidos, tu estante y tus productos.
El acceso dura una hora y se renueva durante siete días; después el asistente te pide que vuelvas a iniciar sesión.
Elimina el conector en tu asistente para desconectarlo.
Las herramientas que leen un marketplace (product, analyze_product, import_product, push_to_shopify) comparten la ventana de 30 por minuto de la API: Límites de tasa.

Nada aquí gasta dinero

Ninguna herramienta paga, crea un envío ni gasta tu saldo. Cuando algo requiere pago, la respuesta indica la página donde hacerlo: el pago desde el carrito, el envío desde la página de tu almacén. push_to_shopify publica un producto como borrador, así que nada sale a la venta hasta que lo publiques.

Herramientas

Cada respuesta lleva requestId (cítalo cuando nos escribas) y warnings, cosas que conviene saber y que no detuvieron la llamada. Una respuesta larga se corta en unos 6.000 tokens con truncated: true; las listas toman entonces un límite menor.

Herramienta	Qué hace
list_orders	Lista mis pedidos de NinjaBuy
order	Un pedido de NinjaBuy
warehouse	Mi almacén de NinjaBuy
product	Leer las variantes de un producto
add_to_cart	Agregar a mi carrito de NinjaBuy
search_products	Buscar productos
analyze_product	Analizar un producto
import_product	Importar un producto
push_to_shopify	Enviar a Shopify
list_synced_products	Lista mis productos sincronizados
set_sync_rule	Fijar una regla de sincronización

`list_orders`solo lectura

Los pedidos de la cuenta, del más reciente al más antiguo: estado, estado del pago, lo que aún se debe, los artículos y la página de cada pedido. Sigue cursor mientras has_more sea true.

cursorstring?: De la respuesta anterior; omítelo en la primera página.
limitnumber?: De 1 a 25. 25 si se omite.

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`solo lectura

Un pedido por id: sus líneas y precios, el estado de cada artículo y cuántos llegaron, y el envío con seguimiento. order es null para un id que no es de esta cuenta.

idstringobligatorio: Un 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`solo lectura

Todo lo que llegó a nuestro almacén: fotos, cuántos llegaron, cuántos se pueden enviar o están en un envío, peso, valor declarado, si está pagado y cuándo termina el almacenamiento gratuito.

Sin 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`solo lectura

Lee una publicación desde cualquier enlace de producto (Taobao, Tmall, Weidian, 1688, el enlace o enlace corto de otro agente de compras, o una página de producto de NinjaBuy): título, imágenes, vendedor y cada variante con su skuId, etiqueta, precio en CN¥ y stock.

linkstringobligatorio: Un enlace de producto, de hasta 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`escritura

Pone variantes de una publicación en el carrito, para comprarlas por adelantado y guardarlas en tu estante. No se compra nada: la respuesta es la página del carrito, donde pagas.

handlestringobligatorio: De product.
lines{ skuId, quantity }[]obligatorio: De 1 a 100 líneas; cantidad de 1 a 9.999. Una variante que ya está en el carrito se suma.

add_to_cart responde

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

`search_products`solo lectura

Búsqueda por palabra clave en Taobao o 1688, la misma búsqueda que en ninjabuy.com. Un enlace pegado responde con ese producto.

querystringobligatorio: De 2 a 120 caracteres, o un enlace.
providerstring?: taobao o 1688. taobao si se omite.
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`solo lectura

Lo que cuesta una venta de cada variante puesta en la puerta del comprador, y el precio que mantiene tu margen en tu marketplace. No se guarda nada. Las mismas cifras que el análisis de importación.

linkstringobligatorio: Un enlace de producto.
weight_gnumberobligatorio: Peso empacado de una unidad, en gramos.
ship_tostring?: País de dos letras. US si se omite.
lanestring?: saver o fast.
marketplacestring?: ebay, shopify, amazon o tiktok.
margin_percentnumber?: El margen para el que se calcula el precio. 30 si se omite.

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`escritura

Importa una publicación con su análisis, como en la API de importaciones. Gratis. Responde con la importación para enviarla o recalcular el precio.

linkstringobligatorio: Un enlace de producto o una hoja de hallazgos.
weight_gnumberobligatorio: Peso empacado de una unidad, en gramos.
ship_tostring?: País de dos letras. US si se omite.
lanestring?: saver o fast.
marketplacestring?: ebay, shopify, amazon o tiktok.
margin_percentnumber?: El margen para el que se calcula el precio. 30 si se omite.

import_product responde

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

`push_to_shopify`escritura

Guarda una importación como producto y la publica en tu tienda de Shopify como borrador, con stock en la ubicación Fulfilled by NinjaBuy. Enviarla de nuevo la actualiza. Las mismas reglas que Enviar a Shopify.

import_idstringobligatorio: De import_product.
variants{ sku, price }[]?: Cuáles conservar y a qué precio en US$. Si se omite, los que están en stock al precio sugerido.
titlestring?: Tu título.
shopstring?: Necesario cuando hay varias tiendas 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`solo lectura

Tus productos con su última revisión, cambios de costo y stock, para que veas qué se movió.

statusstring?: active o paused.
changed_sincestring?: Una fecha: solo los productos cuyo costo o stock cambió desde entonces.
cursorstring?: De la respuesta anterior; omítelo en la primera página.
limitnumber?: De 1 a 25. 25 si se omite.

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`escritura

Qué hacer cuando un vendedor sube un precio: recalcular para mantener un margen, pausar o solo avisarte. Para todos los productos, o para uno. Los mismos campos que Reglas de sincronización.

applies_tostringobligatorio: all, o un id de producto.
on_cost_increasestringobligatorio: reprice, pause o notify.
keep_margin_percentnumber?: Con reprice.
max_increase_percentnumber?: Con reprice: por encima, 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": []
}

Qué preguntar

¿Cuáles de mis pedidos siguen esperando a un vendedor?

list_orders

Dos: #1012 (la sudadera deslavada, comprada el 1 de nov.) y #1015 (dos bolsas de lona). Ambos están pagados y pedidos al vendedor; ninguno ha llegado aún al almacén.

¿Vale la pena vender esta sudadera en eBay? weidian.com/item.html?itemID=7750970856, unos 180 g empacada.

analyze_product

Una venta a EE. UU. cuesta 191,52 CNY puesta en destino, unos $27.71. A $49.99, eBay se queda con unos $7.20 y a ti te quedan $15.08, un margen del 30 %. Black / L está agotado. No hay palabras de marca en el título.

Bien. Pon Black / M en mi Shopify a $49.99, con el título “Heavyweight Washed Hoodie”.

import_productpush_to_shopify

Listo: es un borrador en acme-goods.myshopify.com con 1 variante, con stock en Fulfilled by NinjaBuy. Revisa las fotos y publícalo en Shopify.

Mantén un margen del 40 % en todo, pero nunca subas un precio más de un 15 % de una vez.

set_sync_rule

Fijada para todos los productos. Una subida de más del 15 % pausa el producto en su lugar, y lo veré en list_synced_products.

Conectar#

Claude

ChatGPT

Cursor

Claude Code y otros asistentes de línea de comandos

Inicio de sesión y acceso#

Nada aquí gasta dinero#

Herramientas#

list_orderssolo lectura

ordersolo lectura

warehousesolo lectura

productsolo lectura

add_to_cartescritura

search_productssolo lectura

analyze_productsolo lectura

import_productescritura

push_to_shopifyescritura

list_synced_productssolo lectura

set_sync_ruleescritura

Qué preguntar#