Aller au contenu

Flux de création d'une SPV (EF ↔ API ↔ Lemonway)

Cette documentation décrit, côté produit, l'ordre des étapes pour créer une SPV (société porteuse de projet) et la rattacher à un projet Bricks.

Elle cible les équipes produit et les personnes qui maintiennent l'Espace Financement (EF) sur Bubble. Elle ne détaille pas le code.

1. Introduction

Une SPV (Special Purpose Vehicle) est la société juridique porteuse d'un projet. Côté Bricks, elle passe un onboarding KYB chez Lemonway et reçoit un wallet qui encaissera la collecte, puis payera les opérations du projet.

Trois acteurs interviennent :

  • EF (Bubble / Espace Financement) : interface utilisée par le porteur de projet pour créer la société et lancer le KYB.
  • API Bricks : orchestre la création, persiste la SPV et le projet (Property), parle à Lemonway, notifie EF.
  • Lemonway : fournisseur KYB et paiements (onboarding v3 + wallet classique + IBAN virtuel).

Règle d'or : l'API est la source de vérité pour la SPV, la Property et les identifiants Lemonway. Bubble orchestre l'UX et stocke uniquement les références renvoyées par l'API.

2. Vue d'ensemble de l'ordre des étapes

Ordre macro côté EF :

  1. EF collecte les infos porteur de projet + société (SPV).
  2. EF appelle l'API « créer porteur + SPV » → l'API crée le porteur, crée le compte Lemonway, démarre l'onboarding KYB, insère la SPV et renvoie spvId + onboardingUrl.
  3. EF redirige le porteur vers l'URL d'onboarding Lemonway (KYB).
  4. Lemonway notifie l'API par webhook → l'API synchronise le statut KYB et matérialise le wallet / l'IBAN virtuel.
  5. L'API notifie EF du nouveau statut KYB (callback HTTP).
  6. Quand la SPV est prête (ou en parallèle), EF appelle l'API « créer property v2 » avec le spvId pour rattacher la SPV à un projet.

3. Diagramme de séquence

sequenceDiagram
  autonumber
  participant EF as EF (Bubble)
  participant API as API Bricks
  participant LW as Lemonway

  EF->>API: POST project-owner-and-spv (infos porteur + SPV)
  API->>LW: Créer compte légal (onboarding v3)
  API->>LW: Démarrer onboarding société
  LW-->>API: onboardingUrl
  API->>API: Insérer SPV + porteur
  API-->>EF: spvId, projectOwnerId, onboardingUrl, lemonwayAccountId, lemonwayWalletId

  EF->>LW: Redirige le porteur vers onboardingUrl (KYB)
  LW-->>LW: Le porteur complète le KYB

  LW-->>API: Webhook account/profile status changed
  API->>LW: Lire statuts, récupérer wallet
  API->>API: MAJ SPV (statuts, wallet, IBAN virtuel)
  API-->>EF: POST kyc-status-update (nouveau statut)

  EF->>API: POST property v2 (spvId, projectOwnerId, infos projet)
  API->>API: Insérer Property liée à la SPV
  API-->>EF: propertyId

4. Détail de chaque étape

Étape 1 — Saisie côté EF

  • Qui : le porteur, via l'interface EF (Bubble).
  • Quoi : EF collecte les informations du porteur (email a minima) et de la société : nom, SIREN, date d'immatriculation, adresse du siège, RCS, capital, représentant légal, bénéficiaires effectifs, etc.
  • Persistence : aucune côté API à ce stade. EF peut stocker un brouillon Bubble si nécessaire.

