Claves API y Client ID

Una clave API permite que tu propio software, y herramientas como Zapier, n8n, Make y el plugin de WordPress, envíen mensajes de WhatsApp desde los números de tu espacio de trabajo. Tu propio código envía la clave en una cabecera Authorization: Bearer; las integraciones piden dos valores de la página Claves API: el Client ID de tu espacio de trabajo y una de sus claves. La misma página tiene el secreto que firma nuestros webhooks.

Quién puede hacerlo: solo los Propietarios; todos los Propietarios del espacio de trabajo, no solo su creador. Los Propietarios ven, crean, copian y eliminan todas las claves del espacio de trabajo, las haya creado quien las haya creado. Los Editores y los Analistas no ven Claves API en la barra lateral ni en la página Configuración, y un enlace a ella les abre Perfil (consulta Roles y permisos). Las claves funcionan en todos los planes, también en la prueba gratuita; lo que envías con ellas usa los mensajes del espacio de trabajo.

Abre Claves API en Integraciones en la barra lateral, o ve a Configuración → Claves API.

Cada clave muestra su nombre, cuándo se creó (Creada el …), los cuatro últimos caracteres de la clave (como •••• 7f3a), Copiar clave y Eliminar. La clave más reciente aparece primero.

Crear una clave API#

1. Haz clic en Crear clave

   En Configuración → Claves API, haz clic en Crear clave, arriba a la derecha de la tarjeta.

2. Ponle un nombre (opcional)

   En Nombre (opcional), escribe la app que la usará, como n8n o Website (hasta 50 caracteres). Si lo dejas vacío, recibe un nombre como "API Key 3", como indica el texto bajo el campo.

3. Créala

   Haz clic en Crear clave.

   

4. Copia la clave

   Tu nueva clave API muestra la clave completa: "Cópiala ahora: no volverás a ver la clave completa. Más adelante, “Copiar clave” la copia sin mostrarla." Haz clic en Copiar ("Clave copiada."), pega la clave en tu app o integración y luego haz clic en Listo.

   

• Hasta 10 claves por espacio de trabajo. Con 10, Crear clave aparece en gris y, al pasar el puntero por encima, muestra "Puedes tener hasta 10 claves API. Elimina una para crear otra."
• Las claves no caducan, y no se pueden renombrar ni desactivar: una clave funciona hasta que se elimina.
• Una clave por app. Ponle a cada clave el nombre de la app que la usa, para poder reemplazar o eliminar una sin romper las demás.
• Qué espacio de trabajo: una clave pertenece al espacio de trabajo que estaba seleccionado cuando la creaste, y cada solicitud hecha con ella actúa sobre ese espacio de trabajo: sus números, sus mensajes y su plan. Para enviar desde otro espacio de trabajo, cámbiate a él y crea allí una clave.

Qué introducir en tu app#

Dónde se introducen:

• Tu propio código: en una cabecera Authorization: Bearer YOUR_API_KEY en cada solicitud (recomendado). La clave indica su espacio de trabajo, así que client_id puede omitirse; si lo envías, tiene que seguir siendo el de este espacio de trabajo. Consulta Enviar la clave en una cabecera, y Enviar mensaje para un primer mensaje en cURL, Python, Node.js y PHP.
• Zapier: el Client ID y la clave API, al conectar tu cuenta.
• n8n: Client ID, API Key y WhatsApp Client ID en la credencial de WbizTool.
• Make, Pabbly Connect y otras herramientas: el cuerpo de una solicitud HTTP.
• WordPress: WbizTool → Settings, en API Configuration.

Google Sheets y Shopify se configuran en el panel y no necesitan clave.

Enviar la clave en una cabecera#

Todos los endpoints de /api/v1/ aceptan la clave en una cabecera Authorization, como lo hará la próxima API v2:

Authorization: Bearer YOUR_API_KEY

