# Introducción a la API

> La API REST de Memberfy: dirección, formato, cabeceras y por dónde empezar a integrar.

Todo lo que hace la pantalla de Memberfy pasa por una API REST, y está abierta para ti: puedes automatizar la comunidad, integrarla con otros sistemas o montar tu propia interfaz.

## Lo esencial

| | |
|---|---|
| **Dirección** | `https://api.memberfy.net` |
| **Formato** | JSON, en UTF-8 |
| **Autenticación** | Token JWT en la cabecera `Authorization: Bearer <token>`. Consulta [Autenticación](/api/autenticacao) |
| **Comunidad** | Cabecera `X-CommunityId` en casi todas las llamadas. Consulta [X-CommunityId](/api/x-community-id) |
| **Respuestas** | Siempre en el sobre `{ success, message, data }`. Consulta [Respuestas y errores](/api/respostas-e-erros) |
| **Listados** | `page` y `limit`. Consulta [Paginación](/api/paginacao) |
| **Especificación** | OpenAPI 3 en [`/docs.json`](https://api.memberfy.net/docs.json) |
| **SDK** | JavaScript listo en [`/sdk.js`](https://api.memberfy.net/sdk.js). Consulta [SDK de JavaScript](/api/sdk-js) |

## Las cabeceras

| Cabecera | Cuándo |
|---|---|
| `Authorization: Bearer <token>` | En todo lo que no sea inicio de sesión, registro o ruta pública |
| `X-CommunityId: <uuid>` | Casi siempre: define en qué comunidad ocurre la operación |
| `X-ProfileId: <uuid>` | Opcional: actuar en nombre de otro perfil, para quien tiene permiso |
| `Accept-Language` | Opcional: el idioma de los mensajes (`pt-BR`, `pt-PT`, `en-US`, `es-ES`, `es-MX`, `es-AR`, `it-IT`, `de-DE`, `de-AT`, `de-CH`). Por defecto, `pt-BR` |

## Primera llamada

```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":"tu-contraseña"}'

# 2. con el token y el id de la comunidad
curl -s https://api.memberfy.net/api/spaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CommunityId: $COMMUNITY_ID"
```

## Por dónde empezar

1. [Autenticación](/api/autenticacao): el token.
2. [X-CommunityId](/api/x-community-id): la comunidad de cada llamada.
3. [Orden de creación](/api/ordem-de-criacao): qué tiene que existir antes de cada llamada y de dónde sale cada id.
4. [Respuestas y errores](/api/respostas-e-erros) y [Paginación](/api/paginacao).
5. [SDK de JavaScript](/api/sdk-js), si usas JavaScript.
6. La [Referencia de la API](/api/referencia), para cada endpoint.

## Para qué usan la API las comunidades

| Caso | Ejemplo |
|---|---|
| Integrar con el CRM | Leer las ventas del día y crear el contacto en el CRM |
| Automatizar las altas | Invitar al alumno cuando la matrícula se hace en otro sistema |
| Crear contenido en bloque | Crear un curso con 30 lecciones de una vez |
| Informes | Exportar el extracto a la hoja de cálculo de finanzas |
| Una interfaz propia | Mostrar los eventos de la comunidad en la web de la empresa |
| Búsqueda | Encontrar una publicación, un evento, un curso, un espacio o una convocatoria por el título, sin importar tildes ni mayúsculas, con [`GET /api/search`](/api/referencia/feed/get-search) |

## Lo que permite tu rol

La API aplica las mismas reglas que la pantalla: el token es de una persona, y lo que puede hacer depende de su [rol](/conceitos/papeis-e-permissoes) en la comunidad del `X-CommunityId`. Un miembro normal lee y participa; quien administra crea y configura.

## Cómo cambia la API

La API crece por adición: endpoints y campos nuevos aparecen sin aviso previo, y tu código debe ignorar los campos que no conoce. La referencia de este centro se genera a partir de la propia especificación en cada publicación, así que siempre muestra lo que está en producción.

## Referencia

Cada endpoint, con parámetros, cuerpo, respuestas y ejemplo en curl, está en la [Referencia de la API](/api/referencia), generada a partir de la propia especificación.

## Para IA y generación de código

- [`/docs.txt`](https://api.memberfy.net/docs.txt): referencia compacta, ideal para pegarla en un asistente. Acepta `?tags=Auth,Events` para enviar solo lo que importa.
- [`/docs.json`](https://api.memberfy.net/docs.json): la especificación completa, para generar clientes tipados.

> [!NOTE]
> Parte de los endpoints de escritura (subidas en multipart y algunos POST) no declara los campos del cuerpo en la especificación. En esos casos, la página del endpoint lo avisa, y la guía del tema explica los campos.