API e webhooks

API e webhooks permite que os dados do seu clube cheguem às suas próprias ferramentas. Crie uma chave de API somente leitura para puxar sócios, tipos de associação, eventos, pedidos e check-ins para uma planilha, um painel de relatórios ou um aplicativo próprio — e adicione endpoints de webhook para que seus sistemas fiquem sabendo de novos sócios, pedidos pagos e check-ins no momento em que acontecem. Você também pode conectar um assistente de IA (como o Claude) para que ele responda perguntas sobre o seu clube e prepare rascunhos para você revisar. Você encontra tudo isso na barra lateral do painel, em Sistema → API e webhooks.

Quem pode usar

Você precisa ser administrador pleno da organização — moderadores não veem esta página, e ela não pode ser liberada por um cargo da diretoria nem por uma permissão avulsa. As chaves de API dão acesso de leitura a toda a organização e os endpoints de webhook recebem dados de sócios, então as duas coisas ficam só com os administradores.

A API REST e os webhooks são um recurso do plano Pro (Enterprise incluído); nos outros planos, essa parte da página mostra um convite para fazer upgrade. O acesso de assistente de IA (MCP) é diferente — funciona em todos os planos, inclusive no Free, porque um assistente que age como um administrador não é a mesma coisa que uma torneira de dados em massa.

O que há na página

• Chaves de API — crie chaves com nome, veja quando cada uma foi criada e usada pela última vez, e revogue qualquer chave na hora.
• Acesso de assistente de IA (MCP) — crie tokens que permitem a um assistente de IA se conectar à sua organização pelo Model Context Protocol. Escolha se ele pode só ler, fazer alterações ou publicar; limite-o a partes específicas do clube; defina uma validade; revogue com um clique.
• Endpoints de webhook — adicione URLs HTTPS que devemos avisar, escolha quais eventos cada uma recebe, pause/retome, envie um evento de teste ou exclua um endpoint. Cada endpoint tem o próprio segredo de assinatura, mostrado na página.
• Entregas recentes — as últimas 20 entregas de webhook com evento, status, número de tentativas e horário em que entraram na fila.

Passo a passo

Criar uma chave de API e fazer a primeira requisição

1. Em Chaves de API, dê à chave um nome que diga onde ela será usada (ex.: Planilha de relatórios) e clique em Criar chave.
2. Copie a chave completa no aviso verde na mesma hora — por segurança, guardamos só uma impressão digital, então a chave aparece esta única vez e nunca mais.
3. Chame qualquer endpoint com a chave no cabeçalho Authorization:

curl -H "Authorization: Bearer chk_..." https://clubhelix.com/api/v1/members

4. Endpoints disponíveis (todos GET, JSON, paginados com ?limit= até 100 e ?offset=):
   • /api/v1/members — seu quadro de sócios (status, data de entrada, validade do pagamento, nome e e-mail)
   • /api/v1/membership-types — seus tipos de associação ativos
   • /api/v1/events — eventos publicados (adicione ?upcoming=true para ver só os futuros)
   • /api/v1/orders — pedidos de associação, da loja e de ingressos resumidos, do mais recente para o mais antigo
   • /api/v1/checkins — registros de presença

Usar a API pública de leitura (sem chave)

Tudo o que já é público no seu site também pode ser lido em JSON, sem chave e em qualquer plano. Use para mostrar suas últimas notícias ou próximos eventos em outro site, em uma tela de avisos ou em um aplicativo.

curl https://clubhelix.com/api/public/v1/your-club/events

Substitua your-club pelo endereço da sua organização (a parte depois de /group/). Se você tem um domínio próprio, o mesmo caminho funciona nele também, só para a sua organização.

• news — notícias publicadas, da mais recente para a mais antiga
• events — eventos públicos, os próximos por padrão; adicione ?from=2026-10-01&to=2026-12-31 para um intervalo de datas
• fixtures — jogos públicos; adicione ?timeframe=results para os resultados recentes
• sponsors, teams — como aparecem no seu site
• pages — uma lista das suas páginas públicas publicadas (só títulos e endereços)
• club — seu nome, logo, redes sociais, cores do tema e locale, o idioma em que seu site está escrito (como en-AU ou es)

Adicione ?limit= para até 50 itens (o padrão é 10; jogos param em 20 e equipes em 24). Notícias e eventos também aceitam ?category= e ?tag= com o slug de uma categoria ou tag. Toda resposta tem o formato { "data": ..., "truncated": true }, em que truncated indica que havia mais itens do que você pediu. Os horários estão em UTC.

Nada privado é incluído: eventos e páginas só para sócios, rascunhos e dados de contato ficam de fora, exatamente como para um visitante que não entrou na conta.

Quando algo dá errado, as duas APIs respondem com { "error": { "code": ..., "message": ... } }. Confira o code: ele nunca muda. A message é escrita para uma pessoa e segue o cabeçalho Accept-Language da requisição quando o seu idioma estiver disponível.

