Automatiser les calculs cloud
En un coup d'œil
Un script peut mettre des calculs en file sur vos projets enregistrés et en récupérer les résultats, authentifié par un Jeton de service créé sur Compte plutôt que par votre mot de passe. Le calcul cloud est décompté du quota de votre formule.
Le vrai calcul (simulations, balayages par lots, optimisations) est une tâche : vous la soumettez, vous l'interrogez, puis vous récupérez le résultat.
Il n'y a pas de notification poussée par le serveur. C'est le client qui interroge : l'application elle-même interroge toutes les trois secondes dans le cloud.
Un assistant IA installé sur votre ordinateur (Claude Code, Cursor, VS Code) peut piloter votre compte via le serveur MCP de pvSpline : créer des projets, les calculer et en expliquer les résultats (Assistants IA).
Prérequis : un fichier projet portable (
*.pvspline.json), le document même que l'application exporte et importe. Voir Prise en main pour savoir comment en sortir un du navigateur.
Ce que vous pouvez automatiser
Le navigateur est un client du moteur pvSpline, pas le moteur lui-même. Quand vous appuyez sur Lancer le projet, la page envoie votre document projet à un moteur et l'interroge jusqu'à ce que le résultat revienne. Rien dans cet échange n'est propre au navigateur, et c'est précisément ce qui rend l'automatisation possible.
- Automatiser à partir du cloud.
Vous pouvez soumettre des calculs au service cloud et en récupérer les résultats sans rester devant un navigateur. Vous vous authentifiez avec un Jeton de service créé sur Compte, mettez un calcul en file sur l'une de vos sauvegardes, l'interrogez, puis téléchargez le résultat et ses artefacts. Le calcul cloud est décompté du quota de votre formule.
- Via un assistant IA.
Connectez un assistant à votre compte et formulez votre demande en langage courant : il crée le projet, le calcule sur le moteur cloud et vous en lit les résultats (Assistants IA).
Note
Un script soumet le même document que le navigateur : le fichier projet portable (*.pvspline.json). Il est autonome : puisqu'il embarque les séries météo et de consommation récupérées, un projet que vous exportez aujourd'hui se rejoue à l'identique des mois plus tard. Faire entrer et sortir ce fichier du navigateur est traité dans Prise en main.
Tâches et interrogation
Il n'y a pas de notification poussée par le serveur. Ni websocket, ni événements envoyés par le serveur, ni URL de rappel. C'est le client qui interroge, et la fraîcheur de ce qu'il sait est bornée par son intervalle d'interrogation. L'application elle-même interroge toutes les trois secondes face au cloud ; c'est un intervalle sensé à reprendre. Ne raccourcissez pas un sondage pour simuler de la réactivité : vous n'obtiendrez pas les mises à jour plus vite, vous dépenserez seulement plus de requêtes.
Limites qu'un script doit respecter
Ce sont des plafonds, pas des boutons de réglage. Un script qui les ignore les rencontre sous forme d'échec opaque au milieu d'un envoi.
| Plafonds de la plateforme | Signification / effet |
|---|---|
| Plafond d'appel synchrone | À travers la passerelle cloud, un appel synchrone dispose d'environ 29 secondes avant d'être coupé. Tout ce qui pourrait approcher les dix secondes doit être une tâche, pas une route synchrone. |
| Charge utile intégrée à la requête | La voie cloud transporte environ 6–10 Mo en ligne, et le document projet d'un calcul est refusé au-delà de 5 Mio avec 413 PROJECT_TOO_LARGE. L'application envoie séparément, par référence, les données embarquées les plus lourdes pour rester en dessous. |
| Import de fichier, cloud | Environ 25 Mo par fichier (24 Mio). Le fichier est envoyé puis référencé plutôt qu'inséré en ligne : c'est donc le plafond qu'il rencontre. |
| Illustrations et photos du dossier d'autorisation | Environ 25 Mo, car le navigateur doit décoder l'image choisie à sa taille réelle avant qu'elle ne soit réduite. |
| Fichiers analysés par le navigateur | Projet, préférences, CSV de lot, JSON de thème et séries de production sont analysés dans l'onglet et bornés à 64 Mio pour la sûreté de l'onglet. La vraie pression, bien en dessous, vient du stockage de session du navigateur lui-même (quelques Mo) et de l'historique d'annulation (environ 20 Mo) ; tous deux se dégradent en douceur plutôt que d'échouer. |
| Scénarios par balayage | 1000. Une config plus grande est un 400. |
| Le calcul cloud est décompté | Les calculs sont imputés sur un quota mensuel de secondes-moteur par société. Au-delà, le cloud répond 429 avec ce quota, ce qu'il en reste et ce que le calcul demandait. Sans aucun droit d'accès, il répond 402. Une tâche qui échoue est imputée du temps moteur qu'elle a consommé avant d'échouer : une tâche conçue pour échouer coûte ce qu'elle a brûlé. |
| Calculs cloud en file | Aucun plafond fixe sur le nombre de calculs que vous mettez en file ou faites tourner : la limite est le quota mensuel, et chaque calcul réserve son temps moteur estimé dès sa mise en file, si bien qu'une longue file peut se heurter au 429 avant qu'aucun de ses calculs n'ait tourné. Les workers partagés servent les sociétés à tour de rôle (le prochain worker libre démarre le plus ancien calcul en file de la société servie depuis le plus longtemps), de sorte que votre arriéré ne retient pas les calculs d'une autre société derrière lui, ni le sien les vôtres. Les calculs des clients payants passent toutefois d'abord : avec l'offre gratuite, un calcul ne démarre qu'une fois qu'aucun calcul d'un client payant n'attend, et un calcul batch ou optimize en cours peut être interrompu pour l'un d'eux. Son status repasse à queued, il recommence depuis le début, et la tentative interrompue n'est pas décomptée (Le travail des clients payants passe d'abord). Au sein de votre société, les calculs démarrent du plus ancien au plus récent : tant que les workers sont occupés, un arriéré mis en file par un script passe avant les calculs que vos collègues lancent ensuite. Annulez les calculs en file dont vous n'avez plus besoin ; cela ne coûte rien. |
| API cloud, toutes les formules | Toutes les formules plafonnent les secondes de temps serveur passées à répondre aux requêtes de la société sur un mois civil : synchronisation des projets, calculs cloud, constructions de tuiles, streaming 3D, Enedis, relais moteur, assistants IA et le reste. La connexion et les appels de compte, de licence, de facturation, de paiement et de société ne sont pas comptés, et un appel qui arrête une dépense (un DELETE, un /stop) n'est jamais refusé. Au-delà du quota, tout autre appel compté répond 429 API_ALLOWANCE_EXCEEDED avec quota_seconds et used_seconds, jusqu'au renouvellement du quota le 1er du mois. |
| Usage raisonnable | Au-delà des quotas, la capacité partagée est protégée sur toutes les formules : les rafales de requêtes qui dégradent le service et la soumission soutenue de calculs infra-horaires à la chaîne peuvent être bridées, et un abus prolongé ou délibéré peut entraîner la suspension du compte. Une boucle automatique qui resoumet un calcul en échec est considérée comme un abus : temporisez plutôt et corrigez la cause. |
Astuce
Les tailles sont binaires en interne (Mio) mais l'application les affiche en décimal (Mo), parce que c'est ce que montre un gestionnaire de fichiers, d'où un plafond de 24 Mio qui se lit à l'écran « 25 Mo ». Vérifiez la taille d'un fichier avant de le lire, pas après : l'application refuse les fichiers trop gros dès le sélecteur, exactement pour cette raison.
Automatiser à partir du cloud
Un script peut mettre des calculs en file auprès du service cloud et en récupérer les résultats, avec un identifiant qui n'est pas votre mot de passe.
Jetons de service
Ouvrez la section Sécurité de Compte (/account/security) et trouvez Jetons de service (identifiants machine pour vos serveurs d’intégration continue, vos machines de calcul et vos assistants IA : à portée limitée, révocables, jamais liés à votre mot de passe).
Créer un jeton de service
Allez sur
/account/security, la section Sécurité de la page Compte, et trouvez Jetons de service.Saisissez un nom qui dise où il vivra ; l'exemple proposé est
serveur d’intégration continue.Laissez la portée sur
Scripts et CI.Assistant IA (MCP)crée un jeton qui n'ouvre que le point d'accès des assistants IA, pour un assistant qui ne sait pas s'identifier (Un assistant qui ne sait pas s'identifier).Si le jeton doit vivre sur un serveur, dans un conteneur ou dans une chaîne de CI, cochez Pour un serveur, un conteneur ou une chaîne de CI (occupe un poste) : avec un abonnement, un tel jeton occupe un poste de membre à lui seul (Votre compte, votre équipe & vos calculs cloud). Un jeton que vous utilisez vous-même, sur votre propre ordinateur, n'en occupe aucun. L'offre gratuite ne compte pas de postes : la case s'y intitule Pour un serveur, un conteneur ou une chaîne de CI, et un tel jeton n'en occupe pas non plus.
Cliquez sur Créer un jeton. Le jeton complet n'est affiché qu'une fois. Copiez-le tout de suite dans votre gestionnaire de secrets ; il ne sera plus jamais affiché.
La liste indique ensuite le nom, la portée et la dernière utilisation du jeton, avec Révoquer à côté.
Un jeton ressemble à pvs_at_… et se présente sous la forme Authorization: Bearer <token>. Ce qu'il peut faire est délibérément borné :
Il agit au nom de la personne qui l'a créé, dans sa société : il ne lit le détail, l'entrée et les résultats que des calculs de son propriétaire, et un point d'accès fermé aux jetons de service le refuse avec
403SERVICE_TOKEN_FORBIDDEN. Pour un serveur, un conteneur ou une chaîne de CI, créez le jeton depuis un compte qui a le rôle Utilisateur, et non depuis la direction de votre société ou son membre fondateur (Profils, et ce qu'un responsable peut modifier).Il ne peut pas créer un autre jeton.
Il n'est pas affecté par un changement de mot de passe, et une réinitialisation de mot de passe ne tue pas votre runner CI. Sa révocation lui est propre : Révoquer, immédiate, jeton par jeton.
Contrairement à une session de navigateur, il n'a pas à signer ses requêtes. Une session de navigateur connectée signe chaque appel authentifié avec une clé propre à l'utilisateur ; un client qui n'a qu'un jeton n'a pas de telle clé et on ne lui en demande pas. C'est ce qui rend un jeton utilisable depuis un shell.
Un jeton créé sur la page Compte n'expire pas : il dure jusqu'à sa révocation, ou jusqu'à la suppression du compte de son propriétaire.
Vous pouvez détenir jusqu'à
25jetons actifs, en comptant les connexions des assistants IA.
Soumettre un calcul cloud
Mettre du travail en file dans le cloud nécessite une formule active (l'offre gratuite ou un abonnement) couvrant la simulation cloud ; sans elle, le service répond 402 avant que rien ne soit mis en file. Toutes les routes ci-dessous partent de l'adresse de l'API cloud, https://api.pvspline.fr.
| API des calculs cloud | Signification / effet |
|---|---|
| GET /saves | Les sauvegardes cloud que vous pouvez ouvrir, chacune avec son id, le save_id sous lequel un calcul est classé. |
| POST /simulations | Corps {save_id, project, kind?, options?, report_theme?, language?, verification_qr?}. save_id désigne l'une de vos sauvegardes cloud : c'est le sujet de l'autorisation, le sujet du quota et le lien que suit la vue des résultats. project est le document projet portable que le worker exécutera réellement. kind vaut run (par défaut), optimize ou batch ; options porte les réglages de l'optimiseur ou la config de lot et n'est valide que pour ces deux-là. Les clés report_theme et verification_qr façonnent les artefacts rendus d'un calcul et sont refusées avec tout autre genre. report_theme désigne un thème de rapport de la société. language est la langue dans laquelle la tâche est rédigée, par exemple fr, quel que soit son genre : les artefacts d'un calcul (leurs textes, ainsi que les chiffres du rapport, page de schéma unifilaire comprise, et des lignes de synthèse du classeur ; le dossier CRE reste en français) et ses notes et avertissements, les noms des candidats d'une optimisation (12.0 kWp, 12.0 kWc en français) et ses avertissements, les avertissements d'un lot. verification_qr: true appose le QR code de vérification sur la couverture de report.pdf, en attestant les séries de consommation et de production du calcul (Vérification du rapport), et enregistre la charge utile du code à côté, sous le nom report.pdf.qr.bin. Sans lui, le rapport ne porte aucun code ; les calculs que lance l'application web le demandent toujours. Répond 202 avec {id, status, kind}. |
| GET /simulations | Les calculs de votre société, du plus récent au plus ancien, plafonnés à 50. Chacun porte son save_id et son save_name, le nom actuel du projet (null pour un projet que vous ne pouvez pas ouvrir : celui d'un collègue, si vous avez les droits Utilisateur ou utilisez un jeton de service, ou un projet supprimé depuis le calcul). La liste ne porte aucun lien de téléchargement ; lisez un calcul pour les obtenir. |
| GET /simulations/{id} | Un calcul : état, horodatages, save_name, error_message, engine_version, kind, et ce qu'il a imputé sur le quota. Une fois réussi, il porte aussi une result_url présignée et, par artefact, des artifact_urls : des noms parmi report.pdf, report.pdf.qr.bin, report.pdf.sig, export.xlsx, dossier.pdf et charts/<token>.png. Les artefacts n'existent que pour les calculs simples, et un artefact dont le rendu échoue est simplement absent : suivez donc les noms que liste le calcul. Les liens valent une heure ; relisez le calcul pour en obtenir de nouveaux. Un appelant aux droits Utilisateur, et tout jeton de service, ne lit que ses propres calculs : celui d'un collègue répond 404. |
| GET /simulations/{id}/input-url | Une URL présignée vers le document projet exact qu'a exécuté ce calcul. 404 INPUT_EXPIRED une fois qu'il est sorti de sa rétention de 30 jours : remettez le calcul en file pour le restocker. |
| DELETE /simulations/{id} | Annuler un calcul en file (204). Il apparaît alors failed, avec le message cancelled by user, et ne coûte rien. Une fois qu'un worker l'a pris en charge, 409 : un calcul démarré ne peut pas être interrompu. |
Les téléchargements sont des requêtes nues sur les URL présignées : pas d'en-tête d'autorisation, car la signature est elle-même l'autorisation.
Pour un calcul batch, options est obligatoire : c'est l'enveloppe {config, options?}, où config dit quoi calculer et options comment. config porte exactement une des clés scenarios, parts et axes, plus un nameTemplate facultatif, et se développe en 1000 scénarios au plus.
| Enveloppe d'un lot | Signification / effet |
|---|---|
| config.scenarios | Des lignes explicites, un scénario chacune, toutes leurs clés étant facultatives : name, overrides, panel, inverter, inverterCount, battery et policy. overrides associe un nom de colonne moteur (l'en-tête d'une colonne de paramètre du tableau des scénarios de la vue Lots, par exemple battery_capacity) à la valeur du scénario ; une valeur vide conserve celle du projet. panel, inverter et battery substituent un composant par son empreinte, et inverterCount, 1–10000, accompagne inverter et fixe combien d'unités de cet onduleur la ligne simule. policy n'accepte que offline : un lot cloud travaille sur les séries que le projet embarque. Une ligne sans name s'appelle Scenario N. |
| config.parts | Un comparatif de composants, un scénario par entrée : {category, fingerprint, name?}, category valant module, inverter ou battery, et name donnant le nom du scénario. |
| config.axes | Un balayage ou, avec plusieurs axes, toutes les combinaisons de leurs valeurs : chaque axe est {label, values}, {label, from, to, step} ou {label, from, to, count}, label étant un nom de colonne moteur. |
| config.nameTemplate | Le modèle de nom de scénario du champ Nom : des pages Balayage et Matrice de la vue Lots, avec les mêmes marqueurs (Simulation par lots & balayages de scénarios). |
| options | Les réglages de calcul, tous facultatifs. objective désigne le gagnant : van, par défaut, à la VAN, ou tri au TRI des fonds propres. onFetchError vaut fallback (par défaut), abort ou skip, et keepPolygonCoordinates est un booléen, comme les règlent En cas d'échec de récupération et Conserver les coordonnées des polygones dans la vue Lots. artifacts ne peut demander aucun export par scénario : un lot cloud ne livre que son tableau de comparaison. |
Le service contrôle l'enveloppe avant de mettre quoi que ce soit en file, et répond 400 BATCH_OPTIONS_INVALID, son message nommant le problème, à une clé inconnue dans l'enveloppe, une ligne, un axe ou les réglages de calcul ; à deux clés parmi scenarios, parts et axes à la fois ; à une valeur mal formée ou hors limites ; et à plus de 1000 scénarios. Un problème que seul le moteur peut voir (un nom de colonne qu'il ne connaît pas ou ne peut pas balayer, un name de ligne contenant une barre oblique ou une barre oblique inverse) est détecté plus tard : le calcul est mis en file, puis échoue avec la raison dans son error_message.
La result_url d'un calcul batch est son tableau de comparaison, {columns, rows, stringPlans?, winnerIndex?, winnerBy?, warnings?} : une ligne par scénario sous les jetons de colonne name, design, status, payback, npv, npv_eur, lcoe_eur_per_kwh, performance_ratio, yield_kwh_per_kwp, production_kwh, near_shading_loss_kwh, near_shading_loss_pct, irr_pct, dscr_min et llcr. payback et npv sont des libellés d'affichage et npv_eur le nombre ; irr_pct (le TRI des fonds propres), dscr_min et llcr valent null là où le scénario n'a pas ce chiffre (pas de TRI, pas d'emprunt). Les chiffres d'une ligne n'ont de sens que lorsque son status vaut succeeded : une ligne en échec porte 0 dans chaque colonne de npv_eur à near_shading_loss_pct, des libellés payback et npv vides, et null dans irr_pct, dscr_min et llcr. winnerBy indique quelle métrique a désigné winnerIndex, npv ou irr ; stringPlans, parallèle à rows, contient le câblage sur lequel chaque ligne redimensionnée ou aux composants changés a été évaluée.
Une ligne qui substitue un composant (son panel, son inverter ou sa battery) ne tourne que si le projet embarque ce composant dans sa panelLibrary, son inverterLibrary ou sa batteryLibrary, ou si le composant fait partie de ceux livrés avec l'application. Toute autre ligne de ce type revient failed, et warnings nomme le scénario et le composant. La vue Lots embarque les composants propres à votre société avant de soumettre ; un script doit les embarquer lui-même.
Attention
Le projet voyage séparément de la sauvegarde sous laquelle il est classé : les deux peuvent donc diverger. Le service les compare et répond 409 PROJECT_SAVE_MISMATCH plutôt que de classer silencieusement un calcul (et son quota) sous une sauvegarde sans rapport. N'envoyez confirm_mismatch: true que lorsque la divergence est délibérée. Autres refus à gérer : 422 PROJECT_NOT_PORTABLE (vous avez envoyé une ligne de sauvegarde plate, pas un fichier projet), 413 PROJECT_TOO_LARGE, 404 THEME_NOT_FOUND (un report_theme inconnu), 400 REPORT_THEME_INVALID ou VERIFICATION_QR_INVALID (une valeur mal formée, ou envoyée avec un genre autre que run), LANGUAGE_INVALID (un code de langue mal formé), 402 (aucun droit d'accès actif), 429 (quota mensuel dépassé, avec les chiffres) et 429 API_ALLOWANCE_EXCEEDED (le quota mensuel d'API cloud du propriétaire du jeton est épuisé). Un 503 accompagné d'un en-tête Retry-After signifie que le service est brièvement indisponible : attendez la durée indiquée, puis réessayez.
Via un assistant IA
L'API cloud de pvSpline parle aussi le Model Context Protocol (MCP), le standard ouvert par lequel les assistants IA appellent des outils. Connecté à votre compte, un assistant tel que Claude Code, Cursor ou VS Code travaille sur vos projets à votre demande : il crée un projet à partir d'une adresse ou de coordonnées et de ses champs PV, le calcule sur le moteur cloud et en explique les résultats, avec des liens pour ouvrir le projet, ses résultats et son rapport PDF dans l'application web.
Assistants IA en est le guide complet : ce qu'il vous faut, l'entrée à ajouter pour chaque client, chaque outil que l'assistant peut appeler, et ce sur quoi ses calculs et ses requêtes sont décomptés.
L'authentification et les comptes (connexion, sessions, formules et ce que couvre un droit d'accès) relèvent de Votre compte, votre équipe & vos calculs cloud.