Facturation

Système complet de facturation pour Larapen : gérez les factures, paiements, avoirs, factures récurrentes, dépenses, catalogue de produits et demandes de devis depuis un seul panneau d’administration.

Cas d’utilisation

Freelance / Consultant

Vous gérez un site portfolio sur Larapen et devez facturer vos clients pour le travail effectué.

• Créez des clients avec adresses de facturation et conditions de paiement.
• Ajoutez vos services au catalogue de produits (ex. « Développement web : horaire »).
• Créez des factures, ajoutez des lignes d’articles et envoyez par e-mail avec un lien de paiement public.
• Suivez les paiements et générez des reçus PDF.

Agence avec clients sous contrat

Vous gérez plusieurs clients avec des forfaits mensuels et avez besoin d’une facturation récurrente automatisée.

• Configurez des factures récurrentes pour chaque client avec une fréquence mensuelle.
• Les factures sont générées automatiquement et optionnellement envoyées au client.
• Suivez les soldes impayés et les factures en retard depuis le tableau de bord de facturation.

Entreprise de services avec devis personnalisés

Les clients potentiels soumettent des demandes de devis via votre site web avant l’engagement.

• Intégrez le formulaire de demande de devis sur votre front-end avec des catégories (ex. « Web Design », « SEO »).
• Examinez les demandes dans le panneau d’administration et créez des propositions détaillées.
• Envoyez le devis par e-mail avec un lien public. Une fois accepté, convertissez-le en facture.

Petite entreprise avec suivi des dépenses

Vous avez besoin d’un moyen simple de suivre les dépenses professionnelles en parallèle des revenus.

• Organisez les dépenses par catégorie (Bureau, Voyages, Logiciels, etc.).
• Téléchargez les reçus et exigez optionnellement l’approbation d’un responsable.
• Visualisez revenus vs. dépenses sur le tableau de bord de facturation.

Prérequis

Prérequis	Version
Larapen Core	≥ 1.0.0
PHP	≥ 8.2
DomPDF	Inclus via barryvdh/laravel-dompdf

Installation

Étape 1 : Placer l’add-on

Copiez ou créez un lien symbolique du dossier billing dans extensions/addons/billing.

Étape 2 : Activer l’add-on

Allez dans Admin → Add-ons et activez « Facturation ».

Étape 3 : Exécuter les migrations

Étape 4 : Définir les permissions

Attribuez les permissions de facturation aux rôles administrateurs sous Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Allez dans Admin → Facturation → Paramètres pour configurer les détails de l’entreprise, la numérotation des factures, les paramètres de taxes et les préférences de notifications.

Configuration

Toute la configuration se trouve dans config/billing.php et peut être remplacée via le panneau de paramètres d’administration (stockée dans la base de données via SettingService).

Clé	Par défaut	Description
admin_per_page	15	Éléments par page dans les listes d’administration
invoice_prefix	INV-	Préfixe pour les numéros de facture générés automatiquement
invoice_next_number	1	Prochain numéro de séquence de facture
payment_terms_days	30	Conditions de paiement par défaut en jours
credit_note_prefix	CN-	Préfixe pour les numéros d’avoir
credit_note_next_number	1	Prochain numéro de séquence d’avoir
company_name	—	Nom de votre entreprise (apparaît sur les factures)
company_address	—	Adresse de l’entreprise pour les factures
company_phone	—	Numéro de téléphone de l’entreprise
company_email	—	Adresse e-mail de l’entreprise
company_tax_number	—	Numéro de taxe/TVA affiché sur les factures
tax_enabled	true	Activer les calculs de taxes
default_tax_rate_id	null	Taux de taxe par défaut pour les nouveaux articles
recurring_enabled	true	Activer la fonctionnalité de factures récurrentes
recurring_auto_send	false	Envoyer automatiquement les factures récurrentes générées
expenses_enabled	true	Activer le suivi des dépenses
expenses_require_approval	false	Exiger l’approbation pour les nouvelles dépenses
pdf_logo	—	Chemin vers l’image du logo pour les documents PDF
pdf_footer_text	—	Texte de pied de page personnalisé sur les documents PDF

Paramètres de notification

