API & intégrations — Formafusion

Démarrage rapide

Créer une clé dans Paramètres → Développeurs (sandbox d’abord).
Tester votre premier appel API sur l’environnement sandbox.
Brancher les webhooks nécessaires et vérifier la signature.
Basculer en production et définir des rôles & scopes précis.

Exemple REST

cURL

curl -X GET https://api.formafusion.com/v1/sessions \
 -H "Authorization: Bearer <API_KEY>" \
 -H "Accept: application/json"

Exemple GraphQL

JS

fetch('https://api.formafusion.com/graphql', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: `
    query Sessions($after: String){ sessions(first: 25, after: $after){ edges{ node{ id title startAt } } } }
  `})
})

Authentification & sécurité

🔑

API Keys

Clés par environnement (sandbox/prod), rotation, least privilege via scopes (lecture/écriture, modules).

🔐

OAuth 2.0

Client Credentials / Authorization Code (SSO) avec consentement et périmètres. Rafraîchissement de tokens.

🧾

Audit & conformité

Journal d’accès, IP autorisées, chiffrement TLS, PII masquées selon rôle, RGPD (DPA, rétention, droit d’accès).

Bonnes pratiques

Stockez les secrets hors du code, activez la rotation et isolez les clés par service/équipe.

Principaux endpoints

📚

Catalogue

GET /v1/courses, POST /v1/courses, GET /v1/courses/{id}

👤

Apprenants

GET /v1/learners, POST /v1/learners, PATCH /v1/learners/{id}

🗂️

Dossiers & sessions

GET /v1/sessions, POST /v1/enrollments, POST /v1/attendance

🧾

Facturation

POST /v1/invoices, GET /v1/invoices/{id}, POST /v1/payments

⭐

Qualité

POST /v1/surveys, GET /v1/responses, POST /v1/badges

📊

Analytics

GET /v1/kpi, GET /v1/reports, GET /v1/metrics/series

Requête type

GET /v1/sessions?filter[startAt][gte]=2025-01-01&filter[status]=planned&sort=-startAt&page[size]=50

📄

Pagination : page[size], page[after] (cursor) ou page[number] (offset).

🔍

Filtrage : filter[field][op] (ex. eq, lte, contains).

↕️

Tri : sort=field ou sort=-field (desc).

🧩

Projection : fields[resource]=id,title,startAt.

Webhooks événementiels

Événements : session.created, enrollment.created, attendance.marked, invoice.issued, evaluation.completed, badge.issued, notification.delivered.
Signature HMAC sha256 via entête FF-Signature (horodatage + secret).
Retries exponentiels (max 24h), idempotence par FF-Idempotency-Key.

Vérifier la signature

Node

const sig = req.headers['ff-signature'];
const payload = JSON.stringify(req.body);
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
if (sig !== expected) return res.status(401).end();

Exemple payload

JSON

{
  "type": "attendance.marked",
  "id": "evt_123",
  "createdAt": "2025-01-10T08:21:13Z",
  "data": { "sessionId": "ses_abc", "learnerId": "lea_xyz", "status": "present" }
}

Provisioning SCIM & SSO

SSO SAML / OpenID Connect (OIDC) : authentification centralisée, mappings de rôles.
SCIM 2.0 : /scim/v2/Users, /scim/v2/Groups (création, mise à jour, désactivation).
Attributs : email, prénom, nom, rôles, entités, organisations clients RH.

SDKs & outils

🟦

JavaScript/TypeScript

Client officiel, typé, avec helpers pour pagination & retries.

🐍

Python

Client sync/async, dataclasses, gestion automatique des tokens.

🐘

PHP

Client Guzzle, middlewares d’authent, validation schémas.

📦

OpenAPI

Spécification openapi.yaml pour générer des clients personnalisés.

Limites de débit & erreurs

Rate limit : ex. 600 req/min/org. Entêtes : X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.
Idempotence : entête FF-Idempotency-Key pour les POST/PUT sensibles.
Erreurs : JSON uniforme { "error": { "code": "validation_error", "message": "...", "details": [...] } }.
Codes : 400 validation, 401 auth, 403 droits, 404 ressource, 409 conflit, 429 limite, 5xx serveur.