# Changelog - Versión 1.5.31

## 🔧 Fix: Endpoints ESEA - Migración a API v2

**Fecha:** 24 de Enero, 2026  
**Tipo:** Actualización de API  
**Módulo:** ESEA (Estadísticas del Sector Externo Armonizadas)

---

## 📋 Cambios Realizados

Similar a la actualización de EMFA (v1.5.29), se migraron los endpoints de ESEA del formato legacy al nuevo API v2 con parámetros de consulta.

### Funciones Actualizadas:

#### 1. `esea_get_params()` - Obtener Parámetros/Formularios

**Endpoint Anterior:**
```
/esea/criterios/obtenerPorTema/{tema}
```

**Nuevo Endpoint (API v2):**
```
/public/v1/esea/criterios/{TEMA}
```

**Mejoras:**
- ✅ Integración con debug panel ('📋 Consultar Formularios ESEA')
- ✅ Captura de HTTP status code
- ✅ Conteo de formularios retornados

---

#### 2. `esea_allData2()` - Obtener Datos ESEA

**Endpoint Anterior:**
```
/esea/obtenerDatos/{formulario}/{pais}/{fechas}
```

**Nuevo Endpoint (API v2):**

**Por formulario:**
```
/public/v1/esea/obtenerDatos/{formulario}/{pais}?fechaInicio=dd-mm-yyyy&fechaFin=dd-mm-yyyy
```

**Por variable específica:**
```
/public/v1/esea/obtenerDatos/{formulario}/{variable}/{pais}?fechaInicio=dd-mm-yyyy&fechaFin=dd-mm-yyyy
```

**Características:**
- ✅ Detecta automáticamente si incluye variable o solo formulario
- ✅ Maneja fechas en formato `fechaInicio/fechaFin` que vienen desde JavaScript
- ✅ Convierte parámetros de path a query parameters
- ✅ Debug panel con evento '📊 Consultar Datos ESEA'

**Código Clave:**
```php
// Detectar si $finaldates viene con formato fechaInicio/fechaFin
if (strpos($finaldates, '/') !== false) {
    list($fechaInicio, $fechaFin) = explode('/', $finaldates);
} else {
    $fechaInicio = $finaldates;
    $fechaFin = $finaldates;
}

// Detectar si $newURL contiene formulario/variable
if (strpos($newURL, '/') !== false) {
    // Endpoint con variable específica
    $url = $this->url_base . 'public/v1/esea/obtenerDatos/' . $newURL . '/' . $country . '?fechaInicio=' . $fechaInicio . '&fechaFin=' . $fechaFin;
} else {
    // Endpoint por formulario
    $url = $this->url_base . 'public/v1/esea/obtenerDatos/' . $newURL . '/' . $country . '?fechaInicio=' . $fechaInicio . '&fechaFin=' . $fechaFin;
}
```

---

#### 3. `esea_allData()` - Datos ESEA Matrices Especiales

**Casos especiales:** `test1`, `test2`, `test3`

**Nuevo Endpoint:**
```
/public/v1/esea/obtenerDatos/{formulario}/{pais}?fechaInicio=dd-mm-yyyy&fechaFin=dd-mm-yyyy
```

**Funcionalidad Añadida:**
- ✅ Conversión de trimestres a meses mediante helper `trimesterToMonth()`
- ✅ Manejo de múltiples años/periodos
- ✅ Integración debug panel ('🗂️ Consultar Datos ESEA (Matriz)')

**Helper Function: `trimesterToMonth()`**
```php
private function trimesterToMonth($trimester, $isStart = true) {
    $trimesterMap = array(
        '1' => $isStart ? '01' : '03',  // Q1: Enero-Marzo
        'I' => $isStart ? '01' : '03',
        '2' => $isStart ? '04' : '06',  // Q2: Abril-Junio
        'II' => $isStart ? '04' : '06',
        '3' => $isStart ? '07' : '09',  // Q3: Julio-Septiembre
        'III' => $isStart ? '07' : '09',
        '4' => $isStart ? '10' : '12',  // Q4: Octubre-Diciembre
        'IV' => $isStart ? '10' : '12'
    );
    
    return isset($trimesterMap[$trimester]) ? $trimesterMap[$trimester] : '01';
}
```