Clé	Par défaut	Description
notify_invoice_sent	true	Notifier le client lorsque la facture est envoyée
notify_payment_received	true	Notifier le client lorsqu’un paiement est enregistré
notify_invoice_overdue	true	Notifier le client lorsque la facture est en retard
notify_recurring_generated	true	Notifier l’administrateur lorsqu’une facture récurrente est générée
notify_credit_note_issued	true	Notifier le client lorsqu’un avoir est émis

Paramètres de devis

Clé	Par défaut	Description
quote_validity_days	30	Période de validité par défaut des devis
quote_per_page	12	Éléments par page sur la liste front-end des devis
quote_admin_per_page	15	Éléments par page dans les listes d’administration des devis
allowed_attachment_types	pdf, doc, docx, xls, xlsx, jpg, jpeg, png	Types de fichiers autorisés pour les pièces jointes des demandes de devis
max_attachment_size	10240	Taille maximale des pièces jointes en Ko
notify_new_quote_request	true	Notifier l’administrateur lors d’une nouvelle demande de devis
notify_quote_submission_confirmation	true	Envoyer une confirmation au demandeur
notify_quote_request_reviewing	true	Notifier le demandeur lorsque le statut passe à « en cours d’examen »
notify_quote_sent	true	Notifier le demandeur lorsque le devis est envoyé
notify_quote_request_accepted	true	Notifier le demandeur lorsque la demande est acceptée
notify_quote_request_rejected	true	Notifier le demandeur lorsque la demande est rejetée

Admin : Tableau de bord

Le tableau de bord de facturation (/admin/billing) fournit un aperçu rapide de votre situation financière.

Cartes récapitulatives

• Chiffre d’affaires total : somme de toutes les factures payées
• En attente : solde total dû sur les factures impayées
• En retard : total des factures dépassées
• Total des dépenses : somme de toutes les dépenses approuvées
• Nombre de factures : total des factures créées
• Nombre de clients : total des clients
• Paiements ce mois : total des paiements du mois en cours

Graphique des revenus

Un diagramme en barres sur 12 mois montrant les tendances mensuelles des revenus.

Panneaux d’activité

• Factures récentes : dernières factures avec badges de statut
• Paiements récents : dernières entrées de paiement
• Factures en retard : factures dépassées
• Récurrences à venir : factures récurrentes bientôt générées

Admin : Clients

Gérez les clients de facturation à /admin/billing/customers. Les clients peuvent optionnellement être liés à un compte utilisateur Larapen.

Champs client

Champ	Requis	Description
company_name	Non	Nom de l’entreprise ou de l’organisation
contact_name	Oui	Personne de contact principale
contact_email	Oui	E-mail pour l’envoi des factures
contact_phone	Non	Numéro de téléphone
tax_number	Non	Numéro de taxe/TVA
website	Non	URL du site web du client
billing_address	Non	Objet JSON avec les champs d’adresse
shipping_address	Non	Objet JSON avec les champs d’adresse
default_currency	Oui	Code de devise par défaut (ex. USD)
payment_terms_days	Oui	Conditions de paiement (par défaut : 30 jours)
notes	Non	Notes internes sur ce client

Détail du client

La page de détail du client (/admin/billing/customers/{id}) affiche :

• Informations du client et coordonnées
• Statistiques : total facturé, total payé, solde impayé
• Liste de toutes les factures de ce client

Admin : Produits

Le catalogue de produits (/admin/billing/products) stocke les lignes d’articles réutilisables pour les factures. Les produits sont gérés via des boîtes de dialogue modales (pas de pages de création/modification séparées).

Champ	Requis	Description
name	Oui	Nom du produit (traduisible)
description	Non	Description du produit (traduisible)
sku	Non	Référence article (unique)
type	Oui	product ou service
unit_price	Oui	Prix unitaire par défaut
unit	Non	Unité de mesure (hrs, pcs, kg, etc.)
currency	Oui	Code de devise
tax_rate_id	Non	Taux de taxe par défaut pour ce produit

Options d’unité disponibles : Unité, Pcs, Hrs, Jours, Mois, Kg, G, L, ML, M, Km, Boîte, Pack, Set, Service, Lot.

Admin : Taux de taxe

