# Introduzione all'API

> L'API REST di Memberfy: indirizzo, formato, header e da dove iniziare l'integrazione.

Tutto ciò che fa l'interfaccia di Memberfy passa da un'API REST, ed è aperta anche a te: puoi automatizzare la community, integrarla con altri sistemi o costruire la tua interfaccia.

## L'essenziale

| | |
|---|---|
| **Indirizzo** | `https://api.memberfy.net` |
| **Formato** | JSON, in UTF-8 |
| **Autenticazione** | Token JWT nell'header `Authorization: Bearer <token>`. Vedi [Autenticazione](/api/autenticacao) |
| **Community** | Header `X-CommunityId` in quasi tutte le chiamate. Vedi [X-CommunityId](/api/x-community-id) |
| **Risposte** | Sempre nell'involucro `{ success, message, data }`. Vedi [Risposte ed errori](/api/respostas-e-erros) |
| **Elenchi** | `page` e `limit`. Vedi [Paginazione](/api/paginacao) |
| **Specifica** | OpenAPI 3 su [`/docs.json`](https://api.memberfy.net/docs.json) |
| **SDK** | JavaScript pronto all'uso su [`/sdk.js`](https://api.memberfy.net/sdk.js). Vedi [SDK JavaScript](/api/sdk-js) |

## Gli header

| Header | Quando |
|---|---|
| `Authorization: Bearer <token>` | In tutto ciò che non è login, registrazione o rotta pubblica |
| `X-CommunityId: <uuid>` | Quasi sempre: definisce in quale community avviene l'operazione |
| `X-ProfileId: <uuid>` | Facoltativo: agire a nome di un altro profilo, per chi ha il permesso |
| `Accept-Language` | Facoltativo: la lingua dei messaggi (`pt-BR`, `pt-PT`, `en-US`, `es-ES`, `es-MX`, `es-AR`, `it-IT`, `de-DE`, `de-AT`, `de-CH`). Predefinito `pt-BR` |

## La prima chiamata

```bash
# 1. login
curl -s -X POST https://api.memberfy.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"tu@memberfy.net","password":"la-tua-password"}'

# 2. con il token e l'id della community
curl -s https://api.memberfy.net/api/spaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"
```

## Da dove iniziare

1. [Autenticazione](/api/autenticacao): il token.
2. [X-CommunityId](/api/x-community-id): la community di ogni chiamata.
3. [Ordine di creazione](/api/ordem-de-criacao): che cosa deve esistere prima di ogni chiamata, e da dove arriva ogni id.
4. [Risposte ed errori](/api/respostas-e-erros) e [Paginazione](/api/paginacao).
5. [SDK JavaScript](/api/sdk-js), se usi JavaScript.
6. Il [Riferimento API](/api/referencia), per ogni endpoint.

## Per che cosa le community usano l'API

| Caso | Esempio |
|---|---|
| Integrazione con il CRM | Leggere le vendite del giorno e creare il contatto nel CRM |
| Automatizzare l'ingresso | Invitare lo studente quando l'iscrizione avviene in un altro sistema |
| Creare contenuti in blocco | Creare un corso con 30 lezioni in una volta sola |
| Report | Esportare l'estratto conto nel foglio di calcolo dell'amministrazione |
| Un'interfaccia propria | Mostrare gli eventi della community sul sito dell'azienda |
| Ricerca | Trovare un post, un evento, un corso, uno spazio o una call per titolo, senza badare ad accenti e maiuscole, con [`GET /api/search`](/api/referencia/feed/get-search) |

## Che cosa permette il tuo ruolo

L'API applica le stesse regole dell'interfaccia: il token appartiene a una persona, e ciò che può fare dipende dal suo [ruolo](/conceitos/papeis-e-permissoes) nella community dell'`X-CommunityId`. Un membro comune legge e partecipa; chi amministra crea e configura.

## Come cambia l'API

L'API cresce per aggiunta: nuovi endpoint e nuovi campi compaiono senza preavviso, e il tuo codice deve ignorare i campi che non conosce. Il riferimento di questo centro assistenza viene generato dalla specifica stessa a ogni pubblicazione, quindi mostra sempre ciò che è in produzione.

## Riferimento

Ogni endpoint, con parametri, corpo, risposte ed esempio in curl, si trova nel [Riferimento API](/api/referencia), generato dalla specifica stessa.

## Per l'IA e la generazione di codice

- [`/docs.txt`](https://api.memberfy.net/docs.txt): riferimento compatto, comodo da incollare in un assistente. Accetta `?tags=Auth,Events` per inviare solo ciò che serve.
- [`/docs.json`](https://api.memberfy.net/docs.json): la specifica completa, per generare client tipizzati.

> [!NOTE]
> Una parte degli endpoint di scrittura (upload multipart e alcuni POST) non dichiara i campi del corpo nella specifica. In questi casi la pagina dell'endpoint lo segnala, e la guida dell'argomento spiega i campi.