Parcours d'intégration — de l'onboarding à l'usage complet

Chaque client final que vous embarquez devient un cabinet (organization) Conformitiel, provisionné par vous, isolé des autres. Deux familles de jetons se partagent le travail :

Règle : un appel cfp_ hors /api/partner/* ou un cft_ sur /api/partner/* reçoit un 401 explicite. Seule exception, documentée à l'étape 4 : la création d'un dossier notarial complet, qui accepte les deux.

Votre application                      Conformitiel
──────────────────                     ────────────────────────────────────────
  cfp_  ──►  POST /api/partner/organizations        → cabinet + admin + magic link
  cfp_  ──►  POST /api/partner/organizations/:id/tokens → cft_ du cabinet (une fois)
  cft_  ──►  POST /api/organization/webhooks        → secret HMAC pour vos callbacks
  cft_  ──►  POST /api/screening                    → résultat 6 registres
  cft_  ──►  GET  /api/audit?sirens=                → flux SSE puis rapport PDF signé
  cft_  ──►  POST /api/fiches-vigilance             → fiche KYC
  cft_  ──►  PUT  /api/fiches-vigilance/:id  {validate} → validée (+ signée si notaire)
  cft_  ──►  GET  /api/fiches-vigilance/:id/pdf     → PDF scellé
  cft_  ──►  POST /api/signatures/fiche_vigilance/:id → signature client par email + OTP
  cft_  ──►  POST /api/dossier-lcbft {format:"pdf"} → dossier CSN / ACPR signé
  ◄──  webhook signature.completed / audit.completed / screening.hit_detected

1a. Provisionner le cabinet (scope orgs:create)

curl -X POST https://conformitiel.fr/api/partner/organizations \
  -H "Authorization: Bearer cfp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orgName": "Étude Dupont & Associés",
    "siren": "123456789",
    "profession": "notaire",
    "adminEmail": "maitre.dupont@etude-dupont.fr",
    "adminName": "Me Sophie Dupont",
    "metadata": { "externalId": "client-4711" }
  }'

→ 201
{
  "organization": { "id": "org_…", "name": "Étude Dupont & Associés", "siren": "123456789", "profession": "notaire" },
  "adminUser":    { "id": "usr_…", "email": "maitre.dupont@etude-dupont.fr", "isNewUser": true },
  "magicLinkUrl": "https://conformitiel.fr/verify?token=…",   // à transmettre à l'admin, valable 7 jours
  "magicLinkExpiresAt": "2026-09-17T09:00:00.000Z"
}

Conservez organization.id : c'est la clé de tout le reste. Le champ metadata est libre et vous est restitué, pratique pour stocker votre identifiant client. Le cabinet est facturé sur votre contrat partenaire (aucun Stripe côté cabinet) et son plan ouvre l'API d'office.

1b. Inviter d'autres utilisateurs (scope users:create, optionnel)

curl -X POST https://conformitiel.fr/api/partner/organizations/org_…/users \
  -H "Authorization: Bearer cfp_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "clerc@etude-dupont.fr", "name": "Paul Martin", "role": "collaborateur" }'

→ 201 { "user": { "userId": "usr_…", "email": "…", "role": "collaborateur" }, "magicLinkUrl": "…", "magicLinkExpiresAt": "…" }

# Rôles : admin · dirigeant · consultant · collaborateur (matrice RBAC : voir la doc sécurité)

1c. Émettre le jeton cft_ du cabinet (scope tokens:manage)

C'est ce jeton que votre application utilisera pour toutes les étapes suivantes. Il est émis au nom d'un utilisateur du cabinet : par défaut l'admin créé en 1a, sinon l'utilisateur désigné par userId ou email. Choisissez le porteur selon les droits nécessaires : un collaborateur crée et criblé, un dirigeant ou admin valide, signe et exporte le dossier.

curl -X POST https://conformitiel.fr/api/partner/organizations/org_…/tokens \
  -H "Authorization: Bearer cfp_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Intégration MonLogiciel — prod", "expiresInDays": 365 }'

→ 201
{
  "id": "tok_…",
  "tokenPlaintext": "cft_K7v…",          // AFFICHÉ UNE SEULE FOIS — stockez-le chiffré, par cabinet
  "tokenPrefix": "cft_K7v9Q2mA",
  "expiresAt": "2027-09-10T09:00:00.000Z",
  "user": { "id": "usr_…", "email": "maitre.dupont@etude-dupont.fr", "role": "admin" },
  "organizationId": "org_…"
}

# Lister / révoquer (rotation annuelle recommandée)
GET    /api/partner/organizations/org_…/tokens
DELETE /api/partner/organizations/org_…/tokens/tok_…

1d. Déclarer votre webhook (jeton cft_)

curl -X POST https://conformitiel.fr/api/organization/webhooks \
  -H "Authorization: Bearer cft_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.monlogiciel.fr/webhooks/conformitiel/org_…",
    "events": ["signature.completed", "audit.completed", "screening.hit_detected", "screening.delta_detected"],
    "description": "MonLogiciel — Étude Dupont"
  }'

→ { "id": "wh_…", "secret": "whsec_…" }   // secret HMAC-SHA256, affiché une fois

# Un endpoint par cabinet (le webhook vit dans le cabinet). Mettez organization.id dans votre URL
# pour router côté réception ; le payload contient aussi organizationId.

Synchrone, moins de deux secondes : gels des avoirs, sanctions UE et ONU, OFAC, PPE (HATVP + OpenSanctions), adverse media. Chaque résultat crée une alerte persistante dans le cabinet, réutilisée par les fiches et les dossiers.

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

→ { "person": {…}, "results": [ { "source": "OpenSanctions", "hit": false, "score": 0.72, "matchedName": "…", "alertId": "…" }, … ],
    "summary": { "totalChecks": 6, "hits": 0, "nearMatches": 1, "clean": 5, "errors": 0 } }

# Rapport de criblage PDF scellé (réutilise le résultat ci-dessus)
POST /api/screening/pdf   { "person": {…}, "results": [...], "screeningAlertId": "…" }   → application/pdf

# Toutes les parties d'une fiche en une fois (après l'étape 4)
POST /api/fiches-vigilance/:id/criblage-toutes-parties
→ { success, totalPersonnes, sourcesInterrogees, totalHits, alertIds: [...], diligenceIds: [...], resume: [...], versionCouranteId }

Un hit déclenche le webhook screening.hit_detected (personne, nombre de hits, sources et identifiants d'alerte). Un hit sanctions ouvre aussi automatiquement une procédure de gel et une fiche de vigilance dans le cabinet. Les quotas de criblage du cabinet sont décomptés sur votre contrat.

L'audit interroge INSEE, INPI (bénéficiaires effectifs), BODACC puis crible dirigeants et bénéficiaires. La réponse est un flux Server-Sent Events (5 à 30 s). L'appel est un GET avec le paramètre sirens (plusieurs SIREN séparés par des virgules).

curl -N "https://conformitiel.fr/api/audit?sirens=552032534" \
  -H "Authorization: Bearer cft_..." \
  -H "Accept: text/event-stream"

event: step             data: { "step_id": "insee", "status": "running" | "completed", ... }
event: entity_complete  data: { "siren": "552032534", ... }
event: complete         data: { "totalProcessed": 1, "results": { "siren", "company_name", "risk_level", "risk_score", "date", "identite", "beneficiaires", "dirigeants", ... } }
event: error            data: { "message": "…" }

# Sans SSE (files d'attente, batch) : lancer en masse et interroger la progression
POST /api/audit-batches         { "sirens": ["552032534", "…"] }
GET  /api/audit-batches/:id/progress

# Résultats persistés
GET /api/history/552032534                   → liste des audits de ce SIREN (le plus récent en tête)
GET /api/history/552032534/:timestamp        → détail d'un audit

Livrables de l'audit

GET /api/report/pdf?siren=552032534       → rapport d'audit PDF SIGNÉ (signature simple eIDAS 25.1 + sceau vérifiable)
GET /api/report/package?sirens=552032534  → ZIP : PDF signé + .sha256 + jeton RFC 3161 + journal API + Word de travail
GET /api/audit/:auditId/synthese-vigilance → synthèse 1 page scellée

Le signataire du rapport est l'utilisateur porteur du jeton cft_. Le PDF mentionne « via jeton API « Intégration MonLogiciel — prod » (cft_K7v9Q2mA…) ». Le webhook audit.completed est émis en fin d'audit avec, pour chaque SIREN traité, l'horodatage, le score et le niveau de risque.

La fiche est la documentation KYC persistante (art. L.561-5 CMF). Deux voies selon la profession du cabinet.

4a. Voie générale (toutes professions, jeton cft_)

curl -X POST https://conformitiel.fr/api/fiches-vigilance \
  -H "Authorization: Bearer cft_..." \
  -H "Content-Type: application/json" \
  -d '{
    "typeClient": "PERSONNE_MORALE",              // ou PERSONNE_PHYSIQUE
    "denomination": "DANONE",                     // requis (nom complet pour une personne physique)
    "siren": "552032534",
    "auditId": "…",                               // optionnel : rattache l'audit de l'étape 3
    "identification": { … },                      // état civil / immatriculation
    "beneficiairesEffectifs": [ { "nom": "…", "prenom": "…", "dateNaissance": "…", "nationalite": "FR", "pourcentage": 40 } ],
    "relationAffaires": { … },                    // objet et nature de la relation
    "evaluationRisque": { "estPPE": false, … }
  }'
→ 201 { "id": "fic_…", "statut": "BROUILLON", "niveauRisque": "MOYEN", "niveauVigilance": "STANDARD", ... }

# Seuls typeClient et denomination sont obligatoires ; le détail des objets est dans la référence OpenAPI.
# Le niveau de vigilance (SIMPLIFIEE / STANDARD / RENFORCEE) est calculé par le service ;
# en RENFORCEE, un bloc de mesures renforcées devient obligatoire avant validation.

4b. Voie notariale : dossier complet en un appel

Pour une étude notariale, un seul appel crée la fiche, sa version 1 et les diligences par partie (vendeur, acquéreur, prêteur…). Cet endpoint accepte le cft_ du cabinet ou votre cfp_ avec organizationId (scope orgs:create) : utile pour pré-remplir un dossier avant même que l'étude ait ouvert sa session. C'est la seule route LCB-FT ouverte au cfp_, en écriture uniquement.

POST /api/fiches-vigilance/notaire/dossier
Authorization: Bearer cft_...        (ou Bearer cfp_... + "organizationId": "org_…")
{
  "organizationId": "org_…",                         // requis en mode cfp_ uniquement
  "clientPrincipal": { "typePersonne": "PERSONNE_PHYSIQUE", "nom": "DUPONT", "prenom": "Jean", … },
  "acteNotarie": {
    "typeActe": "VENTE_IMMOBILIERE", "montant": 450000,
    "groupesParties": [
      { "role": "VENDEUR",   "parties": [ { "nom": "…", "prenom": "…", "dateNaissance": "…", "nationalite": "FR" } ], "evaluationRisque": { … } },
      { "role": "ACQUEREUR", "parties": [ … ], "evaluationRisque": { … } }
    ]
  },
  "diligences": [ { "source": "…", "personnesSoumises": [ … ] } ]
}
→ 201 { "ficheId": "fic_…", "versionId": "…", "versionNumber": 1, "hash": "…", "previousHash": null, "diligencesEnregistrees": 4 }

# Le schéma complet (17 rôles de parties, origine des fonds, dépôts) est dans la référence OpenAPI.

Ensuite, criblez toutes les parties d'un coup (étape 2) et passez à la validation (étape 7a).

Le dossier de conformité consolidé rassemble, pour une période, les pièces attendues par l'autorité de contrôle du cabinet (CSN pour un notaire, ACPR, CNB, CNCJ, CVV, CROEC selon la profession) : cartographie des risques, procédures, registre des fiches, synthèses de vigilance, criblages, formations, déclarations, captures adverse media. En format: "pdf" il est livré en un PDF unique, paginé, avec l'attestation signée du responsable LCB-FT et un sceau vérifiable.

# Contrôle de complétude avant génération (ce qui manque pour un dossier présentable)
GET /api/dossier-lcbft
→ { "checks": [ { "id": "procedures", "label": "Procédures internes", "ok": false, "detail": "0 procedure(s)" }, … ] }
#   ids : classification · procedures · organigramme · vigilance · registre · examens · journal · sensibilisation · controle · conservation

# Génération : PDF consolidé signé (recommandé)
curl -X POST https://conformitiel.fr/api/dossier-lcbft \
  -H "Authorization: Bearer cft_..." \
  -H "Content-Type: application/json" \
  -d '{ "dateDebut": "2026-01-01", "dateFin": "2026-06-30", "format": "pdf" }' \
  -o dossier_csn_2026_S1_signe.pdf
→ application/pdf  (Content-Disposition: attachment; filename="Dossier_…_signe.pdf")

# Variante : pièces séparées
… "format": "zip"   → application/zip

# Le dossier est archivé en S3 immuable (Object Lock 5 ans). Pour le retrouver plus tard :
GET /api/document-archives?documentType=dossier_lcbft_pdf
GET /api/document-archives/:id/download

Le porteur du jeton doit avoir le droit d'export du module dossier (rôle dirigeant ou admin). L'attestation est signée en son nom, méthode « jeton API » mentionnée.

# PDF courant de la fiche (sceau vérifiable en pied de page + cachet QR, archivé S3 Object Lock 5 ans)
GET /api/fiches-vigilance/fic_…/pdf                → application/pdf

# PDF d'une version immuable (notariat : sceau déterministe "U" + hash de version, reproductible à 5 ans)
GET /api/fiches-vigilance/fic_…/versions           → { versions: [ { id, versionNumber, motif, createdAt, hasRfc3161, signed, signedBy, … } ] }
GET /api/fiches-vigilance/fic_…/versions/2/pdf

# Synthèse de vigilance 1 page (pièce du dossier CSN)
GET /api/fiches-vigilance/fic_…/synthese-vigilance

# Intégrité de la chaîne de versions (notariat)
GET /api/fiches-vigilance/fic_…/versions/verify    → { valid: true, versionsChecked: 3, errors: [] }

Chaque PDF porte un code « Sceau XXXX-XXXX-XXXX ». N'importe qui peut vérifier un fichier reçu sur conformitiel.fr/v/<code> ou via GET /api/v/<code> (public, sans compte). Vous pouvez afficher ce lien dans votre application à côté du document.

Deux signatures distinctes, toutes deux au niveau simple du règlement eIDAS (art. 25.1, recevable en justice, C. civ. 1367) :

7a. Signature du professionnel (notaire) — automatique à la validation

Pour une étude notariale, valider = signer. La validation crée une version « validation » dont le snapshot embarque la signature du porteur du jeton, scellée par le hash de chaîne et l'horodatage RFC 3161. Aucune friction pour le client.

PUT /api/fiches-vigilance/fic_…
Authorization: Bearer cft_...           # porteur = notaire / dirigeant (droit de validation)
{ "action": "validate", "commentaire": "Diligences complètes, risque standard" }
→ { fiche: { statut: "VALIDEE", … }, signedVersion: { versionNumber: 2, hash: "…" } }

# Fiche déjà validée avant la mise en place de la signature : signer a posteriori
PUT /api/fiches-vigilance/fic_…   { "action": "sign" }

# Fiche à risque élevé rédigée par le porteur lui-même : validation à 4 yeux obligatoire
PUT /api/fiches-vigilance/fic_…   { "action": "request_validation_hierarchique" }
# … puis "validate" par un autre utilisateur (autre jeton cft_ ou session web).

Le PDF de la version signée (étape 6) affiche l'encart « Signé électroniquement » avec la méthode « jeton API « … » (cft_…) », l'IP et le texte de consentement.

7b. Signature du client (vendeur, acquéreur, mandant) — par email + code OTP

Vous demandez la signature ; Conformitiel envoie au signataire un lien sécurisé, lui demande un code à 6 chiffres reçu par email, son nom, sa date de naissance et son consentement, puis produit le PDF signé (certificat de signature, sceau, archivage immuable). Vous êtes prévenu par webhook.

# 1. Demander la signature
curl -X POST https://conformitiel.fr/api/signatures/fiche_vigilance/fic_… \
  -H "Authorization: Bearer cft_..." \
  -H "Content-Type: application/json" \
  -d '{ "signerEmail": "jean.dupont@example.com", "signerNameExpected": "Jean DUPONT", "expiresInDays": 7 }'
→ { "id": "sig_…", "tokenPrefix": "…", "expiresAt": "…", "signerEmail": "…" }
#   (l'email au signataire part immédiatement ; le lien ne vous est pas retourné)

# 2. Être notifié
webhook signature.completed → { "type": "signature.completed", "organizationId": "org_…",
  "data": { "signatureRequestId": "sig_…", "documentType": "fiche_vigilance", "documentId": "fic_…", "documentTitle": "…",
            "signerEmail": "…", "signerName": "…", "signedAt": "…", "signedSha256": "…", "sealCode": "…" } }

# 3. Suivre / récupérer
GET /api/signatures/fiche_vigilance/fic_…                          → { requests: [ { id, status: "pending" | "signed" | "expired" | "revoked", … } ] }
GET /api/signatures/fiche_vigilance/fic_…/sig_…/download           → PDF signé (variant=signed) ou original

Si la fiche évolue après la demande, l'empreinte d'origine ne correspond plus : refaites une demande. Une demande peut être révoquée par DELETE /api/signatures/fiche_vigilance/fic_…/sig_….

# Vigilance constante (art. L.561-6 CMF) : recriblage automatique périodique
POST /api/recurring-screenings   { "ficheVigilanceId": "fic_…", "personNom": "DUPONT", "personPrenom": "Jean", "personNationalite": "FR", "personType": "PP", "frequency": "quarterly" }
→ webhook screening.delta_detected dès qu'un nouveau hit apparaît
GET  /api/recurring-screenings/delta-alerts
GET  /api/recurring-screenings/report?year=2026       → rapport annuel CSV (contrôle)

# Compteurs et facturation (jeton cfp_)
GET /api/partner/organizations/org_…/usage              → fiches / audits / criblages du mois
GET /api/partner/usage                                  → usage cumulé du contrat

# Fin de relation
POST /api/partner/organizations/org_…/archive  { "reason": "…" }   → le cabinet est archivé, ses données conservées 5 ans

• Un cft_ par cabinet, stocké chiffré, jamais partagé entre cabinets. Rotation annuelle via émission puis révocation.
• Choisissez le porteur du jeton selon les actions : un jeton « collaborateur » pour créer et cribler, un jeton « dirigeant » pour valider, signer et exporter. Les refus arrivent en 403 avec le module et l'action manquants.
• Idempotence : le provisioning ne déduplique pas sur le SIREN. Conservez l'identifiant retourné (ou votre metadata.externalId) et vérifiez via GET /api/partner/organizations avant de re-provisionner. Les archives S3 sont dédupliquées 24 h sur le contenu.
• Webhooks : vérifiez la signature HMAC (header X-Conformitiel-Signature, pattern Stripe), répondez 2xx en moins de 10 s, traitez les doublons (rejeu jusqu'à 4 fois).
• Rate limits : criblage et audit sont soumis aux quotas du cabinet et au throttle des sources publiques ; en 429, respectez Retry-After.
• Sandbox : créez votre accès en self-service sur sandbox.conformitiel.fr/sandbox (partenaire, jeton cfp_, cabinet d'exemple et jeton cft_ en un clic). Mêmes appels, registres réels, données purgées chaque semaine.