Démarrage rapide

Ce guide fait un calcul d'impôt sur le revenu en une requête. Les exemples visent le serveur local de développement (npm run dev, port 3001) : aucune adresse publique n'est encore ouverte aux développeurs (phase 5 de la feuille de route).

Les requêtes et les réponses de ce guide sont produites par la documentation elle-même : chaque exemple est exécuté contre le moteur par les tests (packages/api/src/openapi/openapi.test.ts), et les blocs entre les marqueurs debut-exemple et fin-exemple sont réécrits par npm run docs:api. Aucun chiffre n'y est tapé à la main.

1. Trouver le calculateur

GET /v1/calculators liste les calculateurs servis. Chacun a un slug (identifiant de route), une version et, pour l'impôt sur le revenu, l'année des revenus (incomeYear). Le calculateur impot-revenu-2026 calcule l'impôt de la campagne 2026, c'est-à-dire sur les revenus de 2025.

2. Connaître ses champs

GET /v1/calculators/{slug}/schema rend le JSON Schema des entrées : identifiant de chaque champ, case du formulaire officiel (x-physcal-case), type, bornes, choix admis avec leurs libellés (x-physcal-libelles) et valeur par défaut. Un champ absent prend sa valeur par défaut ; un champ inconnu est refusé. Pour un calculateur de quelques champs :

curl -s "http://localhost:3001/v1/calculators/calcul-tva-2025/schema"

GET /v1/calculators/{slug}/fields/search?q=... retrouve un champ à partir de quelques mots (« revenus fonciers », « garde d'enfant », « 1AJ »).

3. Calculer

Un célibataire qui a perçu des salaires (case 1AJ) :

curl -s -X POST "http://localhost:3001/v1/calculators/impot-revenu-2026/calculate?trace=false" \
  -H "Content-Type: application/json" \
  -d '{"filingStatus":"celibataire","salaire1AJ":30000}'

En TypeScript :

const res = await fetch("http://localhost:3001/v1/calculators/impot-revenu-2026/calculate?trace=false", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "filingStatus": "celibataire",
    "salaire1AJ": 30000
  }),
});
const donnees = await res.json();

En Python :

import requests

res = requests.post(
    "http://localhost:3001/v1/calculators/impot-revenu-2026/calculate?trace=false",
    json={
        "filingStatus": "celibataire",
        "salaire1AJ": 30000
    },
)
donnees = res.json()

Réponse : statut 200 ; extrait de result (irFinal, revenuFiscalReference, nombreDeParts, tauxMarginalImposition, tauxMoyenImposition).

{
  "result": {
    "irFinal": "1564",
    "revenuFiscalReference": "27000",
    "nombreDeParts": "1",
    "tauxMarginalImposition": "11",
    "tauxMoyenImposition": "5.79"
  }
}

Chaque sortie de result est une chaîne décimale (voir Montants et arrondis). ?trace=false omet la trace ; sans ce paramètre, la réponse porte aussi steps, les étapes ordonnées du calcul avec leur formule et leurs citations (voir La trace).

4. Montants saisis en français

Un montant se saisit en nombre JSON ou en chaîne, avec la virgule ou le point décimal et des espaces entre les milliers :

curl -s -X POST "http://localhost:3001/v1/calculators/impot-revenu-2026/calculate?trace=false" \
  -H "Content-Type: application/json" \
  -d '{"filingStatus":"marie_pacs","enfantsAChargeEntiere":2,"salaire1AJ":"42 000","salaire1BJ":"27 500,50"}'

Réponse : statut 200 ; extrait de result (irFinal, nombreDeParts, revenuNetImposableCalcule).

{
  "result": {
    "irFinal": "2951",
    "nombreDeParts": "3",
    "revenuNetImposableCalcule": "62551"
  }
}

5. Erreurs

Une saisie refusée répond 400 avec l'enveloppe d'erreur commune, un code stable et un message en français. Le champ fautif est nommé par field, et le message dit les valeurs admises :

curl -s -X POST "http://localhost:3001/v1/calculators/impot-revenu-2026/calculate" \
  -H "Content-Type: application/json" \
  -d '{"filingStatus":"concubinage","salaire1AJ":30000}'

Réponse : statut 400.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "messageFr": "La valeur « concubinage » du champ Situation du foyer fiscal n'est pas autorisée. Valeurs admises : celibataire (Célibataire), marie_pacs (Marié(e) / Pacsé(e)), divorce (Divorcé(e) / Séparé(e)), veuf (Veuf / Veuve).",
    "field": "filingStatus",
    "requestId": "00000000-0000-0000-0000-000000000000"
  }
}

Le catalogue complet des codes est dans Erreurs.

Avertissement

Les résultats sont ceux du moteur appliqué à la saisie transmise ; ils ne constituent pas un conseil fiscal.