Documentos
Ctrl+K Buscar Alt+[Alt+] Guías
Obtener clave API

Guías

Autenticación

Cada punto final programático con medición acepta una única clave API, que se puede enviar de tres formas diferentes. En esta página se explica dónde obtener la clave, cómo enviarla y cómo el servidor la vincula a tu cuenta.

Envío de tu

El servidor comprueba tres ubicaciones, en este orden. El primer valor no vacío es el que prevalece.

Dónde Ejemplo Notas
Clave X-API encabezado X-API-Key: wh_… Preferible. Nombre del encabezado que no distingue entre mayúsculas y minúsculas.
Autorización encabezado Autorización: Portador wh_… Programa «Standard Bearer». Cualquier otra cosa (p. ej., Básico) se ignora.
clave_API parámetro de consulta ?api_key=wh_… Úsalo solo como solución alternativa. Evítalo para cualquier dato confidencial, ya que acaba apareciendo en las URL, los registros del servidor y el historial del navegador. 
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS \
  -H "Authorization: Bearer $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS "{origin}/api/v1/tiktok-shop/credits?api_key=$WH_API_KEY"

Las tres opciones son equivalentes en cuanto al enrutamiento; elige la que te resulte más fácil en tu cliente HTTP.

¿De dónde viene la clave

Las claves se gestionan exclusivamente desde la página de la API de la aplicación:

  • GET /api — Ver tu clave actual, copiarla o volver a generarla.
  • POST /api/regenerate — Regeneración programática (se requiere iniciar sesión).

Una clave tiene este aspecto: wh_ seguido de 48 caracteres hexadecimales. Trátalo como si fuera una contraseña: te da acceso a todo tu cuota mensual de la API.

La regeneración es inmediato y destructivo. La clave anterior deja de funcionar en el momento en que se regenera, y cualquier cliente que siga utilizándola recibirá 401 Acceso no autorizado. Girar cuando:

  • Sospechas que hay una fuga.
  • Se marcha un compañero de equipo o un colaborador externo con acceso.
  • Has enviado una clave al control de versiones por error.

De lo contrario, las claves no caducan: siguen funcionando hasta que las regeneres o se reduzca tu plan.

del plan n.º

Una vez que una clave se asocia a una cuenta, el servidor comprueba que el acceso a la API esté habilitado para dicha cuenta. De no ser así, se recibe un error HTTP 403, incluso si el formato de la clave es válido. Las rebajas de plan o las cancelaciones pueden retirar el acceso de forma inmediata.

de equipos y organizaciones#

Las claves se asignan por usuario. En las configuraciones de equipo, el uso y el acceso se rigen por las normas de facturación de tu organización dentro del producto; utiliza la página de la API integrada en la aplicación y el panel de control para obtener información fiable sobre tu licencia.

sesión frente a autenticación mediante clave API#

Las rutas de WinningHunter se dividen en tres tipos. Asegúrate de que te diriges a la correcta.

Prefijo de ruta Autor Cuándo utilizarlo
/api/v1/tiktok-shop/* Clave API (Clave X-API) Todas las integraciones programáticas y externas. Se contabilizan en los créditos y se aplican límites de frecuencia.
/api/tiktok-shop/*, /api/product-detail/*, etc. Sesión del navegador con inicio de sesión (cookies) Solo los utiliza la aplicación web. Estos son no la interfaz de la clave API — uso /api/v1/tiktok-shop/* para integraciones.
/api/v1/adlibrary, /api/v1/magic-ai, /api/v1/store-tracker, /api/v1/store-explorer, /api/v1/marcas Clave API El espacio programático fuera de TikTok. La misma medición que /api/v1/tiktok-shop/*. El archivo sin versión /api/<x> las formas se mantienen como alias compatibles con versiones anteriores de biblioteca de anuncios, rastreador de tiendas, y explorador de tiendas solo — las nuevas integraciones deben utilizar las rutas de la versión 1. /api/magic-ai y /api/marcas (no v1) son rutas de sesión del panel de control, no la interfaz de la clave API, ya que las páginas del panel de control siguen realizando operaciones POST/GET en esas URL; los clientes clave deben utilizar /api/v1/magic-ai y /api/v1/marcas.

Si estás escribiendo un script o una integración de backend, casi siempre querrás /api/v1/tiktok-shop/... además de las pocas rutas que no son de TikTok mencionadas anteriormente. La superficie completa está documentada en el Referencia de la API y las guías temáticas (TikTok Shop, biblioteca de anuncios de Meta, marcas, etc.).

Comprobación del de la llave

La forma más económica de realizar una prueba de funcionamiento es GET /api/v1/tiktok-shop/credits — devuelve el saldo de crédito actual y cuesta 1 crédito:

curl -i \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

A 200 «with JSON» significa: clave válida, plan correcto, límite de rate y créditos en buen estado. Para cualquier otro estado, consulte Errores.

de comprobación de seguridad#

  • Guarda las claves en variables de entorno o en un almacén de credenciales seguro; nunca en código del lado del cliente, aplicaciones móviles o paquetes del navegador.
  • Uso Clave X-API o Autorización: al portador, y no el parámetro de consulta, siempre que sea posible.
  • Realizar rotaciones tras cualquier incidente, ante cualquier cambio en la composición del equipo y, como mínimo, una vez al año.
  • No compartas claves entre entornos: genera una por cada cuenta de servicio y renuévalas de forma independiente.