624 lines
19 KiB
YAML
624 lines
19 KiB
YAML
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"
|