Configurez les taux de taxe à /admin/billing/tax-rates. Les taux de taxe sont gérés via des boîtes de dialogue modales.

Champ	Requis	Description
name	Oui	Nom du taux de taxe (traduisible), ex. « TVA 20% »
rate	Oui	Taux en pourcentage (décimal, ex. 20.0000)
is_compound	Non	Si cette taxe se compose sur d’autres taxes
is_default	Non	Définir comme taux de taxe par défaut pour les nouveaux articles

Admin : Factures

Le centre de gestion des factures à /admin/billing/invoices. Les factures peuvent être filtrées par client, statut et recherchées par numéro ou contenu.

Créer une facture

Naviguez vers Facturation → Factures → Créer. Le formulaire de facture comprend :

• Client : sélectionner parmi les clients existants
• Devise : par défaut la devise du client
• Date d’émission et Date d’échéance : date d’échéance calculée automatiquement à partir des conditions de paiement
• Lignes d’articles : ajout depuis le catalogue de produits ou saisie d’articles personnalisés. Chaque article a : description (traduisible), quantité, unité, prix unitaire, taux de taxe
• Remise : remise optionnelle en pourcentage ou montant fixe
• Notes et Conditions : champs de texte traduisibles

Les numéros de facture sont générés automatiquement en utilisant le préfixe et le numéro de séquence configurés (ex. INV-0001).

Cycle de vie de la facture

Statut	Description
draft	La facture est en cours de préparation. Peut être modifiée librement.
sent	La facture a été envoyée au client. Plus modifiable.
partial	Un paiement partiel a été reçu.
paid	La facture a été entièrement payée.
overdue	La facture a dépassé sa date d’échéance et est impayée.
cancelled	La facture a été annulée.
refunded	Le paiement de la facture a été remboursé (via avoir).

Actions disponibles

• Envoyer : marque comme envoyée + envoie un e-mail au client avec un lien public
• Modifier le statut : changer manuellement le statut de la facture
• Dupliquer : crée une copie comme nouveau brouillon de facture
• Télécharger le PDF : génère et diffuse un PDF
• Depuis un devis : convertir un devis accepté en facture (crée le client si nécessaire)

Génération de PDF

Les factures PDF sont générées avec InvoicePdfService et DomPDF. Le PDF comprend :

• Logo et détails de l’entreprise (depuis les paramètres)
• Informations de facturation du client
• Tableau des lignes d’articles avec quantités, prix, taxes et totaux
• Sous-total, taxes, remise et total général
• Notes et conditions
• Texte de pied de page personnalisé

Admin : Paiements

Enregistrez les paiements à /admin/billing/payments. Les paiements sont liés aux factures et mettent automatiquement à jour le solde de la facture.

Champ	Requis	Description
invoice_id	Oui	La facture à laquelle ce paiement s’applique
amount	Oui	Montant du paiement
currency	Oui	Devise du paiement
payment_method	Oui	Espèces, Virement bancaire, Chèque, Carte de crédit, PayPal, Stripe ou Autre
reference	Non	Numéro de référence de transaction
payment_date	Oui	Date de réception du paiement
notes	Non	Notes internes

Lorsqu’un paiement est enregistré, le amount_paid et le balance_due de la facture sont recalculés. Si le solde atteint zéro, la facture est automatiquement marquée comme paid.

Admin : Avoirs

Gérez les avoirs à /admin/billing/credit-notes. Les avoirs sont liés à une facture et un client existants.

Cycle de vie de l’avoir

Statut	Description
draft	L’avoir est en cours de préparation.
issued	L’avoir a été émis au client.
applied	Le crédit a été appliqué pour réduire le solde du client.
void	L’avoir a été annulé.

Chaque avoir a ses propres lignes d’articles (description, quantité, prix unitaire, taux de taxe) et un numéro généré automatiquement avec le préfixe configuré (ex. CN-0001).

La génération de PDF est disponible pour les avoirs en utilisant le même InvoicePdfService.

Admin : Factures récurrentes

Configurez la facturation récurrente à /admin/billing/recurring-invoices.

Champs de facture récurrente

