Agent API y MCP

Audiencia: agentes LLM, runtimes de invocación de herramientas y clientes MCP (Cursor, Claude Desktop). Para backends humanos y tiendas, use /v1/* + OpenAPI .

Integraciones de IA: MCP y el Skill hiobuy-agent-api exponen a agentes LLM herramientas en vivo de China sourcing en 1688, Taobao y Weidian — búsqueda por palabra clave, búsqueda por imagen y detalle de producto bilingüe para flujos shopping agent en Cursor y Claude Desktop.

Autenticación: solo claves Live hio_live_*. Las claves sandbox (hio_test_*) y las fixtures de Sandbox no aplican a /ai/v1 ni /mcp.

Relacionado: Autenticación · Productos · Formato de respuesta · Errores · Límites de tasa

Qué superficie usar

Las cargas data de las tools coinciden con las formas standard de modelos de respuesta de producto y endpoints de lista — nunca formato upstream en bruto.

Requisitos previos (clave Live)

Antes de llamar a /ai/v1 o /mcp:

1. Regístrese y cree una app en el portal de desarrolladores HIOBuy ; espere la aprobación.
2. Autorice canales (1688, Taobao, Weidian, …) — igual que la autorización del portal.
3. Cree una clave API Live en API Keys (hio_live_* — se muestra una sola vez al crearla).
4. Conceda scopes mínimos para las tools Phase 1:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Sin autorización de canal o scope → 401 / 403. Las llamadas Live consumen cuota de canal y se registran como /v1.

URL base y autenticación

Mismo host que la API pública, p. ej. https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Cada tool se asigna a un scope API Key existente — no hay scope separado tools:*.

Endpoints HTTP (/ai/v1)

Listar tools

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

Devuelve solo las tools permitidas por los scopes de la clave. Cada entrada incluye id, version, domain, description y JSON Schema input_schema.

Invocar una tool

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

Envoltorio de éxito (todas las tools):

Fallo: HTTP 4xx/5xx con { "error": { "code", "message", "request_id" } } — sin campo ok. Vea Errores para códigos compartidos (INVALID_API_KEY, FORBIDDEN, RATE_LIMITED, …).

Tools Phase 1 (productos)

product.get_detail

• Canal: taobao | 1688 | weidian
• Requerido: channel + uno de product_id | url | mi_id | tao_password
• Opcional: language (predeterminado en)
• data: { "product": StandardProduct }

product.search

• Requerido: channel, keyword
• Opcional: page, page_size, language, sort, price_start, price_end
• data: StandardProductList (igual que el cuerpo de POST /v1/products/search)

product.upload_image

• Canal: 1688 | taobao
• 1688: image_base64 o image_url
• Taobao: se requiere image_base64
• data: { "channel", "image_id" } — reutilice image_id para búsqueda por imagen paginada

product.search_by_image

• Canal: 1688 | taobao (no Weidian)
• Entrada: image_id | image_url | image_base64
• Flujo recomendado para paginación: product.upload_image una vez → varias llamadas product.search_by_image solo con image_id

Flujo del agente (HTTP)

1. GET /ai/v1/tools → cachear metadatos tools / input_schema
2. El modelo elige tool_id + arguments según la intención del usuario
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. Resumir data para el usuario

Cadenas típicas:

• Búsqueda por imagen en un paso: product.search_by_image con image_url o image_base64
• Búsqueda por imagen paginada: product.upload_image → product.search_by_image (image_id + page)
• Tras elegir un artículo: product.get_detail

Servidor MCP (/mcp) — China sourcing para agentes de IA

En Cursor, Claude Desktop y otros clientes MCP, los agentes llaman herramientas de China sourcing y compras por proxy en 1688 (mayorista), Taobao (retail) y Weidian — búsqueda por palabra clave, subida y búsqueda por imagen, detalle de producto bilingüe. Cadenas típicas de shopping agent: comparar cotizaciones de fábrica en 1688, alternativas en Taobao, hojear catálogos Weidian, luego profundizar en SKU/stock vía product.get_detail.

El mismo runtime de herramientas se expone como MCP Server mediante Streamable HTTP (Cursor, Claude Desktop y otros clientes MCP).

Auth: mismo encabezado Authorization: Bearer hio_live_*.

Capacidades:

• Tools — tools/list, tools/call (mismos valores tool_id que /ai/v1)
• Prompts — flujos integrados de búsqueda de productos / por imagen / investigación
• Resources — URI hiobuy://agent/* (resources/list, resources/read, plantillas)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp abre SSE; POST con Accept: text/event-stream puede transmitir JSON-RPC
• Sampling — el servidor puede enviar sampling/createMessage por SSE; el cliente responde vía POST /mcp (202)

Flujo de sesión recomendado:

1. POST initialize → guardar encabezado de respuesta Mcp-Session-Id
2. GET /mcp con sesión → abrir listener SSE
3. POST notifications/initialized
4. POST tools/list / tools/call

En éxito, tools/call → result.content[0].text es el mismo envoltorio JSON que /ai/v1/tools/call.

Configuración de Cursor (MCP shopping agent + China sourcing 1688/Taobao/Weidian)

Añada en Settings → MCP o .cursor/mcp.json para dar a Cursor herramientas en vivo de China sourcing en 1688 / Taobao / Weidian:

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

Sustituya hio_live_xxx por su clave Live. Mantenga las claves en el servidor — no las suba a repositorios públicos.

Cursor Agent Skill (hiobuy-agent-api) — China shopping agent

El Cursor Agent Skill opcional hiobuy-agent-api ayuda a agentes de codificación a conectar flujos China sourcing en 1688, Taobao y Weidian — scopes de claves Live, envoltorios /ai/v1, encabezados de sesión MCP y cadenas búsqueda → búsqueda por imagen → detalle. Para tiendas REST en /v1/*, use OpenAPI.

Enseña al modelo:

• requisitos y scopes de claves Live para herramientas 1688 / Taobao / Weidian
• envoltorios de solicitud/respuesta /ai/v1 y argumentos de tools Phase 1
• encabezados de sesión MCP y cableado Cursor mcp.json para flujos China shopping
• códigos de error y cadenas sourcing (búsqueda → búsqueda por imagen → detalle)

Instálelo desde el repositorio público hiobuy-agent-skills  — clone o copie SKILL.md en su directorio de skills de Cursor (véase Cursor Agent Skills ).

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

El skill complementa esta página — este sitio sigue siendo la referencia API canónica para scopes, cuotas y semántica de campos de producto.

Referencia rápida

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'