ALICE — Analyse Facturation x Sellsy

1. Resume executif

Le module de facturation est le plus complexe d'ALICE, non pas parce que le metier est complexe, mais parce que l'architecture actuelle duplique Sellsy au lieu de l'utiliser. Il en resulte 5 operations manuelles qui necessitent d'aller dans Sellsy pour copier-coller des IDs, rattacher des documents, et pousser des factures a la main.

L'API Sellsy V2 (v2.287.0) offre nativement tout ce qui manque. La migration doit transformer Sellsy en moteur invisible derriere ALICE : personne n'ouvre plus jamais Sellsy directement.

Aujourd'hui (Bubble)

ALICE essaie d'etre un mini-Sellsy. Tout est duplique (produits, contacts, factures). Synchronisation par copier-coller d'IDs. Double saisie, erreurs, generation de factures en plusieurs minutes.

Cible (React + API V2)

ALICE gere la formation, Sellsy gere l'argent. L'API fait le pont automatiquement. Zero copier-coller, zero aller-retour. Facturation en 2-3 secondes.

2. Comment fonctionne la facturation

Les deux flux distincts

Facturation CLIENTE — on facture l'entreprise

Acteur : l'admin (Mayel) depuis l'espace Facturation
Declencheur : les heures de cours realisees
Destinataire : l'entreprise cliente (Capgemini, Alstom...) ou l'OPCO

Facturation FORMATEUR — le formateur nous facture

Acteur : le formateur (consultation uniquement dans ALICE)
Voit un recap de ses heures par contrat, separees LE vs SM
Fait sa propre facture en dehors d'ALICE (freelance / sous-traitant)
Connu dans Sellsy comme "Fournisseur"

Le circuit complet de facturation cliente

FORMATEUR                         ADMIN                              SELLSY
    |                                |                                  |
    | Donne un cours                 |                                  |
    | Declare "Present(e)"           |                                  |
    | ou "Annulation tardive"        |                                  |
    |         |                      |                                  |
    |         v                      |                                  |
    | Les heures s'accumulent        |                                  |
    | dans ALICE                     |                                  |
    |                                |                                  |
    |                      Ouvre "Facturation cliente"                   |
    |                      Filtre : mois + entite (LE/SM)               |
    |                                |                                  |
    |                      Voit les formations avec                     |
    |                      "H facturees / H a facturer"                 |
    |                                |                                  |
    |                      Coche les formations                         |
    |                      Clique "Simuler N facturations"              |
    |                                |                                  |
    |                      Voit le recap :                              |
    |                      heures x PU HT = montant                    |
    |                      + TVA + split OPCO                           |
    |                                |                                  |
    |                      [Valider et pousser] ---------> Sellsy cree  |
    |                                                      le numero    |
    |                                                      FA-LE-xxxx  |
    |                                                      + PDF        |
    |                                                         |         |
    |                                         Webhook <-------'         |
    |                                         statut paiement           |
    |                                         (A regler -> Payee)       |

Calcul des montants

L'unite de base est l'heure. Chaque seance a une duree (1h, 1.5h, 2h). Le formateur declare la presence, l'heure est "realisee". Le produit Sellsy a un prix unitaire/heure. La facture = heures realisees x PU HT.

Les 3 modes de facturation

Mode	Quand	Exemple
Mensuelle	Chaque mois, heures du mois	4h en aout x 65 EUR = 260 EUR
Globale	Une seule fois, toutes les heures	30h x 65 EUR = 1 950 EUR
Specifique	Montant custom, pas lie aux heures	Forfait certification 250 EUR

Cote Sellsy, ces 3 modes produisent le meme appel API. La difference est uniquement dans la logique ALICE (quelles heures on selectionne).

Le role de l'OPCO

Quand l'entreprise cliente a un financement OPCO (Afdas, ATLAS, OPCO EP...), il faut creer 2 factures au lieu d'1 :

Facture 1 -> a l'OPCO (la part financee)
Facture 2 -> a l'entreprise (le reste a charge)

C'est un split du montant total en 2 destinataires. Le calcul d'heures reste identique. Aujourd'hui ce split semble etre gere manuellement.

Les marges

Calcul de la marge

Marge = CA client - Cout formateur

CA client      = heures facturees au client x PU de vente
Cout formateur = memes heures x PU d'achat

