Inicio rápido de la Fansly API: autenticación, endpoints y verificación HMAC de webhooks

La economía de creadores ha pasado de los perfiles aislados en redes sociales a empresas digitales con un enorme volumen de operaciones. En plataformas que superan los 130 millones de usuarios registrados, gestionar varias cuentas de creadores a mano o con frágiles scripts de scraping obtenidos por ingeniería inversa ya no es una estrategia viable para las agencias ni para los proveedores de herramientas empresariales. Esta guía de inicio rápido sirve como documentación de API completa para los desarrolladores que quieren crear CRM escalables, herramientas de envío masivo y paneles de ingresos.

Tanto si integras de forma nativa como si usas orquestadores de flujos de trabajo, entender cómo gestionar las claves de API, procesar los formatos de moneda basados en enteros y verificar de forma segura los webhooks de una API en tiempo real es fundamental para un despliegue de nivel de producción.

¿Qué es la Fansly API?

La Fansly API es una plataforma para desarrolladores de nivel empresarial creada por Fans Holdings OÜ que sustituye la automatización con navegadores headless por una infraestructura oficial y estable. Diseñada para agencias de gestión de creadores y plataformas SaaS, expone más de 200 endpoints REST activos que cubren mensajería, perfiles de CRM, transacciones y bóvedas de contenido multimedia.

Con un historial en producción de más de 5000 cuentas de creadores conectadas y más de 150 millones de solicitudes procesadas sin ningún baneo de la plataforma, la Fansly API ofrece un entorno seguro para escalar cuentas. También incluye una arquitectura push en tiempo real mediante webhooks firmados criptográficamente, que elimina la necesidad de hacer polling continuo, muy costoso en créditos.

Paso 1: autenticación de la API y gestión de claves

Una autenticación de API segura es la base de tu integración. La plataforma usa autenticación con bearer token, que obliga a los desarrolladores a enviar un token seguro en las cabeceras HTTP de cada solicitud.

Generar claves de API y definir su alcance

Para interactuar con la plataforma, debes autenticar tus clientes HTTP con claves de API generadas desde tu panel de desarrollador. Según la guía de integración de la Fansly API, debes seguir estos pasos:

1. Registra una cuenta: crea una cuenta en la plataforma Fansly API. Los nuevos desarrolladores reciben una asignación de prueba de 100 créditos de bienvenida gratuitos para probar conexiones reales.
2. Crea una clave de API: abre app.onlyfansapi.com/api-keys y genera una clave. Las claves no tienen alcance limitado: cada clave puede llamar a todos los endpoints para todas las cuentas conectadas a tu equipo, así que crea una clave por integración y rota cualquier clave que entregues a un desarrollador externo.
3. Protege tus secretos: guarda tus claves de API en un entorno de ejecución seguro, como AWS Secrets Manager o archivos .env cifrados. Nunca las subas a un control de versiones público.

Cabeceras de solicitud estándar

Cada solicitud entrante necesita cabeceras HTTP específicas para definir el tipo de payload, autenticar al cliente y apuntar a cuentas de creadores concretas.

Ejemplo de autenticación con cURL:

curl -X GET "https://app.onlyfansapi.com/api/fansly/fansly_acct_XXXXXXXXXXXXXXX/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Paso 2: recorrido por los endpoints principales de la API

Una vez autenticados, los desarrolladores acceden a más de 200 endpoints de API activos repartidos en seis dominios de recursos principales. Estos endpoints te permiten orquestar por programación flujos de trabajo complejos de agencia.

• Cuentas y sesiones: endpoints como /api/v1/accounts conectan cuentas de creadores mediante 2FA e inspeccionan el estado de las sesiones de proxy.
• Mensajería: usa /api/v1/chats y /api/v1/messages/mass para leer mensajes directos, enviar respuestas de chatbot en tiempo real o poner en cola envíos masivos de PPV.
• Fans y CRM: consulta el historial de gasto de los fans, las fechas de suscripción y los niveles de interacción mediante /api/v1/fans.
• Finanzas: concilia ingresos brutos, comisiones de la plataforma, pagos netos y conversiones de enlaces de seguimiento con /api/v1/earnings/summary.
• Contenido multimedia y bóveda: sube archivos multimedia (hasta 1 GB mediante URL remota) y publica posts del feed bloqueados por nivel a través de /api/v1/vault/media.

Paso 3: integridad de los datos financieros (el formato en milidólares)

Un error de integración habitual en las plataformas de la economía de creadores es el mal manejo de la moneda. Las operaciones estándar de coma flotante IEEE 754 (como 0.1 + 0.2 en JavaScript) introducen desviaciones de precisión, que se acumulan hasta convertirse en errores contables importantes a lo largo de miles de desbloqueos de PPV y propinas.

