# X-CommunityId

> Der Header, der festlegt, in welcher Community jeder Aufruf stattfindet und in welcher deine Rolle geprüft wird. Warum keine Route die Community im Pfad trägt, wo du die Community-ID findest und welche Fehler kommen, wenn er fehlt.

Memberfy ist nach Communities organisiert, und die API auch: **Fast jeder Aufruf braucht den Header `X-CommunityId`** mit der ID der Community.

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

## Was er entscheidet

1. **Wo** die Operation stattfindet: in welcher Community der Bereich angelegt, das Produkt gelistet, die Auszahlung angefordert wird.
2. **Welche Rolle** du hast: Die Berechtigung wird an deinem Profil in **dieser** Community geprüft. Dasselbe Konto kann in einer Community Eigentümer und in einer anderen Mitglied sein; der Header wählt, was gilt.

## Der Header zählt, nicht der Pfad

**Keine Route trägt die Community im Pfad.** Produkte, Gutscheine, Pläne, Gebühren, Kontoauszug, Auszahlungen, Berichte, Geschäftsinformationen, Auszahlungsdaten und die Abonnementverwaltung liegen unter Pfaden ohne Community-ID (`/api/products`, `/api/coupons`, `/api/manage/subscriptions` …), und die Community kommt nur aus `X-CommunityId`. Ohne den Header antworten diese Routen mit `400`.

Das ist kein Detail: Mit nur einer Quelle für die Community kann niemand in einer anderen handeln, indem er eine ID in der URL austauscht.

Die Ausnahme ist der **SuperAdmin, der auf eine andere Community wirkt**, unter `/api/admin/communities/{communityId}/fee-overrides/...`: Dort ist die ID im Pfad die Ziel-Community, nicht der Kontext des Aufrufers. Die Routen der Community selbst, `PUT` und `DELETE /api/communities/{id}`, `GET /api/communities/{id}/members` und `PATCH /api/communities/{id}/settings`, tragen die `id`, weil die Community die Ressource selbst ist; der Header bleibt auch dort Pflicht.

> [!WARNING]
> **Geändert am 6. Oktober 2026.** Die alten Pfade `/api/communities/{communityId}/...` (Produkte, Gutscheine, Pläne, Gebühren, Kontoauszug, Auszahlungen, Berichte, Abonnements, Käufe, Checkout, Geschäftsinformationen, Auszahlungsdaten) wurden ohne Übergangszeit entfernt und antworten mit `404`. Nimm denselben Pfad ohne das Präfix, unter `/api/...`; die Abonnementverwaltung durch das Team liegt jetzt unter `/api/manage/subscriptions`, die E-Mail-Statistik unter `/api/emails/stats`. Die Methodennamen des SDK haben sich nicht geändert. Siehe [Die geänderten Pfade](#die-geanderten-pfade).

Einige ältere Routen verlangen `communityId` auch im **Body** (Kurs anlegen, Mitglieder einladen). Schick dieselbe ID wie im Header.

## Die geänderten Pfade

Am 6. Oktober 2026 hat jeder Pfad unten das Präfix `/api/communities/{communityId}` verloren. HTTP-Methoden, Parameter, Bodys, Antworten und die verlangten Rollen bleiben gleich.

| Vorher | Nachher |
|---|---|
| `/api/communities/{communityId}/products/...` | `/api/products/...` |
| `/api/communities/{communityId}/coupons/...` | `/api/coupons/...` |
| `/api/communities/{communityId}/subscription-groups/...` (auch `reorder` und `downsell-offers`) | `/api/subscription-groups/...` |
| `/api/communities/{communityId}/fees` und `.../fees/simulate` | `/api/fees` und `/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` (die Verwaltung durch das Team: auflisten, exportieren, anlegen, Detail, kündigen, reaktivieren, Rabatt, Add-ons, verlängern, Zahlungslink) | `/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/...`, das es mit denselben Pfaden schon gab |
| `/webhooks/email/stats/{communityId}` | `/api/emails/stats` (Eigentümer oder Administrator) |

Die Methodennamen des [SDK](/api/sdk-js) und die Seiten der [Referenz](/api/referencia) bleiben gleich, weil jede Route ihre `operationId` behalten hat: `/api/products` ist weiterhin `api.products.postCommunitiesByCommunityIdProducts`. Nur die neun Operationen des verschachtelten Checkouts sind weggefallen; nimm die von `/api/checkout/*`.

## Wo du die Community-ID findest

| Aufruf | Was er liefert |
|---|---|
| `GET /api/communities/my` | Die Communities deines Kontos, mit der `id` und deiner Rolle in jeder |
| `GET /api/profiles/my` | Deine Profile, eines pro Community |

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

## Die Fehler, wenn er fehlt

| Situation | Antwort |
|---|---|
| Ohne Header, oder mit einem Wert, der keine gültige ID ist | `400` · *Gib die Community im Header X-CommunityId an.*, mit `errors[0].param = "X-CommunityId"` |
| Der Header gehört zu einer Community, in der du nicht bist | `403` · Du bist kein Mitglied dieser Community |
| Ein alter Pfad mit `/communities/{communityId}/` | `404` |
| Die Ressource gehört zu einer anderen Community | `404`: Für die Community im Header existiert sie nicht |

Der `400` wegen fehlendem Header ist die häufigste Fehlerursache bei der API.

## Beispiel

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

## Im SDK

Einmal `api.setCommunity('<uuid>')`, und das SDK schickt den Header bei allen Aufrufen mit. Um die Community zu wechseln, rufst du `setCommunity` erneut auf. Siehe [JavaScript-SDK](/api/sdk-js).

## Häufige Fragen

**Kann eine Integration zwei Communities bedienen?**
Ja, mit einem Konto, das in beiden eine Rolle hat: Wechsle den Header bei jedem Aufruf.

**Brauchen die Authentifizierungsrouten den Header?**
Nein: Login, Registrierung und `GET /api/auth/me` funktionieren ohne ihn.

## Verwandte Artikel

- [Authentifizierung](/api/autenticacao)
- [Community](/conceitos/comunidade)
- [Antworten und Fehler](/api/respostas-e-erros)