API de administración: gestiona clientes y números desde tu sistema

En resumen: una clave de administración hace por API lo que el dueño de la cuenta hace en el panel de ZapClaw. Tu sistema crea el cliente, genera su clave de API, envía el enlace de conexión, configura el webhook (también en modo Chatwoot) y lee el número en cuanto se conecta. Tus clientes nunca abren ZapClaw.

Qué puede hacer una clave de administración

• Clientes (cuentas de agencia): crear, renombrar, archivar y reactivar, cada uno con tu propio externalId.
• Enlaces de conexión: la página donde tu cliente entra con Facebook y escanea el código QR, con un botón opcional para volver a tu sistema.
• Números: estado, límites, Phone Number ID y WABA ID; renombrar, desconectar y mover entre clientes.
• Claves de API de los clientes: crear y revocar las claves zc_live_ con las que envían tus integraciones.
• Webhooks: tu propio endpoint o Chatwoot, el secreto de firma, pruebas y reenvíos.
• Todo lo que ya hace la clave de un cliente, en cualquier cliente: plantillas, envíos, archivos, perfil, códigos QR, uso y registros.
• Eventos de la cuenta en un webhook tuyo: número conectado, desconectado o restringido, enlace vencido.

Algunas cosas se quedan a propósito con una persona en el panel: la contraseña y la verificación en dos pasos, eliminar la cuenta, facturación y pagos, aceptar términos y aprobar lo que un agente de IA quiere enviar.

Autenticación

Envía la clave en el encabezado X-API-Key. Las rutas de administración están en https://api.zapclaw.app/api/v1/admin e indican el cliente en la ruta. En las rutas que ya llama la clave de un cliente, agrega X-Client-Id para decir en qué cliente actúas.

curl https://api.zapclaw.app/api/v1/admin/clients \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY"

Una clave de administración enviada en la URL se rechaza y se marca como expuesta. Una clave con lista de IP solo atiende llamadas desde esas direcciones.

Permisos

Cada clave tiene solo los permisos marcados al crearla. Administración completa los marca todos; Conectar y configurar clientes marca lo que necesita un flujo de alta.

• clients:read, clients:write: ver y cambiar clientes.
• numbers:read, numbers:write: números, estado y límites; renombrar, desconectar, mover, perfil, códigos QR, automatizaciones y bloqueos.
• links:read, links:write: enlaces de conexión y su historial.
• keys:read, keys:write: claves de API de los clientes.
• webhooks:read, webhooks:write, webhooks:secret: webhooks, entregas y el secreto de firma.
• templates:read, templates:write, messages:read, messages:send: plantillas y mensajes de cualquier cliente.
• usage:read, billing:read, audit:read: uso, límites por cliente, registros, plan, facturas y la actividad de la cuenta (la facturación es solo de lectura).

Endpoints principales

GET    /api/v1/admin/key                                        the calling key
GET    /api/v1/admin/clients                                    clients:read
POST   /api/v1/admin/clients                                    clients:write
PATCH  /api/v1/admin/clients/{clientId}                         clients:write
POST   /api/v1/admin/clients/{clientId}/keys                    keys:write
POST   /api/v1/admin/clients/{clientId}/links                   links:write
GET    /api/v1/admin/clients/{clientId}/links/{linkId}          links:read
GET    /api/v1/admin/clients/{clientId}/numbers                 numbers:read
PUT    /api/v1/admin/clients/{clientId}/webhooks/{mode}         webhooks:write
GET    /api/v1/admin/clients/{clientId}/webhooks/{mode}/secret  webhooks:secret
GET    /api/v1/admin/clients/{clientId}/numbers/{numberId}/chatwoot-inbox numbers:read + webhooks:secret
PUT    /api/v1/admin/event-endpoint                             webhooks:write
GET    /api/v1/admin/activity                                   audit:read

Los cuerpos, respuestas y errores de cada ruta están en la referencia de la API y en openapi.yaml.

Los secretos se muestran una vez

Una clave de administración, una clave de cliente o un enlace de conexión nuevos se devuelven una vez, en la respuesta que los crea, y ZapClaw guarda solo su hash. El secreto de firma del webhook es el único que puedes volver a leer, con webhooks:secret, y cada lectura aparece en la actividad de la cuenta.

Entérate de cuándo se conecta un número

Registra un webhook de eventos de la cuenta y ZapClaw le envía, firmado en el encabezado X-ZapClaw-Signature con su propio secreto: client_link.used, number.connected, number.disconnected, number.restricted y client_link.expired. También puedes consultar el enlace: su status pasa a connected y muestra el número.

Seguridad

• Solo el dueño o un administrador crea una clave, confirmando con la contraseña y, si está activa, el código de la verificación en dos pasos. El dueño recibe un correo.
• Hasta 10 claves de administración activas por cuenta. Una clave revocada deja de funcionar al instante.
• Cada cambio hecho con una clave aparece en Configuración, Actividad, con el nombre de la clave.
• Una clave nunca llega a otra cuenta, y cada cliente que indica se comprueba contra la tuya.
• Cuando quien creó la clave deja de ser dueño o administrador, la clave deja de funcionar.