Esta función convierte trimestres (I, II, III, IV o 1, 2, 3, 4) a meses:
- **Inicio de trimestre**: Q1 → Enero (01)
- **Fin de trimestre**: Q1 → Marzo (03)

---

## 🎯 Compatibilidad con JavaScript (App.js)

El código JavaScript en `App.js` (línea ~680) ya genera fechas en formato correcto:
```javascript
var fechaInicio = `${formattedFirstDay}-${formattedFirstMonth}-${first_year}`;
var fechaFin = `${formattedLastDay}-${formattedLastMonth}-${last_year}`;
finalString = `${fechaInicio}/${fechaFin}`;
```

Ejemplo: `01-03-2020/31-12-2024`

El PHP ahora lo procesa correctamente dividiéndolo en `fechaInicio` y `fechaFin`.

---

## 📊 Ejemplo de URLs Generadas

### Antes (Legacy):
```
/esea/obtenerDatos/BALANCE_PAGOS/3/2020/03
```

### Después (API v2):
```
/public/v1/esea/obtenerDatos/BALANCE_PAGOS/3?fechaInicio=01-03-2020&fechaFin=31-03-2020
```

### Con Variable:
```
/public/v1/esea/obtenerDatos/BALANCE_PAGOS/VARIABLE_123/3?fechaInicio=01-03-2020&fechaFin=31-03-2020
```

---

## 🧪 Testing Recomendado

1. **Navegar a página ESEA** (Balanza de Pagos, Deuda Externa, etc.)
2. **Seleccionar parámetros:**
   - País
   - Rango de fechas (año/mes inicial y final)
3. **Verificar que los datos cargan correctamente**
4. **Abrir Debug Panel** (burbuja morada) y verificar:
   - 📋 Evento "Consultar Formularios ESEA"
   - 📊 Evento "Consultar Datos ESEA"
   - URLs con formato `/public/v1/esea/...?fechaInicio=...&fechaFin=...`
   - HTTP Status 200

5. **Casos especiales de matrices** (test1, test2, test3):
   - Seleccionar trimestres
   - Verificar conversión correcta a meses
   - Debug panel debe mostrar '🗂️ Consultar Datos ESEA (Matriz)'

---

## 📦 Archivos Modificados

- `inc/api.php` (3 funciones actualizadas + 1 helper agregado)
  - `esea_get_params()` - Líneas ~1606-1660
  - `esea_allData2()` - Líneas ~1574-1659
  - `esea_allData()` - Líneas ~1535-1620
  - `trimesterToMonth()` - Helper function (nuevo)
- `secmca-api.php` (versión bump a 1.5.31)

---

## 🔗 Referencias

- **Documentación API v2:** `api-endpoints-documentation.md` (Sección ESEA)
- **Versión Anterior:** 1.5.30 (EMFA múltiples fechas fix)
- **Patrón Base:** Similar a actualización EMFA v1.5.29

---

## 📝 Notas Técnicas

### Diferencias con EMFA:

1. **ESEA maneja trimestres**: Requiere conversión a meses
2. **JavaScript ya envía fechas correctamente**: `01-03-2020/31-12-2024`
3. **Casos especiales de matriz**: `test1`, `test2`, `test3`
4. **Variables opcionales**: Detecta automáticamente si incluye variable específica

### Próximos Pasos:

- ⏳ **EFPA**: Verificar si necesita actualización similar
- ⏳ **SIMAFIR**: Ya actualizado en v1.5.27-1.5.28
- ✅ **EMFA**: Actualizado en v1.5.29-1.5.30
- ✅ **ESEA**: Actualizado en v1.5.31

---

## ✅ Validación

- ✅ Sin errores de sintaxis PHP
- ✅ Endpoints coinciden con documentación API v2
- ✅ Debug panel integrado en todas las funciones
- ✅ Helper function para trimestres documentada
- ✅ Backward compatible con código existente
