API publique BaguetteFiscale

Pour qui ?

• Agents IA conversationnels (Claude via MCP HTTP/SSE, ChatGPT Custom GPT via OpenAPI, agents internes via REST direct).
• Plateformes B2B (cabinets de conseil patrimonial, services RH frontaliers, applications de gestion financière).
• Agents in-browser (Chrome 146+ via WebMCP, déjà câblé sur certaines pages publiques).

Vue d'ensemble

1. Vous enregistrez votre application (auto-onboarding à venir : pour l'instant, contactez hello@baguettefiscale.fr).
2. Vous redirigez l'utilisateur vers https://baguettefiscale.fr/api/oauth/authorize avec PKCE S256.
3. L'utilisateur consent explicitement (page /authorize) : il choisit les scopes accordés et la durée (1 jour à 90 jours, défaut 30 jours).
4. Vous échangez le code contre un access_token via POST /api/oauth/token (PKCE verifier + redirect_uri match).
5. Vous appelez l'API REST https://baguettefiscale.fr/api/v1/* avec Authorization: Bearer <token>.
6. Le PDF final reste payant. Si declaration.paid_at est absent, /generate-pdf retourne 402 avec une URL checkout Polar à transmettre à votre utilisateur final.

Endpoints disponibles

• GET /api/v1/health — liveness, sans auth
• GET /api/v1/discovery — métadonnées self-describing
• GET /api/v1/me — principal courant, scopes accordés
• GET /api/v1/questionnaire — spec déclarative du wizard
• POST /api/v1/declarations — crée la déclaration de l'année
• GET /api/v1/declarations/{year} — état complet (answers déchiffrés en mode agent)
• GET /api/v1/declarations/{year}/required-pieces — pièces justificatives à fournir
• PATCH /api/v1/declarations/{year}/answers — merge les réponses au questionnaire (re-chiffré côté serveur)
• POST /api/v1/declarations/{year}/compute — calcul IR déterministe + récap
• POST /api/v1/declarations/{year}/checkout-link — URL Polar checkout pour le client final
• POST /api/v1/declarations/{year}/generate-pdf — PDF Cerfa final, paywall actif (402 si non payé), checkbox de relecture obligatoire en mode complete
• GET /api/v1/declarations/{year}/pdf — URL signée Storage 7 jours

Scopes OAuth

Granularité fine. Chaque scope contrôle l'accès à un sous-ensemble d'endpoints. L'utilisateur voit la liste exacte sur la page de consent. Demandez le strict minimum.

• declaration.read : lire la déclaration en cours.
• declaration.write : modifier ou signer la déclaration.
• compute: lancer le calcul d'impôt déterministe.
• extract : lire les pièces justificatives uploadées.
• pdf.generate : générer le PDF Cerfa final.
• payment.initiate : obtenir une URL de paiement.
• profile.read: lire l'état civil et la situation familiale.
• profile.write: modifier l'état civil ou la situation familiale.

Architecture de sécurité

BaguetteFiscale stocke identity et profileAnswers chiffrés AES-256-GCM côté client avec une Master Key dérivée du mot de passe utilisateur (PBKDF2 600 000 itérations). Le mode UI reste zero-knowledge.

Le mode agent introduit un User Authorization Token (UAT) : à la page de consent, le client chiffre la Master Key avec une clé scoped dérivée duauthId (HKDF-SHA-256 avec JWT_AGENT_SECRET). Le blob est persisté dans authorizations/{authId}. Quand l'agent appelle, le serveur re-dérive la clé scoped, déchiffre la Master Key, l'utilise en mémoire le temps d'une requête, ne la persiste jamais en clair, et zéroize le buffer Node à la fin.

Toute action agent est auditée dans users/{uid}/auditLog/{id} avec actor.type = "agent", agentId, authId, scopes, IP, User-Agent. L'utilisateur voit l'historique dans Settings et peut révoquer une autorisation à tout moment (révocation immédiate : tous les tokens émis sur cet authId sont invalidés en un coup).

Quickstart curl

# 1. Discovery (pas d'auth)
curl https://baguettefiscale.fr/api/v1/discovery

# 2. (Hors band) Vous redirigez l'utilisateur vers /api/oauth/authorize
#    avec PKCE, vous récupérez un code, vous l'échangez.
# 3. Avec l'access_token :
curl -H "Authorization: Bearer $TOKEN" \
  https://baguettefiscale.fr/api/v1/me

# 4. Crée la déclaration de l'année
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tax_year": 2024}' \
  https://baguettefiscale.fr/api/v1/declarations

# 5. Patch des réponses (scopes declaration.write + profile.write)
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"patch": {"sources_revenus": ["salaire"], "salaire_fr_brut": 42000}}' \
  https://baguettefiscale.fr/api/v1/declarations/2024/answers

# 6. Calcul d'impôt
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://baguettefiscale.fr/api/v1/declarations/2024/compute

# 7. Génération PDF (paywall actif)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://baguettefiscale.fr/api/v1/declarations/2024/generate-pdf
# → 402 Payment Required + checkout_url → l'utilisateur paie → re-tente

Intégrations

Claude (MCP HTTP/SSE)

Le serveur MCP officiel est en cours de finalisation. En attendant, vous pouvez consommer l'API REST directement depuis Claude Code ou un agent custom en utilisant le flow OAuth standard.

ChatGPT (Custom GPT / Actions)

Spec OpenAPI 3.1 à venir sur /api/v1/openapi (limite ChatGPT Actions : 30 opérations, snake_case, OAuth via https://baguettefiscale.fr/.well-known/oauth-authorization-server).

Perplexity, Gemini, autres crawlers IA

llms.txt et llms-full.txt documentent le service au format llmstxt.org. robots.ts autorise GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, etc.

WebMCP (Chrome 146+)

Plusieurs pages publiques exposent des outils via navigator.modelContext et les attributs HTML déclaratifs (toolname, tooldescription). Les agents in-browser peuvent les utiliser sans OAuth puisque l'utilisateur est déjà sur le site avec sa Master Key disponible localement.

Checkbox de relecture obligatoire avant génération du PDF

L'endpoint POST /api/v1/declarations/{year}/generate-pdf (en mode complete, le seul qui produit le PDF final signé) refuse les requêtes sans le champ reviewed_and_accept_responsibility: true dans le body.

Votre application doit obtenir le consentement explicite de votre utilisateur final via votre propre UI, par exemple une case à cocher dont le libellé reprend la formulation utilisée par BaguetteFiscale :

« Je relirai ma déclaration avant envoi. BaguetteFiscale m'aide à la préparation, je reste responsable de toute erreur ou oubli. »

Le flag est audit-loggé sur users/{uid}/auditLog. Passer truesans avoir réellement obtenu ce consentement engage votre responsabilité (mini-DPA signé à l'enregistrement de votre application).

Responsabilités, conformité

BaguetteFiscale est un copilote, pas un cabinet d'expertise comptable. Votre utilisateur final reste légalement responsable du contenu de sa déclaration et c'est lui qui la dépose surimpots.gouv.fr. La page de consent rappelle cette responsabilité.

Conformité RGPD : votre application devient sous-traitant ultérieur au sens de l'article 28. À l'enregistrement, vous acceptez un mini-DPA qui interdit la revente, la mise en commun avec d'autres traitements, et l'usage hors des finalités scopées.

Contact

Question, demande d'enregistrement, bug à signaler : hello@baguettefiscale.fr.

Retour à l'accueil · llms.txt · llms-full.txt · OAuth discovery