API ScanETF — guide de mise en route

Ce document sert à deux choses : vous aider à brancher l'API, et être collé tel quel à un assistant IA pour qu'il écrive le code d'intégration à votre place.

Ce que l'API expose

Vos portefeuilles ETF enregistrés sur ScanETF et leurs analyses : composition, frais, exposition géographique et sectorielle, positions consolidées, performance historique, corrélations. Vous pouvez aussi créer et modifier vos portefeuilles.

L'API n'expose pas le catalogue ETF de ScanETF. Seuls les fonds réellement présents dans vos portefeuilles apparaissent dans les réponses. Il n'existe pas d'endpoint de recherche : pour trouver un ISIN, passez par le screener sur https://scanetf.com/screener.

Mise en route en quatre étapes

Comptez deux minutes. Tout se fait au terminal ; aucune bibliothèque à installer.

1. Enregistrez au moins un portefeuille

L'API sert vos données : sans portefeuille enregistré sur https://scanetf.com/mon-espace/portefeuilles, toutes les réponses seront vides et vous chercherez une panne qui n'existe pas.

2. Générez une clé API

Sur https://scanetf.com/mon-espace/api, bouton Configuration, puis Générer une clé.

Elle n'est affichée qu'une fois : seule son empreinte est conservée. Copiez-la immédiatement. Si vous la perdez, révoquez-la et générez-en une nouvelle.

Une clé de portée api ne fonctionne que sur /api/v1 ; une clé d'assistant IA y est refusée avec un message explicite.

3. Vérifiez que la clé répond

Toutes les requêtes portent un en-tête Authorization :

curl "https://scanetf.com/api/v1/portfolios" -H "Authorization: Bearer sk-scanetf-api-VOTRE_CLE"

Vous devez recevoir un JSON listant vos portefeuilles, chacun avec son portfolio_id. Si vous recevez un 401, la clé est absente, mal recopiée, révoquée, ou de portée MCP.

4. Appelez une première analyse

Reprenez un portfolio_id de l'étape 3 et remplacez-le ci-dessous :

curl "https://scanetf.com/api/v1/portfolios/VOTRE_ID/analysis" -H "Authorization: Bearer sk-scanetf-api-VOTRE_CLE"

La réponse commence par un champ summary en français : si vous le lisez, votre intégration fonctionne. Les autres endpoints suivent la même forme.

Votre activité et vos appels restants apparaissent sur https://scanetf.com/mon-espace/api.

Combien d'appels ?

Le plan gratuit dispose de 30 appels au total, puis l'API se ferme ; ScanETF Pro la rend illimitée. Un garde-fou anti-abus plafonne par ailleurs chaque clé à 2 000 appels par jour.

Conventions de réponse

• Les pourcentages sont des nombres, pas des chaînes : 0.214 signifie 0,214 %.
• Les montants sont en euros, arrondis au centime.
• Chaque réponse commence par un champ summary en français, résumant le résultat.
• Les erreurs métier renvoient un code HTTP 4xx et un champ message explicite en français, destiné à être montré tel quel à l'utilisateur.
• Les corps de requête sont validés strictement : un champ inconnu est refusé, et non ignoré silencieusement. Le message nomme le champ fautif et, pour une valeur hors liste, énumère les valeurs acceptées.
• Rien n'est tronqué en silence. Une liste longue est paginée : offset_suivant donne la page suivante et vaut null quand tout a été lu ; un compteur dit ce qui reste.

Endpoints

Portefeuilles

GET /portfolios — Lister vos portefeuilles

Nom, enveloppe fiscale, courtier, étiquette et nombre de lignes. Point de départ : les autres endpoints attendent un identifiant renvoyé ici.

POST /portfolios — Créer un portefeuille

Crée un portefeuille, avec sa composition si elle est fournie — en pourcentage (la somme des poids doit valoir 100) ou en nombre de parts (valorisées au dernier cours), comme dans l’éditeur du site.

Paramètres :

• nom (requis) — Nom du portefeuille.
• enveloppe — PEA, CTO, PEA-PME, Assurance Vie ou PER.
• courtier — Nom du courtier, texte libre.
• tag — Principal, Optimisé, Test ou Archivé.
• lignes — Tableau de (mode pourcentage) ou de (mode parts). Un seul mode par portefeuille.

GET /portfolios/{id} — Composition détaillée

Chaque ligne avec son ISIN, son poids, le montant investi, les parts, les frais et l’éligibilité PEA.

PATCH /portfolios/{id} — Modifier un portefeuille

Modifie les informations (nom, description, enveloppe, courtier, étiquette) et/ou la composition. Seuls les champs envoyés changent ; lignes, si présent, remplace intégralement la composition. La composition est refusée si le portefeuille comporte des transactions dans le suivi DCA, pour ne pas fausser les positions.

Paramètres :

• nom, description, enveloppe, courtier, tag — Mêmes valeurs qu’à la création. null efface un champ facultatif.
• lignes — Nouvelle composition complète, en ou en . Omettre pour garder la composition actuelle.

DELETE /portfolios/{id} — Supprimer définitivement

Emporte les lignes, les transactions et le plan DCA. Irréversible : le nom exact est exigé en confirmation.

Paramètres :

• nom (requis) — Nom exact du portefeuille.

Analyse

GET /portfolios/{id}/analysis — Analyse Rayon X

Frais pondérés, éligibilité PEA, disponibilité courtiers, rendement de dividende pondéré avec les ETF qui le produisent, exposition complète par continent, pays et secteur, et le détail ligne à ligne (frais, coût annuel, capitalisant ou distribuant avec son rendement, réplication).

