Démarrage rapide Fansly API : authentification, endpoints et vérification HMAC des webhooks

L'économie des créateurs est passée de profils isolés sur les réseaux sociaux à de véritables entreprises numériques à très haut débit. Sur des plateformes qui comptent plus de 130 millions d'utilisateurs inscrits, gérer plusieurs comptes de créateurs à la main ou avec des scripts de scraping fragiles, obtenus par rétro-ingénierie, n'est plus une stratégie viable pour les agences et les éditeurs d'outils professionnels. Ce guide de démarrage rapide sert de documentation API complète aux développeurs qui veulent construire des CRM, des outils d'envoi collectif et des tableaux de bord de revenus capables de passer à l'échelle.

Que vous intégriez l'API directement ou que vous passiez par des orchestrateurs de workflows, il est essentiel de savoir gérer vos clés API, traiter les montants exprimés en entiers et vérifier de façon sécurisée les webhooks de l'API en temps réel pour un déploiement de niveau production.

Qu'est-ce que la Fansly API ?

La Fansly API est une plateforme pour développeurs de niveau entreprise, conçue par Fans Holdings OÜ, qui remplace l'automatisation par navigateur headless par une infrastructure officielle et stable. Pensée pour les agences de gestion de créateurs et les plateformes SaaS, elle expose plus de 200 endpoints REST actifs qui couvrent la messagerie, les profils CRM, les transactions et les coffres-forts de médias.

Avec un historique en production de plus de 5 000 comptes de créateurs connectés et de plus de 150 millions de requêtes traitées sans aucun bannissement de la plateforme, la Fansly API offre un environnement sûr pour faire croître le nombre de comptes. Elle propose aussi une architecture push en temps réel grâce à des webhooks signés cryptographiquement, ce qui supprime le besoin d'un polling continu très gourmand en crédits.

Étape 1 : authentification API et gestion des clés

Une authentification API sécurisée est le socle de votre intégration. La plateforme utilise l'authentification par bearer token : les développeurs doivent transmettre un jeton sécurisé dans les en-têtes HTTP de chaque requête.

Générer et délimiter les clés API

Pour interagir avec la plateforme, vous devez authentifier vos clients HTTP avec des clés API générées depuis votre tableau de bord développeur. Selon le guide d'intégration de la Fansly API, suivez ces étapes :

1. Créez un compte : inscrivez-vous sur la plateforme Fansly API. Les nouveaux développeurs reçoivent une dotation sandbox de 100 crédits de bienvenue gratuits pour tester des connexions réelles.
2. Créez une clé API : ouvrez app.onlyfansapi.com/api-keys et générez une clé. Les clés n'ont pas de périmètre restreint : chaque clé peut appeler tous les endpoints pour tous les comptes connectés à votre équipe. Créez donc une clé par intégration et renouvelez toute clé que vous confiez à un développeur externe.
3. Protégez vos secrets : stockez vos clés API dans un environnement d'exécution sécurisé, comme AWS Secrets Manager ou des fichiers .env chiffrés. Ne les commitez jamais dans un dépôt public.

En-têtes de requête standard

Chaque requête entrante exige des en-têtes HTTP précis pour définir le type de payload, authentifier le client et cibler des comptes de créateurs donnés.

Exemple d'authentification avec cURL :

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

Étape 2 : parcourir les principaux endpoints de l'API

Une fois authentifiés, les développeurs ont accès à plus de 200 endpoints actifs répartis en six grands domaines de ressources. Ces endpoints vous permettent d'orchestrer par programmation des workflows d'agence complexes.

• Comptes et sessions : des endpoints comme /api/v1/accounts connectent les comptes de créateurs via la 2FA et contrôlent l'état des sessions proxy.
• Messagerie : utilisez /api/v1/chats et /api/v1/messages/mass pour lire les messages privés, envoyer des réponses de chatbot en temps réel ou programmer des envois PPV en masse.
• Fans et CRM : interrogez l'historique des dépenses des fans, leurs dates d'abonnement et leurs niveaux d'engagement via /api/v1/fans.
• Finances : rapprochez le chiffre d'affaires brut, la commission de la plateforme, les versements nets et les conversions des liens de tracking avec /api/v1/earnings/summary.
• Médias et coffre-fort : importez des fichiers multimédias (jusqu'à 1 Go via une URL distante) et publiez des posts réservés à certains niveaux d'abonnement avec /api/v1/vault/media.

Étape 3 : l'intégrité des données financières (le format en millidollars)

Une erreur d'intégration fréquente sur les plateformes de l'économie des créateurs est la mauvaise gestion des montants. Les opérations en virgule flottante IEEE 754 standard (comme 0.1 + 0.2 en JavaScript) introduisent une dérive de précision qui, sur des milliers de déblocages PPV et de pourboires, finit par produire de vraies erreurs comptables.

Pour garantir l'intégrité des données financières, Fansly exprime les montants en millièmes de dollar (millidollars).

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

Exemple de conversion en TypeScript

Lorsque vous construisez des tableaux de bord, arrondissez toujours vos conversions pour éviter les anomalies de représentation intermédiaires :

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);
  }
}

Étape 4 : codes de statut HTTP et gestion des erreurs

La plateforme respecte les codes de réponse HTTP standard de la RFC 7231. Selon la page tarifs et architecture RPM de la Fansly API, la gestion des limites de requêtes (429) est particulièrement importante selon votre offre (1 000 RPM pour Basic contre 5 000 RPM pour Pro).

Étape 5 : mettre en place une API en temps réel avec les webhooks HMAC

Passer d'un polling continu à une architecture push en temps réel apporte des gains financiers et de performance considérables. Selon le guide des webhooks Fansly, interroger une fois par minute un portefeuille actif de 20 créateurs consomme environ 28 800 crédits par jour. À l'inverse, les webhooks ne coûtent que 1 crédit pour 100 événements et livrent les données avec une latence inférieure à la seconde.

Sécurité des webhooks et vérification de la signature

Lorsqu'un événement webhook (comme tip.received ou message.received) se déclenche, le payload est envoyé par une requête POST à l'URL HTTPS que vous avez enregistrée. Pour prouver que l'événement provient bien de Fansly, il inclut un en-tête X-Fansly-Signature calculé en HMAC-SHA256.

Exigence de sécurité : vous devez calculer le hachage HMAC sur le buffer brut, non parsé, du corps de la requête. De plus, pour éviter les attaques temporelles décrites dans la RFC 2104, les comparaisons doivent s'exécuter en temps constant.

Implémentation de référence de la vérification en Node.js / Express

import express, { Request, Response } from 'express';
import { createHmac, timingSafeEqual } from 'crypto';
 
const app = express();
 
// Capturer le buffer brut du corps pour la vérification
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. Calculer le hachage HMAC-SHA256 attendu
  const computedHash = createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
 
  // 2. Valider la signature en temps constant
  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. Empêcher les attaques par rejeu grâce aux clés d'idempotence
  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);
 
  // Traiter l'événement et en accuser réception rapidement
  return res.status(200).json({ received: true });
});

Conclusion

Déployer des outils de gestion de créateurs performants exige une documentation API solide et des pratiques sécurisées. En délimitant correctement vos clés API, en respectant le standard des millidollars pour les données financières et en établissant une connexion API en temps réel sécurisée grâce à la vérification HMAC des webhooks, vous échappez au manque de fiabilité des scripts de scraping. En vous appuyant sur la vaste bibliothèque d'endpoints API de la plateforme Fansly, vous garantissez que l'infrastructure de votre agence passe à l'échelle de façon efficace, sûre et rentable.