# Introdução à API

> A API REST da Memberfy: endereço, formato, headers e por onde começar a integrar.

Tudo o que a tela da Memberfy faz passa por uma API REST, e ela é aberta para você: dá para automatizar a comunidade, integrar com outros sistemas ou montar a sua própria interface.

## O essencial

| | |
|---|---|
| **Endereço** | `https://api.memberfy.net` |
| **Formato** | JSON, em UTF-8 |
| **Autenticação** | Token JWT no header `Authorization: Bearer <token>`. Ver [Autenticação](/api/autenticacao) |
| **Comunidade** | Header `X-CommunityId` em quase toda chamada. Ver [X-CommunityId](/api/x-community-id) |
| **Respostas** | Sempre no envelope `{ success, message, data }`. Ver [Respostas e erros](/api/respostas-e-erros) |
| **Listagens** | `page` e `limit`. Ver [Paginação](/api/paginacao) |
| **Especificação** | OpenAPI 3 em [`/docs.json`](https://api.memberfy.net/docs.json) |
| **SDK** | JavaScript pronto em [`/sdk.js`](https://api.memberfy.net/sdk.js). Ver [SDK JavaScript](/api/sdk-js) |

## Os headers

| Header | Quando |
|---|---|
| `Authorization: Bearer <token>` | Em tudo que não seja login, cadastro ou rota pública |
| `X-CommunityId: <uuid>` | Quase sempre: define em qual comunidade a operação acontece |
| `X-ProfileId: <uuid>` | Opcional: agir em nome de outro perfil, para quem tem permissão |
| `Accept-Language` | Opcional: o idioma das mensagens (`pt-BR`, `pt-PT`, `en-US`, `es-ES`, `es-MX`, `es-AR`, `it-IT`, `de-DE`, `de-AT`, `de-CH`). Padrão `pt-BR` |

## Primeira chamada

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

# 2. com o token e o id da comunidade
curl -s https://api.memberfy.net/api/spaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"
```

## Por onde começar

1. [Autenticação](/api/autenticacao): o token.
2. [X-CommunityId](/api/x-community-id): a comunidade de cada chamada.
3. [Ordem de criação](/api/ordem-de-criacao): o que precisa existir antes de cada chamada, e de onde vem cada id.
4. [Respostas e erros](/api/respostas-e-erros) e [Paginação](/api/paginacao).
5. [SDK JavaScript](/api/sdk-js), se você usa JavaScript.
6. A [Referência da API](/api/referencia), para cada endpoint.

## Para que as comunidades usam a API

| Caso | Exemplo |
|---|---|
| Integrar com o CRM | Ler as vendas do dia e criar o contato no CRM |
| Automatizar a entrada | Convidar o aluno quando a matrícula é feita em outro sistema |
| Montar conteúdo em lote | Criar um curso com 30 aulas de uma vez |
| Relatórios | Exportar o extrato para a planilha do financeiro |
| Uma interface própria | Mostrar os eventos da comunidade no site da empresa |
| Busca | Achar um post, evento, curso, espaço ou chamada pelo título, sem acento nem maiúscula, com [`GET /api/search`](/api/referencia/feed/get-search) |

## O que o seu papel permite

A API aplica as mesmas regras da tela: o token é de uma pessoa, e o que ela pode fazer depende do [papel](/conceitos/papeis-e-permissoes) dela na comunidade do `X-CommunityId`. Um membro comum lê e participa; quem administra cria e configura.

## Como a API muda

A API cresce por adição: endpoints novos e campos novos aparecem sem aviso prévio, e o seu código deve ignorar campos que não conhece. A referência desta central é gerada da própria especificação a cada publicação, então mostra sempre o que está no ar.

## Referência

Cada endpoint, com parâmetros, corpo, respostas e exemplo em curl, está na [Referência da API](/api/referencia), gerada da própria especificação.

## Para IA e geração de código

- [`/docs.txt`](https://api.memberfy.net/docs.txt): referência compacta, boa para colar num assistente. Aceita `?tags=Auth,Events` para mandar só o que importa.
- [`/docs.json`](https://api.memberfy.net/docs.json): a especificação completa, para gerar clientes tipados.

> [!NOTE]
> Parte dos endpoints de escrita (uploads em multipart e alguns POSTs) não declara os campos do corpo na especificação. Nesses casos, a página do endpoint avisa, e o guia do assunto explica os campos.