# Integrações & APIs

> Chaves de API pessoais para o seu CRM, uma automação (n8n, Zapier, Make) ou um script chamarem a API da comunidade, e webhooks para avisar esses sistemas quando algo acontece. Módulos e níveis, o segredo que aparece uma vez, IPs permitidos, revogar, criar, editar e testar um webhook, entregas, reenvio, as integrações prontas, o bloco Uso e o que nenhuma chave alcança.

Em **Integrações & APIs** você conecta a comunidade a outros sistemas: *"o seu CRM, uma automação ou um script chamam a API com uma chave sua."* A chave substitui o login nas chamadas à [API](/api/introducao), e só faz o que você marcar.

São três visões, no seletor do alto (quem só vê as chaves não vê o seletor):

- **Chaves de API**: o seu sistema chama a Memberfy. A equipe sempre; os membros, se o proprietário liberar.
- **[Webhooks](#webhooks)**: a Memberfy avisa o seu sistema quando alguém entra, compra, assina, se inscreve num evento ou conclui um curso. Proprietário e administrador.
- **[Integrações](/integracoes/integracoes-prontas)**: apps prontos, feitos pela Memberfy (Discord, Slack, Telegram, RD Station, HubSpot e os atalhos para Zapier, Make e n8n). Proprietário e administrador.

![Configurações › Integrações e APIs › Nova chave](/screens/integracoes-nova-chave.png "A matriz de módulos × ler / criar e editar / apagar e ações destrutivas, com marcar tudo por coluna. Sem nada marcado, a chave não faz nada.")

## Onde fica

| O quê | Onde |
|---|---|
| As **suas** chaves (qualquer papel) | **Minha Conta**, seção **Chaves de API** (`/account?tab=apiKeys`) |
| As chaves de todos, os webhooks e as integrações (proprietário e administrador) | **Configurações › Integrações e APIs** |

**Chaves de API para membros.** Em **Configurações › Integrações e APIs**, o proprietário decide em **Membros podem criar chaves de API**, desligado por padrão em todas as comunidades, inclusive nas que já existiam: *"Desligado, quem não é da equipe não vê Integrações & APIs e as chaves que já tem param de funcionar (não são apagadas)."* Ligar de novo faz essas chaves voltarem como estavam. O administrador vê a opção travada (*"Só o owner da comunidade altera esta opção."*), e a equipe (proprietário, administrador, moderador e financeiro) sempre pode criar as próprias chaves. Com a opção desligada, um membro que abre **Chaves de API** vê *"Chaves de API não estão liberadas para membros"*.

As chaves nunca passam do que o seu papel já permite, então liberar para membros não abre nada novo: um membro pode, por exemplo, levar as próprias reservas para a agenda dele.

## Como funciona

### A chave é sua

Cada chave pertence a você, nesta comunidade, e age em seu nome: o que ela cria fica com você como autor. A permissão de cada chamada é **o que a chave tem marcado e, ao mesmo tempo, o que o seu papel permite hoje**:

- Marcar um módulo que você não acessa não libera nada (*"A chave nunca passa do que o seu papel permite: marcar um módulo não dá um acesso que você não tem."*).
- Se o seu papel diminuir, a chave encolhe junto.
- Se você sair ou for removido da comunidade, a chave para (**Parada**).
- Você pode ter até **5 chaves ativas**.

### Módulos e níveis

A matriz tem uma linha para cada um dos **33 módulos** da comunidade e três colunas, independentes:

| Coluna | O que libera |
|---|---|
| **Ler** | Consultar: listas, detalhes, relatórios |
| **Criar e editar** | Criar e alterar |
| **Apagar e ações destrutivas** | Excluir, e as ações que removem algo do ar ou desfazem (lista abaixo) |

Cada coluna tem **marcar tudo**. **Sem nada marcado, a chave não faz nada**: o padrão é zero, e cada módulo precisa ser liberado de propósito. As colunas não se somam: uma chave com só **Apagar e ações destrutivas** num módulo não lê nem edita nele.

Os módulos: Comunidade e espaços, Membros, Feed, Enquetes, Conteúdo, Eventos, Cursos, Certificados, Galeria, Arquivos enviados, Call4papers, Classificados, Downloads, Loja e produtos, Vendas e assinaturas, Financeiro (leitura), Relatórios e logs, Campanhas, Pesquisas, Upvote, Canais, Gamificação, Moderação, Reservas, Agendamento, Networking, Automações, Presença, Visitantes, Encomendas, Suporte, Empresas e Minhas preferências.

**Automações** é só de leitura por chave: **Ler** lista e consulta os workflows, as versões, o histórico de execuções e as entregas; criar, editar, ligar, pausar, executar, testar, cancelar, aprovar e limpar recusam a chave (`403` `API_KEY_BLOCKED`) e ficam só no app e no assistente de IA.

### O que pede "Apagar e ações destrutivas"

Além de excluir, estas ações pedem a terceira coluna, mesmo não sendo uma exclusão:

| Módulo | Ações |
|---|---|
| Vendas e assinaturas | Cancelar uma assinatura (a sua ou, pela equipe, a de outra pessoa) |
| Loja e produtos | Despublicar um produto |
| Membros | Recusar o convite da comunidade; substituir a lista inteira de tags ou de campos de uma pessoa; recusar um pedido de cadastro |
| Cursos | Sair de um curso |
| Certificados | Revogar um certificado; arquivar um modelo |
| Call4papers | Despublicar e encerrar a chamada; retirar e recusar propostas; recusar o convite de avaliador ou de dono |
| Enquetes | Encerrar uma enquete |
| Eventos | Parar a transmissão ao vivo |
| Downloads | Substituir o arquivo de um item |
| Reservas | Cancelar uma reserva |
| Campanhas | Cancelar uma campanha; restaurar um e-mail automático ao texto padrão |
| Suporte | Cancelar um chamado; remover de uso a sala ou o recurso do chamado (a simulação, antes de confirmar, fica em **Criar e editar**) |
| Moderação | Cada decisão de moderação (aprovar, recusar, devolver à fila) |
| Empresas | Recusar o convite de uma empresa; encerrar uma empresa |
| Encomendas | Descartar uma encomenda |
| Networking | Recusar a entrada de alguém no programa; recusar uma sessão |

### O que nenhuma chave alcança

Mesmo com tudo marcado, a chave recebe *"Esta ação não aceita chave de API."* em:

- **Dinheiro**: reembolso, saque, dados de recebimento, Informação Comercial e documentos (KYC), checkout e compra, cartões salvos, compra de adicional (pelo membro ou pela equipe), troca de plano, **Pagar agora** e a oferta de downsell.
- **Conta**: login, senha, recuperação de senha, e-mail e telefone.
- **SuperAdmin**: as telas de gestão da plataforma.
- **O assistente de IA**: a conexão MCP e a autorização dele.
- **As próprias chaves**: uma chave não cria, edita nem revoga chave. Isso é só pela tela, com você logado.
- **Áreas privadas**: Mensagens, notificações, as [notificações no navegador e no celular](/conceitos/notificacoes-no-navegador) (aparelhos e preferências), Feedbacks, PDI, Reconhecimento, Controle de Ponto e Melhorar com IA.
- **Segredos das automações e integrações**: o cofre de segredos de terceiros, os endereços de entrada dos gatilhos de webhook das automações e os hooks de workflow.
- **Agir como outro membro** (o cabeçalho `X-MemberId`).

O resto continua com as regras de sempre: o que o seu papel não pode na tela, a chave também não pode.

## Passo a passo: criar uma chave

*Papel: qualquer um.*

1. Abra **Integrações & APIs** (veja [Onde fica](#onde-fica)) e clique em **Nova chave**.
2. Dê um **Nome** (*"Ex.: CRM, n8n, agenda"*).
3. **Vencimento** (opcional): uma data em que a chave para sozinha. *"Em branco, a chave vale até ser revogada."*
4. Em **O que a chave pode fazer**, marque só os módulos e as colunas de que a integração precisa.
5. **IPs permitidos** (opcional): um por linha, IPv4, IPv6 ou faixa CIDR, até **20**. *"Em branco, a chave aceita chamadas de qualquer IP."*
6. Clique em **Criar chave**.
7. Copie a chave e guarde num cofre de segredos. Clique em **Já copiei**.

> [!WARNING]
> *"Esta é a única vez que a chave aparece. Ela não será mostrada de novo; se você perder, revogue e crie outra."* Depois, a lista mostra só o início da chave (`mfk_7Hq2Lx9a…`), que serve para reconhecê-la.

A tela também mostra os cabeçalhos que vão em cada chamada: `X-Api-Key` com a chave e `X-CommunityId` com a comunidade. Ver [Autenticação › Chave de API](/api/autenticacao#chave-de-api).

## Gerenciar as chaves

Clique numa chave da lista para abrir o detalhe: **Início da chave**, **Dono**, **Criada em**, **Vencimento**, **Último uso** e **O que a chave pode fazer**.

| Situação | O que mostra |
|---|---|
| **Ativa** | *"A chave está funcionando."* |
| **Expirada** | A data de vencimento passou |
| **Revogada** | Alguém revogou a chave (com a data e quem revogou) |
| **Parada** | O dono saiu da comunidade |

- **Nome e IPs permitidos**: o dono renomeia e troca os IPs a qualquer momento, sem recriar a chave. O detalhe mostra o **Último IP recusado** e quando.
- **Módulos**: não se editam. *"Para mudar, crie outra chave e revogue esta."*
- **Uso**: as chamadas feitas com a chave no mês atual e nos 6 anteriores.
- **Revogar chave**: a chave para de funcionar na próxima chamada, e isso não se desfaz. O histórico de uso e os registros continuam.

### Proprietário e administrador: todas as chaves

Proprietário e administrador alternam entre **Minhas chaves** e **Todas da comunidade**. Em **Todas da comunidade** aparecem as chaves de todo mundo, com o dono, os módulos, o último uso e a situação (nunca o segredo), e eles podem **revogar** qualquer uma. Renomear e trocar IPs continua só com o dono.

### O bloco Uso

Abaixo das chaves, proprietário e administrador veem **Uso**: *"Chamadas à API feitas com chave e webhooks entregues, por mês (UTC)."* São o mês atual e os 6 anteriores; abra um mês para ver as chamadas por chave e por dono.

Contam as chamadas feitas com uma chave válida. Não contam as recusadas antes de chegar à rota: chave inválida, revogada ou vencida, ação que não aceita chave, IP fora da lista e chamada acima do limite por minuto. **Webhooks entregues** conta cada evento entregue com sucesso a um [webhook](#webhooks); o teste (**Enviar teste**) não conta.

### O teto da Memberfy

A equipe da Memberfy ([SuperAdmin](/conceitos/papeis-e-permissoes#superadmin)) vê o uso de cada comunidade no detalhe dela, no cartão **Integrações & APIs**, e pode guardar um **Teto de chamadas por mês**, um **Teto de webhooks por mês** e o **Modelo pretendido** (pacote de requisições ou fee fixo mensal). Por enquanto isso *"só fica guardado: nada é bloqueado nem cobrado, e a comunidade não vê o teto"*. Passar do teto mostra só o aviso *"Acima do teto neste mês."* para a Memberfy; a comunidade continua usando a API normalmente.

## Webhooks

*Papel: proprietário e administrador.*

Um webhook avisa outro sistema na hora em que algo acontece na comunidade: *"Avise outro sistema na hora em que algo acontece na comunidade."* A Memberfy manda um `POST` assinado para a URL que você cadastrar, e o seu CRM, o Zapier, o Make, o n8n ou um script fazem o resto. Quem escreve o código que recebe encontra o formato, a assinatura e as retentativas em [Webhooks para quem integra](/api/webhooks).

![Configurações › Integrações e APIs › Webhooks › Novo webhook](/screens/integracoes-novo-webhook.png "A URL de destino, a descrição e os eventos por família, com a família inteira ou um a um, e o aviso de dados pessoais.")

### Os eventos

São 97 eventos em 27 famílias (os dois de níveis e pontos, `member.level_changed` e `member.points_changed`). Por assunto:

| Assunto | Famílias |
|---|---|
| Pessoas | `member`, `message`, `badge` |
| Dinheiro | `purchase`, `subscription`, `checkout`, `coupon` |
| Eventos e presença | `event`, `booking`, `attendance`, `visitor`, `parcel` |
| Aprendizado | `course`, `lesson`, `quiz`, `certificate` |
| Conteúdo e espaços | `post`, `comment`, `reaction`, `space`, `download`, `classified`, `upvote` |
| Formulários e pedidos | `form`, `survey`, `proposal`, `support_ticket` |

Marque a **família inteira** para receber também os eventos que entrarem nela depois, ou escolha um a um. A lista completa está em [Webhooks para quem integra](/api/webhooks), e o que vai em cada evento, em [Eventos de webhook](/api/eventos-de-webhook). Um membro importado por planilha também dispara `member.joined`, com `source: "import"`.

### Passo a passo: criar um webhook

1. Em **Integrações & APIs**, escolha **Webhooks** no seletor do alto e clique em **Novo webhook**.
2. **URL de destino**: *"Só https, num endereço público."* O Zapier, o Make e o n8n dão essa URL quando você cria um gatilho de webhook.
3. **Descrição** (opcional): *"Ex.: CRM, n8n, planilha"*.
4. **Eventos**: marque as famílias ou os eventos.
5. **Enviar de IPs fixos** (opcional): para destinos que só aceitam endereços conhecidos. As entregas passam a sair de dois IPs, que a opção mostra; ver [IPs fixos](/api/ips-fixos).
6. Leia o aviso: *"Os eventos levam dados pessoais dos membros, como nome, e-mail e telefone, para o destino. Use só um endereço em que você confia."*
7. Clique em **Criar webhook**, copie o segredo (`whsec_…`) e guarde no sistema de destino.

> [!WARNING]
> *"Este é o único momento em que o segredo aparece. Copie agora; se perder, rotacione para gerar outro."* O segredo serve para o destino conferir que a entrega veio mesmo da Memberfy.

A comunidade pode ter até **10 webhooks**; a lista mostra quantos já existem (*"3 de 10 webhooks da comunidade."*). No limite, apague um para criar outro.

### Gerenciar um webhook

A lista mostra cada webhook com a URL (mascarada no meio), os eventos, a situação e a última entrega. Clique num para abrir o detalhe: **URL**, **Eventos**, **IPs fixos**, **Criada em**, **Última entrega com sucesso** e, quando há, **Falhas seguidas**.

| Situação | O que quer dizer |
|---|---|
| **Ativo** | *"O webhook está recebendo os eventos marcados."* |
| **Desligado** | Alguém desligou; nenhum evento é enviado até ele ser religado |
| **Desligado por falha** | O destino falhou por tempo demais, e a Memberfy desligou o webhook (veja abaixo) |

As ações do detalhe:

- **Enviar teste**: manda um evento de teste (`ping`) agora e mostra a resposta do destino (*"Teste entregue: HTTP 200 em 180 ms."*). Não é retentado e não conta no uso.
- **Editar**: troca a URL, a descrição, os eventos e a opção **Enviar de IPs fixos**, sem trocar o segredo (veja [Editar um webhook](#editar-um-webhook)).
- **Rotacionar segredo**: gera um segredo novo, mostrado uma vez. *"O segredo atual deixa de valer na hora"*: atualize o destino logo em seguida.
- **Desligar**: as entregas param na hora e as tentativas pendentes são canceladas. O que acontecer enquanto ele estiver desligado não é enviado depois.
- **Religar**: *"Religar envia um teste antes: o webhook só volta se o destino responder com sucesso."*
- **Apagar**: o webhook para de receber eventos, as tentativas pendentes são canceladas, e isso não se desfaz.

Rotacionar, desligar e apagar pedem confirmação.

### Editar um webhook

No detalhe, clique em **Editar**: *"Mude a URL, a descrição, os eventos ou os IPs fixos. O segredo continua o mesmo."* Ajuste e clique em **Salvar alterações**.

- *"Entregas já em andamento continuam indo para o destino antigo; só os eventos novos usam a configuração nova."* Retentativas e reenvios de uma entrega antiga seguem com a URL e a opção de IPs fixos de quando ela foi criada.
- **Trocar a URL zera as falhas seguidas**, porque é outro destino. A URL nova passa pela mesma checagem da criação.
- **Editar não religa.** Um webhook **Desligado** ou **Desligado por falha** continua desligado depois de salvar (*"Alterações salvas. Editar não religa um webhook desligado."*); use **Religar**, que manda um teste antes.
- O **Histórico de alterações** registra cada edição com o antes e o depois de cada campo (as URLs mascaradas).

### Entregas

A seção **Entregas** do detalhe lista cada envio: o evento, a situação (**Pendente**, **Entregue**, **Falhou**, **Cancelada**), o número de tentativas e a resposta. Filtre por situação e por evento (**Todos os eventos**, ou **Teste (ping)**).

Abra uma entrega para ver o identificador (`webhook-id`), o **Corpo enviado** e cada tentativa, com o status HTTP e o tempo (*"HTTP 500 em 312 ms"*), e quando será a próxima. **Reenviar** manda a entrega de novo, com o mesmo identificador, numa nova série de tentativas; uma entrega ainda em andamento não pode ser reenviada.

Quando o destino falha, a Memberfy tenta de novo depois de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Se o destino responder `410`, ou passar **72 horas sem nenhuma entrega com sucesso**, o webhook fica **Desligado por falha**, e o proprietário e os administradores recebem um e-mail. Confira o destino e clique em **Religar**. Os detalhes estão em [Webhooks › Retentativas](/api/webhooks#retentativas).

As entregas ficam guardadas por 30 dias.

### Histórico de alterações

Abaixo da lista, o **Histórico de alterações** mostra *"Quem criou, editou, testou, desligou, religou, rotacionou ou apagou um webhook ou uma integração, e quando"*, inclusive o **Sistema** quando a Memberfy desliga um webhook por falha (*"Desligado automaticamente por falhas"*). O detalhe de cada webhook tem a aba **Alterações**, só com as dele. O histórico fica guardado por 30 dias.

## Exemplos

**As reservas do membro na agenda dele.** A Carla, membro de um coworking, cria a chave *Agenda* com **Ler** em **Reservas** e nada mais. O script dela lê as próprias reservas e monta o calendário. Se o script tentar cancelar uma reserva, a API recusa: falta **Apagar e ações destrutivas** em **Reservas**.

**O CRM da equipe de vendas.** O Rafael, administrador, cria a chave *CRM* com **Ler** em **Membros** e em **Vendas e assinaturas**, e os IPs do servidor do CRM. O CRM puxa os assinantes novos toda hora. Reembolsar pelo CRM não funciona, nem com tudo marcado: dinheiro só pela tela.

**O Zapier avisa a equipe de cada compra.** A Júlia, proprietária, cria no Zapier um gatilho *Webhooks by Zapier*, copia a URL e cria na Memberfy o webhook *Zapier vendas* com a família **Compras**. Clica em **Enviar teste**, o Zapier recebe o `ping`, e a partir dali cada compra concluída vira uma mensagem no canal da equipe, com o nome e o e-mail de quem comprou.

**O CRM que recusa IP desconhecido.** O firewall do CRM só aceita endereços liberados. O Rafael cria o webhook com **Enviar de IPs fixos**, libera os dois [IPs fixos](/api/ips-fixos) no CRM e envia um teste. Quando o CRM fica fora do ar num fim de semana, as entregas voltam sozinhas nas retentativas; as que esgotaram as tentativas, ele reenvia pela seção **Entregas**.

**A automação que publica no Feed.** O n8n da comunidade usa uma chave com **Criar e editar** em **Feed**. Quando a chave vaza num print, o proprietário abre **Todas da comunidade**, revoga a chave e a próxima chamada do n8n já é recusada. O dono cria outra.

## Perguntas frequentes

**Por que a chave recebe "não tem permissão" num módulo que eu marquei?**
Duas causas: a coluna marcada não é a da ação (cancelar pede **Apagar e ações destrutivas**, não **Criar e editar**), ou o seu papel não pode aquilo nem na tela. A chave nunca passa do seu papel.

**Perdi a chave. Dá para ver de novo?**
Não. Revogue e crie outra.

**Quantas chamadas posso fazer?**
Até 120 por minuto, somando todas as suas chaves nesta comunidade. Acima disso, a API pede para esperar alguns segundos. Ver [Autenticação › Limite](/api/autenticacao#limite-de-chamadas).

**Dá para criar ou revogar chave pelo assistente de IA?**
Não. O assistente lista as chaves (as suas e, para proprietário e administrador, as da comunidade), mas criar, editar e revogar é só na tela. Ver [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations).

**Onde vejo o que uma chave fez?**
Cada chave criada, renomeada, com IPs trocados ou revogada, e cada escrita feita com chave, fica registrada *"via chave {nome}"*, em **Administração › Logs**, tipo **Chaves de API**. Ver [Logs › Chaves de API](/membros/registros-de-atividades#chaves-de-api).

**Uma chave de uma comunidade funciona em outra?**
Não. A chave vale só na comunidade em que foi criada.

**Por que não vejo Webhooks no seletor?**
Ela é só do proprietário e dos administradores. Os outros papéis veem apenas as próprias chaves.

**O webhook ficou Desligado por falha. Perco os eventos?**
Os que aconteceram enquanto ele estava desligado não são enviados. Ao religar, os próximos voltam a chegar. Se o destino respondeu `410`, ele mesmo pediu para parar: confira a URL antes de religar.

**O destino recebeu o mesmo evento duas vezes.**
Pode acontecer (uma resposta que se perdeu, um reenvio). O destino deve ignorar o repetido pelo cabeçalho `webhook-id`. Ver [Webhooks › Responder e processar](/api/webhooks#responder-e-processar).

**Integrações prontas (Discord, Slack, Telegram)?**
Disponíveis, em **Integrações**: Discord, Slack, Telegram, RD Station e HubSpot, mais os atalhos para Zapier, Make e n8n. Ver [Integrações prontas](/integracoes/integracoes-prontas).

## Pelo assistente e pela API

- Pelo assistente de IA: [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations) (*"Quais chaves de API eu tenho?"*; proprietário e administrador também veem os webhooks, *"Algum webhook está falhando?"*, e, com `type: apps`, as integrações prontas, sempre só para consulta), [`list_logs`](/mcp/ferramentas-membros#list-logs) com `type: apiKeys` e [`list_activity_logs`](/mcp/ferramentas-membros#list-activity-logs) com `source: apiKeys` (*"O que a chave do n8n fez esta semana?"*).
- Webhooks pela API: ver [Webhooks › Gerenciar por API](/api/webhooks#gerenciar-por-api); o formato, a assinatura e os eventos em [Webhooks](/api/webhooks) e [Eventos de webhook](/api/eventos-de-webhook).
- Pela API: as rotas `/api/integrations/api-keys` (listar, criar, ver, renomear e trocar IPs, revogar, uso) funcionam só com o login na tela, nunca com uma chave. Ver [Autenticação › Chave de API](/api/autenticacao#chave-de-api) e a [referência](/api/referencia).

## Relacionados

- [Integrações prontas](/integracoes/integracoes-prontas)
- [Webhooks para quem integra](/api/webhooks)
- [IPs fixos](/api/ips-fixos)
- [Autenticação](/api/autenticacao)
- [Respostas e erros](/api/respostas-e-erros#erros-da-chave-de-api)
- [Papéis e permissões](/conceitos/papeis-e-permissoes)
- [Logs](/membros/registros-de-atividades)