# Crear un CRM de OnlyFans con la API: modelo de datos, webhooks y sincronización

> Crea un CRM de OnlyFans con autenticación segura, un modelo de datos relacional, carga del historial y sincronización por webhooks casi en tiempo real.

**En resumen**

- Un modelo de datos completo para un CRM de OnlyFans separa las cuentas de agencia multi-tenant, las carteras de creadores, los perfiles de fans, las conversaciones y los registros financieros.
- La autenticación se basa en sesiones de cliente integradas: los creadores inician sesión con su correo, contraseña y 2FA dentro de un modal seguro.
- El estado inicial de los datos se llena paginando los endpoints de listado de fans, chats e historial de ingresos.
- La sincronización continua funciona con webhooks (desde el plan Basic) como `messages.received` y `transactions.new` para eliminar el polling que consume tanto límite de solicitudes.

Crear un CRM de OnlyFans requiere una base de datos relacional para guardar cuentas, fans, chats y transacciones, combinada con una carga del historial y webhooks basados en eventos que mantengan el sistema sincronizado. Los desarrolladores pueden construir esta arquitectura de backend autenticando a los creadores mediante modales seguros, obteniendo el historial a través de los endpoints de listado REST e ingiriendo los cambios de estado en vivo con webhooks casi en tiempo real (desde el plan Basic).

**Puntos clave**

- Un modelo de datos completo para un CRM de OnlyFans separa las cuentas de agencia multi-tenant, las carteras de creadores, los perfiles de fans, las conversaciones y los registros financieros.
- La autenticación se basa en sesiones de cliente integradas: los creadores inician sesión con su correo, contraseña y 2FA dentro de un modal seguro.
- El estado inicial de los datos se llena paginando los endpoints de listado de fans, chats e historial de ingresos.
- La sincronización continua funciona con webhooks (desde el plan Basic) como `messages.received` y `transactions.new` para eliminar el polling que consume tanto límite de solicitudes.

## ¿Cómo creo un CRM de OnlyFans con una API?

Para crear un CRM de OnlyFans a medida con una API, debes configurar la autenticación integrada, diseñar un modelo de datos relacional para fans y transacciones, cargar el historial mediante los endpoints de listado REST y suscribirte a webhooks casi en tiempo real (desde el plan Basic) para la sincronización continua.

1. **Autenticación y conexión de cuentas**: usa el paquete `@onlyfansapi/auth` para integrar un modal de inicio de sesión seguro.
2. **Modelo de datos relacional**: define tablas para las cuentas de creadores, los perfiles de gasto de los suscriptores, los hilos de chat y los registros de transacciones.
3. **Carga del historial**: pagina endpoints como `GET https://app.fansapi.com/api/{account}/fans/all` para llenar tus bases de datos internas con perfiles e historiales de chat.
4. **Sincronización por webhooks casi en tiempo real**: ingiere eventos como `messages.received` y `transactions.new` para actualizar el estado de la base de datos sin polling continuo.

## Diseño del modelo de datos relacional

Un modelo de datos de CRM aísla las cuentas de agencia multi-tenant de las carteras de creadores, los perfiles de relación con los fans, las conversaciones cronológicas y los registros financieros. Los equipos de ingeniería que desarrollan software propio, como explicamos en nuestra guía de [CRM y software para agencias de OnlyFans](/es/blog/mejor-crm-software-agencias-onlyfans-comparativa), necesitan control programático directo sobre estas entidades.

**Entidades de datos principales**

- **Cuentas de creadores**: guarda los metadatos del creador y el estado de conexión de la sesión. Usa el `onlyfans_id` del creador como clave del registro: un creador que se vuelve a conectar recibe un nuevo ID `acct_`.
- **Fans**: centraliza los metadatos de los suscriptores, el desglose del gasto total, las notas personalizadas y las etiquetas del CRM.
- **Chats y mensajes**: guarda los hilos de conversación, la dirección de los mensajes, los estados PPV y los ID de los medios del CDN adjuntos.
- **Transacciones**: mantiene un registro inmutable de los eventos monetarios para el pago de comisiones y la atribución.

| Nombre del campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | `VARCHAR(64)` | ID de usuario del suscriptor (`fan.id`) |
| `account_id` | `VARCHAR(64)` | ID de la cuenta de creador asociada, que empieza por `acct_` |
| `total_spent` | `DECIMAL(12,2)` | Gasto total (`totalSumm` / `spending.total`) |
| `messages_spent` | `DECIMAL(12,2)` | Gasto en mensajes pagados (`messagesSumm` / `spending.messages`) |
| `subscribes_spent` | `DECIMAL(12,2)` | Gasto en suscripciones (`subscribesSumm` / `spending.subscribes`) |

## Autenticación integrada y conexión de cuentas

Las agencias y los desarrolladores crean flujos de onboarding seguros integrando el paquete oficial de NPM `@onlyfansapi/auth`. El creador inicia sesión con su correo, contraseña y 2FA dentro de nuestro modal seguro.

