💳 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é (Invoice Ninja)

Pour garantir une flexibilité maximale et un rendu visuel optimal des factures, la plateforme intègre l'API d'Invoice Ninja en arrière-plan.

Architecture des 2 Niveaux de Facturation :

1. Niveau 1 — Relevés & Factures AshGateway (Plateforme ➔ Marchand) :

   • Factures de commission de routage (0,5%) et d'abonnements SaaS émises par Ashborn SAS pour le marchand.
   • Consultables et téléchargeables sur ash-gate dans la section Relevés & Factures (/dashboard/billing).

2. Niveau 2 — Factures des Clients du Marchand (Marchand ➔ Client Final) :

   • Factures d'achats émises sous la marque du marchand à destination de ses propres acheteurs finaux.
   • Le marchand choisit le modèle visuel par défaut (Modern, Clean, Bold, Élégant) dans l'onglet Modèles de Facture (/dashboard/templates).
   • L'historique et l'émission sont gérés dans l'onglet Mes Factures Clients (/dashboard/invoices).

---

6. Flux d'Émission Automatique 100% Transparent

Tout paiement validé déclenche automatiquement l'émission de la facture sans aucune action manuelle requise :

[ 1. Intégration SDK/API Marchand ]
             │
             ▼ 1.1 POST /v1/checkout (API Key Marchand)
[ 2. Backend AshGateway ] ───(Sélectionne le Modèle Actif)───> [ 3. API Invoice Ninja ] (Crée facture PENDING)
             │
             ▼ 2.1 L'Acheteur Paye (Wave, FedaPay, Carte)
[ 4. Webhook de Paiement ]
             │
             ▼ 4.1 Validation & Validation du Règlement
[ 5. Invoice Ninja ] ───(Tampon "PAYÉ" + Génération PDF)───> 📧 Envoi Automatique au Client Final

• Headless / Piloté par API : Le moteur fonctionne de façon 100% transparente.
• Envoi Automatique : Le client final reçoit son reçu PDF tamponné "PAYÉ" dès la validation du règlement.
• Téléchargement Sécurisé : Le marchand et l'acheteur peuvent télécharger le PDF à tout moment via l'API sécurisée.