Para garantizar la integridad de los datos financieros, Fansly representa la moneda en milésimas de dólar (milidólares).

• $1,00 USD = 1000
• $5,00 USD = 5000
• $15,50 USD = 15500
• $0,05 USD (5 centavos) = 50

Ejemplo de conversión en TypeScript

Al crear paneles, redondea siempre tus conversiones para evitar anomalías de representación intermedia:

export class FanslyCurrency {
  public static toMillidollars(dollars: number | string): number {
    const parsed = typeof dollars === 'string' ? parseFloat(dollars) : dollars;
    if (isNaN(parsed) || !isFinite(parsed)) throw new TypeError('Invalid amount');
    return Math.round(parsed * 1000);
  }
 
  public static toFormattedUSD(millidollars: number): string {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD',
    }).format(millidollars / 1000);
  }
}

Paso 4: códigos de estado HTTP y gestión de errores

La plataforma cumple con los códigos de respuesta HTTP estándar de la RFC 7231. Según Precios y arquitectura de RPM de la Fansly API, gestionar los límites de solicitudes (429) es especialmente importante según el nivel de tu plan (1000 RPM en Basic frente a 5000 RPM en Pro).

Paso 5: implementar una API en tiempo real con webhooks HMAC

Pasar del polling continuo a una arquitectura push de API en tiempo real aporta enormes ventajas económicas y de rendimiento. Según la guía de webhooks de Fansly, hacer polling una vez por minuto a una cartera activa de 20 creadores consume unos 28.800 créditos al día. En cambio, los webhooks cuestan solo 1 crédito por cada 100 eventos y entregan los datos con latencias inferiores a un segundo.

Seguridad de los webhooks y verificación de la firma

Cuando se dispara un evento de webhook (como tip.received o message.received), el payload se envía mediante una solicitud POST a la URL HTTPS que registraste. Para demostrar que el evento procede de Fansly, incluye una cabecera X-Fansly-Signature calculada con HMAC-SHA256.

Requisito de seguridad: debes evaluar el hash HMAC contra el buffer de texto sin procesar ni parsear del cuerpo de la solicitud. Además, para evitar ataques de temporización como se describe en la RFC 2104, las comparaciones deben ejecutarse en tiempo constante.

Referencia de verificación con Node.js / Express

import express, { Request, Response } from 'express';
import { createHmac, timingSafeEqual } from 'crypto';
 
const app = express();
 
// Captura el buffer del cuerpo sin procesar para la verificación
app.use(express.json({
  verify: (req: any, _res, buf) => {
    req.rawBody = buf;
  }
}));
 
const WEBHOOK_SECRET = process.env.FANSLY_WEBHOOK_SECRET;
const processedEvents = new Set<string>();
 
app.post('/api/fansly/webhook', (req: Request, res: Response): any => {
  const signature = req.headers['x-fansly-signature'] as string;
  const rawBody = (req as any).rawBody;
 
  if (!signature || !rawBody) return res.status(400).send('Missing signature');
 
  // 1. Calcula el hash HMAC-SHA256 esperado
  const computedHash = createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
 
  // 2. Validación de la firma en tiempo constante
  const signatureBuffer = Buffer.from(signature, 'utf8');
  const computedBuffer = Buffer.from(computedHash, 'utf8');
 
  if (signatureBuffer.length !== computedBuffer.length || !timingSafeEqual(signatureBuffer, computedBuffer)) {
    return res.status(401).send('Signature verification failed');
  }
 
  // 3. Evita ataques de repetición mediante claves de idempotencia
  const event = req.body;
  const idempotencyKey = event.idempotencyKey || event.id;
 
  if (processedEvents.has(idempotencyKey)) {
    return res.status(200).json({ status: 'duplicate_ignored' });
  }
  processedEvents.add(idempotencyKey);
 
  // Procesa el evento y confirma la recepción rápidamente
  return res.status(200).json({ received: true });
});

Conclusión

Desplegar herramientas de gestión de creadores de alto rendimiento exige una documentación de API sólida y prácticas seguras. Si defines bien el alcance de tus claves de API, respetas el estándar de milidólares para los datos financieros y estableces una conexión segura de API en tiempo real con verificación HMAC de webhooks, puedes dejar atrás la falta de fiabilidad de los scripts de scraping. Aprovechar la amplia biblioteca de endpoints de API que ofrece la plataforma de Fansly garantiza que la infraestructura de tu agencia escale de forma eficiente, segura y rentable.