Guide API — Getting Started

L'API Conformitiel utilise un token Bearer par cabinet. Chaque token est scopé à une organization unique et à un rôle applicatif.

Créer un token

1. Connectez-vous à l'application (rôle admin ou dirigeant).
2. Rendez-vous dans /parametres/api-tokens.
3. Cliquez sur "Générer un nouveau token" — libellé, rôle, expiration.
4. Copiez le token immédiatement — il n'est jamais réaffiché (seul le SHA-256 est stocké côté serveur).

Format du token : cft_<32 caractères base64url>. Le préfixe permet de le détecter en clair dans les logs (et d'alerter en cas de leak).

Utilisation dans une requête

curl -X GET https://conformitiel.fr/api/fiches-vigilance \
  -H "Authorization: Bearer cft_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Le middleware valide le préfixe côté Edge (rapide) et la signature complète côté route (Node runtime). Un token expiré ou révoqué → 401.

Criblez une personne physique contre les 6 registres de sanctions et PPE en un appel synchrone (< 2 secondes).

curl -X POST https://conformitiel.fr/api/screening \
  -H "Authorization: Bearer cft_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "DUPONT",
    "prenom": "Jean",
    "dateNaissance": "1975-03-14",
    "nationalite": "FR"
  }'

Réponse

{
  "person": { "nom": "DUPONT", "prenom": "Jean", ... },
  "results": [
    {
      "source": "Gels Avoirs (DG Trésor)",
      "type": "sanctions",
      "hit": false,
      "score": null,
      "alertId": "9f3e4c2a-..."
    },
    {
      "source": "OpenSanctions",
      "type": "sanctions",
      "hit": false,
      "score": 0.72,
      "matchedName": "DUPONT Jean-Marc",
      "alertId": "5a1d2b8f-..."
    },
    // ... 4 autres sources
  ],
  "summary": {
    "totalChecks": 6,
    "hits": 0,
    "nearMatches": 1,
    "clean": 5,
    "errors": 0
  }
}

Chaque résultat contient un alertId persistant en base. Utilisez-le pour qualifier l'alerte (faux positif, confirmé, escaladé) via PATCH /api/screening/alerts/[id]/status.

Un audit SIREN interroge INSEE + INPI RBE + BODACC + les 6 registres de sanctions pour chaque personne (dirigeants + BE identifiés). Réponse en SSE streaming (5-30s selon volume).

curl -X POST https://conformitiel.fr/api/audit \
  -H "Authorization: Bearer cft_xxx..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "siren": "552032534" }'

Events SSE reçus

event: pipeline_step
data: { "step_id": "insee", "status": "in_progress" }

event: pipeline_step
data: { "step_id": "insee", "status": "completed", "durationMs": 340 }

event: pipeline_step
data: { "step_id": "bodacc", "status": "in_progress" }

// ... autres étapes

event: complete
data: {
  "auditId": "audit-...",
  "siren": "552032534",
  "denomination": "DANONE",
  "riskScore": 32,
  "riskLevel": "MOYEN",
  "personnes": [/* dirigeants + BE avec leur criblage */]
}

Alternatif : POST synchrone (sans SSE) — retourne le résultat complet en un seul appel (plus long à répondre mais plus simple en intégration).

Les fiches vigilance sont la documentation KYC persistante exigée par Art. L.561-5 CMF.

# Créer une fiche personne morale
POST /api/fiches-vigilance
{
  "typeClient": "PERSONNE_MORALE",
  "denomination": "DANONE",
  "siren": "552032534",
  "identification": { ... },
  "beneficiairesEffectifs": [ ... ],
  "evaluationRisque": { ... }
}

# Générer le PDF opposable
GET /api/fiches-vigilance/[id]/pdf
→ application/pdf (auto-archivé S3 Object Lock 5 ans)

# Lister les fiches
GET /api/fiches-vigilance?statut=VALIDEE&niveauRisque=ELEVE

# Détecter les doublons
GET /api/fiches-vigilance/duplicates
→ { clusters: [...], totalClusters, totalFichesInvolved }

# Fusionner deux fiches doublons
POST /api/fiches-vigilance/merge
{ "targetFicheId": "...", "sourceFicheIds": [...], "mergeReason": "..." }

Les webhooks Conformitiel sont configurables par organization via l'écran /parametres/webhooks (rôle admin requis).

Événements disponibles

• screening.hit — Un hit sanctions ou PPE est détecté sur un criblage
• fiche_vigilance.validated — Une fiche est validée (par admin/dirigeant)
• gel.created — Un gel des avoirs est déclenché
• signature.completed — Un signataire externe a signé un document
• audit.completed — Un audit SIREN a terminé son exécution

Sécurité et livraison

• Signature HMAC-SHA256 dans le header X-Conformitiel-Signature
• Timeout 10s côté receveur — retry avec backoff exponentiel (3 tentatives)
• Historique des envois consultable dans /parametres/webhooks/logs

Les rate-limits protègent l'infrastructure et garantissent l'équité entre partenaires. Ils sont plus généreux pour les tokens partenaires (nous contacter pour élévation).

En cas de dépassement : réponse 429 Too Many Requests avec header Retry-After (secondes à attendre). Aucune facturation additionnelle.

Environnement dédié pour tester votre intégration sans impact sur la production :

• URL : https://sandbox.conformitiel.fr (à venir)
• Données synthétiques (aucune donnée réelle client)
• Quotas illimités
• Webhooks recevables (ngrok / localhost accepté)
• Reset hebdomadaire des données de test
• Registres de sanctions à jour (identiques à prod)

Accès sur demande — formulaire dédié ou partenaires@conformitiel.fr.

Toutes les erreurs suivent un format JSON standard : { "error": "<message>", "issues"?: [...] }. Les messages sont toujours en français.