API y webhooks

API y webhooks permite que los datos de tu club fluyan hacia tus propias herramientas. Crea una clave de API de solo lectura para llevar socios, tipos de membresía, eventos, pedidos y registros de entrada a una hoja de cálculo, un tablero de reportes o una aplicación a medida, y agrega endpoints de webhook para que tus sistemas se enteren de los nuevos socios, los pedidos pagados y los registros de entrada en el momento en que ocurren. También puedes conectar un asistente de IA (como Claude) para que responda preguntas sobre tu club y prepare borradores para que los revises. Encontrarás todo en la barra lateral de administración, en Sistema → API y webhooks.

Quién puede usar esto

Tienes que ser administrador de la organización: los moderadores no pueden ver esta página, y no se puede otorgar mediante un cargo directivo ni un permiso individual. Las claves de API dan acceso de lectura a toda la organización y los endpoints de webhook reciben datos de socios, así que ambos quedan solo en manos de los administradores.

La API REST y los webhooks son una función del plan Pro (incluido Enterprise); en los demás planes, esa parte de la página muestra una invitación a mejorar el plan. El acceso del asistente de IA (MCP) es distinto: funciona en todos los planes, incluido Free, porque un asistente que actúa como un administrador no es lo mismo que una salida masiva de datos.

Qué hay en la página

• Claves de API: crea claves con nombre, mira cuándo se creó y cuándo se usó por última vez cada una, y revoca cualquier clave al instante.
• Acceso del asistente de IA (MCP): crea tokens que permiten que un asistente de IA se conecte a tu organización mediante el Model Context Protocol. Elige si solo puede leer, hacer cambios o publicar; limítalo a ciertas partes del club; define un vencimiento; revócalo con un clic.
• Endpoints de webhook: agrega las URL HTTPS a las que debemos avisar, elige qué eventos recibe cada una, pausa o reanuda, envía un evento de prueba o elimina un endpoint. Cada endpoint tiene su propio secreto de firma, que se muestra en la página.
• Envíos recientes: los últimos 20 envíos de webhooks con su evento, estado, cantidad de intentos y hora en que entraron en la cola.

Paso a paso

Crear una clave de API y hacer tu primera solicitud

1. En Claves de API, ponle a la clave un nombre que diga dónde se va a usar (p. ej., Hoja de cálculo de reportes) y haz clic en Crear clave.
2. Copia la clave completa del banner verde de inmediato: por seguridad solo guardamos una huella, así que la clave se muestra esta única vez y nunca más.
3. Llama a cualquier endpoint con la clave en el encabezado Authorization:

curl -H "Authorization: Bearer chk_..." https://clubhelix.com/api/v1/members

4. Endpoints disponibles (todos GET, en JSON, paginados con ?limit= hasta 100 y ?offset=):
   • /api/v1/members: tu padrón (estado, fecha de alta, fecha de pago al día, nombre y correo electrónico)
   • /api/v1/membership-types: tus tipos de membresía activos
   • /api/v1/events: los eventos publicados (agrega ?upcoming=true para ver solo los futuros)
   • /api/v1/orders: resumen de los pedidos de membresías, de la tienda y de entradas, los más recientes primero
   • /api/v1/checkins: registros de asistencia

Usar la API pública de lectura (sin clave)

Todo lo que ya es público en tu sitio web también se puede leer en JSON, sin clave y en todos los planes. Úsala para mostrar tus últimas noticias o tus próximos eventos en otro sitio, en una pantalla de avisos o en una aplicación.

curl https://clubhelix.com/api/public/v1/your-club/events

Reemplaza your-club por la dirección de tu organización (la parte que va después de /group/). Si tienes un dominio propio, la misma ruta funciona también ahí, solo para tu propia organización.

• news: las noticias publicadas, las más recientes primero
• events: los eventos públicos, por defecto los próximos; agrega ?from=2026-10-01&to=2026-12-31 para un rango de fechas
• fixtures: los partidos públicos; agrega ?timeframe=results para ver los resultados recientes
• sponsors, teams: tal como aparecen en tu sitio
• pages: una lista de tus páginas públicas publicadas (solo títulos y direcciones)
• club: tu nombre, logotipo, redes sociales, colores del tema y locale, el idioma en que está escrito tu sitio (como en-AU o es)

Agrega ?limit= para obtener hasta 50 elementos (por defecto son 10; los partidos llegan hasta 20 y los equipos hasta 24). Las noticias y los eventos también aceptan ?category= y ?tag= con el slug de una categoría o etiqueta. Todas las respuestas tienen la forma { "data": ..., "truncated": true }, donde truncated indica que había más elementos de los que pediste. Las horas están en UTC.

Nunca se incluye nada privado: los eventos y páginas solo para socios, los borradores y los datos de contacto quedan fuera, exactamente igual que para un visitante que no inició sesión.

