# X-CommunityId

> La cabecera que dice en qué comunidad ocurre cada llamada y en cuál se comprueba tu rol. Por qué ninguna ruta lleva la comunidad en el camino, dónde encontrar el id de la comunidad y los errores de quien la olvida.

Memberfy se organiza por comunidad, y la API también: **casi todas las llamadas necesitan la cabecera `X-CommunityId`** con el id de la comunidad.

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

## Qué decide

1. **Dónde** ocurre la operación: en qué comunidad se crea el espacio, se lista el producto, se solicita el retiro.
2. **Qué rol** tienes: el permiso se comprueba en tu perfil de **esa** comunidad. La misma cuenta puede ser propietaria de una comunidad y miembro de otra; la cabecera elige cuál vale.

## Manda la cabecera, no la ruta

**Ninguna ruta lleva la comunidad en el camino.** Productos, cupones, planes, comisiones, extracto, retiros, informes, información empresarial, datos de cobro y la gestión de suscripciones están en rutas sin el id de la comunidad (`/api/products`, `/api/coupons`, `/api/manage/subscriptions`…), y la comunidad llega solo por `X-CommunityId`. Sin la cabecera, esas rutas responden `400`.

No es un detalle: con una sola fuente para la comunidad, no hay forma de actuar en otra cambiando un id en la URL.

La excepción es el **SuperAdmin actuando sobre otra comunidad**, en `/api/admin/communities/{communityId}/fee-overrides/...`: ahí el id de la ruta es la comunidad de destino, no el contexto de quien llama. Las rutas de la propia comunidad, `PUT` y `DELETE /api/communities/{id}`, `GET /api/communities/{id}/members` y `PATCH /api/communities/{id}/settings`, llevan el `id` porque la comunidad es el propio recurso; la cabecera sigue siendo obligatoria en ellas.

> [!WARNING]
> **Cambió el 6 de octubre de 2026.** Las rutas antiguas `/api/communities/{communityId}/...` (productos, cupones, planes, comisiones, extracto, retiros, informes, suscripciones, compras, checkout, información empresarial, datos de cobro) se eliminaron, sin periodo de transición, y responden `404`. Usa la misma ruta sin el prefijo, en `/api/...`; la gestión de suscripciones por el equipo quedó en `/api/manage/subscriptions`, y las estadísticas de correo, en `/api/emails/stats`. Los nombres de método del SDK no cambiaron. Consulta [Las rutas que cambiaron](#las-rutas-que-cambiaron).

Algunas rutas antiguas también piden `communityId` en el **cuerpo** (crear curso, invitar miembros). Envía el mismo id que en la cabecera.

## Las rutas que cambiaron

El 6 de octubre de 2026, cada ruta de abajo perdió el prefijo `/api/communities/{communityId}`. Los métodos HTTP, los parámetros, los cuerpos, las respuestas y los roles exigidos siguen siendo los mismos.

| Antes | Después |
|---|---|
| `/api/communities/{communityId}/products/...` | `/api/products/...` |
| `/api/communities/{communityId}/coupons/...` | `/api/coupons/...` |
| `/api/communities/{communityId}/subscription-groups/...` (incluidos `reorder` y `downsell-offers`) | `/api/subscription-groups/...` |
| `/api/communities/{communityId}/fees` y `.../fees/simulate` | `/api/fees` y `/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` (la gestión por el equipo: listar, exportar, crear, detalle, cancelar, reactivar, descuento, complementos, extender, enlace de pago) | `/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 ya existía con las mismas rutas |
| `/webhooks/email/stats/{communityId}` | `/api/emails/stats` (propietario o administrador) |

Los nombres de método del [SDK](/api/sdk-js) y las páginas de la [referencia](/api/referencia) siguen siendo los mismos, porque cada ruta mantuvo su `operationId`: `/api/products` sigue siendo `api.products.postCommunitiesByCommunityIdProducts`. Solo salieron las nueve operaciones del checkout anidado; usa las de `/api/checkout/*`.

## Dónde encontrar el id de la comunidad

| Llamada | Qué devuelve |
|---|---|
| `GET /api/communities/my` | Las comunidades de tu cuenta, con el `id` y tu rol en cada una |
| `GET /api/profiles/my` | Tus perfiles, uno por comunidad |

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

## Los errores de quien la olvida

| Situación | Respuesta |
|---|---|
| Sin la cabecera, o con un valor que no es un id válido | `400` · *Indica la comunidad en el encabezado X-CommunityId.*, con `errors[0].param = "X-CommunityId"` |
| La cabecera es de una comunidad en la que no estás | `403` · *Você não é membro desta comunidade.* ("No eres miembro de esta comunidad") |
| Una ruta antigua, con `/communities/{communityId}/` | `404` |
| El recurso es de otra comunidad | `404`: para la comunidad de la cabecera, no existe |

El `400` por falta de la cabecera es la causa número uno de errores en la API.

## Ejemplo

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

## En el SDK

`api.setCommunity('<uuid>')` una vez, y el SDK envía la cabecera en todas las llamadas. Para cambiar de comunidad, vuelve a llamar a `setCommunity`. Consulta [SDK de JavaScript](/api/sdk-js).

## Preguntas frecuentes

**¿Una integración puede atender dos comunidades?**
Sí, con una cuenta que tenga rol en las dos: cambia la cabecera en cada llamada.

**¿Las rutas de autenticación piden la cabecera?**
No: el inicio de sesión, el registro y `GET /api/auth/me` funcionan sin ella.

## Relacionados

- [Autenticación](/api/autenticacao)
- [Comunidad](/conceitos/comunidade)
- [Respuestas y errores](/api/respostas-e-erros)