paths:
  /api/v1/valrep/state:
    post:
      summary: Catálogo de estados/provincias
      description: |
        Retorna los estados disponibles. Permite filtrar por país y/o estado específico.

        **Salida utilizada por:**
        - `POST /api/v1/valrep/city` → campo `cestado`
      tags:
        - Valrep
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValrepStateRequest'
            examples:
              sinFiltro:
                summary: Sin filtro (todos los estados)
                value: {}
              porPais:
                summary: Filtrar por país
                value:
                  cpais: 1
              porEstado:
                summary: Filtrar por estado específico
                value:
                  cpais: 1
                  cestado: 20
      responses:
        '200':
          description: Estados disponibles
          content:
            application/json:
              example:
                status: true
                data:
                  - cestado: 1
                    xestado: "DISTRITO CAPITAL"
                  - cestado: 2
                    xestado: "AMAZONAS"
        '400':
          description: Parámetros inválidos
          content:
            application/json:
              example:
                status: false
                message: "Parámetros de entrada inválidos."
                errors:
                  - campo: cpais
                    mensaje: "El parámetro 'cpais' debe ser un número positivo."
        '500':
          description: Error interno del servidor

  /api/v1/valrep/city:
    post:
      summary: Catálogo de ciudades/municipios
      description: |
        Retorna las ciudades disponibles. Permite filtrar por país, estado y/o ciudad específica.

        **Dependencias de entrada:**
        | Campo | Obtener de |
        |-------|------------|
        | `cestado` | `POST /api/v1/valrep/state` → `data[].cestado` |
      tags:
        - Valrep
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValrepCityRequest'
            examples:
              sinFiltro:
                summary: Sin filtro (todas las ciudades)
                value: {}
              porEstado:
                summary: Filtrar por estado
                value:
                  cpais: 1
                  cestado: 23
              porCiudad:
                summary: Ciudad específica
                value:
                  cpais: 1
                  cestado: 23
                  cciudad: 182
      responses:
        '200':
          description: Ciudades disponibles
          content:
            application/json:
              example:
                status: true
                data:
                  - cciudad: 182
                    xciudad: "LA GUAIRA"
        '400':
          description: Parámetros inválidos
        '500':
          description: Error interno del servidor

  /api/v1/valrep/macategtr:
    post:
      summary: Categoría de vehículo por código
      description: Retorna la descripción y datos de la categoría de vehículo para el código indicado.
      tags:
        - Valrep
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValrepMacategtrRequest'
            example:
              categoria: 1
      responses:
        '200':
          description: Categoría encontrada
          content:
            application/json:
              example:
                status: true
                data:
                  - ccategoria: 1
                    xcategoria: "PARTICULAR"
        '400':
          description: Parámetros inválidos
          content:
            application/json:
              example:
                status: false
                message: "Parámetros de entrada inválidos."
                errors:
                  - campo: categoria
                    mensaje: "El parámetro 'categoria' es requerido."
        '500':
          description: Error interno del servidor

  /api/v1/valrep/planesPer:
    post:
      summary: Planes de personas vigentes
      description: |
        Retorna todos los planes vigentes de personas.

        **Salida utilizada por:**
        - `POST /api/v1/app/getParenPlanPer` → campos `cramo` y `cplan`
        - `POST /api/v1/app/getCotizacionPer` → campos `cramo` y `cplan`
      tags:
        - Valrep
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
            example: {}
      responses:
        '200':
          description: Planes de personas obtenidos correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanesPeResponse'
              example:
                status: true
                data:
                  plan:
                    - cramo: 5
                      cplan: "000101"
                      xplan: "VIDA INDIVIDUAL BASICO"
                    - cramo: 9
                      cplan: "000201"
                      xplan: "FUNERAL FAMILIAR"
        '500':
          description: Error interno del servidor
          content:
            application/json:
              example:
                status: false
                message: "Ha ocurrido un error en el procesamiento."

  /api/v1/valrep/list/SEXO:
    get:
      summary: Catálogo de sexos
      description: |
        Retorna la lista de sexos.

        Valores típicos:
        - `M` — Masculino
        - `F` — Femenino

        **Salida utilizada por:**
        - Endpoints de emisión de pólizas → campo `isexo` del tomador/titular.
      tags:
        - Valrep
      responses:
        '200':
          description: Catálogo de sexos obtenido correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListSuccessResponse'
              example:
                status: true
                data:
                  - isexo: "M"
                    xsexo: "MASCULINO"
                  - isexo: "F"
                    xsexo: "FEMENINO"
        '400':
          description: Tipo de lista inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "El parámetro 'tipo' debe ser uno de: SEXO, EDOCIVIL, PARENTESCOS."
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "Ha ocurrido un error al obtener el catálogo."

  /api/v1/valrep/list/EDOCIVIL:
    get:
      summary: Catálogo de estados civiles
      description: |
        Retorna la lista de estados civiles.

        Valores típicos:
        - `S` — Soltero/a
        - `C` — Casado/a
        - `D` — Divorciado/a
        - `V` — Viudo/a
        - `U` — Unión estable de hecho

        **Salida utilizada por:**
        - Endpoints de emisión de pólizas → campo `iestado_civil` del tomador/titular.
      tags:
        - Valrep
      responses:
        '200':
          description: Catálogo de estados civiles obtenido correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListSuccessResponse'
              example:
                status: true
                data:
                  - iestado_civil: "S"
                    xestado_civil: "SOLTERO/A"
                  - iestado_civil: "C"
                    xestado_civil: "CASADO/A"
                  - iestado_civil: "D"
                    xestado_civil: "DIVORCIADO/A"
                  - iestado_civil: "V"
                    xestado_civil: "VIUDO/A"
                  - iestado_civil: "U"
                    xestado_civil: "UNIÓN ESTABLE DE HECHO"
        '400':
          description: Tipo de lista inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "El parámetro 'tipo' debe ser uno de: SEXO, EDOCIVIL, PARENTESCOS."
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "Ha ocurrido un error al obtener el catálogo."

  /api/v1/valrep/list/PARENTESCOS:
    get:
      summary: Catálogo de parentescos
      description: |
        Retorna la lista de parentescos.

        El campo `bunavez` indica si el parentesco solo puede aparecer una vez por póliza
        (`true` = sí, `false` = no).

        **Salida utilizada por:**
        - `POST /api/v1/app/getParenPlanPer` → el campo `cparen` de esta respuesta es
          el mismo que devuelve ese endpoint; úsala para conocer la descripción del parentesco.
        - `POST /api/v1/app/getCotizacionPer` → `asegurados[].cparen`.
      tags:
        - Valrep
      responses:
        '200':
          description: Catálogo de parentescos obtenido correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListSuccessResponse'
              example:
                status: true
                data:
                  - cparen: 1
                    xparentesco: "TITULAR"
                    bunavez: true
                  - cparen: 2
                    xparentesco: "CÓNYUGE"
                    bunavez: true
                  - cparen: 3
                    xparentesco: "HIJO/A"
                    bunavez: false
        '400':
          description: Tipo de lista inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "El parámetro 'tipo' debe ser uno de: SEXO, EDOCIVIL, PARENTESCOS."
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValrepListErrorResponse'
              example:
                status: false
                message: "Ha ocurrido un error al obtener el catálogo."

