# X-CommunityId

> L'header che indica in quale community avviene ogni chiamata e in quale viene verificato il tuo ruolo. Perché nessuna rotta porta la community nel percorso, dove trovare l'id della community e gli errori di chi lo dimentica.

Memberfy è organizzata per community, e lo è anche l'API: **quasi ogni chiamata richiede l'header `X-CommunityId`** con l'id della community.

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

## Che cosa decide

1. **Dove** avviene l'operazione: in quale community viene creato lo spazio, elencato il prodotto, richiesto il prelievo.
2. **Quale ruolo** hai: il permesso viene verificato sul tuo profilo in **quella** community. Lo stesso account può essere proprietario di una community e membro di un'altra; l'header sceglie quale vale.

## Conta l'header, non il percorso

**Nessuna rotta porta la community nel percorso.** Prodotti, coupon, piani, commissioni, estratto conto, prelievi, report, informazioni aziendali, dati di accredito e la gestione degli abbonamenti stanno in percorsi senza l'id della community (`/api/products`, `/api/coupons`, `/api/manage/subscriptions`…), e la community arriva solo dall'`X-CommunityId`. Senza l'header, queste rotte rispondono `400`.

Non è un dettaglio: con un'unica fonte per la community, non c'è modo di agire in un'altra cambiando un id nell'URL.

L'eccezione è il **SuperAdmin che agisce su un'altra community**, in `/api/admin/communities/{communityId}/fee-overrides/...`: lì l'id nel percorso è la community di destinazione, non il contesto di chi chiama. Le rotte della community stessa, `PUT` e `DELETE /api/communities/{id}`, `GET /api/communities/{id}/members` e `PATCH /api/communities/{id}/settings`, portano l'`id` perché la community è la risorsa stessa; anche lì l'header resta obbligatorio.

> [!WARNING]
> **Cambiato il 6 ottobre 2026.** I vecchi percorsi `/api/communities/{communityId}/...` (prodotti, coupon, piani, commissioni, estratto conto, prelievi, report, abbonamenti, acquisti, checkout, informazioni aziendali, dati di accredito) sono stati rimossi, senza periodo di transizione, e rispondono `404`. Usa lo stesso percorso senza il prefisso, in `/api/...`; la gestione degli abbonamenti da parte del team è in `/api/manage/subscriptions`, e le statistiche delle e-mail in `/api/emails/stats`. I nomi dei metodi dell'SDK non sono cambiati. Vedi [I percorsi cambiati](#i-percorsi-cambiati).

Alcune rotte più vecchie chiedono `communityId` anche nel **corpo** (creare un corso, invitare membri). Invia lo stesso id dell'header.

## I percorsi cambiati

Il 6 ottobre 2026 ogni percorso qui sotto ha perso il prefisso `/api/communities/{communityId}`. Metodi HTTP, parametri, corpi, risposte e ruoli richiesti restano gli stessi.

| Prima | Dopo |
|---|---|
| `/api/communities/{communityId}/products/...` | `/api/products/...` |
| `/api/communities/{communityId}/coupons/...` | `/api/coupons/...` |
| `/api/communities/{communityId}/subscription-groups/...` (compresi `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` (la gestione da parte del team: elencare, esportare, creare, dettaglio, annullare, riattivare, sconto, componenti aggiuntivi, estendere, link di 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/...`, che esisteva già con gli stessi percorsi |
| `/webhooks/email/stats/{communityId}` | `/api/emails/stats` (proprietario o admin) |

I nomi dei metodi dell'[SDK](/api/sdk-js) e le pagine del [riferimento](/api/referencia) restano gli stessi, perché ogni rotta ha mantenuto l'`operationId`: `/api/products` è ancora `api.products.postCommunitiesByCommunityIdProducts`. Sono uscite solo le nove operazioni del checkout annidato; usa quelle di `/api/checkout/*`.

## Dove trovare l'id della community

| Chiamata | Che cosa restituisce |
|---|---|
| `GET /api/communities/my` | Le community del tuo account, con l'`id` e il tuo ruolo in ciascuna |
| `GET /api/profiles/my` | I tuoi profili, uno per community |

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

## Gli errori di chi lo dimentica

| Situazione | Risposta |
|---|---|
| Senza l'header, o con un valore che non è un id valido | `400` · *Indica la community nell'header X-CommunityId.*, con `errors[0].param = "X-CommunityId"` |
| L'header è di una community di cui non fai parte | `403` · *Você não é membro desta comunidade.* |
| Un percorso vecchio, con `/communities/{communityId}/` | `404` |
| La risorsa appartiene a un'altra community | `404`: per la community dell'header, non esiste |

Il `400` per header mancante è la causa numero uno di errore nell'API.

## Esempio

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

## Nell'SDK

`api.setCommunity('<uuid>')` una volta, e l'SDK invia l'header in tutte le chiamate. Per cambiare community, chiama di nuovo `setCommunity`. Vedi [SDK JavaScript](/api/sdk-js).

## Domande frequenti

**Un'integrazione può servire due community?**
Sì, con un account che abbia un ruolo in entrambe: cambia l'header a ogni chiamata.

**Le rotte di autenticazione richiedono l'header?**
No: login, registrazione e `GET /api/auth/me` funzionano senza.

## Correlati

- [Autenticazione](/api/autenticacao)
- [Community](/conceitos/comunidade)
- [Risposte ed errori](/api/respostas-e-erros)