Cuando algo sale mal, ambas API responden con { "error": { "code": ..., "message": ... } }. Revisa el code: nunca cambia. El message está escrito para una persona y sigue el encabezado Accept-Language de la solicitud cuando tu idioma está disponible.

Agregar un endpoint de webhook

1. En Endpoints de webhook, ingresa la URL HTTPS en la que escucha tu sistema. Tiene que ser una dirección pública de internet que ya se resuelva: no guardamos ni enviamos a una dirección interna o privada, a una URL con usuario o contraseña, ni a un puerto distinto del 443.
2. Marca los eventos que quieres recibir, o deja todas las casillas sin marcar para recibirlos todos.
3. Elige un formato de firma. Déjalo en v2, salvo que tu receptor se haya escrito para el formato v1, más antiguo (mira más abajo).
4. Haz clic en Agregar endpoint. Anota el secreto de firma que aparece en la tarjeta del endpoint: tu receptor lo usa para verificar los envíos.
5. Haz clic en Enviar evento de prueba para poner en cola un envío test.ping y mira cómo llega a Envíos recientes (los envíos salen cada pocos minutos; los que fallan se reintentan hasta 5 veces).

Verificar la firma de un webhook

Cada envío es un POST en JSON con un encabezado X-ClubHelix-Event (el tipo de evento) y un encabezado X-ClubHelix-Signature. La tarjeta de cada endpoint indica qué formato de firma usa.

v2 (el predeterminado para los endpoints nuevos). El encabezado de firma se ve así: t=1759449600,v2=5f2c…. Contiene una marca de tiempo Unix y un HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto, el identificador del envío del encabezado X-ClubHelix-Delivery, otro punto y el cuerpo sin procesar, con el secreto de tu endpoint como clave. El identificador del envío forma parte de lo que se firma, así que nadie puede reenviar un envío capturado con otro identificador para saltarse tu control de duplicados. Verifícalo así:

t, v2 = parse(header["X-ClubHelix-Signature"])
delivery_id = header["X-ClubHelix-Delivery"]
if abs(now_unix() - t) > 300:
    reject the request            # older than five minutes: a replay
expected = hmac_sha256_hex(secret, t + "." + delivery_id + "." + raw_request_body)
if not constant_time_equals(expected, v2):
    reject the request
if already_seen(delivery_id):
    ignore it                     # a retry of one you already handled

v1 (endpoints agregados antes de la v2). El encabezado es un HMAC-SHA256 en hexadecimal solo del cuerpo sin procesar:

expected = hmac_sha256_hex(secret, raw_request_body)
if not constant_time_equals(expected, header["X-ClubHelix-Signature"]):
    reject the request

Una firma v1 no tiene marca de tiempo, así que quien capture un envío puede volver a mandártelo más tarde. Los endpoints existentes siguen en v1 para que sus receptores sigan funcionando. Para pasar uno a v2, agrega un endpoint nuevo, actualiza tu receptor y luego elimina el anterior.

Calcula siempre el HMAC sobre los bytes sin procesar del cuerpo, antes de interpretar el JSON.

Revocar o rotar una clave

1. Haz clic en Revocar junto a la clave: deja de funcionar de inmediato.
2. Para rotarla, crea primero una clave nueva, cambia tu integración a esa clave y luego revoca la anterior.

Conectar un asistente de IA (MCP)

1. En Acceso del asistente de IA (MCP), ponle al token el nombre del lugar donde se va a usar (p. ej., Claude en la laptop de la secretaría) y elige un vencimiento: 90 días es una buena opción por defecto.
2. Elige qué puede hacer. Con las dos casillas desmarcadas es un asistente de solo lectura que responde preguntas. Permitir cambios le permite crear y editar páginas, noticias y eventos. Permitir publicar además le permite hacer público ese trabajo. La mayoría de los clubes empiezan con los cambios activados y la publicación desactivada, así que una persona sigue siendo quien presiona publicar.
3. Si quieres, abre Limita a qué puede acceder este token y marca algunas áreas. Si no marcas nada, el token puede hacer todo lo que tú puedes hacer. Si marcas solo "Publicar noticias", puede escribir en tu página de noticias y nada más: ni la tienda ni tus socios.
4. Copia el token del banner verde de inmediato: igual que las claves de API, se muestra una sola vez y nunca más.
5. En el asistente, agrega la conexión con el comando que aparece en Conectar Claude Code en la página (el token viaja en un encabezado Authorization; nunca lo pegues en un mensaje del chat). Consulta Conectar un asistente de IA para ver la configuración en otras herramientas y la regla que te dice de antemano si una herramienta determinada puede conectarse.
6. Pruébalo: pídele al asistente que "resuma nuestra membresía" y luego que "redacte una noticia sobre el partido del sábado". Pregúntale "¿qué puedes hacer aquí?" y te dirá exactamente qué facultades tiene este token.

Lo que el token nunca puede hacer, por diseño:

