# SDK de JavaScript

> El cliente que la API publica en /sdk.js y /sdk.mjs, generado a partir de la propia especificación. Cómo cargarlo en el navegador y en Node, los métodos por tema, cómo pasar parámetros y cuerpo, el tratamiento de errores y las opciones del cliente.

La API publica un **SDK de JavaScript** generado a partir de la propia especificación OpenAPI. Cubre todas las operaciones, envía las cabeceras por ti, desenvuelve el sobre de las respuestas y convierte los errores en excepciones.

| Archivo | Uso |
|---|---|
| [`/sdk.js`](https://api.memberfy.net/sdk.js) | UMD: `<script src>` (expone `Memberfy`) o `require()` en Node |
| [`/sdk.mjs`](https://api.memberfy.net/sdk.mjs) | ESM: `import { createClient } from '…/sdk.mjs'` |

## Empezar en el navegador

```html
<script src="https://api.memberfy.net/sdk.js"></script>
<script>
  const api = Memberfy.createClient({ baseUrl: 'https://api.memberfy.net' });

  const session = await api.auth.login({ email, password });
  api.setToken(session.token).setCommunity(communityId);

  const me = await api.auth.getMe();
</script>
```

**Pasa siempre el `baseUrl` con `https://`.**

## Empezar en Node

Descarga el archivo en el proyecto e impórtalo en local (Node 18 o posterior, que ya incluye `fetch`):

```bash
curl -s https://api.memberfy.net/sdk.mjs -o memberfy-sdk.mjs
```

```js
import { createClient } from './memberfy-sdk.mjs';

const api = createClient({ baseUrl: 'https://api.memberfy.net' });
const session = await api.auth.login({ email: process.env.MEMBERFY_EMAIL, password: process.env.MEMBERFY_PASSWORD });
api.setToken(session.token).setCommunity(process.env.MEMBERFY_COMMUNITY_ID);
```

Vuelve a descargarlo cuando quieras actualizarlo.

## Lo que hace por ti

| | |
|---|---|
| **Cabeceras** | `Authorization`, `X-CommunityId`, `X-ProfileId` y `Accept-Language`, a partir de `setToken`, `setCommunity`, `setProfile` y `setLanguage` |
| **Sobre** | Devuelve el `data` directamente; los listados devuelven `{ data, pagination }` |
| **Errores** | Lanza `MemberfyError`, con `.status`, `.body` y `.errors` |
| **Sesión** | `onUnauthorized` se llama ante un `401`, para que vuelvas a iniciar sesión |

## Los métodos

Los métodos están agrupados por tema (el mismo de la [referencia](/api/referencia)): `api.auth`, `api.products`, `api.subscriptions`, `api.coupons`, `api.sectionsSpaces`, `api.events`… El nombre del método sale del `operationId` de la operación: `api.products.postCommunitiesByCommunityIdProducts`, `api.profiles.getList`, `api.auth.login`.

Algunos nombres todavía llevan `CommunitiesByCommunityId` de cuando la ruta tenía la comunidad en el camino. Desde el 6 de octubre de 2026 ninguna ruta lleva la comunidad en el camino, pero los nombres se mantuvieron para que nada se rompa en tu código. La comunidad va siempre por `setCommunity`. Consulta [X-CommunityId](/api/x-community-id#las-rutas-que-cambiaron).

En la página de cada endpoint de la referencia aparece el `operationId`.

## Parámetros y cuerpo

Los parámetros de ruta y de query van por su nombre; **el resto se convierte en el cuerpo**:

```js
api.setCommunity(communityId); // the community goes in the X-CommunityId header

await api.products.putCommunitiesByCommunityIdProductsById({
  id: productId,               // goes to the path
  type: 'SUBSCRIPTION',        // body
  title: 'Alumno · Mensual',   // body
  price: 49,                   // body
  billingInterval: 'MONTHLY',  // body
  allowedPaymentMethods: ['PIX', 'CREDIT_CARD', 'BOLETO'],
});
```

También puedes separarlos: `{ id, body: { … } }`. **No pases `communityId` en los argumentos**: como ya no es parámetro de ruta, iría al cuerpo. Otras opciones por llamada: `headers` (cabeceras adicionales), `query` (parámetros de query extra) y `signal` (un `AbortController`).

Para cualquier ruta, existe `api.request({ httpMethod, path, pathParams, queryParams, hasBody }, args)`.

## Tratar errores

```js
try {
  await api.coupons.postCommunitiesByCommunityIdCouponsValidate({ code: 'LANZAMIENTO20' });
} catch (error) {
  if (error.name === 'MemberfyError') {
    console.log(error.status);  // 400
    console.log(error.errors);  // [{ param: 'code', message: 'El cupón ha expirado' }]
  }
}
```

## Opciones del cliente

| Opción | Para qué |
|---|---|
| `baseUrl` | La dirección de la API. Usa `https://api.memberfy.net` |
| `token`, `communityId`, `profileId`, `language` | Valores iniciales de las cabeceras |
| `raw: true` | Devuelve el cuerpo en bruto, con el sobre |
| `onUnauthorized` | Función que se llama ante un `401` |
| `fetch` | Una implementación de `fetch`, para entornos sin la nativa |

## Siempre al día

El SDK se genera cada vez que se sirve, a partir de las rutas de la API. Volver a descargarlo es actualizarlo.

## Para IA

Para que un asistente genere llamadas correctas, dale también el [`/docs.txt`](https://api.memberfy.net/docs.txt): el SDK dice **cómo** llamar; el `/docs.txt` dice **qué** enviar.

## Relacionados

- [Autenticación](/api/autenticacao)
- [Respuestas y errores](/api/respostas-e-erros)
- [Referencia de la API](/api/referencia)