API da Cool

Uma API REST pra ligar sua comunidade a qualquer sistema: puxar membros pro seu CRM, publicar no feed a partir do seu site, ler pagamentos pro seu financeiro. Respostas em JSON, autenticação por chave.

Como conseguir a chave

No painel da sua comunidade, em Configurações → Chaves de API. A chave aparece uma única vez — guarde num lugar seguro. No nosso banco fica apenas um resumo criptográfico dela, então nem nós conseguimos vê-la depois; se perder, revogue e crie outra.

Toda chave criada pelo dono é presa à comunidade dele: ela nunca enxerga dados de outra comunidade, mesmo que o id de outra seja passado na chamada.

Autenticação

Mande a chave no cabeçalho Authorization:

curl https://coolbases.com/api/v1/me \
  -H "Authorization: Bearer cool_sua_chave_aqui"

Comece por /api/v1/me: ele devolve a quem a chave pertence, o escopo e os limites — é o jeito mais rápido de saber se a credencial está funcionando.

Escopos

read — consultar dados. É o padrão.
write — além de ler, criar coisas (membro, publicação). Só habilite quando precisar: uma chave de escrita vazada cria membros na sua comunidade.

Limites

120 leituras e 30 escritas por minuto, por chave. Ao estourar, a resposta é 429 com o cabeçalho Retry-After em segundos — espere esse tempo em vez de tentar de novo na hora, senão a fila só aumenta.

Escrita tem teto menor porque custa mais: criar um membro dispara e-mail de boas-vindas, automações e webhooks — coisas que chegam em gente de verdade e não dão pra desfazer.

Erros

Sempre no mesmo formato:

{ "error": { "status": 401, "message": "Chave de API inválida ou revogada." } }

401 — chave ausente, inválida ou revogada.
403 — a chave existe mas não pode fazer isso (escopo errado, ou dados de outra comunidade).
400 — corpo ou parâmetro inválido.
429 — limite por minuto atingido.

Endpoints

GET/api/v1/meescopo: read

Quem é esta chave: dono, comunidade, escopos e limites.

GET/api/v1/membersescopo: read

Lista os membros da comunidade (até 200 por chamada, do mais recente pro mais antigo).

Filtros: ?status=ACTIVE|PENDING|REMOVED|BANNED

curl "https://coolbases.com/api/v1/members?status=ACTIVE" \
  -H "Authorization: Bearer cool_..."

POST/api/v1/membersescopo: write

Adiciona um membro já ativo (sem fila de aprovação). Cria a conta se o e-mail ainda não existir.

curl -X POST https://coolbases.com/api/v1/members \
  -H "Authorization: Bearer cool_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"pessoa@exemplo.com","name":"Maria","role":"MEMBER"}'

GET/api/v1/postsescopo: read

Publicações do feed.

GET/api/v1/paymentsescopo: read

Pagamentos recebidos — pra conciliar com o seu financeiro.

GET/api/v1/communitiesescopo: read

Dados da comunidade da chave.

Webhooks

Em vez de ficar perguntando à API se algo mudou, a Cool avisa o seu sistema: cadastramos uma URL sua e mandamos um POST assinado a cada evento (membro novo, pagamento confirmado, publicação criada, assinatura alterada). A assinatura HMAC-SHA256 vai no cabeçalho — confira antes de confiar no corpo, senão qualquer um que descubra sua URL pode fingir ser a Cool. Peça a configuração pelo suporte.

Dúvida ou endpoint que faltou? Escreva pelo suporte dentro da plataforma — a lista cresce conforme o uso real.