# Système de facturation ## Sommaire - [Introduction](#introduction) - [Motivation](#motivation) - [Guide-level explanation](#guide-level-explanation) - [Reference-level explanation](#reference-level-explanation) - [Justification et alternative](#justification-et-alternatives) - [Impacts si la situation reste ainsi](#impacts-si-la-situation-reste-ainsi) - [Etat de l'art](#etat-de-l'art) - [Questions non résolues](#questions-non-resolues) - [Possibilités futures](#possibilites-futures) ## Introduction Il est nécessaire d'avoir un module de facturation afin d'assister les organisations de notre application **Molink** dans ce processus. ## Motivation Les raisons qui nous poussent à développer le module de facturation sont de permettre aux clients de : - Générer et exporter des factures depuis Molink vers les services internes des organisations. - Visualiser et gérer les factures générées. - Automatiser cette gestion de factures via l'API Molink. ## Guide-level explanation ### Fonctionnalités Les raisons qui ont poussé la rédaction du document est de simplifier et d'automatiser tous le processus de facturation des organisations aux déclarants, voici les étapes fonctionnelles visées : - **Générer une facture** Les organisations pourront, pour une période donnée ainsi qu'un déclarant affilié, générer une facture et l'exporter sous multi-format (PDF, JSON, XML) - **Visualiser les factures** Les organisations pourront visualiser leurs factures ainsi que leur statut afin de pouvoir les administrer sur une seule interface. - **Automatiser le système de factures** Notre API Molink permettra aux organisations d'automatiser toute cette gestion de facture (création, visualisation, envoi ...) ### Structure du système de facture Une facture est composée de : - Une organisation (envoyeur) - Un déclarant (receveur) - Une période donnée - Des avis de décès - Détailler avec l'existant ## Reference-level explanation ### Existant Single-Tenant -- A remplir par Alexandre ### Format des données Voici le format d'une facture de la table `invoices` ```json { "id": "uuidv7" "organization__id": "organization_fk" "operator__id": "operator_fk" "start_date": "timestamp" "end_date": "timestamp" "status": "pending" | "created" | "failed" "format": "pdf" | "xml" | "json" "url": "string" | null, } ``` ### Génération de facture Pour générer une facture, une organization va faire un appel d'API ou sélectionner dans son interface Molink : - `operator_id`: L'identifiant d'un déclarant - `start_date`: La date de départ d'une période au format dd/mm/YYYY - `end_date`: La date de fin d'une période au format dd/mm/YYYY - `format`: Le format demandé de la facture Une fois la génération demandée, une ligne va se créer dans la table `invoices` au `status = pending` et `url = null` Un job asynchrone `GenerateInvoice` va alors être lancé qui aura comme responsabilité de : - Récupérer les `commandes` effectuées pour la période et le déclarant donnés - Formatter ces données sous le `format` demandé - Stocker ce fichier dans *Amazon AWS* - Mettre à jour la ligne `invoice` pour passer le `status` à "created" avec l'`url` qui pointera sur le fichier AWS Pour gérer ces jobs, une solution de Message Queuing (existant ?) sera mis en place : - Mettre en place un système de retry pour lancer `3` fois le job si nécessaire - Si le message n'as pas été consommé : - Il sera mis dans une Dead-Letter Queue, ce qui causera une alerte sur notre système de monitoring - Le status de l'`invoice` passera en "failed" ### Export de factures Pour ce qui est de l'export des factures, celle-ci se fera via appel d'API ou sur la page de visualisation des factures : - Une organisation pourra voir ses factures générées, la période donnée, le format demandé, le déclarant associé ainsi que son statut - Si la facture est créée, il pourra télécharger le fichier ### API Molink de factures Pour automatiser ce système et permettre à nos organisations d'intégrer Molink à leurs solutions de factures actuelles, ces ressources seront accessibles via appel d'API sur ces routes suivantes : ``` POST /v2/invoices :operator_id :start_date :end_date :format GET /v2/invoices ?filters[status] ?filters[operator_id] ?filters[between_date] GET /v2/invoices/{id}/download ``` ## Justification et alternatives Dans notre souhait de fournir un service complet de multi-diffusion de faire-part, permettant aux organisations et déclarants d'internaliser l'intégralité de leur processus métier via Molink, il est nécessaire de comprendre dans ce service la génération de factures. ### Autres conceptions envisagées #### Transmission de d'informations de facturation simple Alors que nos organisations auraient déjà un système de facturation et de communication en interne, il est possible d'utiliser la plateforme Molink pour simplement : - Résumer à une organisation ce qu'un déclarant lui doit pour une période donnée ##### Avantages - Facile à implémenter ##### Inconvénients - Nécessite aux organisations de remplir manuellement leurs factures ## Impacts si la situation reste ainsi Le système de facturation actuel ne prend pas en charge le multi-tenant. L'algorithme actuel n'est pas permissif pour aller dans le sens d'un Sass et doit être revu intégralement. ## Etat de l'art Il existe déjà des modules de facturation très performants connus : ### Stripe Stripe permet de générer des factures automatisés pour leur différents clients avec envoi automatique de celles-ci aux clients finaux de l'entreprise. ## Questions non résolues - Quel sera le canal de communication facture entre l'organisation et ses déclarants ? - Est-ce Molink pourra faire office d'intermédiaire afin que les déclarants visualisent leurs coûts et factures ? ## Possibilités futures ### Système de template Les organisations pourront créer leurs propres template de facture personnalisés avec leurs informations Un template de facture est composé de : - Un bloc contenant les informations de l'organisation (envoyeur) - Un bloc contenant les informations du déclarant (receveur) - Un bloc de résumé de la facture (titre, numéro de facture) - Un bloc de détails de la facture (lignes de commande) - Un bloc de références de la facture (TVA, date d'émission, jours avant règlement) ### Export de factures multi-support Dans un premier temps, une facture sera exportée en HTTP, que ce soit via l'interface MOLINK ou lors d'un appel d'API. Il est possible que l'ajout d'un multi-support d'envoi SSH / FTP soit nécessaire par la suite.