Primeros pasos

Esta guía te guía paso a paso por la primera llamada a la API HTTP de WinningHunter. Cinco minutos, de principio a fin.

En resumen: Utiliza una cuenta que incluya Acceso a la API, recupera tu clave de /api, inclúyelo como un Clave X-API encabezado, llamada /api/v1/tiktok-shop/credits para comprobar la conexión y, a continuación, compilar utilizando el Referencia de la API.

1. Acceso a la cuenta#

La API HTTP está disponible en las cuentas de WinningHunter que cumplan los requisitos. Si tu clave es válida pero las solicitudes se rechazan con el código de error HTTP 403, es posible que la cuenta con la que has iniciado sesión no tenga acceso a la API; comprueba el plan y la facturación en tu panel de control después de iniciar sesión.

2. Obtén tu clave API#

Abrir /api mientras se está conectado. La página muestra:

• Tu clave API (valor del encabezado; haz clic para copiar).
• Tu uso mensual del crédito (sobre un límite de 20 000).
• Un registro de solicitudes con códigos de estado y marcas de tiempo.
• Un botón de regeneración: las claves antiguas dejan de funcionar inmediatamente tras la regeneración.

En la misma pantalla también se muestran los puntos finales HTTP de TikTok Shop disponibles para una consulta rápida.

3. Realiza tu primera solicitud#

Utilice un punto de conexión de solo lectura para verificar la autenticación y el control del consumo. /api/v1/tiktok-shop/credits Se recomienda: devuelve el saldo actual de tu cuenta y los costes 1 crédito.

curl -sS \
  -H "X-API-Key: wh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "{origin}/api/v1/tiktok-shop/credits"

Una respuesta correcta es JSON, con un HTTP 200 estado y Tipo de contenido: application/json. Si aparece un error:

• 401 Acceso no autorizado — Falta el encabezado, está mal formado o la clave es incorrecta. Véase Autenticación.
• 403 Prohibido — El acceso a la API no está habilitado para esta cuenta; soluciona el problema desde el panel de control (plan / facturación).
• 429 — véase Límites de velocidad y Créditos y facturación.

4. Realizar una búsqueda#

La mayoría de los desarrolladores empiezan con /api/v1/tiktok-shop/products/explore. Es compatible con ambos OBTENER y PUBLICAR métodos y devuelve una lista paginada de productos.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "{origin}/api/v1/tiktok-shop/products/explore" \
  -d '{
    "country": "US",
    "period": "30d",
    "limit": 20,
    "min_revenue": 50000
  }'

Uso ENVIAR JSON cuando el conjunto de filtros es grande, las cadenas de consulta largas pueden provocar un 414 URI demasiado largo error. Ambos métodos aceptan los mismos parámetros. Los nombres de los filtros, los alias, los valores predeterminados y la paginación se describen en el Referencia de filtros de TikTok Shop.

4b. Llamar a Magic AI (opcional)#

Magic AI también está disponible a través de la interfaz de la clave API en POST /api/v1/magic-ai.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34"

Importante:

• Uso /api/v1/magic-ai para integraciones con claves API.
• /api/magic-ai (sin v1) es la ruta de sesión del panel de control que utiliza la aplicación web.

5. Revisar el uso#

Después de realizar varias llamadas, actualiza la /api página (o llame al /api/uso (mientras estés conectado): tu gráfico de uso y los créditos restantes reflejarán la nueva actividad. Cada solicitud realizada con éxito consume 1 crédito y se contabiliza en el límite de la tarifa por minuto.

6. (Opcional) Utilizar MCP desde un cliente de IA#

Claude Desktop, Cursor, ChatGPT (con conectores MCP), Géminis (cuando Google habilita el MCP remoto), y n8n (Cliente MCP / Herramienta de cliente MCP) puede llamar a WinningHunter como herramientas en lugar de escribir a mano rizo.

• Los mismos requisitos: una cuenta en Acceso a la API y el la misma clave API como arriba — enviado como Clave X-API en la configuración del cliente.
• Resultado: HTTP en streaming en https://YOUR_HOST/mcp (consulte la guía para ver el código JSON exacto).
• Medición: cada uno que haya tenido éxito herramientas/llamada = 1 crédito; MCP tiene su propio límite por minuto (véase Guía de MCP).

Abrir MCP (Claude, Cursor, ChatGPT, Gemini, n8n) — obtienes listo para pegar claude_desktop_config.json y mcp.json fragmentos de código, notas sobre los conectores de ChatGPT y Gemini, pasos para configurar n8n y texto con instrucciones para los agentes. Nombres de herramientas y argumentos: MCP · Referencia de herramientas. Contexto del producto: Filtros de TikTok Shop, Tendencias. Manifiesto del sitio para rastreadores: /llms.txt.

Qué leer a continuación#

• Autenticación: opciones de encabezado y consulta, regeneración, cuentas de equipo.
• Créditos y facturación: el límite de 20 000 al mes, cómo se restablece y qué se tiene en cuenta.
• Límites de velocidad: 60 solicitudes por minuto, estrategia de retroceso.
• Errores: todos los códigos de estado que puede devolver la API.
• Intervalos de tiempo — período, fecha_rango, y cómo funciona realmente el filtrado por fechas.
• Solución de problemas: cuando algo no va bien.
• Glosario: definiciones de términos técnicos.
• Referencia de la API: autenticación y todas las funciones programáticas.
• IA mágica — cuerpo de la solicitud, filtros y paginación para POST /api/v1/magic-ai.
• MCP (Claude, Cursor, ChatGPT, Gemini, n8n): copia y pega configuraciones de clientes, créditos y tarifas.
• MCP · Referencia de herramientas: las 28 herramientas y parámetros de MCP.
• Tendencias · Explorador de tiendas · Rastreador de tiendas API — MCP + REST en contexto.