Exemple :
  On facture Capgemini : 30h x 65 EUR  = 1 950 EUR (PU de vente)
  On paie le formateur : 30h x 35 EUR  = 1 050 EUR (PU d'achat)
  Marge = 900 EUR soit 46%

Chaque produit a 2 prix : le prix unitaire (vente au client) et le prix d'achat (cout formateur). Le tab "Marge operationnelle" fait la soustraction par entreprise et par domaine.

Le PCA (Produit Constate d'Avance)

Calcul du PCA

PCA = (heures facturees - heures realisees) x PU

Exemple : facture 42h, realise 38h
  PCA = 4h x 65 EUR = 260 EUR

C'est de l'argent encaisse pour un service pas encore rendu. Un PCA eleve signifie qu'il faut accelerer les formations.

3. Les 5 operations manuelles (le probleme)

Voici les 5 endroits ou quelqu'un doit sortir d'ALICE pour aller dans Sellsy manuellement :

1. Mapping produits : copier-coller l'ID Sellsy

Le commercial cree un produit dans ALICE. Puis il doit ouvrir Sellsy, trouver le produit, copier son ID numerique, revenir dans ALICE et le coller dans le champ "ID du produit dans Sellsy".

Source : Reference ALICE, Espace Commercial > Produits

Solution API V2 : POST /items cree le produit dans Sellsy et retourne l'ID automatiquement. POST /items/search retrouve un produit existant. Plus jamais de copier-coller.

2. Ajouter un formateur : copier l'ID contact + corp ID

Pour ajouter un formateur, l'admin doit ouvrir Sellsy, creer/trouver le fournisseur, copier l'ID contact + le corp ID (101915 pour LE ou 98044 pour SM), et coller dans ALICE > Admin > Annexes. Operation irreversible. Utilise encore l'API V1.

Source : Reference ALICE, Espace Admin > Annexes

Solution API V2 : POST /companies avec type: supplier cree le fournisseur et retourne l'ID. L'admin remplit un simple formulaire dans ALICE.

3. Rattachement facture / opportunite : manuel

Quand une facture est creee dans Sellsy, elle n'est pas liee a l'opportunite commerciale. L'admin doit aller dans l'onglet "Sellsy DB" du pilotage financier et rattacher a la main.

Source : Reference ALICE, Facturation > Pilotage financier

Solution API V2 : POST /invoices accepte related: [{type: "opportunity", id: X}]. Le rattachement est automatique a la creation.

4. Dates de formation non propagees

Quand un admin modifie les dates d'une formation dans ALICE, ca ne touche pas le devis dans Sellsy. C'est assume et affiche dans l'interface. Le devis peut dire "janvier-mars" alors que la formation est en "mars-juin".

Source : Reference ALICE, Admin > Formations > Parametres

Solution API V2 : PUT /estimates/{id} met a jour les service_dates du devis. Peut etre optionnel via un toggle.

5. Pousser la facture vers Sellsy : etape manuelle

Une facture creee dans ALICE a le statut "Non synchro" — elle n'existe pas dans Sellsy, pas de numero officiel. L'admin doit cliquer "Valider et pousser vers Sellsy" explicitement.

Source : Reference ALICE, Facturation > Statuts

Solution API V2 : POST /invoices cree en draft + POST /invoices/{id}/validate attribue le numero et genere le PDF. Plus d'etat intermediaire.

4. Sellsy API V2 — ce qui est disponible

Endpoints facturation

Endpoint	Methode	Description
`/invoices`	POST	Creer une facture
`/invoices/compute`	POST	Simuler une facture (calcul sans creation)
`/invoices/{id}`	GET	Detail d'une facture (numero, montants, PDF)
`/invoices/{id}/validate`	POST	Valider : draft -> due, attribue le numero
`/invoices/{id}/payments`	GET	Liste des paiements recus
`/invoices/{id}/credit-notes`	GET	Avoirs lies
`/invoices/search`	POST	Recherche avec filtres
`/invoices/export`	POST	Export CSV
`/credit-notes`	POST	Creer un avoir
`/items`	GET/POST	Produits / catalogue
`/companies`	GET/POST	Clients et fournisseurs
`/webhooks`	POST	S'abonner aux evenements

Statuts facture Sellsy

draft -----> due -----> payinprogress -----> paid
              |
              +-------> late
              +-------> cancelled

draft — brouillon modifiable (pas encore de numero)
due — validee, numero attribue, PDF genere, en attente de paiement
payinprogress — paiement partiel recu
paid — integralement payee
late — echeance depassee
cancelled — annulee

Schema d'une facture (champs cles)

POST /invoices — body

{
  "date": "2026-08-01",
  "subject": "Facturation aout 2026 — Anglais B2",
  "currency": "EUR",
  "order_reference": "BC-2026-ALT-0142",

  "related": [
    { "type": "company", "id": 234 },
    { "type": "opportunity", "id": 567 }
  ],

  "rows": [
    {
      "type": "item",
      "item_id": 123,
      "quantity": "30",
      "unit_amount": "65.00",
      "tax_id": 456,
      "description": "Formation Anglais B2 — Visio Individuel"
    }
  ],

  "service_dates": {
    "start": "2026-07-01",
    "end": "2026-07-31"
  }
}

Reponse Sellsy

{
  "id": 3875,
  "number": "FA-LE-2026-0847",
  "status": "due",
  "pdf_link": "https://app.sellsy.com/...",
  "amounts": {
    "total_excl_tax": "1950.00",
    "total_incl_tax": "1950.00",
    "total_remaining_due_incl_tax": "1950.00"
  }
}

Simulation sans creation

POST /invoices/compute accepte le meme body que POST /invoices mais ne cree rien. Il retourne les montants calcules (HT, TVA, TTC). C'est exactement le bouton "Simuler N facturations" — sauf qu'aujourd'hui Bubble fait ce calcul avec des boucles de texte en plusieurs minutes.

5. Architecture cible

Separation des responsabilites

ALICE (MongoDB)

Formations et seances
Heures realisees
Apprenants et formateurs
Contrats
Info OPCO
Calcul PCA et marges
Emargements
Evaluations / Enquetes (Qualiopi)

Sellsy V2 API

Factures (numero, PDF)
Avoirs
Paiements
Produits (catalogue officiel)
Clients (coordonnees legales)
Fournisseurs (formateurs)
Devis
Opportunites

Regle d'or : ALICE gere la FORMATION, Sellsy gere l'ARGENT.

Flux cible : facturer en 3 clics

Etape 1 — L'admin selectionne les formations avec heures a facturer

Etape 2 — Simulation
  ALICE appelle POST /invoices/compute
  Sellsy retourne les montants instantanement
  L'admin voit le recap dans une modale

Etape 3 — Validation
  L'admin clique "Valider"
  ALICE appelle :
    1. POST /invoices          (creation draft)
    2. POST /invoices/{id}/validate  (numero + PDF)
    3. Si OPCO : repete pour la 2e facture

Etape 4 — Suivi automatique
  Sellsy envoie des webhooks quand le statut change
  ALICE met a jour le statut local en temps reel

Temps estime : 2-3 secondes au lieu de plusieurs minutes

Ce que ALICE stocke pour chaque facture

Collection MongoDB : invoices

{
  sellsy_invoice_id: 3875,
  sellsy_number: "FA-LE-2026-0847",
  formation_id: ObjectId("..."),
  entity: "LE",
  type: "mensuelle",
  period: { start: "2026-07-01", end: "2026-07-31" },
  hours_billed: 30,
  status: "due",       // miroir du statut Sellsy
  is_opco: true,
  opco_split: {
    opco_invoice_id: 3876,
    opco_amount: 1200,
    company_amount: 750
  },
  created_by: ObjectId("..."),
  created_at: ISODate("2026-08-01")
}

Pas de montants stockes dans ALICE (sauf cache). La verite financiere = Sellsy.

Multi-entite LE / SM

Les 2 entites sont 2 comptes Sellsy separes (corp 101915 et 98044). En cible, ALICE stocke 2 jeux de credentials OAuth2. Le champ entity sur la formation determine automatiquement quel compte Sellsy utiliser. L'admin ne "switche" plus manuellement.

6. Plan de migration

1

Connecteur Sellsy (socle technique)

Classe SellsyConnector avec OAuth2, gestion des 2 corps (LE/SM), retry avec backoff sur les quotas (429), webhook receiver.

2

Synchronisation produits

Import initial GET /items -> MongoDB. CRUD bidirectionnel : creer/modifier un produit dans ALICE -> POST/PUT /items. Plus jamais de copier-coller d'ID.

3

Synchronisation clients / fournisseurs

Import initial GET /companies -> MongoDB. Creer un formateur -> POST /companies type supplier. Plus jamais d'ID Sellsy a copier.

4

Facturation cliente

Simulation via /invoices/compute. Creation via POST /invoices + /validate. Split OPCO automatique. Rattachement opportunite automatique. Webhooks pour suivi paiement.

5

Pilotage financier

PCA et marges calcules cote ALICE. Plus d'onglet "Sellsy DB" en vrac. Plus de "Attendre que le tableau charge".

7. Decisions validees

Question	Decision	Impact
CRM / Facturation	Sellsy confirme comme outil de facturation	Connecteur Sellsy API V2 en cible. ALICE = formation, Sellsy = argent.
Qui peut facturer ?	Role dedie (admin facturation)	Tracabilite Qualiopi. Un role specifique pour les operations de facturation.
Formateur et ses heures	Lecture seule	Le formateur consulte son recap d'heures dans ALICE. Il fait sa propre facture en dehors d'ALICE.
Propagation dates vers Sellsy	Toggle par formation	Chaque formation peut activer/desactiver la mise a jour automatique des dates de devis Sellsy.
Split OPCO	Automatique	ALICE connait l'OPCO et le % de prise en charge. Genere automatiquement les 2 factures (part OPCO + reste a charge).
API V1	Supprimee	Les 4 appels V1 restants sont migres en V2. Zero dependance legacy.

Annexe — Etat actuel des appels Sellsy

Element	Volume	Detail
API V2	70 appels	36 + 34 configures dans Bubble (devis, factures, contacts, catalogue, opportunites)
API V1	4 appels	Supplier.get*, langues, devises — a migrer imperativement
Webhooks	16 webhooks	Configures dans Bubble, a rationaliser a 3-4 en cible
Securite	Critique	Token Bearer V1 visible en clair dans l'editeur Bubble

Les Erudits / SmartFormation — Migration ALICE — Aout 2026

Analyse du module Facturation ALICE x Sellsy

Sommaire