openapi: 3.0.3
info:
  title: WSCONCILIA API Laravel
  description: |
    API REST migrada desde archivos PHP originales (ObtenCiudades.php y ObtenEmpresas.php) a Laravel.
    
    Esta API proporciona acceso a datos de ciudades y empresas almacenados en SQL Server,
    manteniendo la compatibilidad con los procedimientos almacenados existentes mientras
    añade las ventajas del framework Laravel.
    
    ## Características
    - Migración completa desde PHP vanilla a Laravel
    - Compatibilidad con procedimientos almacenados existentes
    - Respuestas JSON estructuradas y consistentes
    - Manejo de errores mejorado
    - Arquitectura escalable y mantenible
    
    ## Base de Datos
    - **Servidor:** 10.201.84.3 (SQL Server)
    - **Base de datos:** personal
    - **Procedimientos almacenados:** sapObtenListadoCiudadesxNombre, sapObtenEmpresas
    
    ## Formato de Respuesta
    Todas las respuestas siguen el formato estándar:
    ```json
    {
      "tipo": 0,     // 0 = éxito, 1 = error
      "mensaje": "OK", 
      "data": [...] 
    }
    ```
  version: 1.0.0
  contact:
    name: Soporte WSCONCILIA API
    email: soporte@wsconcilia.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8000/api
    description: Servidor de desarrollo
  - url: https://api.wsconcilia.com/api
    description: Servidor de producción

tags:
  - name: Health
    description: Monitoreo y estado del API
  - name: Info
    description: Información y documentación del API
  - name: Ciudades
    description: Operaciones relacionadas con ciudades (migrado desde ObtenCiudades.php)
  - name: Empresas
    description: Operaciones relacionadas con empresas (migrado desde ObtenEmpresas.php)

