paths:
  /api/v1/valrep/planes/v2:
    post:
      summary: Consulta planes por entidad con validaciones de negocio
      description: |
        Retorna planes disponibles para la entidad consultada con validaciones de negocio.

        **Reglas de uso:**
        - `centidad` es obligatorio: `P` Productor · `C` Canal · `G` Gestor.
        - `citem` identifica el código de la entidad según `centidad`.
        - `cusuario` es requerido por auditoría.
        - Si `cramo` se omite o es nulo, retorna todos los ramos excepto automóvil.
        - Para ramos de automóvil (`18`, `28`) se debe enviar `ctipo`.
        - `iplaca = "B"` indica consulta binacional.

        **Salida utilizada por:**
        - `POST /api/v1/external/validateEmissionPerson` → campos `cramo` y `plan`
        - `POST /api/v1/external/validateEmissionAuto` → campo `plan`
        - `POST /api/v1/external/createEmissionAuto` → campos `cramo` y `cplan`
        - `POST /api/v1/external/createEmissionPerson` → campos `cramo` y `cplan`
      tags:
        - Valrep
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValrepPlanesV2Request"
            examples:
              sinRamo:
                summary: Sin definir ramo. Obtiene todo Personas
                value:
                  cusuario: 25221952
                  citem: "205"
                  centidad: "P"
              conRamo:
                summary: Definiendo ramo. Obtiene solo el ramo indicado
                value:
                  cramo: 9
                  cusuario: 25221952
                  citem: "205"
                  centidad: "P"
              ramoAutomovil:
                summary: Definiendo ramo automóvil. Obligatorio el ctipo
                value:
                  cramo: 18
                  ctipo: 1
                  cusuario: 25221952
                  citem: "205"
                  centidad: "P"
              ramoAutomovilBinacional:
                summary: Definiendo el ramo automóvil (binacional)
                value:
                  cramo: 28
                  ctipo: 1
                  cusuario: 25221952
                  citem: "205"
                  centidad: "P"
                  iplaca: "B"
      responses:
        "200":
          description: Consulta de planes realizada correctamente
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValrepPlanesV2SuccessResponse"
              examples:
                ok:
                  value:
                    status: true
                    data:
                      plan:
                        - cramo: 5
                          cplan: "000101"
                          xplan: "Plan Salud Individual"
                          parentescos:
                            - cparen: 1
                              xparentesco: "TITULAR"
                              min_edad: 0
                              max_edad: 69
                          coberturas:
                            - ccobertura: 10
                              xcobertura: "MUERTE ACCIDENTAL"
                      mensaje: null
        "400":
          description: Error de validación de parámetros obligatorios
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValrepErrorResponse"
              examples:
                faltaCentidad:
                  value:
                    status: false
                    message: "El campo centidad es obligatorio."
                faltaCitem:
                  value:
                    status: false
                    message: "El campo citem es obligatorio."
                faltaCtipoAuto:
                  value:
                    status: false
                    message: "Para ramo 18 o 28 el campo ctipo es obligatorio."
        "403":
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValrepErrorResponse"
              example:
                status: false
                message: "No tiene permisos para realizar esta acción"
        "500":
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValrepErrorResponse"
              example:
                status: false
                message: "Ha ocurrido un error en el procesamiento."

components:
  schemas:
    ValrepPlanesV2Request:
      type: object
      required:
        - centidad
        - citem
        - cusuario
      properties:
        centidad:
          type: string
          minLength: 1
          maxLength: 1
          enum: ["P", "C", "G"]
          description: Tipo de entidad consultada.
          example: "P"
        citem:
          type: string
          minLength: 1
          description: Identificador de la entidad según `centidad`.
          example: "215"
        cusuario:
          type: integer
          description: Código de usuario para auditoría.
          example: 1024
        cramo:
          type: integer
          nullable: true
          description: |
            Ramo a consultar.
            Si no se envía o va nulo, la API retorna todos los ramos excepto automóvil (`18`, `28`).
          example: 18
        ctipo:
          type: integer
          nullable: true
          description: |
            Tipo de riesgo/vehículo.
            Obligatorio cuando `cramo` es `18` o `28`.
          example: 5
        iplaca:
          nullable: true
          description: |
            Indicador binacional.
            Puede enviarse como booleano (`true/false`) o como `"B"` para representar `true`.
          oneOf:
            - type: boolean
            - type: string
              enum: ["B"]
          example: "B"
    ValrepPlanesV2SuccessResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        data:
          type: object
          properties:
            plan:
              type: array
              description: >
                Listado de planes resultante de la consulta.
                Los campos `cramo` y `cplan` de cada elemento son requeridos por
                `validateEmissionPerson`, `validateEmissionAuto`,
                `createEmissionAuto` y `createEmissionPerson`.
                El array `parentescos[].cparen` es requerido por
                `POST /api/v1/app/getCotizacionPer` → `asegurados[].cparen`.
              items:
                type: object
                additionalProperties: true
            mensaje:
              type: string
              nullable: true
              description: Mensaje informativo de la consulta.
              example: null
    ValrepErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: "Mensaje de error"
