💳 Spécifications Fonctionnelles — Abonnements & Facturation SaaS

Ce document détaille les règles métier de gestion des abonnements (Billing Engine) et de la génération automatique des factures au sein de la plateforme Ash-Wallet.

---

1. Parcours Développeur (Onboarding & Configuration)

1. Inscription : Le développeur s'inscrit sur la console ash-wallet-gate.
2. Création de Projet : Il configure un projet et renseigne ses clés API FedaPay (Sandbox et Live).
3. Activation du Mode SaaS : Le développeur active le module d'abonnements pour son projet en chargeant les plans de base ou en en créant des personnalisés.
4. Intégration : Le projet expose un endpoint public /billing-plans renvoyant la liste des abonnements disponibles, que le développeur affiche directement sur sa propre plateforme web ou mobile.

---

2. Cycle de Vie des Plans d'Abonnement

Le Billing Engine gère deux typologies de plans :

A. Le Plan d'Essai (Trial)

• Règle d'Unicité : Un projet ne peut comporter qu'un seul plan de type "période d'essai".
• Règle d'Usage : Un client final du projet ne peut souscrire à la période d'essai qu'une seule fois.
• Configuration : La durée de la période d'essai est configurable par le développeur (ex: 7 jours, 14 jours, 30 jours).

B. Les Plans Payants

Le développeur peut choisir entre deux modes de facturation pour le premier cycle d'un plan payant :

1. Paiement Immédiat : Le client paie dès la souscription.
   • Statut Facture : La facture est marquée "Payée" immédiatement après validation de la transaction.
2. Paiement à l'Échéance (Post-payé) : Le premier paiement est dû à la fin du premier cycle d'utilisation.
   • Statut Facture : Une facture temporaire est émise avec la mention "À payer".

---

3. Système de Relance & Retards de Paiement (Past Due)

Si une facture n'est pas réglée à la date d'échéance :

1. Changement d'État : L'abonnement bascule automatiquement dans le statut past_due (en souffrance).
2. Notification Client : Le système envoie un e-mail de notification pour signaler le défaut de paiement.
3. Personnalisation : Le développeur peut personnaliser le modèle de cet e-mail de rappel depuis son dashboard.
4. Fréquence des Relances : Les relances automatiques s'effectuent durant la période de grâce selon une fréquence configurable par le développeur :
   • Options disponibles : relance tous les 3 jours, 7 jours ou 10 jours.

---

4. Génération de Factures PDF & Envoi d'E-mails

• Déclencheur : Tout paiement validé (initialisation, renouvellement ou régularisation) déclenche automatiquement l'émission d'une facture.
• Contenu : Le PDF de la facture est généré à la volée avec les détails de la transaction (opérateur, montant, devise, informations du locataire) et la mention "Payée".
• Envoi : Le client reçoit immédiatement un e-mail automatique contenant la facture PDF en pièce jointe, et une copie est archivée sur le stockage S3.

---

5. Moteur de Facturation Avancé

Pour garantir une flexibilité maximale et un rendu visuel optimal des factures, la plateforme intègre un moteur de facturation dédié en arrière-plan.

Fonctionnement fonctionnel :

• Headless / Piloté par API : Ce moteur fonctionne de façon transparente. Les utilisateurs de la console ash-gate ne s'y connectent jamais directement.
• Personnalisation multi-projet (Branding) : Les factures intègrent de façon dynamique la charte graphique définie au niveau du projet (logo, couleurs primaires, coordonnées et adresse de l'émetteur).
• Téléchargement transparent : Le téléchargement du PDF s'effectue à travers les routes sécurisées de l'API ash-bwallet (sans aucun changement sur l'application frontend).
• Résilience (Secours automatique) : En cas de dysfonctionnement temporaire du moteur de facturation dédié, le système bascule de façon transparente sur son moteur de rendu PDF interne pour assurer la continuité de service et la livraison des factures aux clients.