paths:
  /health:
    get:
      tags:
        - Health
      summary: Verificar estado de salud del API
      description: |
        Endpoint para verificar que el API está funcionando correctamente.
        No requiere conexión a base de datos.
      operationId: getHealthCheck
      responses:
        '200':
          description: API funcionando correctamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "OK"
                  message:
                    type: string
                    example: "WSCONCILIA API está funcionando"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2025-09-12T11:30:00Z"
                  version:
                    type: string
                    example: "1.0.0"
              examples:
                success:
                  summary: Respuesta exitosa
                  value:
                    status: "OK"
                    message: "WSCONCILIA API está funcionando"
                    timestamp: "2025-09-12T11:30:00Z"
                    version: "1.0.0"

  /info:
    get:
      tags:
        - Info
      summary: Información completa del API
      description: |
        Retorna información detallada sobre el API, incluyendo todos los endpoints disponibles,
        configuración de base de datos y documentación automática.
      operationId: getApiInfo
      responses:
        '200':
          description: Información del API
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_name:
                    type: string
                    example: "WSCONCILIA API"
                  version:
                    type: string
                    example: "1.0.0"
                  description:
                    type: string
                    example: "API para obtener ciudades y empresas migrado desde archivos PHP originales"
                  endpoints:
                    type: object
                    additionalProperties:
                      type: string
                  database:
                    type: object
                    properties:
                      driver:
                        type: string
                        example: "sqlsrv"
                      host:
                        type: string
                        example: "10.201.84.3"
                      database:
                        type: string
                        example: "personal"

  /v1/ciudades:
    get:
      tags:
        - Ciudades
      summary: Obtener listado de ciudades
      description: |
        Obtiene el listado completo de ciudades usando el procedimiento almacenado 
        `sapObtenListadoCiudadesxNombre`. 
        
        **Migrado desde:** ObtenCiudades.php
        **Procedimiento:** sapObtenListadoCiudadesxNombre
      operationId: getCiudades
      responses:
        '200':
          description: Listado de ciudades obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiudadesResponse'
              examples:
                success:
                  summary: Respuesta exitosa
                  value:
                    tipo: 0
                    mensaje: "OK"
                    data:
                      - id: 1
                        nombre: "Ciudad de México"
                        codigo: "CDMX"
                        estado_id: 9
                        activo: true
                      - id: 2
                        nombre: "Guadalajara"
                        codigo: "GDL"
                        estado_id: 14
                        activo: true
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                database_error:
                  summary: Error de base de datos
                  value:
                    tipo: 1
                    mensaje: "Error al obtener ciudades: No se pudo conectar a la base de datos"
                    data: []

  /v1/ciudades-alt:
    get:
      tags:
        - Ciudades
      summary: Obtener ciudades (método alternativo)
      description: |
        Obtiene el listado de ciudades usando Query Builder de Laravel en lugar 
        del procedimiento almacenado. Proporciona mayor flexibilidad para filtros y ordenamiento.
        
        **Método:** Query Builder Laravel
        **Tabla:** ciudades
      operationId: getCiudadesAlternativo
      parameters:
        - name: activo
          in: query
          description: Filtrar solo ciudades activas
          required: false
          schema:
            type: boolean
            default: true
        - name: estado_id
          in: query
          description: Filtrar por ID de estado
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Listado de ciudades obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiudadesResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/empresas:
    get:
      tags:
        - Empresas
      summary: Obtener listado de empresas
      description: |
        Obtiene el listado completo de empresas usando el procedimiento almacenado 
        `sapObtenEmpresas`.
        
        **Migrado desde:** ObtenEmpresas.php
        **Procedimiento:** sapObtenEmpresas
      operationId: getEmpresas
      responses:
        '200':
          description: Listado de empresas obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmpresasResponse'
              examples:
                success:
                  summary: Respuesta exitosa
                  value:
                    tipo: 0
                    mensaje: "OK"
                    data:
                      - id: 1
                        nombre: "Empresa Ejemplo S.A. de C.V."
                        rfc: "EEJ890123ABC"
                        direccion: "Av. Principal 123, Col. Centro"
                        telefono: "+52 55 1234 5678"
                        email: "contacto@ejemplo.com"
                        activo: true
                      - id: 2
                        nombre: "Corporativo XYZ"
                        rfc: "CXY901234DEF"
                        direccion: "Blvd. Secundario 456, Col. Industrial"
                        telefono: "+52 33 9876 5432"
                        email: "info@xyz.com"
                        activo: true
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/empresas-alt:
    get:
      tags:
        - Empresas
      summary: Obtener empresas (método alternativo)
      description: |
        Obtiene el listado de empresas usando Query Builder de Laravel en lugar 
        del procedimiento almacenado. Permite filtros y ordenamiento avanzados.
        
        **Método:** Query Builder Laravel
        **Tabla:** empresas
      operationId: getEmpresasAlternativo
      parameters:
        - name: activo
          in: query
          description: Filtrar solo empresas activas
          required: false
          schema:
            type: boolean
            default: true
        - name: search
          in: query
          description: Buscar por nombre o RFC de empresa
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Listado de empresas obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmpresasResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/empresas/{id}:
    get:
      tags:
        - Empresas
      summary: Obtener empresa específica por ID
      description: |
        Obtiene los detalles de una empresa específica mediante su ID único.
        
        **Funcionalidad nueva:** No existe en archivos PHP originales
      operationId: getEmpresaPorId
      parameters:
        - name: id
          in: path
          description: ID único de la empresa
          required: true
          schema:
            type: integer
            minimum: 1
          example: 1
      responses:
        '200':
          description: Empresa encontrada exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  tipo:
                    type: integer
                    example: 0
                  mensaje:
                    type: string
                    example: "OK"
                  data:
                    $ref: '#/components/schemas/Empresa'
              examples:
                success:
                  summary: Empresa encontrada
                  value:
                    tipo: 0
                    mensaje: "OK"
                    data:
                      id: 1
                      nombre: "Empresa Ejemplo S.A. de C.V."
                      rfc: "EEJ890123ABC"
                      direccion: "Av. Principal 123, Col. Centro"
                      telefono: "+52 55 1234 5678"
                      email: "contacto@ejemplo.com"
                      activo: true
        '404':
          description: Empresa no encontrada
          content:
            application/json:
              schema:
                type: object
                properties:
                  tipo:
                    type: integer
                    example: 1
                  mensaje:
                    type: string
                    example: "Empresa no encontrada"
                  data:
                    type: null
                    example: null
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    Ciudad:
      type: object
      description: Modelo de ciudad
      properties:
        id:
          type: integer
          description: ID único de la ciudad
          example: 1
        nombre:
          type: string
          description: Nombre de la ciudad
          example: "Ciudad de México"
        codigo:
          type: string
          description: Código de la ciudad
          example: "CDMX"
        estado_id:
          type: integer
          description: ID del estado al que pertenece
          example: 9
        activo:
          type: boolean
          description: Indica si la ciudad está activa
          example: true
        created_at:
          type: string
          format: date-time
          description: Fecha de creación
          example: "2024-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Fecha de última actualización
          example: "2024-01-01T00:00:00Z"

    Empresa:
      type: object
      description: Modelo de empresa
      properties:
        id:
          type: integer
          description: ID único de la empresa
          example: 1
        nombre:
          type: string
          description: Nombre o razón social de la empresa
          example: "Empresa Ejemplo S.A. de C.V."
        rfc:
          type: string
          description: RFC de la empresa
          example: "EEJ890123ABC"
        direccion:
          type: string
          description: Dirección fiscal de la empresa
          example: "Av. Principal 123, Col. Centro"
        telefono:
          type: string
          description: Teléfono de contacto
          example: "+52 55 1234 5678"
        email:
          type: string
          format: email
          description: Email de contacto
          example: "contacto@ejemplo.com"
        activo:
          type: boolean
          description: Indica si la empresa está activa
          example: true
        created_at:
          type: string
          format: date-time
          description: Fecha de creación
          example: "2024-01-01T00:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Fecha de última actualización
          example: "2024-01-01T00:00:00Z"

    CiudadesResponse:
      type: object
      description: Respuesta estándar para listado de ciudades
      properties:
        tipo:
          type: integer
          description: Tipo de respuesta (0 = éxito, 1 = error)
          example: 0
        mensaje:
          type: string
          description: Mensaje descriptivo
          example: "OK"
        data:
          type: array
          description: Array de ciudades
          items:
            $ref: '#/components/schemas/Ciudad'

    EmpresasResponse:
      type: object
      description: Respuesta estándar para listado de empresas
      properties:
        tipo:
          type: integer
          description: Tipo de respuesta (0 = éxito, 1 = error)
          example: 0
        mensaje:
          type: string
          description: Mensaje descriptivo
          example: "OK"
        data:
          type: array
          description: Array de empresas
          items:
            $ref: '#/components/schemas/Empresa'

    ErrorResponse:
      type: object
      description: Respuesta estándar para errores
      properties:
        tipo:
          type: integer
          description: Tipo de respuesta (1 = error)
          example: 1
        mensaje:
          type: string
          description: Descripción del error
          example: "Error al obtener datos: No se pudo conectar a la base de datos"
        data:
          type: array
          description: Array vacío en caso de error
          example: []

  responses:
    DatabaseError:
      description: Error de conexión o consulta a la base de datos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            connection_error:
              summary: Error de conexión
              value:
                tipo: 1
                mensaje: "Error al obtener datos: No se pudo conectar a la base de datos"
                data: []
            query_error:
              summary: Error en consulta
              value:
                tipo: 1
                mensaje: "Error al obtener datos: Error en procedimiento almacenado"
                data: []

    NotFound:
      description: Recurso no encontrado
      content:
        application/json:
          schema:
            type: object
            properties:
              tipo:
                type: integer
                example: 1
              mensaje:
                type: string
                example: "Recurso no encontrado"
              data:
                type: null
                example: null

  parameters:
    ActivoFilter:
      name: activo
      in: query
      description: Filtrar por estado activo/inactivo
      required: false
      schema:
        type: boolean
        default: true

    SearchQuery:
      name: search
      in: query
      description: Término de búsqueda
      required: false
      schema:
        type: string
        minLength: 1

  headers:
    X-RateLimit-Limit:
      description: Límite de requests por minuto
      schema:
        type: integer
        example: 60

    X-RateLimit-Remaining:
      description: Requests restantes en la ventana actual
      schema:
        type: integer
        example: 59

# Información adicional sobre la migración
x-migration-info:
  original-files:
    - name: "config.php"
      description: "Configuración de conexión SQL Server"
      migrated-to: ".env + config/database.php"
    - name: "ObtenCiudades.php"
      description: "Endpoint para obtener ciudades"
      migrated-to: "CiudadesController::obtenerCiudades()"
      stored-procedure: "sapObtenListadoCiudadesxNombre"
    - name: "ObtenEmpresas.php"
      description: "Endpoint para obtener empresas"
      migrated-to: "EmpresasController::obtenerEmpresas()"
      stored-procedure: "sapObtenEmpresas"
  
  improvements:
    - "Arquitectura MVC estructurada"
    - "Manejo de errores con try-catch"
    - "Middleware CORS para frontend"
    - "Respuestas HTTP apropiadas"
    - "Documentación OpenAPI/Swagger"
    - "Métodos alternativos con Query Builder"
    - "Versionado de API (v1)"

  database:
    server: "10.201.84.3"
    database: "personal"
    username: "sysdev"
    driver: "sqlsrv"
    stored-procedures:
      - "sapObtenListadoCiudadesxNombre"
      - "sapObtenEmpresas"