Aller au contenu principal

Factures Clients

Transactions sont regroupées pour former une facture, qui est envoyée au client pour paiement.

Les factures ont une date de début et une date de fin, qui est la période que la facture couvre, et une date d'échéance, qui est la date à laquelle la facture est due pour paiement.

Générer une Facture Proforma

Les factures peuvent être générées automatiquement par le système, par exemple, lorsque un service est facturé, une facture est créée pour le coût de détail, ou elles peuvent être créées manuellement, par exemple, si un client demande une copie d'une facture, ou si un client est facturé pour un coût unique.

Les factures clients sont entièrement modélisées avec Mailjet et peuvent être personnalisées pour inclure le logo de l'entreprise, l'adresse et les détails de paiement, et peuvent être envoyées au client par e-mail, ou téléchargées au format PDF.

Journal d'Activité

Personnalisation des Modèles de Facture​

OmniCRM utilise des modèles HTML avec Jinja2 pour générer des factures. Vous pouvez personnaliser entièrement le design de la facture, le branding, les couleurs et la mise en page.

Emplacement des Modèles de Facture​

Les modèles de facture sont stockés dans OmniCRM-API/invoice_templates/

Modèles par Défaut :

  • norfone_invoice_template.html - Modèle de facture d'exemple
  • cifi_invoice_template.html - Exemple de modèle alternatif

Configuration :

Le modèle de facture actif est spécifié dans OmniCRM-API/crm_config.yaml :

invoice:
  template_filename: 'norfone_invoice_template.html'

Variables de Modèle Disponibles​

Les modèles de facture ont accès aux variables Jinja2 suivantes :

Informations sur la Facture :

  • {{ invoice_number }} - ID unique de la facture (par exemple, INV-2025-001234)
  • {{ date }} - Date d'émission de la facture (format ISO : 2025-01-10T12:00:00)
  • {{ due_date }} - Date d'échéance de paiement (par exemple, 2025-02-10)
  • {{ start_date }} - Date de début de la période de facturation
  • {{ end_date }} - Date de fin de la période de facturation
  • {{ total_amount }} - Montant total de la facture avant taxes (numérique)
  • {{ total_tax }} - Montant total des taxes calculé à partir de toutes les transactions (numérique)

Informations sur le Client :

  • {{ client.name }} - Nom complet ou nom de l'entreprise du client
  • {{ client.address.address_line_1 }} - Ligne d'adresse 1
  • {{ client.address.address_line_2 }} - Ligne d'adresse 2
  • {{ client.address.city }} - Ville
  • {{ client.address.state }} - État/province
  • {{ client.address.zip_code }} - Code postal
  • {{ client.address.country }} - Pays

Éléments de Ligne de Transaction :

Boucle à travers les transactions en utilisant :

{% for sub_transaction in transactions %}
    <tr>
        <td>{{ sub_transaction.transaction_id }}</td>
        <td>{{ sub_transaction.created.split("T")[0] }}</td>
        <td>{{ sub_transaction.title }}</td>
        <td>{{ sub_transaction.description }}</td>
        <td>${{ "%.2f"|format(sub_transaction.retail_cost) }}</td>
    </tr>
{% endfor %}

Champs de Transaction :

  • sub_transaction.transaction_id - ID de la transaction
  • sub_transaction.created - Date/heure de la transaction
  • sub_transaction.title - Titre de la transaction
  • sub_transaction.description - Description détaillée
  • sub_transaction.retail_cost - Montant de l'élément de ligne
  • sub_transaction.tax_percentage - Pourcentage de taxe appliqué (par exemple, 10 pour 10%)
  • sub_transaction.tax_amount - Montant de la taxe calculé en dollars

Affichage de la Taxe dans les Modèles :

<td>
    {% if sub_transaction.tax_amount and sub_transaction.tax_amount > 0 %}
        ${{ "%.2f"|format(sub_transaction.tax_amount) }} ({{ sub_transaction.tax_percentage }}%)
    {% else %}
        -
    {% endif %}
</td>

Création d'un Modèle de Facture Personnalisé​

Étape 1 : Copier un Modèle Existant

cd OmniCRM-API/invoice_templates/
cp norfone_invoice_template.html your_company_invoice_template.html

Étape 2 : Personnaliser HTML/CSS

Modifiez your_company_invoice_template.html pour correspondre à votre branding :

