openapi: 3.0.3
info:
  title: API de Candidatos
  description: |
    API para gestionar información de candidatos con autenticación OAuth 2.0.
    Permite obtener información detallada de candidatos incluyendo datos demográficos,
    formación académica, exámenes y experiencia de servicio.
  version: 1.0.0

servers:
  - url: https://sgcd.lania.edu.mx/api_candidatos
    description: Servidor principal

security:
  - oauth2: []

paths:
  /oauth/token:
    post:
      summary: Obtener token de acceso OAuth 2.0
      description: Endpoint para obtener un token de acceso utilizando credenciales de cliente
      tags:
        - Autenticación
      security: []  # Este endpoint no requiere token previo
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials]
                  description: Tipo de autorización OAuth 2.0
                client_id:
                  type: string
                  description: Identificador del cliente
                client_secret:
                  type: string
                  description: Secreto del cliente
                scope:
                  type: string
                  description: Alcances solicitados (opcional)
      responses:
        '200':
          description: Token de acceso generado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    example: 3600
                  access_token:
                    type: string
                    example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        '400':
          description: Solicitud inválida o credenciales incorrectas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /candidatos/obtenerCandidatos:
    get:
      summary: Obtener lista de candidatos
      description: Devuelve un listado de todos los candidatos con información detallada.
      tags:
        - Candidatos
      responses:
        '200':
          description: Lista de candidatos obtenida correctamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Candidato'
        '401':
          description: No autorizado - Token de acceso inválido o expirado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://sgcd.lania.edu.mx/api_candidatos/oauth/token
          scopes: {}

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: invalid_request
        message:
          type: string
          example: El token de acceso proporcionado es inválido

    Candidato:
      type: object
      properties:
        id_candidato:
          type: string
          description: Identificador único del candidato
        nombre_completo:
          type: string
          description: Nombre completo del candidato
        contacto:
          type: object
          properties:
            correo:
              type: string
              format: email
              description: Correo electrónico del candidato
            telefono:
              type: string
              description: Número telefónico del candidato
        demograficos:
          type: object
          properties:
            genero:
              type: string
              description: Género del candidato
            rango_edad:
              type: string
              description: Rango de edad del candidato
            tipo_identificacion:
              type: string
              description: Tipo de identificación del candidato
            ubicacion:
              type: object
              properties:
                pais:
                  type: string
                  description: País de residencia
                estado:
                  type: string
                  description: Estado o provincia
                municipio:
                  type: string
                  description: Municipio o ciudad
                colonia:
                  type: string
                  description: Colonia o barrio
        formacion:
          type: object
          properties:
            nivel_estudio:
              type: string
              description: Nivel de estudios del candidato
            giro:
              type: string
              description: Sector o giro de actividad
            nombre_empresa_institucion:
              type: string
              description: Nombre de la empresa o institución donde trabaja/estudia
        examen:
          type: object
          properties:
            id_examen:
              type: string
              description: Identificador del examen
            nombre_examen:
              type: string
              description: Nombre del examen realizado
            motivo:
              type: string
              description: Motivo por el cual realizó el examen
        experiencia_servicio:
          type: object
          properties:
            calificacion_servicio:
              type: integer
              minimum: 0
              maximum: 10
              description: Calificación del servicio (0-10)
            consentimiento_publicidad:
              type: boolean
              description: Consentimiento para recibir publicidad
        fechas:
          type: object
          properties:
            entrada:
              type: string
              format: date-time
              description: Fecha y hora de entrada
            salida:
              type: string
              format: date-time
              description: Fecha y hora de salida