first commit

2026-05-09 14:00:04 -04:00
commit e0ec11977c
42 changed files with 4596 additions and 0 deletions
@@ -0,0 +1,200 @@
+# API Reference
+
+## Descripción General
+
+DataTransferV2 incluye una API REST construida con Flask para consultar y descargar datos de reportes.
+
+## Base URL
+
+```
+http://localhost:5000/api
+```
+
+## Endpoints
+
+### GET /download
+
+Descarga datos de un reporte específico en formato JSON.
+
+#### Parámetros de Query
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| project | string | Sí | Nombre del proyecto (pg, feduro) |
+| task | string | Sí | Nombre del reporte |
+| start_date | string | Sí | Fecha inicio (YYYY-MM-DD) |
+| end_date | string | Sí | Fecha fin (YYYY-MM-DD) |
+
+#### Ejemplos de Uso
+
+```bash
+# Cobertura PG
+curl "http://localhost:5000/api/download?project=pg&task=Cobertura&start_date=2024-01-01&end_date=2024-01-31"
+
+# QualityDisplay FEDURO
+curl "http://localhost:5000/api/download?project=feduro&task=QualityDisplay&start_date=2024-01-15&end_date=2024-01-15"
+```
+
+#### Respuesta Exitosa (200)
+
+```json
+{
+  "status": "success",
+  "project": "pg",
+  "task": "Cobertura",
+  "start_date": "2024-01-01",
+  "end_date": "2024-01-31",
+  "data": [
+    {
+      "fecha": "2024-01-01",
+      "tienda": "001",
+      "categoria": "A",
+      "ventas": 1500.50,
+      "unidades": 25
+    },
+    {
+      "fecha": "2024-01-02",
+      "tienda": "001",
+      "categoria": "B",
+      "ventas": 2100.75,
+      "unidades": 35
+    }
+  ],
+  "count": 62,
+  "execution_time": "2.34s"
+}
+```
+
+#### Respuestas de Error
+
+##### 400 Bad Request - Parámetros Inválidos
+
+```json
+{
+  "status": "error",
+  "message": "Parámetros requeridos faltantes: project, task, start_date, end_date",
+  "code": 400
+}
+```
+
+##### 404 Not Found - Proyecto/Reporte No Encontrado
+
+```json
+{
+  "status": "error",
+  "message": "Proyecto 'invalid' no encontrado. Proyectos disponibles: pg, feduro",
+  "code": 404
+}
+```
+
+##### 500 Internal Server Error
+
+```json
+{
+  "status": "error",
+  "message": "Error de conexión a base de datos",
+  "code": 500
+}
+```
+
+## Autenticación
+
+Actualmente no requiere autenticación. Para producción, considera implementar:
+
+- **Bearer Token:** `Authorization: Bearer <token>`
+- **API Key:** `X-API-Key: <key>`
+
+## Rate Limiting
+
+No implementado actualmente. Recomendado para producción.
+
+## Formatos de Datos
+
+### Fechas
+- Formato: `YYYY-MM-DD`
+- Validación: Fechas válidas, start_date <= end_date
+
+### Nombres de Proyecto
+- `pg`: Pentagono Group
+- `feduro`: Proyecto FEDURO
+- `corripio`: Proyecto Corripio (deshabilitado)
+
+### Nombres de Reportes
+
+#### PG (16 reportes)
+- Cobertura
+- Negociadas
+- Promociones
+- QualityDisplay
+- Checkout
+- QualityShelf
+- SOS
+- OsaAnalogo
+- OsaFotografico
+- Fmot
+- ModuloTareas
+- NegociadasIS001
+
+#### FEDURO (18 reportes)
+- Cobertura
+- Checkout
+- OsaAnalogo
+- OsaFotografico
+- Promociones
+- QualityDisplay
+- QualityShelf
+- SOS
+- Fmot
+- ModuloTareas
+- NegociadasIS001
+
+## Limitaciones
+
+- **Máximo de registros:** No limitado (considera paginación)
+- **Timeout:** 30 segundos por defecto
+- **Formato de respuesta:** Solo JSON (considera CSV/XML)
+
+## Ejemplos de Integración
+
+### Python
+
+```python
+import requests
+
+url = "http://localhost:5000/api/download"
+params = {
+    "project": "pg",
+    "task": "Cobertura",
+    "start_date": "2024-01-01",
+    "end_date": "2024-01-31"
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+
+if data["status"] == "success":
+    print(f"Obtenidos {data['count']} registros")
+    # Procesar data["data"]
+```
+
+### JavaScript
+
+```javascript
+fetch('http://localhost:5000/api/download?project=pg&task=Cobertura&start_date=2024-01-01&end_date=2024-01-31')
+  .then(response => response.json())
+  .then(data => {
+    if (data.status === 'success') {
+      console.log(`Datos obtenidos: ${data.count} registros`);
+      // Procesar data.data
+    }
+  });
+```
+
+## Monitoreo
+
+Los requests a la API se registran en `Logs/api.log` con:
+- Timestamp
+- Endpoint
+- Parámetros
+- Tiempo de respuesta
+- Código de estado