# Integraciones y APIs

> Claves de API personales para que tu CRM, una automatización (n8n, Zapier, Make) o un script llamen a la API de la comunidad, y webhooks que avisan a esos sistemas cuando algo ocurre. Módulos y niveles, el secreto que aparece una vez, IPs permitidas, revocar, crear, editar y probar un webhook, entregas, reenvío, las integraciones listas, el bloque Uso y lo que ninguna clave alcanza.

En **Integraciones y APIs** conectas la comunidad con otros sistemas: *"tu CRM, una automatización o un script llaman a la API con una clave tuya."* La clave sustituye al inicio de sesión en las llamadas a la [API](/api/introducao) y solo hace lo que marques.


Son tres vistas, en el selector de arriba (quien solo ve las claves no ve el selector):

- **Claves de API**: tu sistema llama a Memberfy. El equipo siempre; los miembros, si el propietario lo permite.
- **[Webhooks](#webhooks)**: Memberfy avisa a tu sistema cuando alguien entra, compra, se suscribe, se inscribe en un evento o termina un curso. Propietario y administrador.
- **[Integraciones](/integracoes/integracoes-prontas)**: apps listas, hechas por Memberfy (Discord, Slack, Telegram, RD Station, HubSpot y los atajos para Zapier, Make y n8n). Propietario y administrador.

![Configuración › Integraciones y APIs › Nueva clave](/screens/integracoes-nova-chave.png "La matriz de módulos × leer / crear y editar / eliminar y acciones destructivas, con marcar todo por columna. Sin nada marcado, la clave no hace nada.")

## Dónde está

| Qué | Dónde |
|---|---|
| **Tus** claves (cualquier rol) | **Mi Cuenta**, sección **Claves de API** (`/account?tab=apiKeys`) |
| Las claves de todos, los webhooks y las integraciones (propietario y administrador) | **Configuración › Integraciones y APIs** |

**Claves de API para miembros.** En **Configuración › Integraciones y APIs**, el propietario decide con **Los miembros pueden crear claves de API**, desactivado por defecto en todas las comunidades, incluidas las que ya existían: quien no es del equipo deja de ver sus claves, y las que ya tiene dejan de funcionar (no se eliminan). Volver a activarlo devuelve esas claves tal como estaban. El administrador ve la opción bloqueada (*"Solo el owner de la comunidad puede cambiar esta opción."*), y el equipo (propietario, administrador, moderador y finanzas) siempre puede crear sus propias claves. Con la opción desactivada, un miembro que abre **Claves de API** ve *"Las claves de API no están disponibles para miembros"*.

Las claves nunca van más allá de lo que tu rol ya permite, así que permitirlo a los miembros no abre nada nuevo: un miembro puede, por ejemplo, llevar sus propias reservas a su agenda.

## Cómo funciona

### La clave es tuya

Cada clave te pertenece, en esta comunidad, y actúa en tu nombre: lo que crea queda contigo como autor. El permiso de cada llamada es **lo que la clave tiene marcado y, a la vez, lo que tu rol permite hoy**:

- Marcar un módulo al que no tienes acceso no libera nada (*"La clave nunca va más allá de lo que tu rol permite: marcar un módulo no da un acceso que no tienes."*).
- Si tu rol baja, la clave se reduce con él.
- Si sales o te eliminan de la comunidad, la clave se detiene (**Detenida**).
- Puedes tener hasta **5 claves activas**.

### Módulos y niveles

La matriz tiene una fila por cada uno de los **33 módulos** de la comunidad y tres columnas, independientes:

| Columna | Qué libera |
|---|---|
| **Leer** | Consultar: listas, detalles, informes |
| **Crear y editar** | Crear y modificar |
| **Eliminar y acciones destructivas** | Eliminar, y las acciones que retiran algo o deshacen (lista abajo) |

Cada columna tiene **marcar todo**. **Sin nada marcado, la clave no hace nada**: por defecto es cero, y cada módulo hay que liberarlo a propósito. Las columnas no se suman: una clave con solo **Eliminar y acciones destructivas** en un módulo no lee ni edita en él.

Los módulos: Comunidad y espacios, Miembros, Feed, Votaciones, Contenido, Eventos, Cursos, Certificados, Galería, Archivos subidos, Call4papers, Clasificados, Descargas, Tienda y productos, Ventas y suscripciones, Finanzas (lectura), Informes y registros, Campañas, Encuestas, Upvote, Canales, Gamificación, Moderación, Reservas, Agenda, Networking, Automatizaciones, Asistencia, Visitantes, Paquetes, Soporte, Empresas y Mis preferencias.

**Automatizaciones** es solo de lectura con clave: **Leer** lista y consulta los workflows, las versiones, el historial de ejecuciones y las entregas; crear, editar, activar, pausar, ejecutar, probar, cancelar, aprobar y limpiar rechazan la clave (`403` `API_KEY_BLOCKED`) y quedan solo en la app y en el asistente de IA.

### Lo que pide «Eliminar y acciones destructivas»

Además de eliminar, estas acciones piden la tercera columna, aunque no sean una eliminación:

| Módulo | Acciones |
|---|---|
| Ventas y suscripciones | Cancelar una suscripción (la tuya o, desde el equipo, la de otra persona) |
| Tienda y productos | Despublicar un producto |
| Miembros | Rechazar la invitación de la comunidad; sustituir la lista entera de etiquetas o de campos de una persona; rechazar una solicitud de registro |
| Cursos | Salir de un curso |
| Certificados | Revocar un certificado; archivar una plantilla |
| Call4papers | Despublicar y cerrar la convocatoria; retirar y rechazar propuestas; rechazar la invitación de evaluador o de dueño |
| Votaciones | Cerrar una votación |
| Eventos | Detener la transmisión en directo |
| Descargas | Sustituir el archivo de un elemento |
| Reservas | Cancelar una reserva |
| Campañas | Cancelar una campaña; restaurar un correo automático al texto predeterminado |
| Soporte | Cancelar un ticket; dejar fuera de uso la sala o el recurso del ticket (la simulación, antes de confirmar, queda en **Crear y editar**) |
| Moderación | Cada decisión de moderación (aprobar, rechazar, devolver a la cola) |
| Empresas | Rechazar la invitación de una empresa; cerrar una empresa |
| Paquetes | Descartar un paquete |
| Networking | Rechazar la entrada de alguien en el programa; rechazar una sesión |

### Lo que ninguna clave alcanza

Aunque esté todo marcado, la clave recibe *"Esta acción no acepta clave de API."* en:

- **Dinero**: reembolso, retiro, datos de cobro, Información Comercial y documentos (KYC), checkout y compra, tarjetas guardadas, compra de adicional (por el miembro o por el equipo), cambio de plan, **Pagar ahora** y la oferta de downsell.
- **Cuenta**: inicio de sesión, contraseña, recuperación de contraseña, correo y teléfono.
- **SuperAdmin**: las pantallas de gestión de la plataforma.
- **El asistente de IA**: la conexión MCP y su autorización.
- **Las propias claves**: una clave no crea, edita ni revoca claves. Eso solo se hace en la pantalla, con tu sesión iniciada.
- **Áreas privadas**: Mensajes, notificaciones, las [notificaciones en el navegador y en el móvil](/conceitos/notificacoes-no-navegador) (dispositivos y preferencias), Feedbacks, plan de desarrollo, Reconocimiento, Control horario y Mejorar con IA.
- **Secretos de automatizaciones e integraciones**: el cofre de secretos de terceros, las direcciones de entrada de los disparadores de webhook de las automatizaciones y los hooks de workflow.
- **Actuar como otro miembro** (la cabecera `X-MemberId`).

Lo demás sigue con las reglas de siempre: lo que tu rol no puede hacer en la pantalla, la clave tampoco.

## Paso a paso: crear una clave

*Rol: cualquiera.*

1. Abre **Integraciones y APIs** (ver [Dónde está](#donde-esta)) y haz clic en **Nueva clave**.
2. Ponle un **Nombre** (*"Ej.: CRM, n8n, agenda"*).
3. **Vencimiento** (opcional): una fecha en la que la clave se detiene sola. *"En blanco, la clave vale hasta que se revoque."*
4. En **Lo que la clave puede hacer**, marca solo los módulos y las columnas que necesita la integración.
5. **IPs permitidas** (opcional): una por línea, IPv4, IPv6 o rango CIDR, hasta **20**. *"En blanco, la clave acepta llamadas desde cualquier IP."*
6. Haz clic en **Crear clave**.
7. Copia la clave y guárdala en un gestor de secretos. Haz clic en **Ya la copié**.

> [!WARNING]
> *"Esta es la única vez que aparece la clave. No se mostrará de nuevo; si la pierdes, revócala y crea otra."* Después, la lista muestra solo el inicio de la clave (`mfk_7Hq2Lx9a…`), que sirve para reconocerla.

La pantalla también muestra las cabeceras que van en cada llamada: `X-Api-Key` con la clave y `X-CommunityId` con la comunidad. Consulta [Autenticación › Clave de API](/api/autenticacao#clave-de-api).

## Gestionar las claves

Haz clic en una clave de la lista para abrir el detalle: **Inicio de la clave**, **Dueño**, **Creada el**, **Vencimiento**, **Último uso** y **Lo que la clave puede hacer**.

| Situación | Qué muestra |
|---|---|
| **Activa** | *"La clave está funcionando."* |
| **Vencida** | La fecha de vencimiento pasó |
| **Revocada** | Alguien revocó la clave (con la fecha y quién la revocó) |
| **Detenida** | El dueño salió de la comunidad |

- **Nombre e IPs permitidas**: el dueño cambia el nombre y las IP en cualquier momento, sin volver a crear la clave. El detalle muestra la **Última IP rechazada** y cuándo.
- **Módulos**: no se editan. *"Para cambiarlos, crea otra clave y revoca esta."*
- **Uso**: las llamadas hechas con la clave en el mes actual y en los 6 anteriores.
- **Revocar clave**: la clave deja de funcionar en la próxima llamada, y no se puede deshacer. El historial de uso y los registros se mantienen.

### Propietario y administrador: todas las claves

Propietario y administrador alternan entre **Mis claves** y **Todas de la comunidad**. En **Todas de la comunidad** aparecen las claves de todo el mundo, con el dueño, los módulos, el último uso y la situación (nunca el secreto), y pueden **revocar** cualquiera. Cambiar el nombre y las IP sigue siendo solo del dueño.

### El bloque Uso

Debajo de las claves, propietario y administrador ven **Uso**: *"Llamadas a la API hechas con clave y webhooks entregados, por mes (UTC)."* Son el mes actual y los 6 anteriores; abre un mes para ver las llamadas por clave y por dueño.

Cuentan las llamadas hechas con una clave válida. No cuentan las rechazadas antes de llegar a la ruta: clave no válida, revocada o vencida, acción que no acepta clave, IP fuera de la lista y llamada por encima del límite por minuto. **Webhooks entregados** cuenta cada evento entregado con éxito a un [webhook](#webhooks); la prueba (**Enviar prueba**) no cuenta.

### El tope de Memberfy

El equipo de Memberfy ([SuperAdmin](/conceitos/papeis-e-permissoes#superadmin)) ve el uso de cada comunidad en su detalle, en la tarjeta **Integraciones y APIs**, y puede guardar un **Tope de llamadas por mes**, un **Tope de webhooks por mes** y el **Modelo previsto** (paquete de solicitudes o cuota fija mensual). Por ahora eso *"solo se guarda: no se bloquea ni se cobra nada, y la comunidad no ve el tope"*. Superar el tope solo muestra el aviso *"Por encima del tope este mes."* a Memberfy; la comunidad sigue usando la API con normalidad.

## Webhooks

*Rol: propietario y administrador.*

Un webhook avisa a otro sistema en el momento en que algo ocurre en la comunidad: *"Avisa a otro sistema en el momento en que algo ocurre en la comunidad."* Memberfy envía un `POST` firmado a la URL que registres, y tu CRM, Zapier, Make, n8n o un script hacen el resto. Quien escribe el código que lo recibe encuentra el formato, la firma y los reintentos en [Webhooks para quien integra](/api/webhooks).

![Configuración › Integraciones y APIs › Webhooks › Nuevo webhook](/screens/integracoes-novo-webhook.png "La URL de destino, la descripción y los eventos por familia, la familia entera o uno a uno, y el aviso de datos personales.")

### Los eventos

Son 97 eventos en 27 familias (los dos de niveles y puntos, `member.level_changed` y `member.points_changed`). Por tema:

| Tema | Familias |
|---|---|
| Personas | `member`, `message`, `badge` |
| Dinero | `purchase`, `subscription`, `checkout`, `coupon` |
| Eventos y asistencia | `event`, `booking`, `attendance`, `visitor`, `parcel` |
| Aprendizaje | `course`, `lesson`, `quiz`, `certificate` |
| Contenido y espacios | `post`, `comment`, `reaction`, `space`, `download`, `classified`, `upvote` |
| Formularios y solicitudes | `form`, `survey`, `proposal`, `support_ticket` |

Marca la **familia entera** para recibir también los eventos que entren en ella después, o elige uno a uno. La lista completa está en [Webhooks para quien integra](/api/webhooks), y lo que lleva cada evento, en [Eventos de webhook](/api/eventos-de-webhook). Un miembro importado desde una hoja de cálculo también dispara `member.joined`, con `source: "import"`.

### Paso a paso: crear un webhook

1. En **Integraciones y APIs**, elige **Webhooks** en el selector de arriba y haz clic en **Nuevo webhook**.
2. **URL de destino**: *"Solo https, en una dirección pública."* Zapier, Make y n8n te dan esta URL al crear un disparador de webhook.
3. **Descripción** (opcional): *"Ej.: CRM, n8n, hoja de cálculo"*.
4. **Eventos**: marca las familias o los eventos.
5. **Enviar desde IPs fijas** (opcional): para destinos que solo aceptan direcciones conocidas. Las entregas pasan a salir de dos IPs, que la opción muestra; ver [IPs fijas](/api/ips-fixos).
6. Lee el aviso: *"Los eventos llevan datos personales de los miembros, como nombre, correo electrónico y teléfono, al destino. Usa solo una dirección de confianza."*
7. Haz clic en **Crear webhook**, copia el secreto (`whsec_…`) y guárdalo en el sistema de destino.

> [!WARNING]
> *"Esta es la única vez que aparece el secreto. Cópialo ahora; si lo pierdes, rótalo para generar otro."* El secreto sirve para que el destino compruebe que la entrega vino de verdad de Memberfy.

La comunidad puede tener hasta **10 webhooks**; la lista muestra cuántos existen ya (*"3 de 10 webhooks de la comunidad."*). En el límite, elimina uno para crear otro.

### Gestionar un webhook

La lista muestra cada webhook con la URL (enmascarada en el medio), los eventos, el estado y la última entrega. Haz clic en uno para abrir el detalle: **URL**, **Eventos**, **IPs fijas**, fecha de creación, **Última entrega con éxito** y, cuando los hay, **Fallos seguidos**.

| Estado | Qué significa |
|---|---|
| **Activo** | *"El webhook está recibiendo los eventos marcados."* |
| **Desactivado** | Alguien lo desactivó; no se envía ningún evento hasta que se reactive |
| **Desactivado por fallos** | El destino falló durante demasiado tiempo y Memberfy desactivó el webhook (ver abajo) |

Las acciones del detalle:

- **Enviar prueba**: envía un evento de prueba (`ping`) ahora y muestra la respuesta del destino (*"Prueba entregada: HTTP 200 en 180 ms."*). No se reintenta y no cuenta en el uso.
- **Editar**: cambia la URL, la descripción, los eventos y la opción **Enviar desde IPs fijas**, sin cambiar el secreto (ver [Editar un webhook](#editar-un-webhook)).
- **Rotar secreto**: genera un secreto nuevo, que aparece una vez. *"El secreto actual deja de valer en el acto"*: actualiza el destino enseguida.
- **Desactivar**: las entregas se detienen en el acto y los intentos pendientes se cancelan. Lo que ocurra mientras esté desactivado no se envía después.
- **Reactivar**: *"Reactivar envía una prueba antes: el webhook solo vuelve si el destino responde con éxito."*
- **Eliminar**: el webhook deja de recibir eventos, los intentos pendientes se cancelan y no se puede deshacer.

Rotar, desactivar y eliminar piden confirmación.

### Editar un webhook

En el detalle, haz clic en **Editar**: *"Cambia la URL, la descripción, los eventos o las IP fijas. El secreto sigue siendo el mismo."* Ajusta y haz clic en **Guardar cambios**.

- *"Las entregas ya en curso siguen yendo al destino anterior; solo los eventos nuevos usan la nueva configuración."* Los reintentos y reenvíos de una entrega antigua siguen con la URL y la opción de IPs fijas con que se creó.
- **Cambiar la URL pone a cero los fallos seguidos**, porque es otro destino. La URL nueva pasa por la misma comprobación que en la creación.
- **Editar no reactiva.** Un webhook **Desactivado** o **Desactivado por fallos** sigue desactivado tras guardar (*"Cambios guardados. Editar no reactiva un webhook desactivado."*); usa **Reactivar**, que envía una prueba antes.
- El **Historial de cambios** registra cada edición con el antes y el después de cada campo (URLs enmascaradas).

### Entregas

La sección **Entregas** del detalle lista cada envío: el evento, el estado (**Pendiente**, **Entregada**, **Falló**, **Cancelada**), el número de intentos y la respuesta. Filtra por estado y por evento (**Todos los eventos**, o **Prueba (ping)**).

Abre una entrega para ver el identificador (`webhook-id`), el **Cuerpo enviado** y cada intento, con el estado HTTP y el tiempo (*"HTTP 500 en 312 ms"*), y cuándo será el siguiente. **Reenviar** envía la entrega de nuevo, con el mismo identificador, en una nueva serie de intentos; una entrega aún en curso no se puede reenviar.

Cuando el destino falla, Memberfy lo intenta de nuevo después de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Si el destino responde `410`, o pasa **72 horas sin ninguna entrega con éxito**, el webhook queda **Desactivado por fallos**, y el propietario y los administradores reciben un correo. Revisa el destino y haz clic en **Reactivar**. Los detalles están en [Webhooks › Reintentos](/api/webhooks#reintentos).

Las entregas se guardan durante 30 días.

### Historial de cambios

Debajo de la lista, el **Historial de cambios** muestra *"Quién creó, editó, probó, desactivó, reactivó, rotó o eliminó un webhook o una integración, y cuándo"*, incluido **Sistema** cuando Memberfy desactiva un webhook por fallos (*"Desactivado automáticamente por fallos"*). El detalle de cada webhook tiene la pestaña **Cambios**, solo con los suyos. El historial se guarda durante 30 días.

## Ejemplos

**Zapier avisa al equipo de cada compra.** Julia, propietaria, crea en Zapier un disparador *Webhooks by Zapier*, copia la URL y crea en Memberfy el webhook *Zapier ventas* con la familia **Compras**. Hace clic en **Enviar prueba**, Zapier recibe el `ping` y, a partir de ahí, cada compra completada se convierte en un mensaje en el canal del equipo, con el nombre y el correo de quien compró.

**El CRM que rechaza IPs desconocidas.** El firewall del CRM solo acepta direcciones permitidas. Rafael crea el webhook con **Enviar desde IPs fijas**, permite las dos [IPs fijas](/api/ips-fixos) en el CRM y envía una prueba. Cuando el CRM se cae un fin de semana, las entregas vuelven solas con los reintentos; las que agotaron los intentos las reenvía desde la sección **Entregas**.

**Las reservas del miembro en su agenda.** Carla, miembro de un coworking, crea la clave *Agenda* con **Leer** en **Reservas** y nada más. Su script lee sus propias reservas y arma el calendario. Si el script intenta cancelar una reserva, la API lo rechaza: falta **Eliminar y acciones destructivas** en **Reservas**.

**El CRM del equipo de ventas.** Rafael, administrador, crea la clave *CRM* con **Leer** en **Miembros** y en **Ventas y suscripciones**, y las IP del servidor del CRM. El CRM trae los suscriptores nuevos cada hora. Reembolsar desde el CRM no funciona, ni con todo marcado: el dinero, solo en la pantalla.

**La automatización que publica en el Feed.** El n8n de la comunidad usa una clave con **Crear y editar** en **Feed**. Cuando la clave se filtra en una captura de pantalla, el propietario abre **Todas de la comunidad**, revoca la clave y la siguiente llamada de n8n ya se rechaza. El dueño crea otra.

## Preguntas frecuentes

**¿Por qué la clave recibe "no tiene permiso" en un módulo que marqué?**
Dos causas: la columna marcada no es la de la acción (cancelar pide **Eliminar y acciones destructivas**, no **Crear y editar**), o tu rol no puede hacerlo ni en la pantalla. La clave nunca va más allá de tu rol.

**Perdí la clave. ¿Puedo verla de nuevo?**
No. Revócala y crea otra.

**¿Cuántas llamadas puedo hacer?**
Hasta 120 por minuto, sumando todas tus claves en esta comunidad. Por encima de eso, la API pide esperar unos segundos. Consulta [Autenticación › Límite](/api/autenticacao#limite-de-llamadas).

**¿Se pueden crear o revocar claves desde el asistente de IA?**
No. El asistente lista las claves (las tuyas y, para propietario y administrador, las de la comunidad), pero crear, editar y revocar solo se hace en la pantalla. Consulta [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations).

**¿Dónde veo lo que hizo una clave?**
Cada clave creada, renombrada, con las IP cambiadas o revocada, y cada escritura hecha con clave, queda registrada *"con la clave {nombre}"*. Consulta [Logs › Claves de API](/membros/registros-de-atividades#claves-de-api).

**¿Una clave de una comunidad funciona en otra?**
No. La clave vale solo en la comunidad en la que se creó.

**¿Por qué no veo Webhooks en el selector?**
Es solo del propietario y de los administradores. Los demás roles ven solo sus propias claves.

**El webhook quedó Desactivado por fallos. ¿Pierdo los eventos?**
Los que ocurrieron mientras estaba desactivado no se envían. Al reactivarlo, los siguientes vuelven a llegar. Si el destino respondió `410`, él mismo pidió parar: revisa la URL antes de reactivarlo.

**El destino recibió el mismo evento dos veces.**
Puede ocurrir (una respuesta que se perdió, un reenvío). El destino debe ignorar el repetido por la cabecera `webhook-id`. Ver [Webhooks › Responder y procesar](/api/webhooks#responder-y-procesar).

**¿Integraciones listas (Discord, Slack, Telegram)?**
Disponibles, en **Integraciones**: Discord, Slack, Telegram, RD Station y HubSpot, más los atajos para Zapier, Make y n8n. Ver [Integraciones listas](/integracoes/integracoes-prontas).

## Desde el asistente y la API

- Desde el asistente de IA: [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations) (*"¿Qué claves de API tengo?"*; propietario y administrador también ven los webhooks, *"¿Algún webhook está fallando?"*, y, con `type: apps`, las integraciones listas, siempre solo consulta), [`list_logs`](/mcp/ferramentas-membros#list-logs) con `type: apiKeys` y [`list_activity_logs`](/mcp/ferramentas-membros#list-activity-logs) con `source: apiKeys` (*"¿Qué hizo la clave de n8n esta semana?"*).
- Webhooks desde la API: ver [Webhooks › Gestionar por API](/api/webhooks#gestionar-por-api); el formato, la firma y los eventos en [Webhooks](/api/webhooks) y [Eventos de webhook](/api/eventos-de-webhook).
- Desde la API: las rutas `/api/integrations/api-keys` (listar, crear, ver, renombrar y cambiar las IP, revocar, uso) funcionan solo con el inicio de sesión en la pantalla, nunca con una clave. Consulta [Autenticación › Clave de API](/api/autenticacao#clave-de-api) y la [referencia](/api/referencia).

## Relacionados

- [Integraciones listas](/integracoes/integracoes-prontas)
- [Webhooks para quien integra](/api/webhooks)
- [IPs fijas](/api/ips-fixos)
- [Autenticación](/api/autenticacao)
- [Respuestas y errores](/api/respostas-e-erros#errores-de-la-clave-de-api)
- [Roles y permisos](/conceitos/papeis-e-permissoes)
- [Logs](/membros/registros-de-atividades)