components:
  schemas:
    PlanesPeResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        data:
          type: object
          properties:
            plan:
              type: array
              description: >
                Lista de planes de personas vigentes.
                Los campos `cramo` y `cplan` de cada elemento son requeridos por
                `POST /api/v1/app/getParenPlanPer` y `POST /api/v1/app/getCotizacionPer`.
              items:
                type: object
                properties:
                  cramo:
                    type: integer
                    description: >
                      Código del ramo. Requerido en
                      `POST /api/v1/app/getParenPlanPer` y
                      `POST /api/v1/app/getCotizacionPer` → campo `cramo`.
                    example: 5
                  cplan:
                    type: string
                    description: >
                      Código del plan. Requerido en
                      `POST /api/v1/app/getParenPlanPer` y
                      `POST /api/v1/app/getCotizacionPer` → campo `cplan`.
                    example: "000101"
                  xplan:
                    type: string
                    description: Nombre descriptivo del plan.
                    example: "VIDA INDIVIDUAL BASICO"

    ValrepListSuccessResponse:
      type: object
      properties:
        status:
          type: boolean
          example: true
        data:
          type: array
          description: Lista de ítems del catálogo solicitado.
          items:
            type: object
            additionalProperties: true

    ValrepListErrorResponse:
      type: object
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: "Mensaje de error"

    ValrepStateRequest:
      type: object
      properties:
        cpais:
          type: integer
          nullable: true
          description: Código de país. Filtro opcional.
          example: 1
        cestado:
          type: integer
          nullable: true
          description: >
            Código de estado. Filtro opcional para obtener un estado específico.
            El valor retornado (`data[].cestado`) es requerido por
            `POST /api/v1/valrep/city` → campo `cestado`.
          example: 20

    ValrepCityRequest:
      type: object
      properties:
        cpais:
          type: integer
          nullable: true
          description: Código de país. Filtro opcional.
          example: 1
        cestado:
          type: integer
          nullable: true
          description: >
            Código de estado. **Obtener de** `POST /api/v1/valrep/state`
            → campo `data[].cestado`.
          example: 23
        cciudad:
          type: integer
          nullable: true
          description: >
            Código de ciudad. Filtro opcional para obtener una ciudad específica.
            Si se omite, retorna todas las ciudades del estado indicado.
          example: 182

    ValrepMacategtrRequest:
      type: object
      required: [categoria]
      properties:
        categoria:
          type: integer
          minimum: 1
          description: Código de categoría de vehículo.
          example: 1
