# 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** liga 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 início de sessão nas chamadas à [API](/api/introducao) e só faz o que marcar.


São três vistas, no seletor do topo (quem só vê as chaves não vê o seletor):

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

![Definiçõ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**, secção **Chaves de API** (`/account?tab=apiKeys`) |
| As chaves de todos, os webhooks e as integrações (proprietário e administrador) | **Administração › Definições › Integrações e APIs** |

**Chaves de API para membros.** Em **Definições › Integrações e APIs**, o proprietário decide em **Os membros podem criar chaves de API**, desligado por omissão em todas as comunidades, incluindo as que já existiam: quem não é da equipa deixa de ver as próprias chaves e as que já tem param de funcionar (não são apagadas). Voltar a ligar faz essas chaves voltarem como estavam. O administrador vê a opção bloqueada (*"Só o owner da comunidade altera esta opção."*), e a equipa (proprietário, administrador, moderador e financeiro) pode sempre criar as próprias chaves. Com a opção desligada, um membro que abre **Chaves de API** vê *"As chaves de API não estão disponíveis para membros"*.

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

## Como funciona

### A chave é sua

Cada chave pertence-lhe, nesta comunidade, e age em seu nome: o que ela cria fica com o seu nome 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 a que não tem acesso não liberta nada (*"A chave nunca passa do que o seu papel permite: marcar um módulo não dá um acesso que não tem."*).
- Se o seu papel diminuir, a chave encolhe com ele.
- Se sair ou for removido da comunidade, a chave para (**Parada**).
- 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 liberta |
|---|---|
| **Ler** | Consultar: listas, detalhes, relatórios |
| **Criar e editar** | Criar e alterar |
| **Apagar e ações destrutivas** | Eliminar, e as ações que tiram 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 tem de ser libertado de propósito. As colunas não se somam: uma chave só com **Apagar e ações destrutivas** num módulo não lê nem edita nele.

Os módulos: Comunidade e espaços, Membros, Feed, Sondagens, Conteúdo, Eventos, Cursos, Certificados, Galeria, Ficheiros enviados, Call4papers, Classificados, Transferências, Loja e produtos, Vendas e subscrições, Financeiro (leitura), Relatórios e registos, Campanhas, Inquéritos, Upvote, Canais, Gamificação, Moderação, Reservas, Marcações, Networking, Automações, Presença, Visitantes, Encomendas, Suporte, Empresas e As 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ó na app e no assistente de IA.

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

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

| Módulo | Ações |
|---|---|
| Vendas e subscrições | Cancelar uma subscrição (a sua ou, pela equipa, a de outra pessoa) |
| Loja e produtos | Despublicar um produto |
| Membros | Recusar o convite da comunidade; substituir a lista inteira de etiquetas ou de campos de uma pessoa; recusar um pedido de registo |
| 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 |
| Sondagens | Encerrar uma sondagem |
| Eventos | Parar a transmissão em direto |
| Transferências | Substituir o ficheiro de um item |
| Reservas | Cancelar uma reserva |
| Campanhas | Cancelar uma campanha; repor o texto padrão de um e-mail automático |
| Suporte | Cancelar um pedido; tirar de uso a sala ou o recurso do pedido (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, levantamento, dados de recebimento, Informação Comercial e documentos (KYC), checkout e compra, cartões guardados, compra de adicional (pelo membro ou pela equipa), troca de plano, **Pagar agora** e a oferta de downsell.
- **Conta**: início de sessão, palavra-passe, recuperação da palavra-passe, e-mail e telefone.
- **SuperAdmin**: os ecrãs de gestão da plataforma.
- **O assistente de IA**: a ligação MCP e a autorização dele.
- **As próprias chaves**: uma chave não cria, edita nem revoga chaves. Isso é só pelo ecrã, com a sessão iniciada.
- **Áreas privadas**: Mensagens, notificações, as [notificações no navegador e no telemóvel](/conceitos/notificacoes-no-navegador) (dispositivos e preferências), Feedbacks, PDI, Reconhecimento, Controlo 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 acionadores 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 fazer no ecrã, 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-a 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 a perder, revogue e crie outra."* Depois, a lista mostra só o início da chave (`mfk_7Hq2Lx9a…`), que serve para a reconhecer.

O ecrã mostra também 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).

## Gerir as chaves

Clique numa chave da lista para abrir o detalhe: **Início da chave**, **Proprietário**, **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: a chave não funciona mais."* |
| **Revogada** | Alguém revogou a chave (com a data e quem revogou) |
| **Parada** | *"O proprietário saiu da comunidade, então a chave não funciona mais."* |

- **Nome e IPs permitidos**: o proprietário da chave muda o nome e 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 chamada seguinte, e isso não se desfaz. O histórico de uso e os registos 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 toda a gente, com o proprietário da chave, os módulos, o último uso e a situação (nunca o segredo), e podem **revogar** qualquer uma. Mudar o nome e os IPs continua só com quem criou a chave.

### 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 proprietário.

Contam as chamadas feitas com uma chave válida. Não contam as recusadas antes de chegarem à 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 equipa 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 pedidos** ou **Taxa fixa mensal**). Por enquanto, isto *"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."* à Memberfy; a comunidade continua a usar 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 o URL que registar, 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).