GET /portfolios/{id}/positions — Positions consolidées

Ce que vous détenez réellement, toutes lignes confondues : chaque entreprise avec son poids dans le portefeuille et les ETF par lesquels vous la détenez. Les positions détenues via plusieurs ETF sont marquées en_doublon. Liste paginée, par poids décroissant ; les positions sous 0,01 % du portefeuille ne sont pas listées, mais restent comptées dans chevauchement_pct.

Paramètres :

• limite — Taille de page : 25 par défaut, 100 au maximum.
• offset — Rang de la première position renvoyée, 0 par défaut. Reprendre l’offset_suivant de la réponse ; il vaut null quand tout a été lu.

Performance

GET /portfolios/{id}/backtest — Performance historique

Performance totale, rendement et volatilité annualisés, ratio de Sharpe, perte maximale, rendements annuels et mensuels, à allocation constante. La série ne commence qu’au premier jour où toutes les lignes cotent : si une ligne récente tronque la fenêtre demandée, tronquee_par_historique le signale et ligne_limitante la nomme.

Paramètres :

• periode — Fenêtre nommée : 1M, 3M, 6M, 1Y, 3Y, 5Y, Max. Par défaut 1Y, comme la page Comparer du site.
• date_debut — Date de début AAAA-MM-JJ. Prioritaire sur periode.
• date_fin — Date de fin AAAA-MM-JJ. Aujourd’hui par défaut.
• exclure — ISIN à retirer du calcul, séparés par des virgules.

GET /portfolios/{id}/correlation — Corrélation entre les lignes

Matrice de corrélation, paires les plus corrélées et groupes de lignes quasi interchangeables (≥ 0,8). Deux ETF très corrélés n’apportent pas de diversification l’un par rapport à l’autre.

Paramètres :

• periode — Fenêtre nommée : 1M, 3M, 6M, 1Y, 3Y, 5Y, Max. Par défaut 1Y, comme la page Comparer du site.
• date_debut — Date de début AAAA-MM-JJ. Prioritaire sur periode.
• date_fin — Date de fin AAAA-MM-JJ. Aujourd’hui par défaut.
• exclure — ISIN à retirer du calcul, séparés par des virgules.

GET /portfolios/{id}/prices — Série de valorisation

Valeur du portefeuille jour par jour, base 100 au premier point commun aux lignes retenues. De quoi tracer la courbe dans votre outil. La série est renvoyée entière — sur cinq ans, comptez ~1 300 points et ~50 Ko ; granularite la résume à la semaine ou au mois.

Paramètres :

• periode — Fenêtre nommée : 1M, 3M, 6M, 1Y, 3Y, 5Y, Max. Par défaut 1Y, comme la page Comparer du site.
• date_debut — Date de début AAAA-MM-JJ. Prioritaire sur periode.
• date_fin — Date de fin AAAA-MM-JJ. Aujourd’hui par défaut.
• exclure — ISIN à retirer du calcul, séparés par des virgules.
• granularite — jour (par défaut), semaine ou mois : un point par jour de cotation, ou le dernier point de chaque semaine ou mois. nb_points et nb_jours_cotation disent ce qui a été renvoyé et ce qui a été résumé.

Règles à respecter

Ces règles évitent les erreurs les plus fréquentes. Si vous êtes un assistant écrivant du code pour cette API, suivez-les.

1. N'inventez jamais un ISIN. Utilisez uniquement ceux renvoyés par l'API, ou ceux que l'utilisateur fournit explicitement. Un ISIN inconnu du catalogue est rejeté.
2. Choisissez un mode de saisie par portefeuille. Chaque ligne porte soit poids_pct (la somme doit valoir 100, tolérance 0,05), soit parts (nombre de parts, valorisées au dernier cours connu). PATCH avec lignes remplace toute la composition : relisez d'abord le portefeuille et renvoyez la liste complète.
3. Citez toujours la période effective d'un backtest. La fenêtre par défaut est d'un an, et un historique court gonfle mécaniquement le rendement annualisé : un portefeuille suivi depuis six mois peut afficher 60 %/an sans que cela signifie quoi que ce soit.
4. Une suppression est définitive et emporte les transactions et le plan DCA. Le nom exact est exigé en confirmation. Faites confirmer l'utilisateur avant d'appeler.
5. Un portefeuille suivi en DCA refuse les modifications de composition. C'est volontaire : réécrire ses lignes fausserait le calcul des positions. Le message d'erreur propose la marche à suivre.
6. Vérifiez l'éligibilité PEA avant de recommander un remplacement. Un ETF moins cher peut faire perdre l'éligibilité de l'enveloppe ; le champ eligible_pea est renvoyé pour chaque ligne.

Codes d'erreur

Aller plus loin

• Spécification OpenAPI 3.1 : https://scanetf.com/api/v1/openapi.json — importable dans Postman, Bruno ou Insomnia, et suffisante pour générer un client.
• Serveur MCP : https://scanetf.com/mcp — pour interroger vos portefeuilles en langage naturel depuis ChatGPT, Claude, Mistral, Perplexity, Grok ou Cursor, sans écrire de code. Le guide de connexion est sur https://scanetf.com/assistant-ia/guide.

Un problème ?

Écrivez-moi à pl.danieau@gmail.com. Précisez l'endpoint appelé et le code d'erreur reçu : c'est ce qui permet de débloquer une intégration le plus vite.