crowdlending-app/frontend/public/powerquery/README.md

Power Query — exemples de connexion à l'API v1

Exemples de requêtes Power Query (Excel) pour interroger le portefeuille crowdlending depuis un classeur Excel, en s'appuyant sur la même API v1 (lecture seule) que le serveur MCP.

Aucune écriture : ces requêtes ne font que lire des données, comme le serveur MCP.

Prérequis

• Une clé API générée dans l'app : Mon compte → Clés API → Nouvelle clé
• Le backend accessible (en local http://localhost:4000, ou l'URL de votre instance en production, ex. https://crowdlending.croguennec.net)
• Excel avec Power Query (Excel 365 / 2016+ sous Windows ou Mac — Power Query est intégré nativement, rien à installer)

Option 1 — Classeur prêt à l'emploi (crowdlending-powerquery-exemple.xlsb)

Le plus rapide : ouvrez crowdlending-powerquery-exemple.xlsb directement dans Excel.

Pourquoi un .xlsb et pas un .xlsx ? Le format binaire d'Excel (.xlsb) est celui à partir duquel ce classeur a pu être construit et vérifié de façon fiable en dehors d'Excel. Il s'ouvre et se comporte exactement comme un .xlsx — Power Query, tableaux, actualisation, tout fonctionne à l'identique. Si vous préférez un .xlsx, ouvrez le fichier puis Fichier → Enregistrer sous et changez le format ; les requêtes suivent.

Le classeur contient :

Requête	Rôle
ApiBaseUrl	URL de l'API à interroger (à modifier)
ApiKey	Votre clé API (à modifier — voir ci-dessous)
fnApiGet	Fonction utilitaire partagée (appel HTTP + parsing JSON), utilisée par toutes les requêtes de données
Investisseur	Profil investisseur (ou liste des membres si clé « Famille et entreprises »)
Dashboard	KPIs du portefeuille (capital investi, capital en risque, intérêts, cash), au format « Indicateur / Valeur »
Investissements	Liste des investissements
Remboursements	Historique des remboursements
DepotsRetraits	Historique des mouvements de cash
fnDetailInvestissement	Fonction avancée : détail + remboursements d'un investissement par id
Test	Table d'instructions (« À lire avant de commencer ») — pas une donnée métier

Étapes :

1. Ouvrez le classeur. La feuille affiche par défaut un exemple mis en cache (pas encore vos données) — c'est normal, Excel n'a pas encore appelé l'API.
2. Données → Requêtes et connexions. Repérez ApiKey dans le volet à droite.
3. Clic droit sur ApiKey → Modifier. Dans l'éditeur, remplacez "clk_live_VOTRE_CLE_API" par votre vraie clé (entre guillemets), puis Fermer et charger.
4. Vérifiez ApiBaseUrl de la même façon : http://localhost:4000/api/v1 en local, ou https://crowdlending.croguennec.net/api/v1 en production (adaptez à votre domaine).
5. Données → Actualiser tout (ou Ctrl+Alt+F5). La table « Test » se met à jour avec les instructions, signe que la connexion fonctionne.
6. Pour chaque requête de données qui vous intéresse (Investissements, Remboursements…) : clic droit dans le volet Requêtes et connexions → Charger dans… → choisissez Tableau (ou Tableau croisé dynamique) et la feuille de destination.

Option 2 — Coller les requêtes manuellement (queries/*.pq)

Utile si vous préférez tout construire vous-même dans un classeur existant, ou si une requête du classeur ne s'affiche pas correctement chez vous.

Pour chaque fichier, dans l'ordre ci-dessous : Données → Obtenir des données → À partir d'autres sources → Requête vide, renommez la requête (volet de droite, ou après double-clic sur son nom) avec exactement le nom du fichier (sans .pq), puis Accueil → Éditeur avancé, effacez le contenu par défaut, collez le contenu du fichier, Terminé.

Ordre à respecter (chaque requête réutilise les précédentes par leur nom) :

1. ApiBaseUrl.pq — modifiez l'URL avant de coller si besoin
2. ApiKey.pq — remplacez VOTRE_CLE_API par votre clé avant de coller
3. fnApiGet.pq
4. Investisseur.pq, Dashboard.pq, Investissements.pq, Remboursements.pq, DepotsRetraits.pq — dans l'ordre que vous voulez
5. fnDetailInvestissement.pq (optionnel, usage avancé — voir plus bas)

Une fois fnApiGet créée, Fermer et charger chaque requête de données individuellement (clic droit → Charger dans…) pour l'ajouter comme tableau.

Filtres

Les requêtes Dashboard, Investissements et Remboursements acceptent des filtres côté API (année, statut, période). Par défaut elles ramènent tout (null). Pour filtrer, ouvrez la requête dans l'éditeur avancé et remplacez null par le paramètre indiqué en commentaire en tête du fichier .pq correspondant, par exemple :

Source = fnApiGet("/investissements", [statut = "rembourse"])

Statuts possibles : en_cours, rembourse, en_retard, procedure, cloture.

Usage avancé — détail d'un investissement par ligne

fnDetailInvestissement permet de ramener, pour chaque ligne de la table Investissements, le détail complet (dont les remboursements) sans requête séparée : sur la table Investissements, Ajout de colonne → Colonne personnalisée, formule = fnDetailInvestissement([id]). Attention : ceci déclenche un appel API par ligne — à réserver à un nombre raisonnable d'investissements (quelques dizaines).

Dépannage

• Impossible de se connecter au service distant — le backend n'est pas démarré, ou ApiBaseUrl est incorrecte (vérifiez le port et le suffixe /api/v1).
• Erreur API (401) / Clé API invalide ou révoquée — régénérez une clé dans Mon compte → Clés API et remplacez la valeur de ApiKey.
• Une requête du classeur n'apparaît pas dans le volet, ou affiche une erreur au premier chargement — repartez de l'Option 2 pour cette requête précise : créez une requête vide portant son nom et collez le contenu du .pq correspondant.
• Avertissement de sécurité / niveau de confidentialité au premier chargement — normal pour toute nouvelle source Web dans Power Query ; choisissez « Organisationnel » ou « Public » selon votre contexte, ce n'est pas spécifique à ce classeur.