paths:
  /api/v1/app/getParenPlanPer:
    post:
      summary: Parentescos válidos para un plan de personas
      description: |
        Retorna los parentescos (`cparen`) disponibles para la combinación `cramo` + `cplan` indicada.

        **Dependencias de entrada:**
        | Campo  | Obtener de |
        |--------|------------|
        | `cramo` | `POST /api/v1/valrep/planesPer` → `data.plan[].cramo` |
        | `cplan` | `POST /api/v1/valrep/planesPer` → `data.plan[].cplan` |

        **Salida utilizada por:**
        - `POST /api/v1/app/getCotizacionPer` → `asegurados[].cparen`
      tags:
        - App
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParenPlanPerRequest'
            example:
              cramo: 5
              cplan: "000101"
      responses:
        '200':
          description: Parentescos disponibles para el plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParenPlanPerSuccessResponse'
              example:
                status: true
                result:
                  records:
                    - cparen: 1
                      xparentesco: "TITULAR"
                    - cparen: 2
                      xparentesco: "CÓNYUGE"
                    - cparen: 3
                      xparentesco: "HIJO/A"
        '400':
          description: Parámetros faltantes o inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppValidationErrorResponse'
              examples:
                faltaCramo:
                  summary: cramo no enviado
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "cramo"
                        mensaje: "El parámetro 'cramo' es requerido."
                faltaCplan:
                  summary: cplan no enviado
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "cplan"
                        mensaje: "El parámetro 'cplan' es requerido."

  /api/v1/app/getCotizacionPer:
    post:
      summary: Cotización de póliza de personas
      description: |
        Calcula la prima para cada asegurado del array.

        **Flujo recomendado (llamar en este orden):**
        1. `POST /api/v1/valrep/planesPer` → obtener `cramo` y `cplan` válidos.
        2. `POST /api/v1/app/getParenPlanPer` → obtener los `cparen` disponibles para ese plan.
        3. `POST /api/v1/app/getCotizacionPer` → calcular la prima con los datos obtenidos.

        **Dependencias de entrada:**
        | Campo | Obtener de |
        |-------|------------|
        | `cramo` | `POST /api/v1/valrep/planesPer` → `data.plan[].cramo` |
        | `cplan` | `POST /api/v1/valrep/planesPer` → `data.plan[].cplan` |
        | `asegurados[].cparen` | `POST /api/v1/app/getParenPlanPer` → `result.records[].cparen` |

        **Reglas de uso:**
        - `asegurados` debe contener al menos un elemento.
        - `ifrecuencia` acepta: `A` Anual · `S` Semestral · `T` Trimestral · `M` Mensual.
        - `msumaaseg` es opcional; si se omite o es `null`, el SP usa el valor del plan.
        - `ptasamon` puede omitirse; el servicio lo toma automáticamente de la tasa BCV interna.
      tags:
        - App
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CotizacionPerRequest'
            examples:
              basico:
                summary: Cotización con un asegurado
                value:
                  cramo: 5
                  cplan: "000101"
                  ptasamon: 40.50
                  ifrecuencia: "A"
                  msumaaseg: null
                  asegurados:
                    - cparen: 1
                      xrif_asegurado: "25221952"
                      nedad_asegurado: 35
              multiples:
                summary: Cotización con titular y cónyuge
                value:
                  cramo: 5
                  cplan: "000101"
                  ptasamon: 40.50
                  ifrecuencia: "A"
                  msumaaseg: null
                  asegurados:
                    - cparen: 1
                      xrif_asegurado: "25221952"
                      nedad_asegurado: 35
                    - cparen: 2
                      xrif_asegurado: "18345678"
                      nedad_asegurado: 32
      responses:
        '200':
          description: Cotización calculada correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CotizacionPerSuccessResponse'
              example:
                status: true
                result:
                  data:
                    - total_asegurado:
                        - mprima: 150.00
                          mprimaext: 3.70
                    - total_asegurado:
                        - mprima: 130.00
                          mprimaext: 3.21
                  total_extension:
                    mprimatotal: 280.00
                    mprimatotalext: 6.91
        '400':
          description: Parámetros faltantes/inválidos o error retornado por el SP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppValidationErrorResponse'
              examples:
                faltaCramo:
                  summary: cramo no enviado
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "cramo"
                        mensaje: "El parámetro 'cramo' es requerido."
                faltaCplan:
                  summary: cplan no enviado
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "cplan"
                        mensaje: "El parámetro 'cplan' es requerido."
                faltaIfrecuencia:
                  summary: ifrecuencia no enviado
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "ifrecuencia"
                        mensaje: "El parámetro 'ifrecuencia' es requerido."
                aseguradosVacio:
                  summary: asegurados vacío o sin elementos
                  value:
                    status: false
                    message: "Parámetros de entrada inválidos."
                    errors:
                      - campo: "asegurados"
                        mensaje: "El parámetro 'asegurados' es requerido."
                errorSP:
                  summary: Error retornado por el SP (tarifa no encontrada)
                  value:
                    status: false
                    result:
                      error: true
                      result:
                        error: "No se encontró tarifa para el plan indicado."
                        message: "Ha ocurrido un error en el procesamiento."

