API MCP - Integración MSSQL, SAP HANA y SAP B1
Estructura del Proyecto```
./
├── api_mcp/
│ ├── .env # Variables de entorno
│ └── Docker/
│ ├── Dockerfile.api-mcp # Imagen del servicio Python
│ ├── Dockerfile.mssql2022 # Imagen de MSSQL Server
│ ├── Dockerfile.postfix # Imagen del servidor SMTP
│ ├── entrypoint_add_gw.sh # Script de rutas estáticas (api-mcp)
│ ├── entrypoint_mssql.sh # Script de inicialización MSSQL
│ ├── entrypoint_postfix.sh # Script de configuración Postfix
│ └── requirements.txt # Dependencias Python
├── app/ # Código fuente FastAPI
│ ├── auth.py # Autenticación con Session Tokens
│ ├── config.py # Configuración desde variables de entorno
│ ├── database.py # Conexiones a MSSQL y HANA
│ ├── main.py # Punto de entrada de la API
│ ├── mcp.py # Endpoints MCP
│ ├── sap_service_layer.py # Cliente SAP B1 Service Layer
│ ├── session.py # Gestión de sesiones en MSSQL
│ └── websettings.py # Interfaz web (login y ajustes)
├── tests/ # Scripts y reportes de pruebas
│ ├── test_completo_sistema.sh # Script de prueba completa automatizada
│ ├── prueba_session_tokens.md # Pruebas del sistema de sesiones
│ └── prueba_inicializa_datos_session_preservation.md
├── db/
│ └── mssql/ # Datos persistentes de MSSQL (generado)
│ ├── .system/
│ ├── data/
│ ├── log/
│ └── secrets/
└── docker-compose.yml
## Requisitos Previos
- Docker
- Docker Compose
- Red externa `vpn-proxy` creada previamente
## Configuración
1. Editar el archivo `./api_mcp/.env` con las credenciales correspondientes:```env
# JWT
JWT_SECRET_KEY=tu_clave_secreta_aqui
JWT_ALGORITHM=HS256
JWT_EXPIRATION_MINUTES=30
# Configuración de sesiones y filtros
SESIONES_ACTIVAS=2
ANOS_ACTIVO=0
# Microsoft SQL Server
SA_PASSWORD=tu_password_sa
MSSQL_HOST=mssql-api-mcp
MSSQL_PORT=1433
MSSQL_USER=sa
MSSQL_PASSWORD=tu_password_sa
MSSQL_DATABASE=tu_base_de_datos
# SAP HANA
SAP_HANA_HOST=direccion_hana
SAP_HANA_PORT=puerto_hana
SAP_HANA_USER=usuario_hana
SAP_HANA_PASSWORD=password_hana
# SAP Business One Service Layer
SAP_B1_SERVICE_LAYER_URL=https://servidor:50000/b1s/v1/
SAP_B1_USER=usuario_b1
SAP_B1_PASSWORD=password_b1
# Email
EMAIL_SUPERVISOR=correo@dominio.com
SMTP_HOST=postfix-api-mcp
SMTP_PORT=25
EMAIL_FROM=aviso@progex.grupoexpansion
# Postfix - Relay externo (opcional)
# POSTFIX_HOSTNAME=mail.tudominio.com
# POSTFIX_DOMAIN=tudominio.com
# POSTFIX_RELAY_HOST=smtp.office365.com
# POSTFIX_RELAY_PORT=587
# POSTFIX_RELAY_USER=usuario@dominio.com
# POSTFIX_RELAY_PASSWORD=password
# Locale y Timezone
TZ=America/Mexico_City
LANG=es_MX.UTF-8
LC_ALL=es_MX.UTF-8
Variables de Configuración
- SESIONES_ACTIVAS: Número máximo de sesiones simultáneas por usuario (default: 2)
- Cuando se excede el límite, se elimina automáticamente la sesión más antigua
-
Valor recomendado: 1-5 sesiones
-
ANOS_ACTIVO: Número de años hacia atrás para filtrar proveedores activos (default: 0)
- 0 = Año actual solamente
- 1 = Año actual y anterior
- n = Últimos n años
Ejecución```bash
docker compose up -d
## Endpoints Disponibles
Total de endpoints: **25**
### Autenticación (5 endpoints)
- `POST /auth/login` - Obtener token de sesión (Session ID)
- `POST /auth/logout` - Cerrar sesión actual
- `GET /auth/sessions` - Listar sesiones activas del usuario
- `POST /auth/logout-all` - Cerrar todas las sesiones del usuario
- `POST /auth/cleanup` - Limpiar sesiones expiradas (mantenimiento)
### Sistema (7 endpoints)
- `GET /health` - Verificar estado del servicio
- `GET /me` - Información del usuario autenticado y sesión actual
- `GET /pruebas` - Consultar modo actual (productivo/pruebas)
- `POST /pruebas/{valor}` - Establecer modo (0=productivo, 1=pruebas)
- `GET /start` - Interfaz web con login y panel de ajustes
- `GET /config/email` - Consultar configuración de email del sistema
- `GET /config/sesiones` - Consultar configuración de sesiones y años activos
### SAP HANA (1 endpoint)
- `GET /empresas_registradas` - Listar empresas SAP B1 registradas en HANA (requiere autenticación)
### MSSQL (3 endpoints)
- `POST /inicializa_datos` - Inicializa las tablas SAP_EMPRESAS y SAP_PROVEEDORES (requiere autenticación)
- `POST /actualizar_empresas` - Actualiza SAP_EMPRESAS con datos de HANA (SAP es fuente de verdad, preserva SL)
- `POST /actualizar_proveedores` - Actualiza SAP_PROVEEDORES con datos de Service Layer (requiere autenticación)
### SAP Service Layer (2 endpoints)
- `GET /proveedores/{instancia}` - Obtener proveedores de una instancia SAP (requiere autenticación)
- `GET /test_service_layer` - Prueba conexión a Service Layer para todas las instancias SAP (requiere autenticación)
### Análisis (3 endpoints)
- `POST /proveedores/analizar-actividad` - Analiza actividad de proveedores en los últimos N años (requiere autenticación)
- `GET /inicializa_datos/status/{job_id}` - Consulta el estado de un job de inicialización (público, sin autenticación)
- `GET /inicializa_datos/jobs` - Lista todos los jobs de inicialización (requiere autenticación)
### MCP (4 endpoints - requieren autenticación con scopes específicos)
- `POST /mcp/tools/list` - Listar herramientas disponibles (scope: `mcp:tools:list`)
- `POST /mcp/tools/call` - Ejecutar herramienta (scope: `mcp:tools:call`)
- `POST /mcp/resources/list` - Listar recursos disponibles (scope: `mcp:resources:list`)
- `POST /mcp/resources/read` - Leer recurso (scope: `mcp:resources:read`)
## Interfaz Web
El sistema incluye una interfaz web accesible en `http://localhost:8000/start` que proporciona:
### Características de la Interfaz Web
- **Formulario de login integrado**: Autenticación directa desde el navegador
- **Gestión de sesión con cookies**: Token almacenado en cookie con validez de 1 hora
- **Diseño de 3 tarjetas independientes**:
1. **Tarjeta API MCP**:
- Indicador de sesión activa
- Visualización del token de sesión
- Botón para copiar token al portapapeles
- Botón de cerrar sesión
2. **Tarjeta INFORMACIÓN DEL USUARIO**:
- Nombre de usuario
- Session ID
- Fecha de creación de la sesión
- Fecha de expiración (calculada con sliding expiration)
- Scopes asignados al usuario
3. **Tarjeta AJUSTES**:
- **Fila 1**: Modo de Operación + Sesiones activas (1, 2, 5)
- **Fila 2**: Proveedores activos (0-9 años hacia atrás) + Enviar correo a (readonly)
- **Botones fila 1**: Iniciar Base Auxiliar (degradado rojo-naranja) + Cambiar Ajustes (degradado amarillo-verde)
- **Botones fila 2**: Actualizar Proveedores (degradado amarillo-verde) + Respaldar Usuarios (degradado amarillo-verde)
- **Área de status**: Mensaje de progreso con spinner animado durante ejecución
- Spinner: Círculo giratorio (20px) alineado a la derecha
- Colores: Amarillo durante ejecución, verde al completar, rojo en error
- Formato de mensaje en dos líneas: título + estado actual
- Los 4 botones se deshabilitan simultáneamente durante la ejecución de "Iniciar Base Auxiliar"
- Botón "Iniciar Base Auxiliar" con flujo completo de confirmación y monitoreo en tiempo real
- **Validación automática**: Verifica el token contra el servidor al cargar la página
- **Diseño responsive**: Layout de 3 columnas en escritorio, adaptado para dispositivos móviles
- **Centrado vertical**: Contenido de las tarjetas centrado verticalmente
### Acceso a la Interfaz Web```bash
# Navegador web
http://localhost:8000/start
La interfaz valida automáticamente si existe una sesión activa (cookie) y muestra:
- Login form si no hay sesión válida
- Panel autenticado con 3 tarjetas si la sesión es válida
Funcionalidad "Iniciar Base Auxiliar"
El botón "Iniciar Base Auxiliar" en la tarjeta AJUSTES ejecuta el siguiente flujo:
-
Lectura de configuración:
- Modo de operación (Productivo/Pruebas)
- Años de actividad para análisis de proveedores (0-9)
- Email del supervisor para notificaciones -
Confirmación del usuario:
- Muestra popup modal personalizado con todos los parámetros
- Advierte que la base operativa actual será eliminada y recreada
- Botones "Cancelar" e "Iniciar" -
Ejecución del proceso:
- Deshabilita los 4 botones de la tarjeta AJUSTES para evitar múltiples ejecuciones
- Muestra mensaje de estatus en tiempo real bajo los botones
- Establece el modo de operación víaPOST /pruebas/{modo}
- Inicia la inicialización víaPOST /inicializa_datos?anos={anos}&email={email}
- Retorna Job ID para monitorear el progreso -
Monitoreo en tiempo real:
- Realiza polling automático cada 2 segundos al endpoint/inicializa_datos/status/{job_id}
- Actualiza el mensaje de estatus con el progreso actual en formato de dos líneas:Ejecutando proceso de inicialización [Estado actual del job]
- Muestra spinner animado (círculo giratorio) alineado a la derecha durante la ejecución
- Estados visuales: running (amarillo con spinner), completed (verde), failed (rojo)
- Manejo robusto de reinicios del servidor:- Si el servidor reinicia durante la ejecución, detecta el error 404
- Detiene el polling automáticamente
- Muestra mensaje de completado con historial de jobs disponible
- Re-habilita los 4 botones para permitir nuevas operaciones
- Habilita los 4 botones cuando el proceso termina (exitosamente o con error)
- Muestra historial de las últimas 3 inicializaciones con fechas y estados
-
Uso de parámetros:
- anos: Utilizado enanalizar_actividad_proveedores(0=solo año actual, 1=actual+1 anterior, etc.)
- email: Si es diferente a EMAIL_SUPERVISOR del .env, se usa como destinatario de notificaciones
Otros Botones de la Tarjeta AJUSTES
La tarjeta AJUSTES incluye tres botones adicionales para operaciones específicas:
-
Cambiar Ajustes (degradado amarillo-verde):
- Pendiente de implementación
- Permitirá modificar configuraciones de sesiones activas, proveedores activos y email del supervisor -
Actualizar Proveedores (degradado amarillo-verde):
- Pendiente de implementación
- Sincronizará la tabla SAP_PROVEEDORES con Service Layer sin recrear la base de datos -
Respaldar Usuarios (degradado amarillo-verde):
- Pendiente de implementación
- Creará un respaldo de la tabla USER_SESSIONS
Nota: Los 4 botones se deshabilitan simultáneamente cuando "Iniciar Base Auxiliar" está en ejecución.
Endpoints de Configuración
GET /config/email
Obtiene la configuración de email del sistema desde las variables de entorno.```bash
curl http://localhost:8000/config/email \
-H "Authorization: Bearer <token>"
Respuesta:```json
{
"email_supervisor": "supervisor@empresa.com",
"smtp_host": "postfix-api-mcp",
"smtp_port": 25,
"email_from": "aviso@progex.grupoexpansion"
}
GET /config/sesiones
Obtiene la configuración de sesiones y años activos desde las variables de entorno.```bash
curl http://localhost:8000/config/sesiones \
-H "Authorization: Bearer <token>"
Respuesta:```json
{
"sesiones_activas": 2,
"anos_activo": 0
}
Sistema de Autenticación
La API utiliza Session Tokens almacenados en MSSQL con renovación automática (sliding expiration).
Características del Sistema de Sesiones
- Sliding Expiration: La sesión se renueva automáticamente en cada petición
- Timeout configurable: 30 minutos de inactividad por defecto (configurable en
JWT_EXPIRATION_MINUTES) - Control total: Invalidar sesiones individual o masivamente
- Sin dependencias externas: Usa MSSQL existente (no requiere Redis)
- Límite de sesiones activas: Configurable por usuario vía variable de entorno
SESIONES_ACTIVAS(default: 2) - Cuando un usuario excede el límite, se elimina automáticamente su sesión más antigua
- Permite controlar recursos y seguridad limitando sesiones simultáneas
Tabla USER_SESSIONS```sql
CREATE TABLE USER_SESSIONS (
SessionID NVARCHAR(100) PRIMARY KEY,
Username NVARCHAR(100) NOT NULL,
CreatedAt DATETIME NOT NULL,
LastActivity DATETIME NOT NULL,
Scopes NVARCHAR(500),
INDEX idx_username (Username),
INDEX idx_last_activity (LastActivity)
)
### Flujo de Autenticación
1. **Login**: Usuario se autentica y recibe un SessionID (UUID)
2. **Cada petición**: El SessionID se valida y la sesión se renueva automáticamente
3. **Inactividad**: Si pasan 30 minutos sin actividad, la sesión expira
4. **Logout**: El usuario puede cerrar sesión manualmente
### Comportamiento de Sliding Expiration
**Ejemplo:**
- Login a las 8:00 → Sesión expira a las 8:30
- Petición a las 8:10 → Sesión se renueva, ahora expira a las 8:40
- Petición a las 8:35 → Sesión se renueva, ahora expira a las 9:05
- Si no hay actividad por 30 minutos, la sesión expira automáticamente
## Uso de la API
### Obtener Token (Login)```bash
curl -X POST http://localhost:8000/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "sa", "password": "tu_password"}'
Respuesta:```json
{
"access_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"token_type": "bearer"
}
### Usar Endpoints Protegidos```bash
curl http://localhost:8000/me \
-H "Authorization: Bearer <token>"
Respuesta:```json
{
"username": "sa",
"scopes": ["mcp:tools:list", "mcp:tools:call", "mcp:resources:list", "mcp:resources:read"],
"session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"created_at": "2026-01-22T10:00:00",
"expires_at": "2026-01-22T10:30:00"
}
### Gestión de Sesiones
#### Listar sesiones activas```bash
curl http://localhost:8000/auth/sessions \
-H "Authorization: Bearer <token>"
Respuesta:```json
{
"username": "sa",
"total_sessions": 2,
"sessions": [
{
"session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"username": "sa",
"created_at": "2026-01-20T10:00:00",
"last_activity": "2026-01-20T10:30:00",
"scopes": ["mcp:tools:list", "mcp:tools:call", ...]
}
]
}
#### Cerrar sesión actual```bash
curl -X POST http://localhost:8000/auth/logout \
-H "Authorization: Bearer <token>"
Cerrar todas las sesiones```bash
curl -X POST http://localhost:8000/auth/logout-all \
-H "Authorization: Bearer <token>"
#### Limpiar sesiones expiradas (mantenimiento)```bash
curl -X POST http://localhost:8000/auth/cleanup \
-H "Authorization: Bearer <token>"
Listar Empresas SAP B1```bash
curl http://localhost:8000/empresas_registradas \
-H "Authorization: Bearer <token>"
### Obtener Proveedores de una Instancia```bash
# Todos los proveedores
curl http://localhost:8000/proveedores/NOMBRE_INSTANCIA \
-H "Authorization: Bearer <token>"
# Limitar cantidad de resultados
curl "http://localhost:8000/proveedores/NOMBRE_INSTANCIA?top=10" \
-H "Authorization: Bearer <token>"
# Filtrar por CardCode (contiene)
curl "http://localhost:8000/proveedores/NOMBRE_INSTANCIA?card_code=N1000" \
-H "Authorization: Bearer <token>"
# Filtrar por nombre (contiene)
curl "http://localhost:8000/proveedores/NOMBRE_INSTANCIA?card_name=CEMEX" \
-H "Authorization: Bearer <token>"
# Filtrar por RFC (contiene)
curl "http://localhost:8000/proveedores/NOMBRE_INSTANCIA?federal_tax_id=ABC123" \
-H "Authorization: Bearer <token>"
# Combinación de filtros
curl "http://localhost:8000/proveedores/NOMBRE_INSTANCIA?card_name=AMERICAN&top=5" \
-H "Authorization: Bearer <token>"
Parámetros disponibles:
| Parámetro | Descripción |
|---|---|
top |
Limita el número de registros retornados |
card_code |
Filtra por CardCode que contenga el valor |
card_name |
Filtra por CardName que contenga el valor |
federal_tax_id |
Filtra por FederalTaxID (RFC) que contenga el valor |
Respuesta:```json
{
"instancia": "NOMBRE_INSTANCIA",
"total": "4075",
"proveedores": [
{
"CardCode": "N1000011",
"CardName": "American Express Company México SA de CV",
"FederalTaxID": "AEC810901298",
"Phone1": "5551234567",
"EmailAddress": "proveedor@ejemplo.com",
"Address": "Av. Patriotismo 635",
"City": "CDMX",
"Country": "MX",
...
}
]
}
### Listar Herramientas MCP```bash
curl -X POST http://localhost:8000/mcp/tools/list \
-H "Authorization: Bearer <token>"
Documentación Interactiva
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
Servicios
| Servicio | Puerto | Descripción |
|---|---|---|
| api-mcp | 8000 | API FastAPI |
| mssql-api-mcp | 1433 | SQL Server (solo red interna) |
| postfix-api-mcp | 25 | Servidor SMTP (solo red interna) |
Red Docker
Todos los servicios están conectados a la red externa vpn-proxy. El servicio Python puede conectarse a:
- MSSQL usando el hostname mssql-api-mcp
- Postfix usando el hostname postfix-api-mcp
- SAP HANA mediante rutas estáticas configuradas en el entrypoint
Rutas Estáticas
El contenedor api-mcp configura automáticamente las siguientes rutas al iniciar:
- 10.0.0.0/8 via 172.19.50.254
- 172.16.1.0/24 via 172.19.50.254
Locale y Timezone
Todos los contenedores están configurados con:
- Timezone: America/Mexico_City (CST)
- Locale: es_MX.UTF-8
Esto asegura que las fechas y horas se muestren correctamente en español y con la zona horaria de México.
Inicialización Automática de MSSQL
El contenedor mssql-api-mcp ejecuta un script de inicialización que:
1. Inicia SQL Server
2. Espera a que el servicio esté disponible
3. Verifica si existe la base de datos especificada en MSSQL_DATABASE
4. Si no existe, la crea automáticamente
5. Verifica si existe la tabla SAP_EMPRESAS
6. Si no existe, la crea con la siguiente estructura:```sql
CREATE TABLE SAP_EMPRESAS (
Instancia NVARCHAR(100) NOT NULL,
Prueba BIT NOT NULL DEFAULT 0,
ServiceLayer BIT NOT NULL DEFAULT 0,
PrintHeadr NVARCHAR(255),
CompnyAddr NVARCHAR(500),
TaxIdNum NVARCHAR(50),
PRIMARY KEY (Instancia)
)
| Columna | Tipo | Descripción |
|--------------|----------------|--------------------------------------------------|
| Instancia | NVARCHAR(100) | Identificador único (PK) |
| Prueba | BIT | 1 si existe instancia _PRUEBAS en HANA, 0 si no |
| ServiceLayer | BIT | 1 si login en Service Layer exitoso, 0 si falló |
| PrintHeadr | NVARCHAR(255) | Encabezado de impresión (o nombre de instancia) |
| CompnyAddr | NVARCHAR(500) | Dirección de la empresa |
| TaxIdNum | NVARCHAR(50) | Número de identificación fiscal |
Esto garantiza que la base de datos y las tablas estén listas antes de que el servicio `api-mcp` intente conectarse.
### Tabla SAP_PROVEEDORES
La tabla `SAP_PROVEEDORES` se crea automáticamente al ejecutar `/inicializa_datos`:```sql
CREATE TABLE SAP_PROVEEDORES (
-- Identificación básica
Instancia NVARCHAR(100) NOT NULL,
CardCode NVARCHAR(50) NOT NULL,
CardName NVARCHAR(200),
GroupCode INT,
FederalTaxID NVARCHAR(50),
-- Fechas de auditoría
CreateDate DATE,
CreateTime TIME,
UpdateDate DATE,
UpdateTime TIME,
-- Dirección principal
Address NVARCHAR(500),
Block NVARCHAR(200),
ZipCode NVARCHAR(20),
City NVARCHAR(100),
County NVARCHAR(100),
BillToState NVARCHAR(10),
Country NVARCHAR(10),
-- Dirección postal / Envío
MailAddress NVARCHAR(500),
MailZipCode NVARCHAR(20),
ShipToState NVARCHAR(10),
ShipToDefault NVARCHAR(100),
-- Contacto
Phone1 NVARCHAR(50),
Phone2 NVARCHAR(50),
Fax NVARCHAR(50),
Cellular NVARCHAR(50),
EmailAddress NVARCHAR(200),
ContactPerson NVARCHAR(200),
-- Condiciones financieras
PayTermsGrpCode INT,
PeymentMethodCode NVARCHAR(50),
CreditLimit DECIMAL(18,2),
MaxCommitment DECIMAL(18,2),
DiscountPercent DECIMAL(5,2),
PriceListNum INT,
Currency NVARCHAR(10),
-- Impuestos y deducciones
DeductibleAtSource NVARCHAR(10),
DeductionPercent DECIMAL(5,2),
DeductionValidUntil DATE,
VatGroupLatinAmerica NVARCHAR(20),
-- Datos bancarios
DefaultBankCode NVARCHAR(50),
DefaultAccount NVARCHAR(100),
BankCountry NVARCHAR(10),
HouseBank NVARCHAR(50),
HouseBankCountry NVARCHAR(10),
HouseBankAccount NVARCHAR(50),
HouseBankBranch NVARCHAR(20),
HouseBankIBAN NVARCHAR(50),
IBAN NVARCHAR(50),
CreditCardCode INT,
CreditCardNum NVARCHAR(50),
CreditCardExpiration DATE,
DebitorAccount NVARCHAR(50),
-- Saldos y oportunidades
CurrentAccountBalance DECIMAL(18,2),
OpenDeliveryNotesBalance DECIMAL(18,2),
OpenOrdersBalance DECIMAL(18,2),
OpenChecksBalance DECIMAL(18,2),
OpenOpportunities INT,
-- Estado del proveedor
Valid NVARCHAR(10),
Frozen NVARCHAR(10),
BlockDunning NVARCHAR(10),
BackOrder NVARCHAR(10),
PartialDelivery NVARCHAR(10),
PRIMARY KEY (Instancia, CardCode)
)
| Grupo | Campos |
|---|---|
| Identificación | Instancia, CardCode, CardName, GroupCode, FederalTaxID |
| Fechas | CreateDate, CreateTime, UpdateDate, UpdateTime |
| Dirección principal | Address, Block, ZipCode, City, County, BillToState, Country |
| Dirección postal | MailAddress, MailZipCode, ShipToState, ShipToDefault |
| Contacto | Phone1, Phone2, Fax, Cellular, EmailAddress, ContactPerson |
| Financiero | PayTermsGrpCode, PeymentMethodCode, CreditLimit, MaxCommitment, DiscountPercent, PriceListNum, Currency |
| Impuestos | DeductibleAtSource, DeductionPercent, DeductionValidUntil, VatGroupLatinAmerica |
| Bancario | DefaultBankCode, DefaultAccount, BankCountry, HouseBank, HouseBankCountry, HouseBankAccount, HouseBankBranch, HouseBankIBAN, IBAN, CreditCardCode, CreditCardNum, CreditCardExpiration, DebitorAccount |
| Saldos | CurrentAccountBalance, OpenDeliveryNotesBalance, OpenOrdersBalance, OpenChecksBalance, OpenOpportunities |
| Estado | Valid, Frozen, BlockDunning, BackOrder, PartialDelivery |
Job Tracking para Inicialización de Datos
El sistema de inicialización de datos utiliza un modelo asíncrono con tracking de jobs para permitir operaciones de larga duración.
POST /inicializa_datos - Iniciar proceso de inicialización
Inicia un proceso asíncrono de inicialización y retorna inmediatamente un Job ID para monitorear el progreso.
Parámetros opcionales:
- anos (int, default: 0): Años de actividad a analizar (0=solo año actual, 1=actual+1 anterior, etc.)
- email (str, opcional): Email destinatario de notificaciones. Si no se proporciona o es igual a EMAIL_SUPERVISOR, usa el configurado en .env```bash
Inicialización básica
curl -X POST http://localhost:8000/inicializa_datos \
-H "Authorization: Bearer <token>"
Con parámetros personalizados
curl -X POST "http://localhost:8000/inicializa_datos?anos=2&email=supervisor@empresa.com" \
-H "Authorization: Bearer <token>"
Respuesta:```json
{
"job_id": "174f89bd-9f47-48c0-ac2f-2fc75f926ec8",
"message": "Inicialización iniciada. Use GET /inicializa_datos/status/{job_id} para consultar el progreso"
}
GET /inicializa_datos/status/{job_id} - Consultar estado de un job
Consulta el estado actual de un job de inicialización específico.
NOTA IMPORTANTE: Este endpoint NO requiere autenticación para permitir el monitoreo durante el proceso de inicialización, cuando la sesión del usuario puede estar siendo recreada en la base de datos.```bash
Sin autenticación (recomendado durante inicialización)
curl http://localhost:8000/inicializa_datos/status/174f89bd-9f47-48c0-ac2f-2fc75f926ec8
Con autenticación (también funciona)
curl http://localhost:8000/inicializa_datos/status/174f89bd-9f47-48c0-ac2f-2fc75f926ec8 \
-H "Authorization: Bearer <token>"
**Manejo de errores:**
- Si el job no existe o el servidor reinició, retorna `404 Not Found`
- La interfaz web maneja automáticamente este caso mostrando el mensaje de completado con historial
Respuesta (en progreso):```json
{
"job_id": "174f89bd-9f47-48c0-ac2f-2fc75f926ec8",
"status": "running",
"message": "Sincronizando proveedores..."
}
Respuesta (completado):```json
{
"job_id": "174f89bd-9f47-48c0-ac2f-2fc75f926ec8",
"status": "completed",
"message": "Inicialización completada",
"result": {
"sap_empresas": {...},
"service_layer": {...},
"sap_proveedores": {...}
}
}
### GET /inicializa_datos/jobs - Listar todos los jobs
Lista todos los jobs de inicialización del usuario actual.```bash
curl http://localhost:8000/inicializa_datos/jobs \
-H "Authorization: Bearer <token>"
Respuesta:json
{
"username": "sa",
"total_jobs": 3,
"jobs": [
{
"job_id": "174f89bd-9f47-48c0-ac2f-2fc75f926ec8",
"status": "completed",
"created_at": "2026-01-22T10:00:00",
"completed_at": "2026-01-22T10:05:30"
},
{
"job_id": "a2b3c4d5-...",
"status": "running",
"created_at": "2026-01-22T11:00:00",
"completed_at": null
}
]
}
Manejo de Reinicios del Servidor
El sistema de tracking de jobs utiliza un diccionario en memoria que se resetea cuando el servidor se reinicia (por ejemplo, cuando uvicorn detecta cambios en el código con --reload). Para manejar esta situación:
Comportamiento del sistema:
1. Los jobs en ejecución continúan procesándose en segundo plano incluso si el servidor reinicia
2. El tracking del job (estado, progreso) se pierde al reiniciar porque está en memoria
3. La interfaz web detecta automáticamente cuando un job ya no existe (404) durante el polling
4. Al detectar un 404, la interfaz:
- Detiene el polling automáticamente
- Re-habilita los botones de la tarjeta AJUSTES
- Muestra mensaje de completado con el historial disponible de jobs
- Permite al usuario verificar manualmente si la inicialización se completó
Recomendación:
- Si un job queda "atorado" en estado running después de un reinicio del servidor, refresca la página en el navegador
- Verifica el estado de la base de datos para confirmar si la inicialización se completó exitosamente
- Consulta los logs del contenedor para ver el resultado completo: docker compose logs api-mcp --tail=200
Endpoint inicializa_datos - Detalle del proceso
El proceso de inicialización realiza las siguientes operaciones:
-
Verificación de infraestructura:
- Verifica si la base de datos existe, si no la crea
- Verifica si la tablaSAP_EMPRESASexiste, si no la crea -
Sincronización SAP_EMPRESAS:
- Elimina todos los registros existentes enSAP_EMPRESAS(MSSQL)
- Obtiene la lista de instancias/empresas desde SAP HANA (solo lectura)
- Para cada instancia:- Verifica si existe una versión
{instancia}_PRUEBASen HANA - Obtiene
PrintHeadr,CompnyAddryTaxIdNumde la tablaOADM - Si
PrintHeadrestá vacío, usa el nombre de la instancia - Inserta los registros en
SAP_EMPRESAS(MSSQL)
- Verifica si existe una versión
-
Test de Service Layer:
- Para cada instancia, intenta hacer login en Service Layer
- Si el login es exitoso, hace logout para liberar la sesión
- Actualiza el campoServiceLayerenSAP_EMPRESAS(1=éxito, 0=fallo)
- SiEMAIL_SUPERVISORestá configurado, envía un correo con los resultados
- Retorna un resumen de conexiones exitosas y fallidas -
Sincronizar SAP_PROVEEDORES:
- Verifica si la tablaSAP_PROVEEDORESexiste, si no la crea
- Para cada instancia conServiceLayer = 1:- Obtiene todos los proveedores (BusinessPartners con CardType='S') desde Service Layer
- Actualiza registros existentes, inserta nuevos, elimina los que ya no existen en SAP
- SAP Service Layer es la fuente de verdad
- Retorna un resumen de proveedores actualizados/insertados/eliminados por instancia
-
Análisis de actividad de proveedores:
- Analiza la actividad de proveedores usando el parámetroanosespecificado
- Crea/actualiza las tablas SAP_PROV_ACTIVOS y SAP_PROV_INACTIVOS
- Crea la vistadbo.vw_maestro_proveedores(INNER JOIN entre SAP_PROV_ACTIVOS y SAP_PROVEEDORES)
- Retorna un resumen de proveedores activos e inactivos -
Notificación por correo:
- Destinatario: Usa el parámetroemailsi se proporciona y es diferente a EMAIL_SUPERVISOR, caso contrario usa EMAIL_SUPERVISOR del .env
- Remitente: aviso@progex.grupoexpansion
- Asunto: Inicializacion de datos - YYYY-MM-DD HH:MM:SS
- Cuerpo:```
Inicializacion de datos realizadaSAP Empresas: 24 insertadas
Service Layer: 21 exitosos, 3 fallidos (ALIANZA, BALLIANCE, ZZMAQGEX)
SAP Proveedores: 13,199 sincronizados de 21 instancias
- Actualizados: 12,500
- Insertados: 699Desglose de proveedores por instancia:
EXPANSION: 4,075
HEARST: 1,272
ANDENES: 1,215
CINETICA: 1,171
NOTICIAS: 1,077
AIRPORTS: 1,069
...
- **Adjunto:** `inicializacion_YYYYMMDD_HHMMSS.json` con resumen (sin desglose detallado):json
{
"sap_empresas": {...},
"service_layer": {...},
"sap_proveedores": {
"total_instancias": 21,
"proveedores_actualizados": 12500,
"proveedores_insertados": 699,
"proveedores_eliminados": 0,
"errores": []
}
}
```
Modo de operación: Se controla con el endpoint /pruebas/{valor}:
- /pruebas/0: modo productivo (sincroniza proveedores de instancias normales)
…(正文过长,页面只展示前面部分,完整内容见仓库)