Integrações & APIs

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 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: 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: apps prontas, feitas pela Memberfy (Discord, Slack, Telegram, RD Station, HubSpot e os atalhos para Zapier, Make e n8n). Proprietário e administrador.

#Onde fica

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:

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:

#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 (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) 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.

"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.

#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.

• 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; o teste (Enviar teste) não conta.

#O teto da Memberfy

A equipa da Memberfy (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.

#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:

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, e o que vai em cada evento, em 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.
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.

"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.

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).
• 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.

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 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.

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.

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.

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.

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.

#Pelo assistente e pela API

• Pelo assistente de IA: 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 com type: apiKeys e list_activity_logs com source: apiKeys ("O que fez a chave do n8n esta semana?").
• Webhooks pela API: ver Webhooks › Gerir por API; o formato, a assinatura e os eventos em Webhooks e 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 e a referência.

#Relacionados

• Integrações prontas
• Webhooks para quem integra
• IPs fixos
• Autenticação
• Respostas e erros
• Papéis e permissões
• Logs