components:
  schemas:
    AppValidationErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: "Parámetros de entrada inválidos."
        errors:
          type: array
          items:
            type: object
            properties:
              campo:
                type: string
                example: "cramo"
              mensaje:
                type: string
                example: "El parámetro 'cramo' es requerido."

    ParenPlanPerRequest:
      type: object
      required:
        - cramo
        - cplan
      properties:
        cramo:
          type: integer
          description: >
            Código del ramo. **Obtener de** `POST /api/v1/valrep/planesPer`
            → campo `data.plan[].cramo`.
          example: 5
        cplan:
          type: string
          maxLength: 10
          description: >
            Código del plan. **Obtener de** `POST /api/v1/valrep/planesPer`
            → campo `data.plan[].cplan`.
          example: "000101"

    ParenPlanPerRecord:
      type: object
      properties:
        cparen:
          type: integer
          description: >
            Código de parentesco. Usado en `POST /api/v1/app/getCotizacionPer`
            → `asegurados[].cparen`.
          example: 1
        xparentesco:
          type: string
          description: Descripción del parentesco.
          example: "TITULAR"

    ParenPlanPerSuccessResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        result:
          type: object
          properties:
            records:
              type: array
              description: >
                Lista de parentescos disponibles para el plan consultado.
                Los valores de `cparen` son requeridos por
                `POST /api/v1/app/getCotizacionPer` → `asegurados[].cparen`.
              items:
                $ref: '#/components/schemas/ParenPlanPerRecord'

    CotizacionPerAsegurado:
      type: object
      required:
        - cparen
        - xrif_asegurado
        - nedad_asegurado
      properties:
        cparen:
          type: integer
          description: >
            Código de parentesco del asegurado. **Obtener de**
            `POST /api/v1/app/getParenPlanPer` → `result.records[].cparen`.
          example: 1
        xrif_asegurado:
          type: string
          maxLength: 10
          description: RIF numérico del asegurado (sin prefijo de letra).
          example: "25221952"
        nedad_asegurado:
          type: integer
          description: Edad del asegurado en años completos al momento de la cotización.
          example: 35

    CotizacionPerRequest:
      type: object
      required:
        - cramo
        - cplan
        - ptasamon
        - ifrecuencia
        - asegurados
      properties:
        cramo:
          type: integer
          description: >
            Código del ramo. **Obtener de** `POST /api/v1/valrep/planesPer`
            → campo `data.plan[].cramo`.
          example: 5
        cplan:
          type: string
          maxLength: 10
          description: >
            Código del plan de personas. **Obtener de** `POST /api/v1/valrep/planesPer`
            → campo `data.plan[].cplan`.
          example: "000101"
        ptasamon:
          type: number
          format: float
          description: >
            Tasa de cambio BCV para el cálculo en moneda extranjera.
            Si se omite, el servicio usa la tasa BCV interna actualizada automáticamente.
            **Obtener de** `GET /api/v1/valrep/tasaBCV` → campo `ptasamon`.
          example: 40.50
        ifrecuencia:
          type: string
          minLength: 1
          maxLength: 1
          enum: ["A", "S", "T", "M"]
          description: |
            Frecuencia de pago:
            - `A` — Anual
            - `S` — Semestral
            - `T` — Trimestral
            - `M` — Mensual
          example: "A"
        msumaaseg:
          type: number
          format: float
          nullable: true
          description: Suma asegurada. Si es `null` o se omite, el SP usa el valor configurado en el plan.
          example: null
        asegurados:
          type: array
          minItems: 1
          description: >
            Lista de asegurados a cotizar. Debe contener al menos un elemento.
            Los valores de `cparen` se obtienen de
            `POST /api/v1/app/getParenPlanPer` → `result.records[].cparen`.
          items:
            $ref: '#/components/schemas/CotizacionPerAsegurado'

    CotizacionPerTotalAsegurado:
      type: object
      properties:
        mprima:
          type: number
          format: float
          description: Prima en moneda local (Bs) para este asegurado.
          example: 150.00
        mprimaext:
          type: number
          format: float
          description: Prima en moneda extranjera (USD) para este asegurado.
          example: 3.70

    CotizacionPerDataItem:
      type: object
      properties:
        total_asegurado:
          type: array
          items:
            $ref: '#/components/schemas/CotizacionPerTotalAsegurado'

    CotizacionPerSuccessResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        result:
          type: object
          properties:
            data:
              type: array
              description: Un elemento por cada asegurado enviado, en el mismo orden del request.
              items:
                $ref: '#/components/schemas/CotizacionPerDataItem'
            total_extension:
              type: object
              description: Totales acumulados de todos los asegurados.
              properties:
                mprimatotal:
                  type: number
                  format: float
                  description: Suma de primas en moneda local (Bs).
                  example: 280.00
                mprimatotalext:
                  type: number
                  format: float
                  description: Suma de primas en moneda extranjera (USD).
                  example: 6.91

    CotizacionPerErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        result:
          type: object
          properties:
            error:
              type: boolean
              example: true
            result:
              type: object
              properties:
                error:
                  type: string
                  example: "No se encontró tarifa para el plan indicado."
                message:
                  type: string
                  example: "Ha ocurrido un error en el procesamiento."