Champ	Requis	Description
customer_id	Oui	Client à facturer
title	Oui	Titre du modèle
frequency	Oui	Hebdomadaire, Mensuelle, Trimestrielle, Semestrielle ou Annuelle
interval	Oui	Multiplicateur (ex. 2 = tous les 2 mois)
start_date	Oui	Date de début de la récurrence
next_invoice_date	Oui	Prochaine date de génération
end_date	Non	Date de fin (null = illimité)
occurrences_limit	Non	Nombre maximum de factures à générer (null = illimité)
auto_send	Non	Envoyer automatiquement les factures générées
items	Oui	Lignes d’articles stockées en JSON

Fonctionnement

• Une commande planifiée s’exécute quotidiennement à 06:00 et vérifie les factures récurrentes où next_invoice_date ≤ aujourd’hui.
• Pour chaque facture récurrente échue, une nouvelle BillingInvoice est créée à partir des articles du modèle.
• La next_invoice_date est avancée en fonction de la fréquence et de l’intervalle.
• Si auto_send est activé, la facture est immédiatement marquée comme envoyée et le client est notifié.
• La génération s’arrête lorsque end_date est atteinte ou occurrences_limit est remplie.

Vous pouvez également déclencher manuellement la génération via le bouton Générer maintenant sur la page de détail d’une facture récurrente.

Admin : Dépenses

Suivez les dépenses professionnelles à /admin/billing/expenses. Les dépenses sont gérées via des boîtes de dialogue modales.

Champ	Requis	Description
category_id	Non	Catégorie de dépense
vendor	Non	Nom du fournisseur
reference	Non	Numéro de référence/reçu
amount	Oui	Montant de la dépense
currency	Oui	Code de devise
expense_date	Oui	Date de la dépense
notes	Non	Description ou notes
receipt	Non	Téléchargement du reçu

Statuts des dépenses

Statut	Description
pending	En attente d’approbation (lorsque l’approbation est requise)
approved	La dépense a été approuvée
rejected	La dépense a été rejetée

Catégories de dépenses

Organisez les dépenses par catégorie à /admin/billing/expense-categories. Les catégories ont un name et une description traduisibles, et peuvent être activées/désactivées.

Admin : Système de devis

Le système de devis gère le cycle de vie complet, de la demande du client à la proposition acceptée jusqu’à la facture.

Demandes de devis

Consultez et gérez les demandes de devis entrantes à /admin/billing/quotes/requests.

Champs de la demande

Champ	Description
reference_number	Référence unique générée automatiquement (ex. QR-0001)
category_id	Catégorie optionnelle (depuis la table unifiée des catégories)
company_name	Entreprise du demandeur
contact_name	Nom du demandeur
contact_email	E-mail du demandeur
title	Titre du projet (traduisible)
description	Description du projet (traduisible)
requirements	Exigences détaillées (traduisible)
budget_min / budget_max	Fourchette budgétaire
timeline	Délai prévu
priority	Basse, Normale, Haute ou Urgente
attachment	Pièce jointe optionnelle

Statuts des demandes

Statut	Description
pending	Nouvelle demande en attente d’examen
reviewing	La demande est en cours d’examen
quoted	Un devis a été envoyé
accepted	Demande/devis accepté par le demandeur
rejected	Demande refusée
cancelled	Demande annulée

Propositions de devis

Créez des propositions à /admin/billing/quotes/quotes. Chaque devis est lié à une demande de devis.

Champs du devis

Champ	Description
quote_number	Numéro unique généré automatiquement
request_id	Demande de devis liée
title	Titre du devis (traduisible)
scope	Périmètre des travaux (traduisible)
terms	Conditions générales (traduisible)
items	Lignes d’articles avec description, quantité, unité, prix unitaire
amount	Montant total du devis
currency	Code de devise
valid_until	Date d’expiration du devis

Statuts des devis

Statut	Description
draft	Le devis est en cours de préparation
sent	Devis envoyé au demandeur avec un lien public
accepted	Devis accepté : peut être converti en facture
rejected	Devis rejeté par le demandeur
expired	La période de validité du devis est dépassée

Catégories de devis

Gérez les catégories de devis à /admin/billing/quotes/categories. Ce sont des entrées de catégories standard de la table unifiée categories, limitées aux demandes de devis. Les catégories apparaissent sur le formulaire public de demande de devis.