Zones de Personnalisation Clés :

  1. Logo de l'Entreprise et Branding

    <!-- Remplacez par l'URL de votre logo -->
    <img src="https://yourcompany.com/logo.png" alt="Votre Entreprise" width="200">

    <!-- Mettez à jour le nom de l'entreprise -->
    <h1>Nom de Votre Entreprise</h1>

  2. Schéma de Couleurs

    <style>
        /* Couleur de marque principale */
        .navbar {
            background: linear-gradient(to bottom right, #your-color-1, #your-color-2);
        }

        /* En-têtes de tableau */
        .table thead th {
            background-color: #your-brand-color !important;
            color: white !important;
        }

        /* Boutons et liens */
        .btn-primary {
            background-color: #your-brand-color;
        }
    </style>

  3. Informations sur l'Entreprise dans le Pied de Page

    <footer>
        <p>Nom de Votre Entreprise</p>
        <p>123 Rue des Affaires, Ville, Pays</p>
        <p>Téléphone : +1-555-123-4567 | Email : billing@yourcompany.com</p>
        <p>ABN/ID Fiscal : 12345678900</p>
    </footer>

  4. Instructions de Paiement

    <div class="payment-info">
        <h3>Méthodes de Paiement</h3>
        <p><strong>En Ligne :</strong> Payez sur https://yourcompany.com/pay</p>
        <p><strong>Virement Bancaire :</strong></p>
        <ul>
            <li>Nom du Compte : Votre Entreprise Ltd</li>
            <li>BSB : 123-456</li>
            <li>Numéro de Compte : 987654321</li>
            <li>Référence : {{ invoice_number }}</li>
        </ul>
    </div>

  5. Conditions Générales

    <div class="terms">
        <h4>Conditions de Paiement</h4>
        <p>Paiement dû dans les 30 jours suivant la date de la facture.</p>
        <p>Frais de retard : 2% par mois sur les soldes en souffrance.</p>
        <p>Pour les questions de facturation : billing@yourcompany.com</p>
    </div>

Étape 3 : Mettre à Jour la Configuration

Modifiez OmniCRM-API/crm_config.yaml :

invoice:
  template_filename: 'your_company_invoice_template.html'

Étape 4 : Redémarrer l'API

cd OmniCRM-API
sudo systemctl restart omnicrm-api

Étape 5 : Tester la Génération de Factures

  1. Naviguez vers un client avec des transactions
  2. Générez une facture de test
  3. Téléchargez le PDF pour vérifier le formatage
  4. Envoyez la facture par e-mail à vous-même pour tester la livraison par e-mail

Personnalisation Avancée​

Contenu Conditionnel :

Utilisez des conditionnels Jinja2 pour afficher/masquer du contenu :

{% if total_amount > 1000 %}
    <div class="high-value-notice">
        <p><strong>Remarque :</strong> Solde élevé - Plan de paiement disponible sur demande.</p>
    </div>
{% endif %}

{% if client.address.country == "Australia" %}
    <p>GST Inclus : ${{ "%.2f"|format(total_amount * 0.10) }}</p>
{% endif %}

Support Multilingue :

Créez des modèles spécifiques à la langue :

invoice_template_en.html
invoice_template_es.html
invoice_template_fr.html

Configurez en fonction de la préférence linguistique du client.

Calculs Personnalisés :

<!-- Afficher le sous-total et le détail de la taxe -->
<tr>
    <td colspan="4" class="text-right"><strong>Sous-total :</strong></td>
    <td>${{ "%.2f"|format(total_amount) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Taxe :</strong></td>
    <td>${{ "%.2f"|format(total_tax) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Total :</strong></td>
    <td>${{ "%.2f"|format(total_amount + total_tax) }}</td>
</tr>

Remarque : La variable total_tax est automatiquement calculée en sommant le tax_amount de toutes les transactions dans la facture. Chaque taxe de transaction est calculée en fonction de son champ tax_percentage, qui par défaut est le tax_percentage du produit ou 0% si non spécifié.

QR Code pour le Paiement :

Générez un QR code pour le paiement mobile :

<div class="qr-payment">
    <img src="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data={{ payment_url }}"
         alt="Scannez pour Payer">
    <p>Scannez avec votre téléphone pour payer instantanément</p>
</div>

Meilleures Pratiques de Style PDF​

OmniCRM utilise WeasyPrint pour convertir HTML en PDF. Suivez ces directives :

CSS Supporté :

  • La plupart des propriétés CSS 2.1
  • CSS3 limité (flexbox, certaines transformations)
  • Polices Web via @font-face

Non Supporté :

  • JavaScript
  • CSS Grid (utilisez des tableaux à la place)
  • Animations complexes
  • Certaines propriétés CSS modernes

Taille de Page et Marges :

@page {
    size: A4;
    margin: 1cm;
}

body {
    font-family: Arial, sans-serif;
    font-size: 10pt;
}

Style Spécifique à l'Impression :

@media print {
    .no-print {
        display: none;
    }

    .page-break {
        page-break-after: always;
    }
}

Mise en Page des Tableaux :

.table {
    table-layout: fixed;
    width: 100%;
}

.table th, .table td {
    word-wrap: break-word;
    padding: 4px;
}

Intégration de Polices :

Pour des polices personnalisées, utilisez des polices sûres pour le Web ou intégrez :

@font-face {
    font-family: 'YourFont';
    src: url('https://yourcompany.com/fonts/yourfont.woff2') format('woff2');
}

body {
    font-family: 'YourFont', Arial, sans-serif;
}

Tester les Modèles de Facture​

Liste de Vérification de Test :

  1. Inspection Visuelle :
    • Le logo s'affiche correctement
    • Les couleurs correspondent aux directives de la marque
    • Le texte est lisible (pas trop petit)
    • Les tableaux sont correctement alignés
    • Toutes les sections sont présentes
  2. Exactitude des Données :
    • Détails du client corrects
    • Montants des transactions additionnés correctement
    • Dates formatées correctement
    • Toutes les variables substituées correctement
  3. Qualité du PDF :
    • Taille de fichier raisonnable (<5MB)
    • Images nettes et claires
    • Pas de texte coupé ou débordant
    • Sauts de page aux endroits appropriés
  4. Factures Multi-Page :
    • En-têtes se répètent sur chaque page
    • Numéros de page affichés
    • Longs listes de transactions paginées correctement
  5. Livraison par E-mail :
    • PDF attaché à l'e-mail
    • Taille de fichier sous la limite de Mailjet (15MB)
    • S'affiche dans Gmail, Outlook, Apple Mail

Commande de Test (Génération Manuelle) :

Vous pouvez tester la génération de factures via l'API :

curl -X GET "http://localhost:5000/crm/invoice/{invoice_id}/pdf" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     --output test_invoice.pdf

Problèmes Courants de Modèle​

Variables non substituées :

  • Cause : Fautes de frappe dans le nom de la variable ou données manquantes
  • Correction : Vérifiez l'orthographe exactement (sensible à la casse), vérifiez que les données existent dans la base de données

Le style PDF est cassé :

  • Cause : Propriété CSS non supportée
  • Correction : Utilisez des propriétés CSS 2.1, testez avec CSS compatible WeasyPrint

Les images ne s'affichent pas :

  • Cause : URL relatives ou ressources externes bloquées
  • Correction : Utilisez des URL HTTPS absolues, assurez-vous que les images sont accessibles publiquement

Les tableaux débordent de la page :

  • Cause : Largeurs de colonnes fixes trop larges
  • Correction : Utilisez des largeurs en pourcentage, table-layout: fixed

Les polices ne s'affichent pas :

  • Cause : Police non intégrée ou indisponible
  • Correction : Utilisez des polices sûres pour le Web (Arial, Times New Roman, etc.) ou intégrez correctement des polices personnalisées

La génération de PDF échoue :

  • Cause : Erreurs de syntaxe HTML ou plantage de WeasyPrint
  • Correction : Validez HTML, vérifiez les journaux de WeasyPrint, simplifiez des mises en page complexes

Mise en Cache des PDF de Factures​

Pour améliorer les performances et réduire la génération redondante de PDF, OmniCRM inclut un système de mise en cache des PDF de factures. Lorsqu'un PDF de facture est généré pour la première fois, il est mis en cache dans la base de données pour les demandes ultérieures.

Comment Fonctionne la Mise en Cache des PDF :

  1. Première Demande - Lorsqu'un PDF de facture est demandé (téléchargement ou e-mail), le système :
    • Génère le PDF à partir du modèle de facture
    • Encode le PDF en Base64
    • Calcule un hash SHA256 du contenu du PDF
    • Stocke dans la table Invoice_PDF_Cache avec :
      • Référence de l'ID de la facture
      • Données PDF (encodées en Base64)
      • Nom de fichier
      • Hash de contenu (pour vérification d'intégrité)
      • Horodatage de création
  2. Demandes Suivantes - Lorsque la même facture est demandée à nouveau :
    • Le système vérifie le PDF mis en cache par invoice_id
    • Si le cache existe et est valide, renvoie immédiatement le PDF mis en cache
    • Met à jour l'horodatage last_accessed pour suivre l'utilisation du cache
  3. Invalidation du Cache - Les PDF mis en cache sont invalidés lorsque :
    • La facture est modifiée (transactions ajoutées/enlevées, détails changés)
    • Le modèle de facture est mis à jour
    • Un effacement manuel du cache est déclenché

Avantages :

  • Performance - Livraison instantanée de PDF pour les demandes répétées (pas de délai de régénération)
  • Cohérence - Même PDF pour tous les téléchargements d'une facture (sauf si la facture est modifiée)
  • Charge Serveur - Réduit l'utilisation du CPU pour la génération de PDF
  • Expérience Utilisateur - Un indicateur de chargement apparaît lors de la génération initiale, les demandes suivantes sont instantanées

Gestion du Cache :

Le Cache PDF de Facture est automatiquement géré par le système. Les anciennes ou entrées de cache inutilisées peuvent être purgées périodiquement en fonction de :

  • Âge (par exemple, supprimer les entrées de cache de plus de 90 jours)
  • Modèles d'accès (supprimer les entrées non accédées dans les 30 jours)
  • Limites de stockage (implémenter des limites de taille de cache si nécessaire)

Comportement de l'API :

Lors du téléchargement d'une facture via l'API ou l'UI :

  • Première demande : Affiche un indicateur de chargement pendant que le PDF se génère, puis met en cache
  • Demandes suivantes : Téléchargement immédiat depuis le cache
  • Le hit/miss de cache est transparent pour l'utilisateur

Important : Lorsque vous mettez à jour votre modèle de facture, videz le cache pour vous assurer que les nouvelles factures utilisent le design mis à jour :

-- Vider tous les PDF de factures mis en cache (exécuter dans MySQL)
DELETE FROM Invoice_PDF_Cache;

Ou mettez à jour crm_config.yaml pour invalider automatiquement le cache lors du changement de modèle.

Accéder aux Factures​

Les factures peuvent être consultées au niveau du système ou par client :

Vue par Client :

  1. Naviguez vers Clients → [Sélectionner Client]
  2. Cliquez sur l'onglet Facturation
  3. Consultez la liste des factures dans la troisième carte

Vue Système :

  1. Naviguez vers Facturation → Factures (depuis le menu principal)
  2. Consultez toutes les factures de tous les clients

Widgets de Statistiques de Factures​

En haut de la page des factures, quatre cartes statistiques affichent des résumés financiers.

Statistiques de Factures et Liste{.align-center width="800px"}

Descriptions des Widgets :

  • Total des Factures - Somme de tous les coûts de détail des factures (tous les temps) et nombre de factures envoyées
  • Factures Impayées - Somme des factures non encore payées et nombre de factures impayées
  • Factures de Ce Mois - Somme des factures créées ce mois calendaire avec le compte
  • Factures du Mois Dernier - Somme des factures créées le mois calendaire dernier avec le compte

Formatage des Valeurs :

  • Valeurs supérieures à 1 000 : Afficher avec suffixe "k" (par exemple, $1.5k)
  • Valeurs supérieures à 1 000 000 : Afficher avec suffixe "M" (par exemple, $2.3M)
  • Valeurs supérieures à 1 000 000 000 : Afficher avec suffixe "B" (par exemple, $1.1B)

Indicateurs de Tendance :

  • Widgets pour "Ce Mois" et "Le Mois Dernier" montrent le pourcentage de changement
  • Flèche verte vers le haut : Augmentation par rapport à la période précédente
  • Flèche rouge vers le bas : Diminution par rapport à la période précédente
  • Flèche grise vers la droite : Pas de changement

Liste des Factures​

Le tableau des factures affiche toutes les factures avec les colonnes suivantes :

Liste des Factures Globales

Descriptions des Colonnes :

  • ID - ID unique de la facture
  • Titre - Titre/description de la facture
  • Période - Période de facturation (date de début - date de fin) ou "N/A" pour factures uniques
  • Date d'Échéance - Date d'échéance de paiement
  • Créé - Date de création de la facture
  • Montant - Montant total de la facture (coût de détail)
  • Statut - Payé, Impayé ou Remboursé
  • Actions - Actions disponibles (varie selon le statut)

Icônes d'Action :

  • ⬇ (Télécharger) - Télécharger le PDF de la facture
  • 🗑️ (Supprimer) - Annuler la facture (uniquement si non payée)
  • 💰 (Payer) - Payer la facture en ligne (uniquement si impayée)
  • ✉️ (E-mail) - Envoyer l'e-mail de la facture au client
  • 💸 (Rembourser) - Rembourser le paiement Stripe (uniquement pour les factures Stripe payées)

Générer une Facture​

Cliquez sur "+ Générer une Facture Proforma" pour créer une nouvelle facture.

Modal de Génération de Facture avec Aperçu de Transaction{.align-center width="800px"}

Descriptions des Champs :

  • Rechercher des Clients - Sélectionnez un client (uniquement affiché dans la vue système, pré-rempli dans la vue client)
  • Titre - Titre/nom de la facture (optionnel, par défaut "Facture pour [Période]")
  • Date de Début - Début de la période de facturation (par défaut 14 jours auparavant)
  • Date de Fin - Fin de la période de facturation (par défaut aujourd'hui)
  • Date d'Échéance - Date limite de paiement (par défaut aujourd'hui)
  • Aperçu de la Transaction - Affiche toutes les transactions non facturées dans la plage de dates avec la possibilité d'inclure/exclure des transactions spécifiques

Sélection de Transaction :

  • ✓ (Plus Vert) - Cliquez pour exclure une transaction de la facture
  • × (X Rouge) - Cliquez pour inclure une transaction précédemment exclue
  • Tout Sélectionner - Inclure toutes les transactions affichées
  • Tout Effacer - Exclure toutes les transactions
  • Les transactions exclues apparaissent grises avec un texte barré
  • Les totaux se mettent à jour en temps réel lorsque vous sélectionnez/désélectionnez des transactions

Ce Qui Se Passe :

  1. Le système trouve toutes les transactions non facturées pour le client dans la plage de dates
  2. Affiche l'aperçu des transactions avec la possibilité d'inclure/exclure des transactions individuelles
  3. Montre le calcul en temps réel du sous-total, de la taxe et du total basé sur les transactions sélectionnées
  4. Seules les transactions sélectionnées (incluses) sont ajoutées à la facture
  5. Génère le PDF de la facture et le met en cache
  6. Marque les transactions sélectionnées comme facturées (champ invoice_id peuplé)
  7. Les transactions exclues restent non facturées et disponibles pour de futures factures
  8. La facture apparaît dans la liste avec le statut "Impayé"

Exemples de Cas d'Utilisation :

Facturation Mensuelle : Définissez la date de début au premier du mois, la date de fin au dernier jour du mois, l'aperçu montre toutes les transactions non facturées de cette période. Sélectionnez tout ou excluez manuellement des transactions spécifiques.

Facture Spécifique au Service : Utilisez la même plage de dates, puis excluez manuellement les transactions non désirées (par exemple, excluez les transactions non mobiles pour créer une facture uniquement mobile).

Facture Unique : Définissez à la fois la date de début et la date de fin au même jour, l'aperçu montre uniquement les transactions de cette date. Excluez les frais non pertinents pour cette facture spécifique.

Voir les Détails de la Facture​

Cliquez sur n'importe quelle ligne de facture dans le tableau pour voir les détails complets de la facture y compris toutes les transactions, totaux et actions disponibles.

Vue des Détails de la Facture{.align-center width="800px"}

Modal des Détails de la Facture :

  • Informations sur la Facture - Affiche l'ID de la facture, le titre, les dates, le statut de paiement et le statut d'annulation
  • Liste des Transactions - Affiche toutes les transactions incluses dans la facture avec :
    • Date de la transaction
    • Titre et description
    • Coût de détail
    • Montant et pourcentage de taxe (formaté comme $10.00 (10%))
    • Les transactions exonérées de taxe affichent "-" dans la colonne Taxe
  • Résumé des Totaux - Calcul en temps réel montrant :
    • Nombre de transactions
    • Sous-total (somme de tous les coûts de détail)
    • Taxe (somme de tous les montants de taxe)
    • Total de la Facture (sous-total + taxe)
  • Boutons d'Action - Les mêmes actions disponibles que dans le tableau :
    • Télécharger PDF - Télécharger le PDF de la facture (toujours disponible)
    • Envoyer un E-mail - E-mail de la facture au client (factures non annulées)
    • Payer la Facture - Traiter le paiement (factures impayées, non annulées uniquement)
    • Rembourser - Rembourser le paiement Stripe (uniquement pour les factures Stripe payées)
    • Supprimer - Annuler la facture (factures impayées, non annulées uniquement)

Télécharger les PDFs de Factures​

Cliquez sur l'icône de téléchargement (⬇) dans le tableau ou sur le bouton "Télécharger PDF" dans le modal des détails de la facture pour télécharger une facture au format PDF.

Processus de Téléchargement :

  1. Cliquez sur l'icône de téléchargement à côté de la facture
  2. Un indicateur de chargement apparaît pendant la génération (la première fois seulement)
  3. Le navigateur invite à enregistrer le fichier : Invoice_01234.pdf
  4. Le PDF s'ouvre ou est enregistré dans le dossier Téléchargements

Comportement de Mise en Cache des PDF :

  • Premier Téléchargement - PDF généré à partir du modèle, mis en cache dans la base de données (peut prendre 2-3 secondes)
  • Téléchargements Suivants - Téléchargement instantané depuis le cache
  • Invalidation du Cache - Cache vidé si la facture est modifiée ou le modèle mis à jour

Résolution des Problèmes de Téléchargement :

  • L'indicateur de chargement ne s'arrête jamais - Vérifiez la console du navigateur, l'API peut être hors service
  • PDF vide ou corrompu - Vérifiez le modèle de facture pour des erreurs de syntaxe
  • Le téléchargement échoue - Vérifiez les paramètres du bloqueur de fenêtres contextuelles, essayez un autre navigateur

Payer des Factures​

Cliquez sur l'icône de paiement (💰) pour payer une facture en ligne.

Modal de Paiement de Facture{.align-center width="800px"}

Processus de Paiement :

  1. Cliquez sur l'icône de paiement sur la facture impayée
  2. Le modal de paiement s'ouvre montrant les détails de la facture
  3. Sélectionnez le mode de paiement :
    • Transaction Stripe - Facturer la carte de crédit enregistrée (disponible pour tous les utilisateurs)
    • Espèces - Paiement en espèces manuel (personnel uniquement)
    • Remboursement - Appliquer un remboursement comme paiement (personnel uniquement)
    • Transaction POS - Terminal de point de vente (personnel uniquement)
    • Virement Bancaire - Virement bancaire manuel (personnel uniquement)
  4. Si Stripe est sélectionné :
    • Sélectionnez une carte parmi les méthodes de paiement enregistrées
    • La carte par défaut est pré-sélectionnée
    • Cliquez pour sélectionner une carte différente
  5. Si une autre méthode est sélectionnée :
    • Entrez le numéro de référence (optionnel)
  6. Cliquez sur "Payer la Facture" pour traiter
  7. Le système traite le paiement :
    • Stripe - Charge la carte via l'API Stripe
    • Autres méthodes - Crée une transaction négative pour le montant du paiement
  8. Le statut de la facture change en "Payée"
  9. Notification de succès affichée

Self-Care vs Paiement du Personnel :

:doc:`Portail Self-Care <self_care_portal>` (Clients) :

  • Seul le paiement Stripe est disponible
  • Doit avoir une méthode de paiement enregistrée
  • Avertissement affiché si aucune méthode de paiement n'existe
  • Lien pour ajouter une méthode de paiement fourni

Portail du Personnel (Administrateurs) :

  • Tous les modes de paiement disponibles
  • Peut marquer la facture comme payée manuellement (espèces, POS, virement bancaire)
  • Peut entrer des numéros de référence pour le suivi

Avertissement sur les Méthodes de Paiement :

Si le client n'a pas de méthodes de paiement enregistrées, un avertissement est affiché l'invitant à ajouter une méthode de paiement avant de pouvoir payer des factures.

Avertissement de Méthode de Paiement Manquante{.align-center width="800px"}

E-mail des Factures​

Cliquez sur l'icône d'e-mail (✉️) pour envoyer la facture au client.

Ce Qui Se Passe :

  1. Cliquez sur l'icône d'e-mail à côté de la facture
  2. Le système récupère le PDF de la facture depuis le cache (ou génère s'il n'est pas mis en cache)
  3. Envoie l'e-mail via Mailjet en utilisant le modèle api_crmCommunicationCustomerInvoice
  4. L'e-mail inclut :
    • PDF de la facture en pièce jointe
    • Nom du client
    • Numéro de facture et date d'échéance
    • Montant total dû
    • Lien pour payer la facture en ligne
    • Lien pour voir/télécharger la facture
  5. Notification de succès : "E-mail de facture envoyé avec succès"

Destinataires de l'E-mail :

L'e-mail est envoyé à tous les contacts clients avec le type "facturation" ou au contact principal si aucun contact de facturation n'existe.

Variables de Modèle d'E-mail :

  • {{ var:customer_name }} - Nom complet du client
  • {{ var:invoice_number }} - ID de la facture
  • {{ var:invoice_date }} - Date d'émission de la facture
  • {{ var:due_date }} - Date d'échéance de paiement
  • {{ var:total_amount }} - Montant total dû
  • {{ var:invoice_url }} - Lien pour voir/télécharger le PDF
  • {{ var:pay_url }} - Lien pour payer la facture en ligne

Résolution des Problèmes d'E-mail :

  • E-mail non envoyé - Vérifiez les identifiants API Mailjet dans crm_config.yaml
  • Client ne reçoit pas - Vérifiez les adresses e-mail des contacts clients
  • PDF non attaché - Vérifiez que la génération du PDF a réussi (essayez de télécharger d'abord)

Annuler des Factures​

Cliquez sur l'icône de suppression (🗑️) pour annuler une facture.

Exigences :

  • La facture doit être Impayée
  • Les factures payées ne peuvent pas être annulées (doivent être remboursées à la place)

Comment Annuler :

  1. Localisez la facture impayée dans la liste
  2. Cliquez sur l'icône de suppression (🗑️)
  3. Confirmez dans le modal :

Modal de Confirmation d&#39;Annulation de Facture{.align-center width="600px"}

Ce Qui Se Passe :

  • La facture est marquée comme void = true
  • Toutes les transactions sont dissociées de la facture (invoice_id défini sur null)
  • Les transactions redeviennent "non facturées"
  • Les transactions peuvent être incluses dans une nouvelle facture
  • La facture apparaît dans la liste avec le préfixe "Annulé:" dans le titre
  • Les actions de la facture sont désactivées (pas de téléchargement, paiement ou e-mail)
  • Peut être consultée en filtrant pour les factures "Annulées"

Remarques Importantes :

  • Annuler n'est PAS la même chose que rembourser
  • Annuler = "Cette facture n'aurait jamais dû exister" (erreur de facturation, doublon)
  • Rembourser = "Inverser une facture valide payée" (retour d'argent au client)

Rembourser des Factures​

Cliquez sur l'icône de remboursement (💸) pour rembourser une facture payée.

Exigences :

  • La facture doit être Payée
  • La facture doit avoir été payée via Stripe
  • La facture doit avoir une payment_reference valide (ID d'intention de paiement Stripe)
  • Disponible uniquement pour les utilisateurs du personnel (pas de Self-Care)

Comment Rembourser :

  1. Localisez la facture Stripe payée
  2. Cliquez sur l'icône de remboursement (💸)
  3. Le modal de confirmation de remboursement s'ouvre :

Modal de Confirmation de Remboursement de Facture{.align-center width="800px"}

  1. Cliquez sur "Confirmer le Remboursement"
  2. Le système traite le remboursement Stripe :
    • Appelle l'API Stripe pour rembourser le paiement
    • Crée une transaction de remboursement dans Stripe
    • Met à jour la facture avec refund_reference
  3. Le statut de la facture change en "Remboursée"
  4. Notification de succès affichée

Ce Qui Se Passe Après le Remboursement :

  • La facture reste dans le système (non annulée)
  • Le statut affiche "Remboursée"
  • Les transactions restent liées à la facture
  • Le client reçoit un remboursement sur le mode de paiement d'origine (3-7 jours ouvrables)
  • Le tableau de bord Stripe affiche la transaction de remboursement

Restrictions de Remboursement :

  • Ne peut pas rembourser les factures payées par espèces, POS ou virement bancaire (inversion manuelle requise)
  • Ne peut pas rembourser partiellement (montant total de la facture uniquement)
  • Ne peut pas rembourser deux fois

Recherche et Filtrage des Factures​

Recherche​

Utilisez la barre de recherche pour trouver des factures. Recherche dans :

  • ID de la facture
  • Titre de la facture
  • Nom du client (vue système uniquement)

Filtres​

Appliquez des filtres pour affiner la liste des factures :

Filtres Disponibles :

  • Statut d'Annulation - Tout, Annulé, Non Annulé
  • Statut de Paiement - Tout, Payé, Pas encore Payé

Actions de Filtre :

  • Appliquer les Filtres - Appliquer les filtres sélectionnés à la liste
  • Réinitialiser les Filtres - Effacer tous les filtres et afficher toutes les factures

Tri​

Cliquez sur n'importe quel en-tête de colonne pour trier :

  • ID - Trier par ID de facture (le plus récent/le plus ancien)
  • Titre - Trier par ordre alphabétique
  • Date d'Échéance - Trier par date d'échéance
  • Créé - Trier par date de création
  • Montant - Trier par coût de détail (le plus élevé/le plus bas)
  • Statut - Trier par statut de paiement (payé en premier ou impayé en premier)

Cliquez à nouveau pour inverser la direction du tri (ascendant ↔ descendant).

Pagination​

Naviguez à travers de grandes listes de factures avec des contrôles de page affichant la page actuelle, le nombre total de pages et un sélecteur d'éléments par page (10, 25, 50 ou 100 éléments).

Flux de Travail Courants des Factures​

Flux de Travail 1 : Facturation Mensuelle avec Aperçu des Transactions​

  1. La fin du mois arrive (par exemple, 31 janvier)
  2. Naviguez vers Facturation → Factures
  3. Cliquez sur "+ Générer une Facture Proforma"
  4. Sélectionnez un client (ou faites-le par client si vous facturez de nombreux clients)
  5. Définissez les dates :
    • Date de Début : 2025-01-01
    • Date de Fin : 2025-01-31
    • Date d'Échéance : 2025-02-15 (15 jours à partir de maintenant)
    • Titre : "Services de Janvier 2025" (optionnel)
  6. La section Aperçu des Transactions apparaît montrant toutes les transactions non facturées de janvier
  7. Vérifiez l'aperçu :
    • Toutes les transactions sont incluses par défaut
    • Vérifiez les totaux : Sous-total, Taxe et Total de la Facture
    • Vérifiez que tous les frais sont corrects
  8. Cliquez sur "Générer la Facture" (le bouton affiche le nombre de transactions, par exemple, "Générer la Facture (15)")
  9. Facture créée avec toutes les transactions sélectionnées
  10. Cliquez sur la ligne de la facture pour voir les détails et vérifier
  11. Cliquez sur le bouton "Envoyer un E-mail" dans le modal de détails ou sur l'icône d'e-mail dans le tableau
  12. Le client reçoit un e-mail de facture avec le PDF et le lien de paiement

Flux de Travail 2 : Facturation Sélective des Transactions​

  1. Le client a plusieurs services (Mobile + Internet) et des frais divers
  2. Souhaite des factures séparées pour chaque service
  3. Générer la première facture (Services Mobiles) :
    • Cliquez sur "+ Générer une Facture Proforma"
    • Titre : "Services Mobiles - Janvier 2025"
    • Début/Fin : Jan 1-31
    • Date d'Échéance : Février 15
    • Dans l'aperçu des transactions, excluez toutes les transactions non mobiles :
      • Cliquez sur le bouton X à côté des transactions Internet
      • Cliquez sur le bouton X à côté des frais divers
      • Seules les transactions de services mobiles restent sélectionnées
    • Vérifiez que les totaux reflètent uniquement les services mobiles
    • Cliquez sur "Générer la Facture" (affiche le nombre de transactions mobiles)
  4. Générer la deuxième facture (Services Internet) :
    • Cliquez à nouveau sur "+ Générer une Facture Proforma"
    • Titre : "Services Internet - Janvier 2025"
    • Début/Fin : Jan 1-31 (même période)
    • Dans l'aperçu des transactions :
      • Les transactions mobiles ont déjà été facturées (n'apparaissent pas)
      • Excluez les frais divers en utilisant le bouton X
      • Seules les transactions de services Internet restent
    • Cliquez sur "Générer la Facture"
  5. Générer la troisième facture (Frais Supplémentaires) :
    • Cliquez à nouveau sur "+ Générer une Facture Proforma"
    • Titre : "Frais Supplémentaires - Janvier 2025"
    • Seuls les frais divers non facturés apparaissent dans l'aperçu
    • Cliquez sur "Tout Sélectionner" pour inclure tout
    • Cliquez sur "Générer la Facture"
  6. Envoyez les trois factures au client

Flux de Travail 3 : Exclure les Transactions Contestées ou en Attente​

  1. La fin de la période de facturation arrive
  2. Naviguez vers l'onglet Facturation du client
  3. Cliquez sur "+ Générer une Facture Proforma"
  4. Définissez les dates de la période de facturation
  5. L'aperçu des transactions montre 20 transactions
  6. Le client a contesté un frais et un autre est en attente d'enquête
  7. Dans l'aperçu des transactions :
    • Localisez la transaction contestée (par exemple, "Frais de dépassement de données")
    • Cliquez sur le bouton X pour l'exclure
    • Localisez la transaction en attente (par exemple, "Frais d'installation")
    • Cliquez sur le bouton X pour l'exclure
    • Le nombre de transactions se met à jour : "18 Transactions sélectionnées"
    • Les totaux se recalculent automatiquement
  8. Vérifiez les totaux mis à jour (exclut les montants contestés)
  9. Cliquez sur "Générer la Facture (18)"
  10. Facture générée avec uniquement les transactions approuvées
  11. Les transactions contestées/en attente restent non facturées pour le prochain cycle de facturation

Flux de Travail 4 : Révision Rapide de la Facture et Ajustement​

  1. Le personnel génère la facture mensuelle
  2. L'aperçu des transactions montre un total élevé inattendu
  3. Vérifiez chaque transaction dans l'aperçu :
    • Remarquez un frais dupliqué pour le même service
    • Cliquez sur X pour exclure le duplicata
    • Remarquez une transaction de test qui ne devrait pas être facturée
    • Cliquez sur X pour exclure la transaction de test
  4. Les totaux se mettent à jour en temps réel
  5. Vérifiez que le nouveau total correspond au montant attendu
  6. Cliquez sur "Générer la Facture" avec les transactions corrigées
  7. Revenez en arrière et annulez/supprimez les transactions exclues si nécessaire
  8. Envoyez la facture au client en toute confiance

Flux de Travail 5 : Facture d'Installation Unique​

  1. Le technicien de terrain termine l'installation
  2. Le personnel ajoute manuellement la transaction d'installation
  3. Naviguez vers l'onglet Facturation du client
  4. Cliquez sur "+ Générer une Facture Proforma"
  5. Définissez les dates :
    • Date de Début : aujourd'hui
    • Date de Fin : aujourd'hui
    • Date d'Échéance : aujourd'hui + 7 jours
    • Titre : "Services d'Installation"
  6. L'aperçu des transactions montre uniquement les transactions d'aujourd'hui
  7. Vérifiez que le frais d'installation apparaît
  8. Excluez tous les frais récurrents en utilisant le bouton X (s'ils sont présents)
  9. Cliquez sur "Générer la Facture"
  10. Envoyez immédiatement au client
  11. Le client paie en ligne via Stripe

Flux de Travail 6 : Révision de la Facture Avant le Contact Client​

  1. Le client appelle avec une question de facturation
  2. Le personnel navigue vers la liste des factures du client
  3. Cliquez sur la ligne de la facture pour ouvrir le modal des Détails de la Facture
  4. Vérifiez les informations de la facture :
    • ID de la facture, dates, statut
    • Toutes les transactions incluses avec descriptions
    • Détail de la taxe par transaction
    • Sous-total, Taxe et Montants Totaux
  5. Répondez aux questions du client avec des détails exacts
  6. Si le client demande le PDF, cliquez sur le bouton "Télécharger PDF" dans le modal
  7. Si le client demande un renvoi d'e-mail, cliquez sur le bouton "Envoyer un E-mail"
  8. Fermez le modal lorsque vous avez terminé

Flux de Travail 7 : Correction d'une Erreur de Facturation​

  1. Le client signale un frais incorrect
  2. Le personnel clique sur la ligne de la facture pour voir les détails
  3. Vérifie la liste des transactions dans le modal des Détails de la Facture
  4. Identifie la transaction incorrecte
  5. La facture est impayée, donc peut être annulée
  6. Cliquez sur le bouton "Supprimer" dans le pied de modal
  7. Confirmez l'annulation
  8. Les transactions redeviennent non facturées
  9. Le personnel modifie ou supprime la transaction incorrecte de la liste des transactions
  10. Générez une nouvelle facture avec les transactions corrigées :
    • Utilisez l'aperçu des transactions pour exclure la transaction corrigée si nécessaire
    • Incluez uniquement les frais valides
  11. Envoyez la facture corrigée au client

Flux de Travail 8 : Traitement de Plusieurs Paiements​

  1. Le client apporte de l'argent pour payer plusieurs factures
  2. Naviguez vers l'onglet Facturation du client
  3. Consultez les factures impayées
  4. Cliquez sur la première ligne de facture pour voir les détails
  5. Vérifiez le montant et les transactions
  6. Cliquez sur le bouton "Payer la Facture" dans le pied de modal
  7. Sélectionnez le mode de paiement "Espèces"
  8. Entrez la référence : "Espèces payées 2025-01-15"
  9. Cliquez sur "Payer la Facture"
  10. Le modal se ferme, la facture est marquée comme "Payée"
  11. Répétez pour les factures restantes
  12. Toutes les factures sont maintenant marquées comme "Payées"

Flux de Travail 9 : Gestion d'une Demande de Remboursement​

  1. Le client demande un remboursement pour un trop-payé
  2. Le personnel vérifie que la facture a été payée via Stripe
  3. Naviguez vers la facture dans la liste
  4. Cliquez sur la ligne de la facture pour voir les détails
  5. Vérifiez les informations de paiement et le montant
  6. Cliquez sur le bouton "Rembourser" dans le pied de modal (n'apparaît que pour les factures Stripe)
  7. Confirmez le remboursement
  8. Le système traite le remboursement Stripe
  9. Le statut de la facture change en "Remboursée"
  10. Le client reçoit un remboursement dans les 3 à 7 jours ouvrables
  11. Le personnel suit avec le client pour confirmer la réception

Résolution des Problèmes​

Impossible de générer la facture - Aucune transaction trouvée

  • Cause : Aucune transaction non facturée dans la plage de dates spécifiée
  • Correction : Vérifiez la liste des transactions, vérifiez que les transactions existent et ne sont pas déjà facturées. Ajustez la plage de dates ou retirez le filtre.

Échec de la génération du PDF de la facture

  • Cause : Erreur de syntaxe dans le modèle, plantage de WeasyPrint ou données client manquantes
  • Correction : Vérifiez le HTML du modèle de facture pour des erreurs, vérifiez que les champs d'adresse du client sont peuplés, examinez les journaux de l'API.

Échec de paiement avec erreur Stripe

  • Cause : Carte refusée, fonds insuffisants, carte expirée ou problème avec l'API Stripe
  • Correction : Essayez un autre mode de paiement, vérifiez que la carte est valide, consultez le tableau de bord Stripe pour connaître la raison du refus.

Impossible d'annuler la facture

  • Cause : La facture est déjà payée
  • Correction : Les factures payées ne peuvent pas être annulées. Si un remboursement est nécessaire, utilisez la fonction de remboursement pour les factures Stripe ou créez une transaction de crédit manuellement.

E-mail de facture non envoyé

  • Cause : Identifiants API Mailjet invalides, le client n'a pas de contact de facturation, ou modèle d'e-mail manquant
  • Correction : Vérifiez la configuration de Mailjet dans crm_config.yaml, vérifiez les contacts clients, vérifiez que le modèle d'e-mail de facture existe.

Le bouton de remboursement n'apparaît pas

  • Cause : Facture payée par espèces/POS/virement bancaire (pas Stripe), ou facture non payée
  • Correction : Le bouton de remboursement n'apparaît que pour les paiements Stripe. Pour d'autres modes de paiement, créez une transaction de crédit manuelle.

Le téléchargement du PDF montre l'ancien design du modèle

  • Cause : PDF mis en cache avant la mise à jour du modèle
  • Correction : Videz le cache PDF de la facture : DELETE FROM Invoice_PDF_Cache WHERE invoice_id = X;

Le client ne peut pas payer la facture (pas de méthodes de paiement)

  • Cause : Aucune méthode de paiement enregistrée dans le portail Self-Care
  • Correction : Le client doit ajouter une carte de crédit à la page Méthodes de Paiement avant de payer des factures.

Plusieurs factures générées pour la même période

  • Cause : Le personnel a généré la facture deux fois, ou les plages de dates se chevauchent
  • Correction : Annulez la facture en double. Ajustez les plages de dates pour éviter le chevauchement. Utilisez l'aperçu des transactions pour garantir des ensembles de transactions uniques.

L'aperçu des transactions ne montre aucune transaction

  • Cause : Toutes les transactions dans la plage de dates ont déjà été facturées ou aucune transaction n'existe
  • Correction : Vérifiez que la plage de dates est correcte. Vérifiez la liste des transactions pour confirmer que les transactions existent. Filtrez les factures pour voir quelle facture contient les transactions.

Impossible d'exclure une transaction de la génération de facture

  • Cause : La transaction a déjà été facturée ou problème de navigateur
  • Correction : Vérifiez que la transaction s'affiche dans l'aperçu avec une coche. Rafraîchissez la page et réessayez. Effacez le cache du navigateur si le problème persiste.

Le total de la facture ne correspond pas au montant attendu

  • Cause : Transactions inattendues incluses, taxe non calculée, ou transactions exclues comptées
  • Correction : Examinez attentivement l'aperçu des transactions. Vérifiez le coût de détail et la taxe de chaque transaction. Vérifiez que les transactions exclues sont grises. Vérifiez le badge de nombre de transactions sur le bouton Générer la Facture.

Le bouton Générer la Facture est désactivé

  • Cause : Aucune transaction sélectionnée ou plage de dates invalide
  • Correction : Assurez-vous qu'au moins une transaction est incluse (pas exclue). Vérifiez que la Date de Début est avant la Date de Fin. Vérifiez que la Date d'Échéance est définie.

Le modal des Détails de la Facture ne s'ouvre pas

  • Cause : Erreur JavaScript ou page non complètement chargée
  • Correction : Rafraîchissez la page. Vérifiez la console du navigateur pour des erreurs. Essayez un autre navigateur. Vérifiez la connexion Internet.

La taxe de transaction ne s'affiche pas dans les Détails de la Facture

  • Cause : La transaction a un taux de taxe de 0% ou tax_amount est nul
  • Correction : Vérifiez que la transaction a un tax_percentage défini. Vérifiez que tax_amount a été calculé lorsque la transaction a été créée. Mettez à jour la transaction si nécessaire.

Les boutons d'action manquent dans le modal des Détails de la Facture

  • Cause : La facture est annulée ou l'utilisateur n'a pas les autorisations
  • Correction : Les factures annulées n'affichent que le bouton Télécharger PDF. Vérifiez le statut de la facture. Vérifiez le rôle et les autorisations de l'utilisateur.

Documentation Connexe​

  • integrations_mailjet - Livraison et modèles d'e-mail de facture
  • administration_configuration - Configuration du modèle de facture
  • payments_transaction - Création de transactions qui apparaissent sur les factures
  • payments_process - Traitement des paiements de factures
  • basics_payment - Méthodes de paiement et intégration Stripe