# X-CommunityId

> O header que diz em qual comunidade cada chamada acontece e em qual o seu papel é conferido. Por que nenhuma rota leva a comunidade no caminho, onde encontrar o id da comunidade e os erros de quem esquece.

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 saque é 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, cupons, planos, taxas, extrato, saques, relatórios, informação comercial, dados de recebimento e a gestão de assinaturas 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`.

Isso não é detalhe: com uma fonte só para a comunidade, não há como agir em outra trocando um id na URL.

A exceção é o **SuperAdmin agindo sobre outra comunidade**, em `/api/admin/communities/{communityId}/fee-overrides/...`: ali 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.

> [!WARNING]
> **Mudou em 6 de outubro de 2026.** Os caminhos antigos `/api/communities/{communityId}/...` (produtos, cupons, planos, taxas, extrato, saques, relatórios, assinaturas, 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 assinaturas pela equipe 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](#os-caminhos-que-mudaram).

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

## Os caminhos que mudaram

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

| Antes | Depois |
|---|---|
| `/api/communities/{communityId}/products/...` | `/api/products/...` |
| `/api/communities/{communityId}/coupons/...` | `/api/coupons/...` |
| `/api/communities/{communityId}/subscription-groups/...` (inclusive `reorder` e `downsell-offers`) | `/api/subscription-groups/...` |
| `/api/communities/{communityId}/fees` e `.../fees/simulate` | `/api/fees` e `/api/fees/simulate` |
| `/api/communities/{communityId}/ledger/...` | `/api/ledger/...` |
| `/api/communities/{communityId}/payouts/...` | `/api/payouts/...` |
| `/api/communities/{communityId}/reports/...` | `/api/reports/...` |
| `/api/communities/{communityId}/business-information/...` | `/api/business-information/...` |
| `/api/communities/{communityId}/payout-settings/...` | `/api/payout-settings/...` |
| `/api/communities/{communityId}/subscriptions` (a gestão pela equipe: listar, exportar, criar, detalhe, cancelar, reativar, desconto, adicionais, estender, link de pagamento) | `/api/manage/subscriptions/...` |
| `/api/communities/{communityId}/subscriptions/me` | `/api/subscriptions/me` |
| `/api/communities/{communityId}/purchases/me` | `/api/purchases/me` |
| `/api/communities/{communityId}/checkout/...` | `/api/checkout/...`, que já existia com os mesmos caminhos |
| `/webhooks/email/stats/{communityId}` | `/api/emails/stats` (proprietário ou administrador) |

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

## Onde achar o id da comunidade

| Chamada | O que devolve |
|---|---|
| `GET /api/communities/my` | As comunidades da sua conta, com o `id` e o seu papel em cada uma |
| `GET /api/profiles/my` | Os seus perfis, um por comunidade |

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

## Os erros de quem esquece

| Situação | Resposta |
|---|---|
| Sem o header, ou com um valor que não é um id válido | `400` · *Informe a comunidade no header X-CommunityId.*, com `errors[0].param = "X-CommunityId"` |
| O header é de uma comunidade em que você não está | `403` · *Você não é membro desta comunidade.* |
| Um caminho antigo, com `/communities/{communityId}/` | `404` |
| O recurso é de outra comunidade | `404`: para a comunidade do header, ele não existe |

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

## Exemplo

```bash
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](/api/sdk-js).

## 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, cadastro e `GET /api/auth/me` funcionam sem ele.

## Relacionados

- [Autenticação](/api/autenticacao)
- [Comunidade](/conceitos/comunidade)
- [Respostas e erros](/api/respostas-e-erros)