![Definições › Integrações e APIs › Webhooks › Novo webhook](/screens/integracoes-novo-webhook.png "O 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` |
| Aprendizagem | `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 folha de cálculo também dispara `member.joined`, com `source: "import"`.

### Passo a passo: criar um webhook

1. Em **Integrações & APIs**, escolha **Webhooks** no seletor do topo 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 esse URL quando cria um gatilho de webhook.
3. **Descrição** (opcional): *"Ex.: CRM, n8n, folha de cálculo"*.
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 confia."*
7. Clique em **Criar webhook**, copie o segredo (`whsec_…`) e guarde-o no sistema de destino.

> [!WARNING]
> *"Este é o único momento em que o segredo aparece. Copie agora; se perder, rode-o 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 o URL (mascarado 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**: muda o URL, a descrição, os eventos e a opção de IPs fixos, sem mudar o segredo (veja [Editar um webhook](#editar-um-webhook)).
- **Rodar 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.

Rodar, 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 **Guardar alterações**.

- *"Entregas já em curso continuam a ir para o destino antigo; só os eventos novos usam a configuração nova."* Novas tentativas e reenvios de uma entrega antiga seguem com o URL e a opção de IPs fixos de quando foi criada.
- **Mudar o URL põe a zero as falhas seguidas**, porque é outro destino. O URL novo passa pela mesma verificação da criação.
- **Editar não religa.** Um webhook **Desligado** ou **Desligado por falha** continua desligado depois de guardar (*"Alterações guardadas. Editar não religa um webhook desligado."*); use **Religar**, que envia um teste antes.
- O **Histórico de alterações** regista cada edição com o antes e o depois de cada campo (os URL mascarados).

### 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. Verifique o destino e clique em **Religar**. Os detalhes estão em [Webhooks › Retentativas](/api/webhooks#novas-tentativas).

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, rodou 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 o separador **Alterações**, só com as dele. O histórico fica guardado por 30 dias.

## Exemplos

**O Zapier avisa a equipa de cada compra.** A Júlia, proprietária, cria no Zapier um gatilho *Webhooks by Zapier*, copia o 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 equipa, 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**.

**As reservas do membro na agenda dele.** A Carla, membro de um coworking, cria a chave *Agenda* com **Ler** em **Reservas** e mais nada. 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 equipa de vendas.** O Rafael, administrador, cria a chave *CRM* com **Ler** em **Membros** e em **Vendas e subscrições**, e os IPs do servidor do CRM. O CRM vai buscar os novos subscritores de hora a hora. Reembolsar pelo CRM não funciona, nem com tudo marcado: dinheiro, só pelo ecrã.

**A automação que publica no Feed.** O n8n da comunidade usa uma chave com **Criar e editar** em **Feed**. Quando a chave aparece numa captura de ecrã, o proprietário abre **Todas da comunidade**, revoga a chave e a chamada seguinte do n8n já é recusada. Quem a criou cria outra.

## Perguntas frequentes

**Porque é que a chave recebe "não tem permissão" num módulo que 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 fazer aquilo nem no ecrã. A chave nunca passa do seu papel.

**Perdi a chave. Posso vê-la de novo?**
Não. Revogue-a 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).

**Posso criar ou revogar uma 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ó no ecrã. Ver [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations).

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

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

**Porque não vejo Webhooks no seletor?**
É 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 estava desligado não são enviados. Ao religar, os seguintes voltam a chegar. Se o destino respondeu `410`, foi ele que pediu para parar: verifique o 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. Veja [Integrações prontas](/integracoes/integracoes-prontas).

## Pelo assistente e pela API

- Pelo assistente de IA: [`list_integrations`](/mcp/ferramentas-comunidade#list-integrations) (*"Que chaves de API tenho?"*; proprietário e administrador também veem os webhooks, *"Algum webhook está a falhar?"*, 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 fez a chave do n8n esta semana?"*).
- Webhooks pela API: ver [Webhooks › Gerir por API](/api/webhooks#gerir-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, mudar o nome e os IPs, revogar, uso) funcionam só com a sessão iniciada no ecrã, 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)