Admin : Paramètres

Tous les paramètres de facturation sont gérés à /admin/billing/settings. Le formulaire de paramètres est groupé en sections :

• Informations de l’entreprise : nom, adresse, téléphone, e-mail, numéro de taxe
• Paramètres de facturation : préfixe, prochain numéro, conditions de paiement
• Paramètres d’avoir : préfixe, prochain numéro
• Paramètres de taxe : activer/désactiver, taux de taxe par défaut
• Paramètres de récurrence : activer/désactiver, envoi automatique
• Paramètres de dépenses : activer/désactiver, exiger l’approbation
• Paramètres de devis : jours de validité, pièces jointes, par page
• Paramètres PDF : logo, texte de pied de page
• Notifications : activer/désactiver chaque type de notification

Les paramètres sont stockés dans la base de données via le SettingService (préfixés avec billing_) et mis en cache pour les performances.

Front-end : Formulaire de demande de devis

URL & Routes

Route	URL	Description
front.billing.quotes.index	/quote-requests/new	Afficher le formulaire de demande de devis
front.billing.quotes.submit	POST /quote-requests/submit	Soumettre la demande de devis

Des variantes localisées sont également enregistrées (ex. /fr/quote-requests/new).

Champs du formulaire

Les visiteurs peuvent remplir les champs suivants :

• Coordonnées : nom, e-mail, téléphone, nom de l’entreprise
• Catégorie : sélection parmi les catégories de devis configurées
• Détails du projet : titre, description, exigences (traduisible)
• Budget : fourchette minimum et maximum avec devise
• Délai : calendrier prévu du projet
• Priorité : Basse, Normale, Haute ou Urgente
• Pièce jointe : téléchargement de fichier optionnel (validé par rapport aux types autorisés et à la taille maximale)

Après la soumission

• Un enregistrement BillingQuoteRequest est créé avec un numéro de référence unique.
• L’administrateur reçoit une NewQuoteRequestNotification (si activée).
• Le demandeur reçoit une QuoteSubmissionConfirmationNotification (si activée).
• L’adresse IP du visiteur est enregistrée.

Front-end : Vue publique de la facture

URL & Routes

Route	URL	Description
front.billing.invoice.show	/billing/invoice/{token}	Voir la facture (public, sans authentification)
front.billing.invoice.pdf	/billing/invoice/{token}/pdf	Télécharger le PDF

Chaque facture possède un public_token unique de 64 caractères généré à la création. Ce jeton est inclus dans l’e-mail envoyé au client, lui permettant de consulter et télécharger la facture sans se connecter.

La vue publique affiche : détails de l’entreprise, détails du client, lignes d’articles, totaux, statut de paiement et notes/conditions.

Front-end : Vue publique du devis

URL & Routes

Route	URL	Description
front.billing.quote.show	/billing/quote/{token}	Voir le devis (public, sans authentification)
front.billing.quote.pdf	/billing/quote/{token}/pdf	Télécharger le PDF

Les devis possèdent également un public_token unique. La vue publique affiche : périmètre des travaux, lignes d’articles, montant total, période de validité et conditions.

Front-end : Paiement en ligne

URL & Routes

Route	URL	Description
front.billing.invoice.checkout	/billing/invoice/{token}/pay	Page de paiement
front.billing.invoice.pay	POST /billing/invoice/{token}/pay	Traiter le paiement

Le modèle BillingInvoice implémente le contrat Payable, le rendant compatible avec tout add-on de passerelle de paiement (Stripe, PayPal, etc.). Le contrat fournit :

• getPayableAmount() : retourne le solde dû
• getPayableDescription() : numéro et description de la facture
• getPayableCurrency() : devise de la facture
• getPayableCustomerEmail() : e-mail du client
• getPayableCustomerName() : nom d’affichage du client
• getPayableUserId() : ID utilisateur lié (le cas échéant)
• getPayableIdentifier() : identifiant unique du paiement
• getPaymentSuccessUrl() : URL de redirection après un paiement réussi
• getPaymentCancelUrl() : URL de redirection après un paiement annulé

Lorsque le paiement réussit, la méthode markAsPaid() de la facture est appelée. En cas d’échec, markPaymentFailed() est appelée.

