# CHANGELOG v1.5.45 - SIMAFIR: Códigos SDMX en Params

**Fecha**: 2025-01-27  
**Tipo de cambio**: Migración completa a códigos SDMX en formulario de parámetros  
**Módulo afectado**: SIMAFIR params-shortcode.php  
**Versión anterior**: v1.5.44

---

## 🎯 Resumen del Cambio

En la versión 1.5.45, se realizó una **migración completa** del formulario de parámetros de SIMAFIR para utilizar **códigos SDMX** en lugar de IDs numéricos internos en todos los criterios de búsqueda:

1. **Países**: Ahora usan códigos **ISO-3** (3 dígitos): CRI, SLV, GTM, HND, NIC, DOM, PAN, BLZ
2. **Variables**: Ya usan `codigoVariable` (implementado en v1.5.44)
3. **Frecuencias**: Usan `codigoSDMX` (M, Q, A, etc.)
4. **Unidades**: Usan `codigoSDMX` (IX, PT, USD, etc.)
5. **Ajustes**: Usan `codigoSDMX` (N, SA, etc.)
6. **Valoraciones**: Mantienen `id` (no tienen código SDMX en el API)

Este cambio alinea el frontend con la estructura real del API y genera URLs legibles usando estándares internacionales.

---

## 📋 Problema Identificado

### ❌ Antes (v1.5.44 y anteriores)

El formulario usaba **IDs numéricos internos** inconsistentes:

```html
<!-- Países -->
<input name="country[]" value="3">     <!-- ID de Costa Rica -->
<input name="country[]" value="13">    <!-- ID de El Salvador -->

<!-- Frecuencias -->
<input name="per[]" value="39">        <!-- ID de Mensual -->

<!-- Unidades -->
<input name="units[]" value="19">      <!-- ID de Índice -->

<!-- Ajustes -->
<input name="fits[]" value="14">       <!-- ID de No ajustado -->
```

**URL generada**:
```
?country=3+13+50&var=CPI_T&per=39&units=19&fits=14
```

**Problemas**:
1. ❌ Mezcla de códigos (variables) con IDs (todo lo demás)
2. ❌ URLs no descriptivas
3. ❌ Dependencia de IDs internos del API
4. ❌ No compatible con estándares SDMX
5. ❌ Estructura del código desactualizada vs API real

---

## ✅ Solución Implementada

### ✅ Después (v1.5.45)

Todos los criterios usan **códigos estándar**:

```html
<!-- Países (ISO-3, 3 dígitos) -->
<input name="country[]" value="CRI">   <!-- Costa Rica -->
<input name="country[]" value="SLV">   <!-- El Salvador -->

<!-- Variables (ya implementado v1.5.44) -->
<input name="var[]" value="CPI_T">     <!-- IPC general -->

<!-- Frecuencias (SDMX) -->
<input name="per[]" value="M">         <!-- Mensual -->

<!-- Unidades (SDMX) -->
<input name="units[]" value="IX">      <!-- Índice -->

<!-- Ajustes (SDMX) -->
<input name="fits[]" value="N">        <!-- No ajustado -->
```

**URL generada**:
```
?country=CRI+SLV+GTM&var=CPI_T&per=M&units=IX&fits=N
```

**Beneficios**:
1. ✅ URLs completamente legibles y autodocumentadas
2. ✅ Compatible con estándar SDMX internacional
3. ✅ Códigos estables independientes de BD interna
4. ✅ Consistente en todos los parámetros
5. ✅ Alineado con estructura real del API


### 1. Países: Migración a ISO-3 (3 dígitos)

**Función actualizada**: `simafir_country_id_to_code()`

