openapi: 3.1.0
info:
  title: ComparaPA API
  version: 1.0.0
  description: >-
    Comparador financiero independiente para Panamá. Datos con base en
    tarifarios oficiales de la Superintendencia de Bancos de Panamá (SBP) y la
    ACODECO.
  contact:
    name: ComparaPA
    url: https://www.comparapa.com/developers
  license:
    name: UNLICENSED
    url: https://www.comparapa.com/terms
servers:
  - url: https://www.comparapa.com
    description: Producción
tags:
  - name: Catálogo
    description: Productos financieros panameños
  - name: Referencia
    description: Tasas y entidades regulatorias
  - name: Cálculos
    description: Motores de cálculo tributario y financiero
paths:
  /api/v1/products:
    get:
      operationId: listProducts
      summary: Catálogo de productos financieros
      description: >-
        Devuelve tarjetas de crédito, préstamos, seguros y cuentas de ahorro
        disponibles en Panamá. Se puede filtrar por categoría, banco o etiqueta
        de beneficio.
      tags:
        - Catálogo
      parameters:
        - name: category
          in: query
          description: >-
            Slug público de la categoría (por ejemplo: tarjetas-de-credito,
            prestamos-personales, seguros).
          schema:
            type: string
        - name: bank
          in: query
          description: >-
            Nombre o slug del banco/aseguradora (por ejemplo: Banco General,
            bac-credomatic).
          schema:
            type: string
        - name: tag
          in: query
          description: >-
            Etiqueta de beneficio (por ejemplo: cashback, sin-anualidad,
            aprobacion-rapida).
          schema:
            type: string
      responses:
        "200":
          description: Lista de productos filtrados
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - count
                  - filters
                  - data
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                  filters:
                    type: object
                    properties:
                      category:
                        type:
                          - string
                          - "null"
                      bank:
                        type:
                          - string
                          - "null"
                      tag:
                        type:
                          - string
                          - "null"
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
  /api/v1/rates:
    get:
      operationId: getRates
      summary: Tasas y parámetros legales de referencia
      description: >-
        Parámetros estatutarios usados por las calculadoras: CSS 9.75%, Seguro
        Educativo 1.25% y tramos progresivos del ISR de la DGI.
      tags:
        - Referencia
      responses:
        "200":
          description: Parámetros legales de referencia
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - data
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    required:
                      - cssEmployeeRate
                      - educativoRate
                      - isrBrackets
                      - source
                    properties:
                      cssEmployeeRate:
                        type: number
                        example: 0.0975
                      educativoRate:
                        type: number
                        example: 0.0125
                      isrBrackets:
                        type: array
                        items:
                          type: object
                          properties:
                            upperBound:
                              type: number
                            rate:
                              type: number
                      deductionCaps:
                        type: object
                      source:
                        type: string
  /api/v1/banks:
    get:
      operationId: listBanks
      summary: Directorio de entidades bancarias y aseguradoras
      description: >-
        Listado de instituciones financieras y aseguradoras autorizadas en
        Panamá presentes en el catálogo de ComparaPA.
      tags:
        - Referencia
      responses:
        "200":
          description: Directorio de entidades
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - count
                  - data
                properties:
                  status:
                    type: string
                    example: success
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Bank"
  /api/v1/calculators/salario-neto:
    post:
      operationId: calculateNetSalary
      summary: Calculadora de salario neto panameño
      description: >-
        Calcula el salario líquido mensual descontando CSS (9.75%), Seguro
        Educativo (1.25%) e ISR progresivo de la DGI.
      tags:
        - Cálculos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grossMonthly
              properties:
                grossMonthly:
                  type: number
                  minimum: 0
                  description: Salario bruto mensual en balboas (B/.).
                  example: 1500
      responses:
        "200":
          description: Desglose del salario neto
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - data
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: "#/components/schemas/NetSalaryResult"
        "400":
          description: Entrada inválida
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - error
                properties:
                  status:
                    type: string
                    example: error
                  error:
                    type: string
components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - bank
        - category
        - benefits
        - metrics
        - canonicalUrl
      properties:
        id:
          type: string
        name:
          type: string
        bank:
          type: string
        category:
          type: string
        benefits:
          type: array
          items:
            type: string
        metrics:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
              numeric:
                type: number
              hot:
                type: boolean
        canonicalUrl:
          type: string
          format: uri
    Bank:
      type: object
      required:
        - slug
        - name
        - description
        - productCount
      properties:
        slug:
          type: string
        name:
          type: string
        description:
          type: string
        productCount:
          type: integer
    NetSalaryResult:
      type: object
      required:
        - grossMonthly
        - grossAnnual
        - cssMonthly
        - educativoMonthly
        - isrAnnual
        - isrMonthly
        - totalDeductionsMonthly
        - netMonthly
        - netAnnual
      properties:
        grossMonthly:
          type: number
        grossAnnual:
          type: number
        cssMonthly:
          type: number
        educativoMonthly:
          type: number
        isrAnnual:
          type: number
        isrMonthly:
          type: number
        totalDeductionsMonthly:
          type: number
        netMonthly:
          type: number
        netAnnual:
          type: number