Étape 2 — Création du porteur + de la SPV

  • Qui déclenche : EF, quand la saisie est complète.
  • Quoi : un unique appel API qui enchaîne, côté backend :
  • création ou récupération du porteur de projet (par email),
  • création du compte légal Lemonway (onboarding v3), avec l'UUID de la SPV en identifiant externe,
  • démarrage de l'onboarding société (ou reprise s'il existe déjà),
  • insertion de la SPV en base.
  • Renvoyé à EF :
  • spvId
  • projectOwnerId
  • onboardingUrl (à ouvrir côté porteur)
  • lemonwayAccountId
  • lemonwayWalletId (optionnel : absent si le wallet n'existe pas encore à la création de la SPV)
  • Sécurité : appel authentifié par la clé API interne EF (header x-api-key).

Étape 3 — Parcours KYB chez Lemonway

  • Qui : le porteur de projet.
  • Quoi : EF redirige le porteur vers onboardingUrl. Le porteur complète le KYB directement chez Lemonway (documents, vérifications, signatures).
  • Redirection retour : Lemonway renvoie vers une URL EF configurée côté API (onboardingRedirectUrl). EF gère l'affichage « merci / en analyse ».
  • Persistence côté API : rien pendant le parcours. L'API attend les webhooks.

Étape 4 — Webhooks Lemonway

  • Qui : Lemonway, à chaque changement de statut côté onboarding.
  • Quoi : Lemonway envoie account-status-changed et profile-status-changed.
  • Traitement côté API :
  • résoudre la SPV concernée par le AccountID Lemonway,
  • relire compte + profil,
  • tenter de récupérer le wallet associé,
  • mettre à jour la SPV (statuts compte/profil, wallet),
  • au passage à ACCEPTED, créer l'IBAN virtuel.
  • Cas limite : profil ACCEPTED mais wallet pas encore créé chez Lemonway → la synchronisation est reportée (retry via webhook suivant ou cron).

Étape 5 — Callback API → EF

  • Qui déclenche : l'API, à chaque changement effectif de statut KYB.
  • Quoi : l'API appelle EF sur POST /kyc-status-update avec spvId et status, authentifiée par un Bearer token EF.
  • Attendu côté EF : EF met à jour son interface (statut de la SPV, débloque la suite du parcours projet, notifie le porteur).

Étape 6 — Liaison SPV ↔ Property (projet)

  • Qui déclenche : EF, quand le produit a besoin de créer le projet (peut se faire avant la fin du KYB : la SPV et le projet sont découplés).
  • Quoi : EF appelle l'API « créer property v2 » avec spvId, projectOwnerId et les infos du projet (opération, contrat, documents, échéancier, etc.).
  • Persistence : insertion d'une ligne Property qui référence la SPV. Un businessId lisible (EF…) est généré par l'API.
  • Renvoyé à EF : propertyId et businessId.

5. Statuts KYB côté produit

Les statuts fonctionnels visibles par EF suivent grossièrement :

  • Création en cours : compte Lemonway créé, onboarding non terminé.
  • Information attendue : Lemonway demande une pièce ou une correction.
  • En analyse : dossier complet, en revue côté Lemonway.
  • Accepté : KYB validé. Wallet disponible, IBAN virtuel créé.
  • Refusé : KYB rejeté, la SPV ne peut pas encaisser.

Cas intermédiaire « accepté mais wallet pas encore créé » : l'API attend la matérialisation du wallet côté Lemonway. Résolu automatiquement par les webhooks suivants ou par le cron de secours.

6. Rôles et responsabilités

  • EF (Bubble)
  • Saisie et validation produit.
  • Déclenche les appels API.
  • Affiche les statuts KYB.
  • Stocke les références renvoyées par l'API (spvId, projectOwnerId, onboardingUrl, lemonwayAccountId, lemonwayWalletId).
  • API Bricks
  • Source de vérité SPV et Property.
  • Orchestration Lemonway (création compte, onboarding, wallet, IBAN virtuel).
  • Réception webhooks Lemonway.
  • Callback KYB vers EF.
  • Synchronisation périodique de secours.
  • Lemonway
  • KYB (onboarding v3).
  • Wallet classique + IBAN virtuel.
  • Webhooks de statut.

7. Cas particuliers / hors flux principal

  • SPV technique : wallet opérationnel secondaire (ex. compte de frais). Créée côté admin Bricks, pas par EF.
  • SPV historiques v1 : anciennes SPV créées avant l'onboarding v3. Toujours supportées en lecture et synchronisation, mais plus créées — tout nouveau flux EF passe par v2.
  • Polling de secours : un job périodique reprend les SPV dont le KYB n'est ni ACCEPTED ni DENIED et relance la synchronisation, au cas où un webhook serait perdu.
  • Reprise d'onboarding : si le porteur n'a pas terminé, EF peut redemander l'onboardingUrl à l'API, qui renvoie un lien de reprise sans recréer la SPV.

8. Points de vigilance pour EF

  • Ne jamais générer les identifiants côté Bubble. Toujours utiliser ceux renvoyés par l'API (spvId, projectOwnerId, lemonwayAccountId).
  • Identité unique. Une SPV ne peut pas être recréée avec la même identité (SIREN / compte Lemonway déjà utilisé par une autre SPV → erreur explicite).
  • Reprise, pas recréation. Si le porteur revient plus tard, demander à l'API un onboardingUrl de reprise plutôt que relancer « créer porteur + SPV ».
  • Property v1 dépréciée. Utiliser uniquement property v2 pour créer un projet.
  • Découplage SPV ↔ projet. Une SPV peut exister sans projet, et inversement le projet se crée en référant une SPV existante. La liaison se fait via spvId au moment de créer la Property.
  • Statut KYB = bloquant pour la collecte. Tant que la SPV n'est pas ACCEPTED avec wallet + IBAN, la collecte ne peut pas démarrer.

Annexe — Pour les développeurs

Principaux fichiers côté API pour creuser un point précis :

  • Contrôleur EF (entrée de tous les appels Bubble) : [projects/api/src/administration/controllers/espace-financement.controller.ext.ts](../projects/api/src/administration/controllers/espace-financement.controller.ext.ts)
  • Service SPV (orchestration création + synchronisation) : [projects/api/src/__new/modules/special-purpose-vehicule/special-purpose-vehicule.service.ts](../projects/api/src/__new/modules/special-purpose-vehicule/special-purpose-vehicule.service.ts)
  • Service compte Lemonway (hooks onboarding) : [projects/api/src/__new/modules/lemonway-account/lemonway-account.service.ts](../projects/api/src/__new/modules/lemonway-account/lemonway-account.service.ts)
  • Webhooks Lemonway : [projects/api/src/customers/controllers/lemonway/hook.controller.ts](../projects/api/src/customers/controllers/lemonway/hook.controller.ts)
  • Cron de synchronisation de secours : [projects/api/cron-task/sync-lemonway/sync-lw-onboarding-v2-status.cron-task.ts](../projects/api/cron-task/sync-lemonway/sync-lw-onboarding-v2-status.cron-task.ts)
  • Création de Property (liaison au spvId) : [projects/api/src/__new/modules/property-creation/property-creation.service.ts](../projects/api/src/__new/modules/property-creation/property-creation.service.ts)