Adicionar um endpoint de webhook

1. Em Endpoints de webhook, informe a URL HTTPS em que o seu sistema escuta. Ela precisa ser um endereço público da internet que já resolva: não salvamos nem entregamos para um endereço interno ou privado, uma URL com usuário ou senha, nem uma porta diferente da 443.
2. Marque os eventos que você quer receber — ou deixe todas as caixas desmarcadas para receber todos.
3. Escolha um formato de assinatura. Deixe em v2, a menos que o seu receptor tenha sido escrito para o formato v1, mais antigo (veja abaixo).
4. Clique em Adicionar endpoint. Anote o segredo de assinatura mostrado no cartão do endpoint — o seu receptor o usa para verificar as entregas.
5. Clique em Enviar evento de teste para colocar uma entrega test.ping na fila e acompanhe a chegada dela em Entregas recentes (as entregas saem a cada poucos minutos; as que falham são tentadas de novo até 5 vezes).

Verificar a assinatura de um webhook

Cada entrega é um POST em JSON com um cabeçalho X-ClubHelix-Event (o tipo de evento) e um cabeçalho X-ClubHelix-Signature. O cartão de cada endpoint mostra qual formato de assinatura ele usa.

v2 (o padrão para endpoints novos). O cabeçalho de assinatura tem este aspecto: t=1759449600,v2=5f2c…. Ele traz um carimbo de data/hora Unix e um HMAC-SHA256 em hexadecimal do carimbo, um ponto, o id da entrega do cabeçalho X-ClubHelix-Delivery, outro ponto e o corpo bruto, com o segredo do seu endpoint como chave. O id da entrega faz parte do que é assinado, então ninguém consegue reenviar uma entrega capturada com outro id para furar a sua verificação de duplicatas. Verifique assim:

t, v2 = parse(header["X-ClubHelix-Signature"])
delivery_id = header["X-ClubHelix-Delivery"]
if abs(now_unix() - t) > 300:
    reject the request            # older than five minutes: a replay
expected = hmac_sha256_hex(secret, t + "." + delivery_id + "." + raw_request_body)
if not constant_time_equals(expected, v2):
    reject the request
if already_seen(delivery_id):
    ignore it                     # a retry of one you already handled

v1 (endpoints adicionados antes da v2). O cabeçalho é um HMAC-SHA256 em hexadecimal apenas do corpo bruto:

expected = hmac_sha256_hex(secret, raw_request_body)
if not constant_time_equals(expected, header["X-ClubHelix-Signature"]):
    reject the request

Uma assinatura v1 não tem carimbo de data/hora, então quem capturar uma entrega pode enviá-la a você de novo mais tarde. Os endpoints existentes continuam na v1 para que os receptores deles sigam funcionando. Para passar um deles para a v2, adicione um endpoint novo, atualize o seu receptor e depois exclua o antigo.

Sempre calcule o HMAC sobre os bytes brutos do corpo, antes de qualquer interpretação do JSON.

Revogar ou trocar uma chave

1. Clique em Revogar ao lado da chave — ela para de funcionar na hora.
2. Para trocar, crie primeiro uma chave nova, mude a sua integração para ela e depois revogue a antiga.

Conectar um assistente de IA (MCP)

1. Em Acesso de assistente de IA (MCP), dê ao token um nome que diga onde ele vai ficar (ex.: Claude no notebook do secretário) e escolha uma validade — 90 dias é um bom padrão.
2. Escolha o que ele pode fazer. Com as duas caixas desmarcadas, é um assistente somente leitura que responde perguntas. Permitir alterações deixa que ele crie e edite páginas, notícias e eventos. Permitir publicação deixa, além disso, que ele torne esse trabalho público. A maioria dos clubes começa com alterações ativadas e publicação desativada, para que uma pessoa ainda clique em publicar.
3. Se quiser, abra Limitar o que este token pode acessar e marque algumas áreas. Não marque nada e o token pode fazer tudo o que você pode. Marque só "Publicar notícias" e ele pode escrever a sua página de notícias e mais nada — nem a loja, nem os seus sócios.
4. Copie o token no aviso verde na mesma hora — como as chaves de API, ele aparece uma única vez e nunca mais.
5. No assistente, adicione a conexão usando o comando mostrado em Conectar o Claude Code na página (o token vai em um cabeçalho Authorization — nunca o cole em uma mensagem de chat). Veja Como conectar um assistente de IA para a configuração em outras ferramentas e para a única regra que diz de antemão se uma ferramenta consegue se conectar.
6. Experimente: peça ao assistente para "resumir nosso quadro de sócios" e depois para "escrever o rascunho de uma notícia sobre o jogo de sábado". Pergunte "o que você pode fazer aqui?" e ele dirá exatamente quais poderes este token tem.

