Aller au contenu

Investor Taxation

Contrôleur HTTP de la fiscalité investisseur : historique d'imposition (prélèvement à la source) et soumission d'une demande de dispense (formulaire d'exemption fiscale). Source : taxation.controller.ts.

Tous les endpoints requièrent un JWT investisseur valide (JwtAuthGuard) et le rôle CUSTOMER (UserRoleGuard).

GET /customers/taxation

Retourne l'historique de fiscalité pour l'investisseur connecté : pour chaque année concernée, le taux applicable, le détail mensuel des prélèvements withholding_tax (statuts confirmed ou waiting) et le formulaire d'exemption éventuellement soumis (controller#L32-L79).

L'union des années provient à la fois des transactions withholding_tax (table wallet_transactions) et des demandes existantes (table investor_tax_rate_request).

Response

Type CustomerTaxationHistory :

[
  {
    "year": 2026,
    "taxRate": 30,
    "taxAmountHistory": [
      { "period": "2026-01", "amount": 1234 },
      { "period": "2026-02", "amount": 5678 }
    ],
    "taxExemptionRequestedAt": "2025-09-15T10:00:00Z",
    "taxExemptionFormAnswers": {
      "year": 2026,
      "fiscalResidence": "france",
      "socialSecurity": "france",
      "fiscalHousehold": "couple",
      "income": "<25",
      "keepPFU": false
    }
  }
]

taxRate est résolu via businessRules.taxation.getTaxRateForYear(year, taxRequest?.taxRate) : taux par défaut de l'année, écrasé par le taux issu d'une demande validée si présente.

POST /customers/taxation

Crée une demande de taux d'imposition (formulaire d'exemption fiscale) pour une année future. La demande influence le taux appliqué aux futurs prélèvements via la jointure faite par le GET /customers/taxation (controller#L81-L137).

Pré-conditions

  • Le formulaire est validé par taxExemptionForm (discriminé sur fiscalResidence)
  • computeTaxExemptionForm doit retourner un taux valide (sinon invalid-tax-exemption-form)
  • L'année visée doit être dans les années soumissibles, calculées par getPossibleTaxExemptionRequestYears :
  • Si l'investisseur n'a pas encore reçu de revenu imposable : années courante et N+1 disponibles
  • Sinon, demande pour l'année N possible jusqu'au 30 novembre N-1 (logique dans investor-tax-rate-request.service.ts)
  • Toute année déjà demandée est exclue

Request body

Variante fiscalResidence === 'france' :

{
  "year": 2027,
  "fiscalResidence": "france",
  "socialSecurity": "france",
  "fiscalHousehold": "couple",
  "income": "<25",
  "keepPFU": false
}

Variante fiscalResidence === 'abroad' :

{
  "year": 2027,
  "fiscalResidence": "abroad"
}

Effet

Insertion atomique (safePgTransaction) dans la table investor_tax_rate_request du tuple {investorId, year, taxRate, taxExemptionFormAnswers, createdAt}.

Response

Le contrôleur renvoie le résultat actualisé de GET /customers/taxation (cf. ci-dessus).

Erreurs

Code Statut Cause
investor.taxation.invalid-tax-exemption-form 400 computeTaxExemptionForm n'a pas pu calculer un taux à partir des réponses
investor.taxation.not-allowed-to-submit-tax-exemption-form 400 Hors fenêtre temporelle, ou année déjà demandée, ou revenu imposable déjà reçu pour l'année

Liens