El backend genera un [token de sesión de cliente](https://docs.fansapi.com/api-reference/client-sessions/create-client-session) mediante `POST https://app.fansapi.com/api/client-sessions`. Después, el frontend abre el modal con `startOnlyFansAuthentication`. Cuando se completa la 2FA, el modal devuelve un `accountId` con el formato `acct_XXXX`, que vincula al creador con el tenant del CRM.

## Carga inicial del historial con los endpoints de listado

En cuanto una cuenta se conecta, el CRM ejecuta una sincronización inicial del historial para llenar la base de datos antes de depender de los webhooks. Como detallamos en nuestra página de la [API de CRM para OnlyFans](https://fansapi.com/onlyfans-crm-api), este proceso recorre suscriptores, conversaciones, historiales de mensajes y transacciones anteriores.

### Paginación de suscriptores y perfiles de gasto

[Obtén todos los fans activos y vencidos](https://docs.fansapi.com/api-reference/fans/list-all-fans) con paginación por offset para capturar el desglose financiero completo.

```typescript
export async function backfillFans(accountId: string, apiKey: string) {
  let offset = 0;
  const limit = 20;
  let hasMore = true;

  while (hasMore) {
    const url = `https://app.fansapi.com/api/${accountId}/fans/all?limit=${limit}&offset=${offset}`;
    const res = await fetch(url, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    const result = await res.json();
    const fans = result.data?.list ?? [];

    // Aquí va la lógica de upsert de cada perfil de fan y sus datos de gasto

    hasMore = result.data?.hasMore === true;
    offset += limit;
  }
}
```

## Sincronización casi en tiempo real con webhooks

Consultar las API de forma continua agota los límites de solicitudes y genera retrasos en la sincronización. Los webhooks entregan los [eventos de mensajes y transacciones](https://docs.fansapi.com/webhooks/available-events) casi en tiempo real (`transactions.new` puede retrasarse hasta 3 minutos). Los webhooks y la infraestructura de proxy móvil dedicada están disponibles desde el plan Basic ($69/mes). OnlyFansAPI ofrece acceso a más de 320 endpoints, ha procesado más de 300 millones de solicitudes de API y webhooks, y lo usan más de 1.100 empresas.

### Catálogo de eventos de webhook principales

- `accounts.connected`: se dispara cuando un creador completa el flujo de autenticación.
- `messages.received`: mensaje entrante de un fan.
- `messages.ppv.unlocked`: un fan compra un mensaje PPV que enviaste.
- `subscriptions.new`: se une un nuevo suscriptor.
- `subscriptions.renewed`: se vuelve a cobrar la suscripción de un suscriptor.
- `subscriptions.expired`: una suscripción vence.
- `transactions.new`: cualquier cobro, como propinas, publicaciones o suscripciones.

Los enrutadores de webhooks deben ingerir estos eventos para actualizar la base de datos del CRM.

```typescript
export async function handleOnlyFansWebhook(req: Request, res: Response) {
  // Primero verifica el encabezado Signature (HMAC SHA256 del cuerpo sin procesar) y omite los valores repetidos de X-OFAPI-Idempotency-Key
  const { event, account_id, payload } = req.body;
  res.status(200).json({ received: true });

  if (event === 'messages.received') {
    // Insertar el mensaje en la base de datos del CRM y actualizar los contadores de no leídos
  } else if (event === 'transactions.new') {
    // Registrar el evento financiero en el libro contable
  }
}
```

## Ejecución de acciones del CRM y sincronización saliente

Para funcionar como un CRM operativo, el sistema ejecuta acciones salientes de vuelta hacia la plataforma. OnlyFansAPI enruta estas solicitudes a través de una IP móvil dedicada por cada cuenta de OnlyFans conectada (EE. UU. o Reino Unido, desde el plan Basic), sin rotación. OnlyFansAPI ha registrado cero baneos en más de 5 años.

### Envío de mensajes salientes y PPV

Los mensajes de chat salientes admiten texto plano, archivos multimedia subidos al CDN y precios PPV. Los mensajes pagados requieren un precio entre 3 y 200 y necesitan `mediaFiles`, salvo que `lockedText` sea true. Los mensajes masivos no tienen modo de prueba (dry-run).

```typescript
export async function sendCrmReply(
  accountId: string,
  chatId: string,
  text: string,
  price: number = 0,
  apiKey: string,
  mediaFiles: string[] = []
) {
  const payload: any = { text };
  if (price > 0) {
    payload.price = price;
    payload.mediaFiles = mediaFiles; // obligatorio en mensajes pagados, salvo que lockedText sea true
  }

  const msgRes = await fetch(`https://app.fansapi.com/api/${accountId}/chats/${chatId}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await msgRes.json();
}
```

### Actualización de notas y segmentación de fans

Un CRM a medida permite a los operadores mantener notas persistentes y listas de segmentos que se sincronizan directamente. Los desarrolladores pueden crear o editar las notas de un fan en la cuenta del creador llamando a `PUT https://app.fansapi.com/api/{account}/fans/{fan_id}/notes` (campo `notes` del cuerpo) y añadir fans a una lista de OnlyFans con `POST https://app.fansapi.com/api/{account}/user-lists/{userListId}/users`.

Crear una herramienta interna a medida permite a las agencias controlar por completo su capa de datos. Combinando autenticación integrada, carga del historial con endpoints de listado e ingesta de webhooks casi en tiempo real, los equipos de desarrollo pueden construir aplicaciones escalables respaldadas por una disponibilidad del 99,98 %.