```php
// Mapeo actualizado en simafir-functions.php
function simafir_country_id_to_code($country_id) {
    $country_map = array(
        // ISO 3166-1 alpha-3 (3 dígitos)
        3   => 'CRI',     // Costa Rica
        13  => 'SLV',     // El Salvador  
        50  => 'GTM',     // Guatemala
        17  => 'HND',     // Honduras
        4   => 'NIC',     // Nicaragua
        52  => 'DOM',     // República Dominicana
        161 => 'PAN',     // Panamá
        999 => 'BLZ',     // Belice
        
        // Regiones
        95  => 'CA',      // Centroamérica (5)
        56  => 'CARD',    // CA + RD (6)
        78  => 'CAPARD',  // CA + RD + PA (7)
    );
    return isset($country_map[$country_id]) ? $country_map[$country_id] : strval($country_id);
}
```

**Cambio de ISO-2 a ISO-3**:
- **Antes**: CR, SV, GT, HN, NI, DO, PA (2 caracteres)
- **Después**: CRI, SLV, GTM, HND, NIC, DOM, PAN, BLZ (3 caracteres)

### 2. Frecuencias: Adaptación a estructura real del API

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44): Usaba campo inexistente
<?php if($all && isset($all[0]["periocidad"])): ?>
  <input name="per[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45): Usa estructura real del API
<?php if($all && isset($all[0]["frecuencias"])): ?>
  <input name="per[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "frecuencias": [
    {
      "id": 39,
      "codigoSDMX": "M",
      "nombre": "Mensual",
      "descripcion": "datos mensuales"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `M` = Mensual
- `Q` = Trimestral
- `A` = Anual
- `D` = Diario

### 3. Unidades: Migración a codigoSDMX

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["unidadMedida"])): ?>
  <input name="units[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["unidades"])): ?>
  <input name="units[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "unidades": [
    {
      "id": 19,
      "codigoSDMX": "IX",
      "nombre": "Indice",
      "descripcion": "Indice"
    },
    {
      "id": 258,
      "codigoSDMX": "PT",
      "nombre": "Porcentajes",
      "descripcion": "datos en porcentajes"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `IX` = Índice
- `PT` = Porcentaje
- `USD` = Dólares estadounidenses
- `NAT` = Moneda nacional

### 4. Ajustes: Migración a codigoSDMX

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["ajuste"])): ?>
  <input name="fits[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["ajustes"])): ?>
  <input name="fits[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "ajustes": [
    {
      "id": 14,
      "codigoSDMX": "N",
      "nombre": "Datos no ajustados estacionalmente ni ajustados por calendario",
      "descripcion": "Datos ni ajustados estacionalmente ni ajustados por calendario"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `N` = No ajustado
- `SA` = Ajustado estacionalmente
- `CA` = Ajustado por calendario

### 5. Valoraciones: Actualización de nombres de campos

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["referencia"])): ?>
  <h3>Referencia</h3>
  <input name="refs[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["valoraciones"])): ?>
  <h3>Valoración</h3>
  <input name="refs[]" value="<?php echo $value["id"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**⚠️ Nota**: Valoraciones **NO** tienen `codigoSDMX` en el API, por lo que continúan usando `id`.

**Estructura real del API**:
```json
{
  "valoraciones": [
    {
      "id": 265,
      "nombre": "No aplica",
      "descripcion": "No se define una referencia"
    }
  ]
}
```

---

## 📊 Tabla Comparativa de Cambios