• client_id es opcional con la cabecera: la clave decide el espacio de trabajo. Si además envías client_id, tiene que ser el Client ID de este espacio de trabajo, como hasta ahora.
• Envía la clave en un solo sitio. Con la cabecera, omite api_key del cuerpo o envía la misma clave. Si son distintas, se usa la clave de la cabecera cuando es una clave válida; si la cabecera contiene otra cosa (el token de otra herramienta, por ejemplo), se usa la api_key del cuerpo.
• Las claves en el cuerpo siguen funcionando (client_id y api_key como JSON o campos de formulario), así que nada cambia para las apps e integraciones que las envían. La cabecera es mejor porque los cuerpos de las solicitudes acaban en registros, proxies e historiales de creadores de formularios con más frecuencia que las cabeceras.
• Los campos de formulario, las subidas multipart y los cuerpos JSON funcionan todos con la cabecera.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Probar tu clave#

Llama a Comprobar credenciales (POST /api/v1/me/) con tu clave y, si quieres, un whatsapp_client. "status": 1 con "message": "Okay" significa que funcionan juntos. No envía nada ni usa mensajes, pero no comprueba si te quedan mensajes ni si el número está conectado.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Una clave que funciona responde {"status": 1, "message": "Okay", "name": "…"}.

Volver a copiar una clave#

Haz clic en Copiar clave junto a la clave. La clave completa pasa a tu portapapeles sin mostrarse en la página; verás, por ejemplo, "“Zapier” copiada." y el botón muestra Copiado ✓ durante un momento. No necesitas una clave nueva por haber perdido la anterior.

Para saber qué clave usa una app, compara los cuatro últimos caracteres de su clave con la lista.

Eliminar una clave#

1. Haz clic en Eliminar

   Haz clic en Eliminar junto a la clave.

2. Confirma

   El diálogo "¿Eliminar “…”?" avisa: "Todo lo que use esta clave dejará de funcionar de inmediato: Zaps de Zapier, escenarios de n8n y Make, el plugin de WordPress y tus propias llamadas a la API. Dales otra clave antes. Esto no se puede deshacer." Haz clic en Eliminar clave. Verás "“…” eliminada."

A partir de ese momento, las solicitudes con esa clave reciben Auth Error: invalid api key. Lo que hizo antes se mantiene: los mensajes que puso en cola se siguen enviando (cancélalos en Reportes si hace falta) y los recordatorios que creó siguen funcionando. Un disparador Incoming WhatsApp Message de Zapier configurado con ella también sigue recibiendo mensajes, porque su webhook ya está en el número: desactiva el Zap en Zapier para detenerlo.

Reemplazar una clave#

Reemplaza una clave cuando pueda haberse filtrado, cuando se vaya alguien que podía copiarla, o de vez en cuando. No hay un botón para rotarla: crea primero la clave nueva, para que nada se detenga entretanto.

1. Crea una clave nueva

   Crea una clave y cópiala. Si tienes 10 claves, elimina antes una que ya no uses.

2. Actualiza tus apps

   Pega la clave nueva en cada app e integración que usaba la anterior y comprueba cada una, por ejemplo con Comprobar credenciales.

3. Elimina la clave anterior

   Elimínala. Deja de funcionar al instante.

4. Busca usos indebidos (tras una filtración)

   Revisa Reportes en busca de mensajes que no enviaste y cancela los que sigan pendientes. En Recordatorios, elimina los recordatorios que no creaste, porque siguen funcionando. Quita en Números de WhatsApp los números que no añadiste. Con el complemento Unibox, busca en Números de la bandeja una insignia Zapier o un webhook que no reconozcas.

Mantén tus claves seguras#

Una clave no tiene permisos propios: cualquiera que tenga una puede hacer en tu espacio de trabajo todo lo que permite la API, sea cual sea su rol. Eso incluye enviar mensajes desde cualquiera de sus números (con sus mensajes), leer su historial de mensajes, cancelar mensajes pendientes, gestionar recordatorios y archivos multimedia, verificar números y conectar números nuevos.