Notifications

L’add-on comprend 11 classes de notification, toutes dans Addons\Billing\Notifications :

Notifications de factures & paiements

Notification	Destinataire	Déclencheur
InvoiceSentNotification	Client	Facture marquée comme envoyée
PaymentReceivedNotification	Client / Admin	Paiement enregistré
InvoiceOverdueNotification	Client	Facture en retard (via commande planifiée)
RecurringInvoiceGeneratedNotification	Admin	Facture récurrente génère une nouvelle facture
CreditNoteIssuedNotification	Client	Avoir émis

Notifications de devis

Notification	Destinataire	Déclencheur
NewQuoteRequestNotification	Admin	Nouvelle demande de devis soumise
QuoteSubmissionConfirmationNotification	Demandeur	Après la soumission du formulaire
QuoteRequestReviewingNotification	Demandeur	Statut changé en « en cours d’examen »
QuoteSentNotification	Demandeur	Devis envoyé avec lien public
QuoteRequestAcceptedNotification	Demandeur	Demande acceptée
QuoteRequestRejectedNotification	Demandeur	Demande rejetée

Chaque notification peut être activée/désactivée individuellement dans Facturation → Paramètres.

Mise à jour

Étape 1 : Remplacer les fichiers

Remplacez le dossier billing dans extensions/addons/ par la nouvelle version.

Étape 2 : Exécuter les migrations

Étape 3 : Vider les caches

Étape 4 : Vérifier

• Vérifiez que toutes les pages de facturation se chargent correctement dans le panneau d’administration.
• Vérifiez que les statistiques du tableau de bord sont exactes.
• Testez la création d’une nouvelle facture et la génération d’un PDF.
• Vérifiez que les commandes planifiées fonctionnent toujours correctement.

Dépannage

La génération de PDF de facture échoue

• Assurez-vous que barryvdh/laravel-dompdf est installé : composer require barryvdh/laravel-dompdf.
• Vérifiez que le chemin du logo PDF (dans les paramètres) pointe vers un fichier image valide.
• Vérifiez que le répertoire storage est accessible en écriture.

Les factures récurrentes ne se génèrent pas

• Assurez-vous que le planificateur Laravel fonctionne : * * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
• Vérifiez que la facture récurrente est active (is_active = true).
• Vérifiez que next_invoice_date n’est pas dans le futur.
• Vérifiez que end_date et occurrences_limit n’ont pas été atteints.
• Exécutez manuellement pour déboguer : php artisan billing:generate-recurring

Les notifications de retard ne sont pas envoyées

• Vérifiez que notify_invoice_overdue est activé dans les paramètres de facturation.
• Vérifiez que le statut de la facture est sent ou partial (seuls ces statuts passent en retard).
• Vérifiez la configuration du courrier dans .env (paramètres SMTP).
• Exécutez manuellement pour déboguer : php artisan billing:check-overdue

Le paiement en ligne n’est pas disponible

• Au moins un add-on de passerelle de paiement (Stripe, PayPal, etc.) doit être installé et actif.
• La facture doit implémenter le contrat Payable (intégré).
• La facture doit avoir un balance_due > 0 et un public_token valide.

Le formulaire de demande de devis n’est pas visible

• Assurez-vous que l’add-on de facturation est activé.
• Vérifiez que la route front.billing.quotes.index est accessible.
• Si vous utilisez un lien de menu, vérifiez que l’élément de menu pointe vers la bonne route.

Le client n’est pas lié à un compte utilisateur

• Le champ user_id sur les clients de facturation est optionnel.
• Lors de la conversion d’un devis en facture, un nouveau client de facturation est créé automatiquement s’il n’en existe pas pour le demandeur.
• Vous pouvez lier manuellement un client à un utilisateur via le formulaire de modification du client.

Les calculs de taxes semblent incorrects

• La taxe est calculée par ligne d’article, pas sur le total de la facture.
• Vérifiez que le bon taux de taxe est attribué à chaque ligne d’article.
• Vérifiez si les taux de taxe composés sont utilisés correctement : les taxes composées s’appliquent en plus des autres taxes.
• Assurez-vous que tax_enabled est défini sur true dans les paramètres de facturation.