| Parámetro | Campo API v1.5.44 | Campo usado v1.5.44 | Campo API v1.5.45 | Campo usado v1.5.45 |
|-----------|-------------------|---------------------|-------------------|---------------------|
| **Países** | `paises[].id` | `idDetalle` (❌ no existe) | `paises[].id` | `simafir_country_id_to_code(id)` → ISO-3 ✅ |
| **Variables** | `variables[].codigoVariable` | `codigoVariable` ✅ | `variables[].codigoVariable` | `codigoVariable` ✅ |
| **Frecuencias** | `frecuencias[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `frecuencias[].codigoSDMX` | `codigoSDMX` ✅ |
| **Unidades** | `unidades[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `unidades[].codigoSDMX` | `codigoSDMX` ✅ |
| **Ajustes** | `ajustes[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `ajustes[].codigoSDMX` | `codigoSDMX` ✅ |
| **Valoraciones** | `valoraciones[].id` | `idDetalle` (❌ campo equivocado) | `valoraciones[].id` | `id` ✅ |

---

## �️ Mapeo Completo de Códigos

### Países (ISO 3166-1 alpha-3)
| Código | País | ID API |
|--------|------|--------|
| **CRI** | Costa Rica | 3 |
| **SLV** | El Salvador | 13 |
| **GTM** | Guatemala | 50 |
| **HND** | Honduras | 17 |
| **NIC** | Nicaragua | 4 |
| **DOM** | República Dominicana | 52 |
| **PAN** | Panamá | 161 |
| **BLZ** | Belice | 999 |

### Regiones
| Código | Descripción | ID API |
|--------|-------------|--------|
| **CA** | Centroamérica (5) | 95 |
| **CARD** | CA + RD (6) | 56 |
| **CAPARD** | CA + RD + PA (7) | 78 |

### Frecuencias (SDMX)
| Código | Descripción | ID API |
|--------|-------------|--------|
| **M** | Mensual | 39 |
| **Q** | Trimestral | 40 |
| **A** | Anual | 41 |
| **D** | Diario | 42 |

### Unidades (SDMX)
| Código | Descripción | ID API |
|--------|-------------|--------|
| **IX** | Índice | 19 |
| **PT** | Porcentajes | 258 |
| **USD** | Dólares estadounidenses | 45 |
| **NAT** | Moneda nacional | 67 |

### Ajustes (SDMX)
| Código | Descripción | ID API |
|--------|-------------|--------|
| **N** | No ajustado | 14 |
| **SA** | Ajustado estacionalmente | 15 |
| **CA** | Ajustado por calendario | 16 |

---

## ⚠️ Consideraciones Importantes

### Backend Compatibility

El backend debe aceptar:
1. ✅ **Códigos ISO-3 para países**: CRI, SLV, GTM (NO IDs 3, 13, 50)
2. ✅ **Códigos SDMX para frecuencias**: M, Q, A (NO IDs 39, 40, 41)
3. ✅ **Códigos SDMX para unidades**: IX, PT, USD (NO IDs 19, 258, 45)
4. ✅ **Códigos SDMX para ajustes**: N, SA, CA (NO IDs 14, 15, 16)
5. ✅ **IDs para valoraciones**: 265, 266, etc. (NO hay codigoSDMX disponible)

### Endpoints Afectados

```
/public/v1/obtenerDatos/porCriterio/{pais}/{variable}/{valoracion}/{unidad}/{frecuencia}
/public/v1/obtenerDatos/porCriterio/{pais}/{variable}/{unidad}/{frecuencia}
```

**Ejemplo ANTES (v1.5.44)**:
```
/public/v1/obtenerDatos/porCriterio/3/CPI_T/265/19/39
                                     ^ ^ ID  ^ ID ^ ID
                                     ID código   ID  ID
```

**Ejemplo DESPUÉS (v1.5.45)**:
```
/public/v1/obtenerDatos/porCriterio/CRI/CPI_T/265/IX/M
                                     ^^^ código ID  ^^ ^
                                     ISO-3        SDMX SDMX
```

---

## 🧪 Testing Requerido

### Test 1: Verificar HTML Generado

1. Acceder al dashboard de SIMAFIR
2. Abrir formulario de parámetros
3. Inspeccionar checkboxes con DevTools
4. **Verificar**:
   - ✅ Países muestran códigos ISO-3 (CRI, SLV, GTM)
   - ✅ Frecuencias muestran códigos SDMX (M, Q, A)
   - ✅ Unidades muestran códigos SDMX (IX, PT, USD)
   - ✅ Ajustes muestran códigos SDMX (N, SA)
   - ✅ Valoraciones muestran IDs numéricos (265, 266)

### Test 2: Verificar URL Generada

1. Seleccionar:
   - Países: Costa Rica + El Salvador
   - Variable: IPC general (CPI_T)
   - Frecuencia: Mensual
   - Unidad: Índice
   - Ajuste: No ajustado
2. **URL esperada**:
   ```
   ?country=CRI+SLV&var=CPI_T&per=M&units=IX&fits=N
   ```
3. **URL NO esperada**:
   ```
   ?country=3+13&var=CPI_T&per=39&units=19&fits=14
   ```

### Test 3: Verificar Backend API Call

```bash
# Test con códigos (v1.5.45):
curl -X GET "http://192.168.100.137:8081/simafir_api/ws/public/v1/obtenerDatos/porCriterio/CRI/CPI_T/IX/M?startPeriod=01-01-2024&endPeriod=31-12-2024"

# Verificar:
# ✅ Status Code: 200 OK
# ✅ Response contiene datos de Costa Rica
# ✅ Variable CPI_T correcta
# ✅ Frecuencia mensual (M)
# ✅ Unidad índice (IX)
```

### Test 4: Verificar Regiones

1. Seleccionar región "CA" (Centroamérica)
2. **Verificar**:
   - ✅ URL contiene `country=CA`
   - ✅ API devuelve datos agregados de 5 países

### Test 5: Verificar Fallback (un solo parámetro)

1. Buscar dataset con:
   - Un solo país disponible
   - Una sola frecuencia disponible
   - Una sola unidad disponible
2. **Verificar**:
   - ✅ Checkboxes muestran códigos (no IDs)
   - ✅ Checkboxes están marcados y readonly
   - ✅ URL genera códigos correctamente

---

## 🐛 Troubleshooting

### Problema 1: Checkboxes siguen mostrando IDs

**Síntomas**:
```html
<input name="country[]" value="3">  <!-- ❌ Sigue mostrando ID -->
```

**Causas posibles**:
1. Caché de WordPress no limpiado
2. Archivo `simafir-functions.php` no cargado
3. Versión antigua del plugin activa

**Solución**:
```bash
# 1. Verificar versión del plugin
# Dashboard > Plugins > secmca-api > Versión 1.5.45

# 2. Limpiar caché
# Dashboard > Configuración > Limpiar caché

# 3. Verificar carga del archivo
grep -n "simafir-functions.php" secmca-api.php
# Debe aparecer: require_once(...'simafir-functions.php');
```

### Problema 2: Frecuencias/Unidades/Ajustes siguen mostrando IDs

**Síntomas**:
```html
<input name="per[]" value="39">   <!-- ❌ ID en lugar de "M" -->
<input name="units[]" value="19"> <!-- ❌ ID en lugar de "IX" -->
```

**Causa**: Código no actualizado a usar `codigoSDMX`

**Solución**: Verificar que el código use:
```php
$value["codigoSDMX"]  // ✅ Correcto
// NO:
$value["idDetalle"]   // ❌ Campo incorrecto
$value["id"]          // ❌ Campo incorrecto (excepto para valoraciones)
```

### Problema 3: API devuelve 404 con códigos

**Síntomas**:
```bash
GET /porCriterio/CRI/CPI_T/IX/M
# Response: 404 Not Found
```

**Causa**: Backend NO acepta códigos, solo IDs

**Solución**: Actualizar el backend para aceptar códigos o mantener conversión interna.

### Problema 4: Región "CA" no funciona

**Síntomas**:
- Checkbox de "CA" genera `value="95"` en lugar de `value="CA"`

**Causa**: Función `simafir_country_id_to_code()` no está siendo llamada para regiones

**Solución**: Verificar línea ~275 en `params-shortcode.php`:
```php
$region_code = simafir_country_id_to_code($value["id"]);
```

---

## 📚 Referencias

- [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) - Códigos de país de 3 letras
- [SDMX Technical Standards](https://sdmx.org/) - Statistical Data and Metadata eXchange
- [CHANGELOG v1.5.44](CHANGELOG-v1.5.44.md) - Variables usando códigos
- [CHANGELOG v1.5.43](CHANGELOG-v1.5.43.md) - EMFA códigos SDMX

---

## ✅ Checklist de Actualización

Antes de marcar v1.5.45 como completo:

- [x] Crear `simafir-functions.php` con función de mapeo ISO-3
- [x] Actualizar `secmca-api.php` para cargar funciones
- [x] Actualizar checkboxes de países (4 instancias)
- [x] Actualizar checkboxes de frecuencias (2 instancias) - codigoSDMX
- [x] Actualizar checkboxes de unidades (2 instancias) - codigoSDMX
- [x] Actualizar checkboxes de ajustes (2 instancias) - codigoSDMX
- [x] Actualizar checkboxes de valoraciones (2 instancias) - id
- [x] Validar sintaxis PHP (sin errores)
- [x] Documentar cambios en CHANGELOG
- [ ] Generar archivo ZIP actualizado
- [ ] Coordinar con equipo de backend para aceptar códigos SDMX
- [ ] Testing en ambiente de desarrollo
- [ ] Testing de regiones (CA, CARD, CAPARD)
- [ ] Testing de fallback (un solo parámetro)
- [ ] Verificar compatibilidad con API backend
- [ ] Deployment a producción

---

**Versión del documento**: 1.0  
**Última actualización**: 2025-01-27


**Función actualizada**: `simafir_country_id_to_code()`

```php
// Mapeo actualizado en simafir-functions.php
function simafir_country_id_to_code($country_id) {
    $country_map = array(
        // ISO 3166-1 alpha-3 (3 dígitos)
        3   => 'CRI',     // Costa Rica
        13  => 'SLV',     // El Salvador  
        50  => 'GTM',     // Guatemala
        17  => 'HND',     // Honduras
        4   => 'NIC',     // Nicaragua
        52  => 'DOM',     // República Dominicana
        161 => 'PAN',     // Panamá
        999 => 'BLZ',     // Belice
        
        // Regiones
        95  => 'CA',      // Centroamérica (5)
        56  => 'CARD',    // CA + RD (6)
        78  => 'CAPARD',  // CA + RD + PA (7)
    );
    return isset($country_map[$country_id]) ? $country_map[$country_id] : strval($country_id);
}
```

**Cambio de ISO-2 a ISO-3**:
- **Antes**: CR, SV, GT, HN, NI, DO, PA (2 caracteres)
- **Después**: CRI, SLV, GTM, HND, NIC, DOM, PAN, BLZ (3 caracteres)

### 2. Frecuencias: Adaptación a estructura real del API

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44): Usaba campo inexistente
<?php if($all && isset($all[0]["periocidad"])): ?>
  <input name="per[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45): Usa estructura real del API
<?php if($all && isset($all[0]["frecuencias"])): ?>
  <input name="per[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "frecuencias": [
    {
      "id": 39,
      "codigoSDMX": "M",
      "nombre": "Mensual",
      "descripcion": "datos mensuales"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `M` = Mensual
- `Q` = Trimestral
- `A` = Anual
- `D` = Diario

### 3. Unidades: Migración a codigoSDMX

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["unidadMedida"])): ?>
  <input name="units[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["unidades"])): ?>
  <input name="units[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "unidades": [
    {
      "id": 19,
      "codigoSDMX": "IX",
      "nombre": "Indice",
      "descripcion": "Indice"
    },
    {
      "id": 258,
      "codigoSDMX": "PT",
      "nombre": "Porcentajes",
      "descripcion": "datos en porcentajes"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `IX` = Índice
- `PT` = Porcentaje
- `USD` = Dólares estadounidenses
- `NAT` = Moneda nacional

### 4. Ajustes: Migración a codigoSDMX

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["ajuste"])): ?>
  <input name="fits[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["ajustes"])): ?>
  <input name="fits[]" value="<?php echo $value["codigoSDMX"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**Estructura real del API**:
```json
{
  "ajustes": [
    {
      "id": 14,
      "codigoSDMX": "N",
      "nombre": "Datos no ajustados estacionalmente ni ajustados por calendario",
      "descripcion": "Datos ni ajustados estacionalmente ni ajustados por calendario"
    }
  ]
}
```

**Códigos SDMX comunes**:
- `N` = No ajustado
- `SA` = Ajustado estacionalmente
- `CA` = Ajustado por calendario

### 5. Valoraciones: Actualización de nombres de campos

**Cambios en params-shortcode.php**:

```php
// ❌ ANTES (v1.5.44):
<?php if($all && isset($all[0]["referencia"])): ?>
  <h3>Referencia</h3>
  <input name="refs[]" value="<?php echo $value["idDetalle"]; ?>">
  <label><?php echo $value["nombreEsp"]; ?></label>
<?php endif; ?>

// ✅ DESPUÉS (v1.5.45):
<?php if($all && isset($all[0]["valoraciones"])): ?>
  <h3>Valoración</h3>
  <input name="refs[]" value="<?php echo $value["id"]; ?>">
  <label><?php echo $value["nombre"]; ?></label>
<?php endif; ?>
```

**⚠️ Nota**: Valoraciones **NO** tienen `codigoSDMX` en el API, por lo que continúan usando `id`.

**Estructura real del API**:
```json
{
  "valoraciones": [
    {
      "id": 265,
      "nombre": "No aplica",
      "descripcion": "No se define una referencia"
    }
  ]
}
```

---

## 📊 Tabla Comparativa de Cambios

| Parámetro | Campo API v1.5.44 | Campo usado v1.5.44 | Campo API v1.5.45 | Campo usado v1.5.45 |
|-----------|-------------------|---------------------|-------------------|---------------------|
| **Países** | `paises[].id` | `idDetalle` (❌ no existe) | `paises[].id` | `simafir_country_id_to_code(id)` → ISO-3 ✅ |
| **Variables** | `variables[].codigoVariable` | `codigoVariable` ✅ | `variables[].codigoVariable` | `codigoVariable` ✅ |
| **Frecuencias** | `frecuencias[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `frecuencias[].codigoSDMX` | `codigoSDMX` ✅ |
| **Unidades** | `unidades[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `unidades[].codigoSDMX` | `codigoSDMX` ✅ |
| **Ajustes** | `ajustes[].codigoSDMX` | `idDetalle` (❌ campo equivocado) | `ajustes[].codigoSDMX` | `codigoSDMX` ✅ |
| **Valoraciones** | `valoraciones[].id` | `idDetalle` (❌ campo equivocado) | `valoraciones[].id` | `id` ✅ |

---

## 🧪 Validación y Testing

### 1. Verificar códigos en HTML generado

```bash
# Abrir página de parámetros SIMAFIR e inspeccionar checkboxes
```

```html
<!-- ✅ Esperado (v1.5.45): -->

<!-- Países (ISO-3) -->
<input name="country[]" value="CRI">
<input name="country[]" value="SLV">
<input name="country[]" value="GTM">

<!-- Variables (código) -->
<input name="var[]" value="CPI_T">
<input name="var[]" value="CPI_F">

<!-- Frecuencias (SDMX) -->
<input name="per[]" value="M">

<!-- Unidades (SDMX) -->
<input name="units[]" value="IX">
<input name="units[]" value="PT">

<!-- Ajustes (SDMX) -->
<input name="fits[]" value="N">
```

### 2. Verificar URL generada

```bash
# URL esperada (v1.5.45):
https://api.secmca.org/SIMAFIR?country=CRI+SLV+GTM&var=CPI_T&per=M&units=IX&fits=N

# URL anterior (v1.5.44):
https://api.secmca.org/SIMAFIR?country=3+13+50&var=CPI_T&per=39&units=19&fits=14
```

### 3. Verificar compatibilidad con el backend

⚠️ **CRÍTICO**: El backend debe aceptar códigos SDMX en todos los parámetros.

Según la documentación del API (api-endpoints-documentation.md):

```
Endpoint:
/public/v1/obtenerDatos/porCriterio/{pais}/{variable}/{unidad}/{frecuencia}
```

**Test**:
```bash
# Test con códigos SDMX (v1.5.45):
curl "http://192.168.100.137:8081/simafir_api/ws/public/v1/obtenerDatos/porCriterio/CRI/CPI_T/IX/M?startPeriod=01-01-2024&endPeriod=31-12-2024"

# Verificar:
# ✅ Status: 200 OK
# ✅ Response contiene datos de Costa Rica
# ✅ Variable CPI_T, Unidad IX, Frecuencia M
```

---

## 🔍 Mapeo Completo de Códigos

---

## 🧪 Validación y Testing

### 1. **Inspeccionar HTML generado**

Después de instalar v1.5.45:

1. Abrir la página de parámetros SIMAFIR
2. Inspeccionar los checkboxes con DevTools
3. Verificar que los `value` son códigos ISO-2:

```html
✅ Correcto (v1.5.45):
<input name="country[]" value="CR">
<input name="country[]" value="SV">
<input name="country[]" value="GT">
<input name="country[]" value="CA">

❌ Incorrecto (v1.5.44):
<input name="country[]" value="3">
<input name="country[]" value="13">
<input name="country[]" value="50">
<input name="country[]" value="997">
```

### 2. **Verificar URL generada**

Seleccionar países y generar consulta:

```bash
# ✅ URL esperada (v1.5.45):
https://api.secmca.org/SIMAFIR/consulta?country=CR+SV+GT&var=CPI_T

# ❌ URL anterior (v1.5.44):
https://api.secmca.org/SIMAFIR/consulta?country=3+13+50&var=CPI_T
```

### 3. **Verificar respuesta del API**

El API debe aceptar códigos ISO-2 en el parámetro `country`:

```bash
# Test con cURL:
curl "https://api.secmca.org/SIMAFIR/consulta?country=CR+SV&var=CPI_T&dateStart=2024-01&dateEnd=2024-12"

# Verificar:
# ✅ Status: 200 OK
# ✅ Response contiene datos de Costa Rica y El Salvador
# ✅ No hay error 400/404
```

### 4. **Test de casos límite**

#### Caso 1: Un solo país disponible
- Verificar que el checkbox único usa `codigo`
- Debe estar checked y readonly

#### Caso 2: Región (esPais = FALSE)
- Verificar que regiones usan códigos (ej: "CA" para Centroamérica)
- Tab "Regiones" debe funcionar correctamente

#### Caso 3: Combinación de países y regiones
- Seleccionar múltiples países + región
- URL debe contener: `country=CR+SV+CA`

---

## 🔍 Comparación con Versiones Anteriores

### Evolución del sistema de identificadores:

| Versión | Componente | Campo usado | Ejemplo de valor |
|---------|-----------|-------------|------------------|
| v1.5.42 | SIMAFIR variables | `idVariable` | `78` |
| v1.5.43 | EMFA países | `country_id` → SDMX | `3` → `CR` (backend) |
| v1.5.44 | SIMAFIR variables | `codigoVariable` | `CPI_T` ✅ |
| v1.5.45 | SIMAFIR países | `codigo` | `CR` ✅ |

**Progreso hacia la consistencia**:
1. ✅ v1.5.43: EMFA implementa conversión ID→SDMX en backend
2. ✅ v1.5.44: SIMAFIR variables usan códigos directamente en frontend
3. ✅ v1.5.45: SIMAFIR países usan códigos directamente en frontend

---

## 📝 Notas de Implementación

### ¿Por qué este cambio?

1. **Consistencia**: Después de v1.5.44 (variables usan códigos), era inconsistente que países usaran IDs
2. **Estándar ISO**: Los códigos ISO-2 son un estándar internacional reconocido
3. **Legibilidad**: URLs y formularios más fáciles de entender y debuggear
4. **Mantenibilidad**: Códigos estables que no dependen de estructura interna de BD

### ¿Afecta a consultas existentes?

⚠️ **Impacto potencial**: Si hay consultas guardadas o enlaces permanentes que usan IDs numéricos (`country=3`), necesitarán actualización.

**Solución recomendada**: Implementar compatibilidad hacia atrás en el backend para aceptar tanto IDs como códigos:
```php
// Backend debería aceptar:
?country=3     // ID legacy (v1.5.44)
?country=CR    // Código ISO (v1.5.45)
```

### ¿Requiere cambios en el API?

✅ **No debería requerir cambios** si el API ya acepta códigos ISO-2 en el parámetro `country`.

⚠️ **Si el API solo acepta IDs**: Requerirá actualización del backend para convertir códigos a IDs antes de consultar la BD.

---

## 🚀 Instalación

```bash
# 1. Descargar v1.5.45
cd /path/to/wordpress/wp-content/plugins/

# 2. Backup de versión actual
cp -r secmca-api secmca-api-backup-v1.5.44

# 3. Descomprimir nueva versión
unzip secmca-api-v1.5.45-SIMAFIR-CODIGO-PAIS.zip

# 4. Verificar versión
grep "Version:" secmca-api/secmca-api.php
# Output: Version: 1.5.45

# 5. Limpiar caché de WordPress
wp cache flush
```

---

## 🐛 Troubleshooting

### Problema 1: Checkboxes muestran IDs en lugar de códigos

**Síntomas**:
```html
<input name="country[]" value="3">  <!-- ID, no código -->
```

**Causas posibles**:
1. Plugin no actualizado correctamente
2. Caché de WordPress/navegador

**Solución**:
```bash
# 1. Verificar versión instalada
wp plugin list | grep secmca-api
# Debe mostrar: 1.5.45

# 2. Limpiar caché
wp cache flush

# 3. Limpiar caché del navegador (Ctrl+Shift+R)

# 4. Desactivar y reactivar plugin
wp plugin deactivate secmca-api
wp plugin activate secmca-api
```

### Problema 2: API devuelve error 400 con códigos

**Síntomas**:
```bash
curl "https://api.secmca.org/SIMAFIR?country=CR"
# Error 400: Invalid country parameter
```

**Causa**: El API backend aún no acepta códigos ISO-2

**Solución temporal**: Revertir a v1.5.44
```bash
cd wp-content/plugins/
rm -rf secmca-api
cp -r secmca-api-backup-v1.5.44 secmca-api
wp cache flush
```

**Solución permanente**: Actualizar el backend del API para aceptar códigos ISO-2

### Problema 3: Tab "Regiones" no funciona

**Síntomas**: Al hacer clic en tab "Regiones", no se muestran opciones

**Verificación**:
```javascript
// Abrir DevTools Console
console.log($('#pill-region input[name="country[]"]'));
// Debe mostrar checkboxes con value="CA", "OT", etc.
```

**Solución**: Verificar que el API devuelve elementos con `esPais: "FALSE"` y campo `codigo`

---

## 📚 Recursos Relacionados

- **v1.5.44 CHANGELOG**: Variables usan `codigoVariable`
- **v1.5.43 CHANGELOG**: EMFA implementa conversión ID→SDMX
- **ISO 3166-1 alpha-2**: Estándar de códigos de países (CR, SV, GT, etc.)
- **API SECMCA Documentation**: `api-endpoints-documentation.md`

---

## 👥 Autores y Créditos

- **Implementación**: Hugo Ferrufino
- **Testing**: [Pendiente]
- **Revisión**: [Pendiente]

---

## 🗓️ Roadmap Futuro

### Siguientes pasos (v1.5.46+):

1. **Unidades y frecuencia**: Evaluar si también deben usar códigos
2. **Compatibilidad hacia atrás**: Backend acepta IDs y códigos
3. **Validación mejorada**: Frontend valida códigos antes de enviar
4. **Documentación API**: Actualizar docs con ejemplos usando códigos

---

## ✅ Checklist de Verificación Post-Instalación

- [ ] Plugin actualizado a v1.5.45
- [ ] Caché limpiado
- [ ] HTML inspeccionado: checkboxes usan códigos ISO-2
- [ ] URL generada contiene códigos (ej: `country=CR+SV`)
- [ ] API responde 200 OK con códigos
- [ ] Tab "Pais" funciona correctamente
- [ ] Tab "Regiones" funciona correctamente
- [ ] Caso de un solo país funciona (checkbox único)
- [ ] Caso de múltiples países funciona
- [ ] Consulta generada devuelve datos correctos

---

**Versión**: 1.5.45  
**Estado**: ✅ Completado  
**Fecha de release**: 2025-01-XX
