Integrações & APIs

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, 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: 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: apps prontos, feitos 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 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:

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:

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

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

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

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

#O teto da Memberfy

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

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

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

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

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

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.

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.

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.

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.

#Pelo assistente e pela API

• Pelo assistente de IA: 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 com type: apiKeys e list_activity_logs com source: apiKeys ("O que a chave do n8n fez esta semana?").
• Webhooks pela API: ver Webhooks › Gerenciar 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, renomear e trocar IPs, revogar, uso) funcionam só com o login na tela, 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