La trace

Chaque calcul rend, à côté de ses sorties, la suite ordonnée des étapes qui y mènent : c'est ce que l'interface affiche pour qu'un résultat se refasse à la main. La trace est servie par défaut ; ?trace=false l'omet.

Une étape

Clé	Contenu
`id`	Identifiant de l'étape dans son module.
`moduleId`	Module qui l'a produite (`fr_tva_standard_2025`…), lié à son registre de mécanismes.
`descriptionFr`	Ce que fait l'étape, en français.
`formula`	La formule appliquée, lisible.
`inputs`	Les valeurs lues, par nom (montants en chaînes décimales).
`output`	La valeur produite.
`citations`	Les textes qui fondent l'étape : `authority` (CGI, BOFiP, CSS, LoiFinances, BOSS, URSSAF…), `reference`, `url` (Légifrance quand elle existe), `asOfDate` (date de la version citée).

Exemple exécuté, avec la trace :

curl -s -X POST "http://localhost:3001/v1/calculators/calcul-tva-2025/calculate" \
  -H "Content-Type: application/json" \
  -d '{"montantHT":"100"}'

Réponse : statut 200.

{
  "slug": "calcul-tva-2025",
  "version": "1.0.0",
  "legalCorrections": [],
  "engineExtensions": [],
  "result": {
    "montantTVA": "20",
    "montantTTC": "120"
  },
  "cotisations": [],
  "steps": [
    {
      "id": "calcul_tva",
      "descriptionFr": "Application du taux normal de TVA (20 %)",
      "formula": "montantHT × 20 %",
      "inputs": {
        "montantHT": "100"
      },
      "output": "20",
      "citations": [
        {
          "authority": "CGI",
          "reference": "art. 278",
          "url": "https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000026950057/",
          "asOfDate": "2014-01-01"
        }
      ],
      "moduleId": "fr_tva_standard_2025"
    },
    {
      "id": "calcul_ttc",
      "descriptionFr": "Calcul du montant TTC",
      "formula": "montantHT + montantTVA",
      "inputs": {
        "montantHT": "100",
        "montantTVA": "20"
      },
      "output": "120",
      "citations": [],
      "moduleId": "fr_tva_standard_2025"
    }
  ],
  "warnings": [],
  "rulesVersion": "[email protected]"
}

Cotisations

Pour un calculateur de paie, cotisations détaille chaque cotisation : group (salariale ou patronale), montant, base, taux, ses propres étapes et avertissements. Il est vide pour les autres calculateurs, et avec ?trace=false.

Avertissements

warnings liste en français les remarques non bloquantes du calcul : règle écartée faute de condition remplie, valeur non renseignée prise par défaut.

Écarts avec le simulateur officiel

Le moteur suit le texte applicable aux revenus de l'année (CGI, doctrine BOFiP opposable, formulaire officiel de la campagne). Les simulateurs officiels servent à le vérifier, sans faire foi. Deux listes de la réponse le disent pour la saisie transmise :

legalCorrections : les points où le simulateur de la DGFiP s'écarte du texte et où le moteur suit le texte. Chaque entrée nomme sa base légale (legalBasis), le comportement du simulateur (dgfipBehaviorFr) et celui du moteur (correctionFr).
engineExtensions : les cas réels que le simulateur ne traite pas et que le moteur calcule d'après le texte (simulatorBehaviorFr, engineBehaviorFr, legalBasis). Le montant n'y est pas vérifiable par le simulateur.

Pour un client, une liste vide veut dire que le résultat ne dépend d'aucun de ces écarts.

Explication

POST /v1/calculators/{slug}/explain reçoit la même saisie et rend l'explication déterministe du calcul : mécanismes déclenchés avec leur base légale, textes épinglés cités en français (verbatim), écarts avec le simulateur, et questions non bloquantes (questions). Tant qu'une question reste ouverte, présentez le résultat comme provisoire.