Facturia est une application web de facturation mono-entreprise destinée aux marchés UEMOA (Afrique de l'Ouest, devise FCFA / XOF). Elle couvre la gestion des clients, des produits/services, l'émission de factures avec TVA, la génération de PDF (plusieurs modèles), un tableau de bord analytique et une API REST.
- Clients, produits/services, factures multi-lignes avec TVA par ligne et ventilation par taux.
- Numérotation séquentielle par année, finalisation atomique, immuabilité des factures émises (snapshot émetteur/client).
- PDF conforme (mentions légales UEMOA) avec 3 modèles sélectionnables et extensibles.
- Tableau de bord (CA, en attente, en retard, top produits…).
- API REST (Django REST Framework).
- Interface en français, identifiant fiscal configurable (NINEA, IFU…).
| Tableau de bord | Facture (détail) |
|---|---|
 |
 |
| Éditeur de facture (totaux en direct) | PDF (modèle Éditorial) |
 |
 |
Captures réalisées sur un jeu de données de démonstration fictif.
| Composant | Version |
|---|---|
| Python | 3.12 (3.13 fonctionne en local) |
| Django | 5.2.x (LTS) |
| Django REST Framework | 3.17.x |
| WeasyPrint | 66.0 |
| Tailwind CSS | v3.4.17 (CLI standalone) |
| Alpine.js | 3.x (auto-hébergé, static/js/alpine.min.js) |
| Base de données | PostgreSQL 16 (prod) / SQLite (dev) |
WeasyPrint a besoin de Pango (rendu des PDF).
brew install pango
brew install python@3.12sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0 \
libpq-dev fonts-dejavu-core fonts-liberationWeasyPrint dépend de bibliothèques GTK / Pango, parfois délicates à installer nativement sur Windows. Par ordre de simplicité :
- WSL2 (recommandé) : installez WSL2 + Ubuntu, puis suivez les instructions Linux ci-dessus à l'intérieur de votre distribution.
- Docker :
docker compose up --build(voir Docker) — aucune dépendance native à installer. - Installation native (avancé) :
- Installez Python 3.12 (python.org). Créez le venv avec
py -3.12 -m venv .venvpuis activez-le :.venv\Scripts\activate. - Installez le runtime GTK requis par WeasyPrint — voir la doc officielle : https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#windows.
- Binaire Tailwind : téléchargez
tailwindcss-windows-x64.exedepuis les releases tailwindlabs/tailwindcss et renommez-letailwindcss.exe. - Le reste (
pip install,migrate,runserver) est identique — utilisezpython/.venv\Scripts\python.
- Installez Python 3.12 (python.org). Créez le venv avec
# macOS Apple Silicon
curl -sLo tailwindcss https://github.com/tailwindlabs/tailwindcss/releases/download/v3.4.17/tailwindcss-macos-arm64
# Linux x64
curl -sLo tailwindcss https://github.com/tailwindlabs/tailwindcss/releases/download/v3.4.17/tailwindcss-linux-x64
chmod +x tailwindcssPlacez le binaire à la racine du dépôt (déjà gitignored).
git clone <url-du-repo> facturia && cd facturia
python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env # ajuster selon votre environnement
python manage.py migrate
python manage.py createsuperuser
# Compiler le CSS (watch en dev, --minify en prod)
./tailwindcss -c theme/tailwind.config.js -i theme/input.css -o static/css/app.css --watch
python manage.py runserver # http://127.0.0.1:8000/- Se connecter sur
/accounts/login/avec le superutilisateur créé. - Compléter les paramètres sur
/settings/: raison sociale, adresse, identifiant fiscal (NINEA/IFU) et RCCM (facultatifs), devise, taux de TVA, délai de paiement, et le modèle de facture (PDF). - Créer des clients, des produits/services, puis des factures.
Le PDF utilise WeasyPrint. Trois modèles sont fournis (Éditorial,
Classique, Minimal) et choisis dans /settings/. Pour en ajouter un :
créez templates/billing/pdf/<clé>.html (un simple habillage CSS au-dessus du
corps partagé _invoice_body.html) et déclarez-le dans billing/pdf_templates.py.
Téléchargement : /invoices/<id>/pdf/.
pytest -q # toute la suite doit être verte
ruff check . # lint# Définir au moins SECRET_KEY et POSTGRES_PASSWORD (dans .env)
docker compose up --build # web + PostgreSQL, sur http://localhost:8000/DEBUG=False,SECRET_KEYunique,ALLOWED_HOSTSstrict,DATABASE_URLPostgreSQL. Le durcissement (SSL redirect, HSTS, cookies sécurisés) s'active automatiquement quandDEBUG=False— servez derrière HTTPS.python manage.py collectstatic(WhiteNoise sert les statiques).- Lancer via
gunicorn config.wsgi(leDockerfilele fait déjà). - Vérifier la configuration :
python manage.py check --deploy.
Préfixe /api/ (Django REST Framework).
| Endpoint | Description |
|---|---|
…/api/customers/ …/<id>/ |
CRUD clients |
…/api/products/ …/<id>/ |
CRUD produits |
…/api/invoices/ …/<id>/ |
CRUD factures (lignes imbriquées) |
POST …/api/invoices/<id>/finalize/ |
Finaliser |
POST …/api/invoices/<id>/status/ |
Changer le statut (paid/unpay/cancel) |
POST …/api/invoices/<id>/duplicate/ |
Dupliquer |
GET …/api/invoices/<id>/pdf/ |
Télécharger le PDF |
Authentification par token :
# 1. Obtenir un token
curl -X POST http://127.0.0.1:8000/api/auth-token/ -d "username=USER&password=PASS"
# -> {"token":"<votre-token>"}
# 2. Appel authentifié
curl http://127.0.0.1:8000/api/invoices/ -H "Authorization: Token <votre-token>"- docs/ARCHITECTURE.md — architecture, modèle de données, règles métier.
- CONTRIBUTING.md — comment contribuer.
- SECURITY.md — signaler une vulnérabilité.
config/ Settings (pilotés par l'env), urls, wsgi/asgi
core/ CompanySettings (singleton), dashboard, paramètres, filtres monnaie
billing/ Modèles, services (calcul/numérotation/finalisation), selectors,
vues, API DRF, PDF (pdf.py + pdf_templates.py)
templates/ base.html, pages core/billing, modèles PDF (billing/pdf/)
static/ CSS Tailwind compilé, Alpine.js
theme/ Sources Tailwind
docs/ ARCHITECTURE.md
Les contributions sont bienvenues — voir CONTRIBUTING.md (workflow, Conventional Commits en français, tests).
Distribué sous licence MIT — voir le fichier LICENSE. Composants tiers : voir THIRD-PARTY-NOTICES.md.
© 2026 Rafik226