O que o token nunca pode fazer, por projeto:

• Ele só vê a sua organização. O token fica preso ao seu clube — perguntas sobre qualquer outra organização são recusadas, e a mesma segurança por linha que protege o painel se aplica a cada requisição por baixo.
• Ele nunca pode fazer mais do que você. Um token age como o administrador que o criou, então fica limitado às permissões dessa pessoa, verificadas de novo a cada requisição. Marcar caixas só pode tirar poderes, nunca acrescentar.
• Ele nunca envia e-mails nem movimenta dinheiro. Os comunicados continuam esperando, sem envio, no editor até você escolher o público, e nada sobre pagamentos, reembolsos ou registros de sócios pode ser alterado por um token.
• Nada acontece sem confirmação. Toda alteração é mostrada antes em uma prévia: o assistente mostra exatamente o que faria e só age quando recebe uma segunda ordem para seguir.
• Ele para de funcionar quando você para. Se o administrador que o criou perder a função de administrador, o token para de funcionar na hora — a função é verificada de novo a cada requisição. Revogá-lo nesta página também é imediato. Mudar de plano não o afeta.
• Ele nunca pode alterar a sua assinatura. Planos, cobrança e configurações de pagamento são ferramentas da equipe da plataforma; nenhum token de organização chega a elas, seja o que for que você marque.
• Toda ação fica registrada. Tudo o que o assistente lê ou altera fica no registro de auditoria em nome do administrador que criou o token.

Referência de campos

Tipos de evento de webhook:

Os eventos de conteúdo avisam outro site (o seu site WordPress, por exemplo) de que algo que ele mostra mudou, para que possa se atualizar:

Os payloads de entrega têm todos o mesmo formato: { "event": "...", "tenant_id": "...", "data": { ... }, "created_at": "..." }. Nos eventos de pagamento, de sócios e de check-in, data é uma pequena cópia do registro (ids, status, valores — você pode buscar os detalhes completos na API usando os ids). Nos eventos de conteúdo, data é apenas { "id": "...", "updated_at": "..." }: o seu sistema busca o item por conta própria, então nada sobre pessoas viaja em um evento de conteúdo.

Dicas e perguntas frequentes

A chave que criei sumiu — onde a encontro? Não dá: a chave completa aparece uma vez na criação e só uma impressão digital é guardada. Crie uma chave nova e revogue a antiga.

Por que estou recebendo respostas 403? A API exige o plano Pro ou Enterprise. Se o seu clube mudou para um plano inferior, as chaves existentes param de funcionar até você fazer upgrade de novo.

Por que estou recebendo respostas 429? Cada chave tem um limite de 120 requisições por minuto. Diminua o ritmo ou espalhe as requisições — o cabeçalho Retry-After diz quanto tempo esperar.

A API pode alterar ou excluir dados? Não. As chaves da versão 1 são estritamente somente leitura, e cada chave vale só para a sua organização.

Marquei uma reserva como paga no local — por que não houve webhook? Os eventos .paid disparam quando um pagamento com cartão passa pelo seu provedor de pagamentos. Dinheiro que você mesmo registra no painel, como Marcar como paga em uma reserva de espaço, é salvo na reserva, mas não envia nada aos seus endpoints. Marcar um sócio como pago é a exceção: isso dispara member.updated.

Uma entrega aparece como Falhou — ela vai ser tentada de novo? Cada entrega é tentada de novo até 5 vezes. Depois da quinta falha ela para; corrija o seu endpoint e use Enviar evento de teste para confirmar que ele voltou a funcionar.

Qual é a diferença entre uma chave de API e um token MCP? Uma chave de API (chk_…) é para os seus próprios scripts e ferramentas — REST simples, somente leitura. Um token MCP (chmx_…) é para assistentes de IA — ele fala o Model Context Protocol, pode fazer e publicar alterações se você permitir e age como o administrador que o criou.

O assistente pode alterar o nosso site? Sim, se você deixar. Com Permitir alterações ativado, ele pode criar e editar páginas, notícias e eventos; com Permitir publicação ativado, pode torná-los públicos e tirá-los do ar de novo. Deixe a publicação desativada e tudo o que ele escrever espera por uma pessoa. De qualquer forma, ele mostra uma prévia de cada alteração e pergunta antes de agir.

Ele pode mandar e-mails para os nossos sócios? Não. Os comunicados ficam só em rascunho — esperam sem envio no editor até você escolher o público e enviá-los você mesmo. Pagamentos, reembolsos e registros de sócios também ficam fora do alcance dele.

Posso dar a um assistente uma única tarefa? Sim. Em Limitar o que este token pode acessar, marque só as áreas de que ele precisa. Um token limitado a "Publicar notícias" é recusado em todo o resto, e a recusa diz qual permissão faltou — assim você pode entregar a página de notícias a um assistente e o site inteiro a outro, cada um com o próprio token.