• Guarda las claves en tu servidor, en una variable de entorno o en el almacén de credenciales de tu integración. Nunca pongas una en el JavaScript de un sitio web, en una app móvil, en una hoja de cálculo compartida o en código que publiques.
• No envíes claves por correo ni por chat. Pégalas directamente en la app que las necesita.
• Usa una clave por app y elimina las que ya no uses.
• Reemplaza las claves de vez en cuando, y de inmediato si una puede haberse filtrado.

El Client ID por sí solo no es secreto, pero trata cada clave como una contraseña.

Claves API v2#

La API v2 tiene sus propias claves, que se crean en la tarjeta Claves API v2 de la misma pestaña. Son más seguras que las claves anteriores:

• Se muestran una sola vez. La clave completa (wbz_live_…) solo se muestra al crearla; WbizTool guarda solo una huella. Si la pierdes, revócala y crea una nueva.
• Solo lo que necesita. Marca lo que puede hacer la clave (enviar mensajes, leer mensajes, recordatorios, números, medios, verificación de números), limítala a algunos de tus números y, si quieres, ponle una fecha de caducidad.
• Claves de prueba. Una clave de prueba (wbz_test_…) comprueba cada solicitud igual que una clave real, pero no envía nada: sirve para crear y probar una integración.
• Último uso. Cada clave muestra cuándo y desde dónde se usó por última vez. Revocar la detiene al instante, junto con los endpoints de webhook que se configuraron con ella.

Las claves anteriores solo funcionan con la API v1, y las claves API v2 solo con la v2. Consulta Pasar de v1 a v2.

Firmas de webhooks#

WbizTool firma cada webhook que te envía, para que tu endpoint pueda comprobar que una solicitud de verdad viene de nosotros y no se modificó por el camino: el webhook de estado del mensaje (enviado, fallido, cancelado, caducado), los eventos de conexión del número y los webhooks de la bandeja de entrada. Los cuerpos son los mismos que antes; se añaden dos cabeceras:

La firma cubre exactamente los bytes que enviamos: los campos de formulario tal como llegan, todo el cuerpo multipart cuando se adjunta una imagen de código QR, y el JSON de los webhooks de la bandeja de entrada. Los receptores que ignoran las cabeceras siguen funcionando.

Obtener el secreto de firma#

En Configuración → Claves API, la tarjeta Secreto de firma de webhooks, bajo tus claves, muestra los cuatro últimos caracteres del secreto, como •••• b70d. Cada espacio de trabajo tiene un secreto para todos sus webhooks; se crea con el primer webhook que te enviamos.

1. Haz clic en Mostrar nuevo secreto

   Haz clic en Mostrar nuevo secreto (o en Crear secreto si el espacio de trabajo aún no tiene ninguno). El diálogo "¿Reemplazar el secreto de firma?" avisa de que el secreto actual deja de funcionar de inmediato. Haz clic en Generar nuevo secreto.

2. Cópialo

   Tu secreto de firma de webhooks muestra el secreto completo una sola vez. Haz clic en Copiar y guárdalo donde tu receptor de webhooks pueda leerlo, como una variable de entorno. No volverás a verlo: si lo pierdes, genera uno nuevo.

Solo los Propietarios ven la tarjeta. Generar un nuevo secreto reemplaza el anterior al instante, así que actualiza tus receptores justo después; los webhooks enviados entretanto no pasan tu comprobación.

Comprobar un webhook#

Calcula la firma a partir del cuerpo sin procesar (antes de que tu framework lo analice), compárala con la cabecera en tiempo constante y rechaza las marcas de tiempo de hace más de 5 minutos, para que no se pueda repetir una solicitud antigua:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Responde 2xx cuando la comprobación sea correcta y 401 cuando falle. Los webhooks de la bandeja de entrada con su propio secreto de número siguen llevando también X-Wbiztool-Signature; WbizTool-Signature es el mismo esquema en todos los webhooks.

Solución de problemas#

Relacionado#

• Primeros pasos con la API
• Resumen de la API v2
• API para comprobar credenciales
• API de envío de mensajes
• Apps e integraciones
• Configuración del espacio de trabajo, miembros del equipo y roles
• Conecta tu número de WhatsApp