• Solo ve tu organización. El token está fijado a tu club: cualquier pregunta sobre otra organización se rechaza, y la misma seguridad a nivel de fila que protege el área de administración se aplica a cada solicitud por debajo.
• Nunca puede hacer más que tú. Un token actúa como el administrador que lo creó, así que está limitado a los permisos de esa persona, que se vuelven a comprobar en cada solicitud. Marcar casillas solo puede quitar facultades, nunca agregarlas.
• Nunca envía correos ni mueve dinero. Las difusiones siguen esperando sin enviar en el editor hasta que elijas un público, y nada relacionado con pagos, reembolsos o registros de socios se puede cambiar mediante un token.
• No pasa nada sin una confirmación. Cada cambio se muestra antes en una vista previa: el asistente muestra exactamente lo que haría y solo actúa cuando se le dice una segunda vez que siga adelante.
• Deja de funcionar cuando tú dejas de tener acceso. Si el administrador que lo creó pierde su rol de administrador, el token deja de funcionar de inmediato: el rol se vuelve a comprobar en cada solicitud. Revocarlo en esta página también es instantáneo. Cambiar de plan no lo afecta.
• Nunca puede cambiar tu suscripción. Los planes, la facturación y la configuración de pagos son herramientas del personal de la plataforma; ningún token de organización llega a ellas, marques lo que marques.
• Cada acción queda registrada. Todo lo que el asistente lee o cambia queda en el registro de auditoría a nombre del administrador que lo creó.

Referencia de campos

Tipos de eventos de webhook:

Los eventos de contenido avisan a otro sitio web (por ejemplo, tu sitio de WordPress) de que cambió algo que muestra, para que pueda actualizarse:

Todos los contenidos de los envíos tienen la misma forma: { "event": "...", "tenant_id": "...", "data": { ... }, "created_at": "..." }. En los eventos de pagos, socios y registros de entrada, data es una pequeña copia del registro (identificadores, estado, montos; puedes obtener más detalles desde la API usando los identificadores). En los eventos de contenido, data es solo { "id": "...", "updated_at": "..." }: tu sistema obtiene el elemento por su cuenta, así que en un evento de contenido nunca viaja nada sobre las personas.

Consejos y preguntas frecuentes

La clave que creé desapareció, ¿dónde la encuentro? No se puede: la clave completa se muestra una sola vez al crearla y solo se guarda una huella. Crea una clave nueva y revoca la anterior.

¿Por qué recibo respuestas 403? La API requiere el plan Pro o Enterprise. Si tu club pasó a un plan inferior, las claves existentes dejan de funcionar hasta que vuelvas a mejorar el plan.

¿Por qué recibo respuestas 429? Cada clave tiene un límite de 120 solicitudes por minuto. Haz tus solicitudes más despacio o repártelas: el encabezado Retry-After indica cuánto esperar.

¿La API puede cambiar o eliminar datos? No. Las claves de la versión 1 son estrictamente de solo lectura, y cada clave está limitada a tu organización.

Marqué una reserva como pagada en la sede, ¿por qué no hubo webhook? Los eventos .paid se disparan cuando un pago con tarjeta pasa por tu proveedor de pagos. El dinero que registras tú en la administración, como Marcar como pagada en una reserva de instalación, se guarda en la reserva pero no envía nada a tus endpoints. Marcar a un socio como pagado es la excepción: eso dispara member.updated.

Un envío aparece como Fallido, ¿se va a reintentar? Cada envío se reintenta hasta 5 veces. Después del quinto fallo se detiene; corrige tu endpoint y usa Enviar evento de prueba para confirmar que vuelve a funcionar.

¿Cuál es la diferencia entre una clave de API y un token de MCP? Una clave de API (chk_…) es para tus propios scripts y herramientas: REST simple, de solo lectura. Un token de MCP (chmx_…) es para asistentes de IA: usa el Model Context Protocol, puede hacer y publicar cambios si lo permites, y actúa como el administrador que lo creó.

¿El asistente puede cambiar nuestro sitio web? Sí, si se lo permites. Con Permitir cambios activado puede crear y editar páginas, noticias y eventos; con Permitir publicar activado puede hacerlos públicos y volver a quitarlos. Deja la publicación desactivada y todo lo que escriba esperará a que una persona lo revise. En cualquier caso, muestra cada cambio en una vista previa y pregunta antes de actuar.

¿Puede enviar correos a nuestros socios? No. Las difusiones solo se redactan: quedan sin enviar en el editor hasta que elijas un público y las envíes tú. Los pagos, los reembolsos y los registros de socios también quedan fuera de su alcance.

¿Puedo darle a un asistente una sola tarea? Sí. En Limita a qué puede acceder este token, marca solo las áreas que necesita. Un token limitado a "Publicar noticias" es rechazado en todo lo demás, y el rechazo dice qué permiso faltaba; así puedes darle a un asistente la página de noticias y a otro todo el sitio web, cada uno con su propio token.