X-CommunityId

A Memberfy é organizada por comunidade, e a API também: quase toda chamada precisa do header X-CommunityId com o id da comunidade.

X-CommunityId: 3562c7a0-0000-0000-0000-000000000000

#O que ele decide

1. Onde a operação acontece: em qual comunidade o espaço é criado, o produto é listado, o levantamento é pedido.
2. Qual papel você tem: a permissão é conferida no seu perfil daquela comunidade. A mesma conta pode ser proprietária de uma comunidade e membro de outra; o header escolhe qual vale.

#O header manda, o caminho não

Nenhuma rota leva a comunidade no caminho. Produtos, cupões, planos, taxas, extrato, levantamentos, relatórios, informação comercial, dados de recebimento e a gestão de subscrições ficam em caminhos sem o id da comunidade (/api/products, /api/coupons, /api/manage/subscriptions…), e a comunidade vem só do X-CommunityId. Sem o header, essas rotas respondem 400.

A exceção é o SuperAdmin a agir sobre outra comunidade, em /api/admin/communities/{communityId}/fee-overrides/...: aí o id no caminho é a comunidade-alvo, não o contexto de quem chama. As rotas da própria comunidade, PUT e DELETE /api/communities/{id}, GET /api/communities/{id}/members e PATCH /api/communities/{id}/settings, levam o id porque a comunidade é o próprio recurso; o header continua obrigatório nelas.

Mudou a 6 de outubro de 2026. Os caminhos antigos /api/communities/{communityId}/... (produtos, cupões, planos, taxas, extrato, levantamentos, relatórios, subscrições, compras, checkout, informação comercial, dados de recebimento) foram removidos, sem período de transição, e respondem 404. Troque pelo mesmo caminho sem o prefixo, em /api/...; a gestão de subscrições pela equipa ficou em /api/manage/subscriptions, e as estatísticas de e-mail, em /api/emails/stats. Os nomes de método do SDK não mudaram. Veja Os caminhos que mudaram.

Isto não é um pormenor: com uma única fonte para a comunidade, não há como agir noutra trocando um id no URL.

Algumas rotas antigas também pedem communityId no corpo (criar curso, convidar membros). Envie o mesmo id do header.

#Os caminhos que mudaram

A 6 de outubro de 2026, cada caminho abaixo perdeu o prefixo /api/communities/{communityId}. Os métodos HTTP, os parâmetros, os corpos, as respostas e os papéis exigidos continuam os mesmos.

Os nomes de método do SDK e as páginas da referência continuam os mesmos, porque cada rota manteve o operationId: /api/products continua a ser api.products.postCommunitiesByCommunityIdProducts. Só as nove operações do checkout aninhado saíram; use as de /api/checkout/*.

#Onde achar o id da comunidade

curl -s https://api.memberfy.net/api/communities/my \
  -H "Authorization: Bearer $TOKEN"

#Os erros de quem esquece

O 400 por falta do header é a causa número um de erro na API.

#Exemplo

curl -s https://api.memberfy.net/api/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"

#No SDK

api.setCommunity('<uuid>') uma vez, e o SDK envia o header em todas as chamadas. Para trocar de comunidade, chame setCommunity de novo. Ver SDK JavaScript.

#Perguntas frequentes

Uma integração pode atender duas comunidades? Pode, com uma conta que tenha papel nas duas: troque o header a cada chamada.

As rotas de autenticação pedem o header? Não: login, registo e GET /api/auth/me funcionam sem ele.

#Relacionados

• Autenticação
• Comunidade
• Respostas e erros