openapi: 3.0.3
info:
  title: SalaireNet Québec Calculation API
  version: 1.0.0
  description: |
    API officielle pour calculer le salaire net après impôts au Québec et en Ontario (Canada).

    Cette API utilise les taux d'imposition officiels de 2026 pour :
    - Impôt fédéral canadien (5 tranches progressives)
    - Impôt provincial (Québec : 4 tranches, Ontario : 5 tranches)
    - Cotisations RRQ/CPP (Régime de rentes du Québec / Canada Pension Plan)
    - Cotisations RQAP (Régime québécois d'assurance parentale - Québec seulement)
    - Assurance-emploi (salariés seulement)

    **Idéal pour :**
    - Agents IA et assistants virtuels
    - Applications RH et de gestion de paie
    - Calculateurs financiers
    - Outils de planification budgétaire

    **Source des données :** Agence du revenu du Canada (ARC) et Revenu Québec

  contact:
    name: SalaireNet.ca
    url: https://salairenet.ca
  license:
    name: Public Domain
    url: https://creativecommons.org/publicdomain/zero/1.0/

servers:
  - url: https://salairenet.ca/api
    description: Production API
  - url: http://localhost:4321/api
    description: Local development

paths:
  /calculate.json:
    get:
      summary: Calculer le salaire net
      description: |
        Calcule le salaire net après toutes les déductions fiscales et cotisations sociales.

        Le calcul inclut :
        - Impôt fédéral (tranches progressives de 15% à 33%)
        - Impôt provincial (QC : 14% à 25.75%, ON : 5.05% à 13.16%)
        - RRQ/CPP (6.4% pour salariés, 12.8% pour freelance)
        - RQAP (0.494% pour salariés QC, 0.878% pour freelance QC)
        - Assurance-emploi (1.31% pour salariés seulement)

      operationId: calculateNetSalary
      tags:
        - Salary Calculation

      parameters:
        - name: amount
          in: query
          required: true
          description: Montant du salaire brut
          schema:
            type: number
            format: float
            minimum: 0
            exclusiveMinimum: true
            example: 75000

        - name: frequency
          in: query
          required: false
          description: Fréquence du montant fourni
          schema:
            type: string
            enum: [annual, monthly, hourly]
            default: annual
            example: annual

        - name: province
          in: query
          required: false
          description: Province de résidence
          schema:
            type: string
            enum: [QC, ON]
            default: QC
            example: QC

        - name: status
          in: query
          required: false
          description: Statut d'emploi
          schema:
            type: string
            enum: [salarie, freelance]
            default: salarie
            example: salarie

      responses:
        '200':
          description: Calcul réussi
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculationResponse'
              examples:
                salarie-qc:
                  summary: Salarié au Québec (75 000$ annuel)
                  value:
                    input:
                      amount: 75000
                      frequency: annual
                      province: QC
                      status: salarie
                    calculated:
                      grossAnnual: 75000
                      netAnnual: 54453.75
                      deductions:
                        federal: 8706.25
                        provincial: 6321.25
                        rrq: 4288
                        rqap: 370.5
                        ae: 860.25
                        totalDeductions: 20546.25
                      effectiveRate: 27.4
                    breakdown:
                      annual:
                        gross: 75000
                        net: 54453.75
                      monthly:
                        gross: 6250
                        net: 4537.81
                      biWeekly:
                        gross: 2884.62
                        net: 2094.38
                      weekly:
                        gross: 1442.31
                        net: 1047.19
                      hourly:
                        gross: 41.21
                        net: 29.92
                    meta:
                      year: 2026
                      calculatedAt: "2026-02-05T15:30:00.000Z"
                      source: SalaireNet.ca

                freelance-qc:
                  summary: Travailleur autonome au Québec (80 000$ annuel)
                  value:
                    input:
                      amount: 80000
                      frequency: annual
                      province: QC
                      status: freelance
                    calculated:
                      grossAnnual: 80000
                      netAnnual: 53942.4
                      deductions:
                        federal: 9331.25
                        provincial: 6871.25
                        rrq: 8576
                        rqap: 702.4
                        totalDeductions: 26057.6
                      effectiveRate: 32.6
                    breakdown:
                      annual:
                        gross: 80000
                        net: 53942.4
                      monthly:
                        gross: 6666.67
                        net: 4495.2
                    meta:
                      year: 2026
                      source: SalaireNet.ca

        '400':
          description: Paramètres invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing-amount:
                  summary: Paramètre 'amount' manquant
                  value:
                    error: Missing required parameter: amount
                    message: Please provide a gross salary amount using the "amount" query parameter.
                    example: /api/calculate.json?amount=75000&frequency=annual&province=QC&status=salarie

                invalid-province:
                  summary: Province invalide
                  value:
                    error: Invalid province
                    message: The "province" parameter must be either "QC" or "ON".
                    provided: AB

components:
  schemas:
    CalculationResponse:
      type: object
      required:
        - input
        - calculated
        - breakdown
        - meta
      properties:
        input:
          type: object
          description: Paramètres d'entrée utilisés pour le calcul
          properties:
            amount:
              type: number
              description: Montant brut fourni
            frequency:
              type: string
              enum: [annual, monthly, hourly]
              description: Fréquence du montant
            province:
              type: string
              enum: [QC, ON]
              description: Province de résidence
            status:
              type: string
              enum: [salarie, freelance]
              description: Statut d'emploi

        calculated:
          type: object
          description: Résultats du calcul
          properties:
            grossAnnual:
              type: number
              format: float
              description: Salaire brut annuel en CAD
            netAnnual:
              type: number
              format: float
              description: Salaire net annuel en CAD
            deductions:
              type: object
              description: Détail de toutes les déductions
              properties:
                federal:
                  type: number
                  format: float
                  description: Impôt fédéral annuel
                provincial:
                  type: number
                  format: float
                  description: Impôt provincial annuel
                rrq:
                  type: number
                  format: float
                  description: Cotisation RRQ/CPP annuelle
                rqap:
                  type: number
                  format: float
                  description: Cotisation RQAP annuelle (Québec seulement)
                ae:
                  type: number
                  format: float
                  description: Assurance-emploi annuelle (salariés seulement)
                totalDeductions:
                  type: number
                  format: float
                  description: Total de toutes les déductions
            effectiveRate:
              type: number
              format: float
              description: Taux effectif d'imposition en pourcentage

        breakdown:
          type: object
          description: Ventilation par période
          properties:
            annual:
              $ref: '#/components/schemas/PeriodBreakdown'
            monthly:
              $ref: '#/components/schemas/PeriodBreakdown'
            biWeekly:
              $ref: '#/components/schemas/PeriodBreakdown'
            weekly:
              $ref: '#/components/schemas/PeriodBreakdown'
            hourly:
              $ref: '#/components/schemas/PeriodBreakdown'

        meta:
          type: object
          description: Métadonnées sur le calcul
          properties:
            year:
              type: integer
              description: Année fiscale des taux utilisés
            calculatedAt:
              type: string
              format: date-time
              description: Horodatage du calcul (ISO 8601)
            source:
              type: string
              description: Source des calculs

    PeriodBreakdown:
      type: object
      properties:
        gross:
          type: number
          format: float
          description: Salaire brut pour cette période
        net:
          type: number
          format: float
          description: Salaire net pour cette période

    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Code ou type d'erreur
        message:
          type: string
          description: Message d'erreur détaillé
        provided:
          type: string
          description: Valeur fournie qui a causé l'erreur (optionnel)
        example:
          type: string
          description: Exemple d'utilisation correcte (optionnel)

tags:
  - name: Salary Calculation
    description: Endpoints de calcul de salaire net

externalDocs:
  description: Documentation complète sur SalaireNet.ca
  url: https://salairenet.ca/api-docs
