# CHANGELOG

Formato: fecha · cambio · archivos · motivo · impacto.

---

## 2026-08-12 (noche) — Guía de integración y modelo de consumo explícito

| Cambio | Archivos | Motivo | Impacto |
|---|---|---|---|
| Alta de `GUIA-INTEGRACION.md` | `doc/GUIA-INTEGRACION.md` | `README.md` e `index.html` ya la enlazaban, pero el archivo no existía: la puerta principal del integrador devolvía 404 | Ninguno sobre la API |
| Se explicita que la integración es **consulta directa REST, sin iframe** | `doc/integracion.html`, `doc/index.html`, `doc/API.md`, `doc/openapi.yaml`, `doc/SYSTEM_ANALYSIS.md` | Un tercero podía suponer el modelo del portal legado (`<iframe src="index.php?token=JWT">`), que no aplica y además no funcionaría: la API solo devuelve JSON y responde `X-Frame-Options: DENY` | Solo documentación |

Todo el contenido de la guía fue verificado contra `https://api.recarga.do` (sandbox):
autenticación, saldo, catálogo, recarga `201`, rechazo `502 INVALID_PHONE`, `422` por falta de
`Idempotency-Key`, replay con `Idempotent-Replay: true` sin segunda transacción, `415` sin
`Content-Type`, `413` con cuerpo de 70 KB, `301` de HTTP a HTTPS y `401` con credencial inválida.

Comprobado además que **ningún enlace local de la documentación queda roto** y que todos los
recursos publicados responden `200` en `doc.recarga.do`. La pista de mantenimiento apunta ahora
a `ARCHITECTURE.md`; `GUIA-DESARROLLADOR.md` no existe y ya no se enlaza desde ningún sitio.

---

## 2026-08-12 (tarde) — Endurecimiento y cierre de la ventana de pérdida

### Corrección del incidente
El saldo de las 6 empresas afectadas se restauró con respaldo previo en
`api/storage/respaldo_correctivo_20260812.json`. Verificado: **0 invariantes rotos en toda la
tabla de balances** y 0 saldos retenidos negativos.

### Cierre de la ventana de pérdida de dinero
Si el proceso muere entre la respuesta del proveedor y el `COMMIT`, la transacción quedaba en
`procesando` con el importe retenido: recarga entregada y sin cobrar. Ahora `bin/reconcile.php`
cubre ese caso, corre cada 5 minutos por cron y revalida el estado bajo `SELECT … FOR UPDATE`
para que dos barridos solapados no puedan liquidar dos veces.

### Blindaje añadido

| Medida | Efecto |
|---|---|
| Freno de fuerza bruta por IP y por `api_key` | Bloqueo 15 min tras 10 intentos fallidos por clave, 20 por IP |
| Lista blanca de IPs por token | Un secreto filtrado no sirve desde otro origen |
| Permisos por token (`Authorize`) | Modelo estricto solo si el token declara permisos; compatible con los 360 existentes |
| Solo HTTPS | `403 HTTPS_REQUIRED` en texto plano |
| Cuerpo máximo 64 KB | `413` |
| `Content-Type` obligatorio | `415` |
| Redacción de logs por hash | Ningún fragmento de secreto en claro, ni siquiera un prefijo |
| Cuerpo de autenticación del proveedor no registrado | El usuario del proveedor viajaba en un campo `user`, sin enmascarar |

### Bugs propios detectados y corregidos por las pruebas

| Bug | Consecuencia | Detección |
|---|---|---|
| `throw` dentro de `Db::transaction()` | El rollback deshacía la liberación del saldo: dinero del cliente atrapado | Prueba de escenario FAILED |
| Barrido sin acotar el alcance | Reconciliaba transacciones legacy con otro modelo de saldo | Vigilante de integridad |
| Sandbox reconciliado contra el proveedor real | Un `xid` de prueba consultado en producción | Revisión del barrido |
| Redacción con prefijo en claro | 6 caracteres de la contraseña del proveedor en el log | Auditoría del log |

### Migraciones aplicadas
`2026_08_12_000002_api_hardening.sql` — crea `api_auth_throttle` y `api_integrity_alerts`.
Aditiva, con rollback documentado.

### Mantenimiento instalado
`/etc/cron.d/recarga-api`: reconcile cada 5 min, integrity cada 10 min, purge diario.
`/etc/logrotate.d/recarga-api`: 8 semanas de logs de cron, 30 días de log estructurado.

### Pruebas
`api/tests/smoke.sh` — 28 comprobaciones automatizadas, todas superadas. Incluye idempotencia
bajo repetición, escenarios de sandbox y verificación del invariante del saldo.

### Documentación reorganizada
Tres pistas por audiencia: `RESUMEN-EJECUTIVO.md` (negocio), `GUIA-INTEGRACION.md` (comercios),
`GUIA-DESARROLLADOR.md` (mantenimiento). `index.html` pasa a ser una puerta de entrada que enruta
por rol; el manual técnico interactivo se movió a `integracion.html`.

---

## 2026-08-12 — INCIDENTE: liberación indebida de saldo (contenido)

**Qué pasó.** La primera ejecución de `bin/reconcile.php` no acotaba su alcance y procesó
**48 transacciones pendientes del sistema legado** (julio–agosto 2025) en lugar de limitarse
a las de la API v1.

MidasRed respondió «Transaccion no encontrada» para todas, por lo que se marcaron como
`fallida` — **eso es correcto y se conserva**. El problema fue el saldo: marcarlas fallidas
disparó `liberar()`, que devuelve el importe a `saldo_disponible`. Pero el sistema legado
nunca reservó esos importes: descontaba el saldo solo al completarse la transacción, y
estas nunca se completaron.

**Impacto.** RD$ 3,740.00 acreditados indebidamente a **6 empresas** (16, 17, 33, 37, 82, 87),
y `saldo_retenido` en negativo en esas mismas 6. No se creó ningún asiento en
`movimientos_balance` ni se alteró ninguna otra tabla.

**Causa raíz — corregida.** `RechargeService::barrer()` ahora exige `xid LIKE 'RD-%'`,
`empresa_id IS NOT NULL` y `request_id IS NOT NULL`: solo reconcilia transacciones creadas
por la API v1, que sí usan el modelo de reserva. Las 318 pendientes legacy restantes quedan
intactas y se tratarán con revisión humana (`MIGRATION.md` R-06).

**Corrección del saldo — PENDIENTE DE EJECUTAR.**
`api/database/migrations/2026_08_12_000003_corregir_liberacion_legacy.sql`, con verificación
previa, corrección y rollback documentado. Requiere autorización explícita.

**Lección incorporada a la documentación.** El barrido de reconciliación solo es válido
sobre transacciones que pasaron por el ciclo reservar → confirmar/liberar. Aplicarlo a
transacciones de un modelo de saldo distinto crea dinero de la nada.

---

## 2026-08-12 — Auditoría y API v1 (núcleo)

### Infraestructura

| Cambio | Archivos | Motivo | Impacto |
|---|---|---|---|
| Alta de `doc.recarga.do` con TLS | `/etc/apache2/sites-available/doc.recarga.do*.conf` | Publicar la documentación | Ninguno sobre lo existente |
| Alta de `api.recarga.do` con TLS | `/etc/apache2/sites-available/api.recarga.do*.conf` | Publicar la API | Ninguno sobre lo existente |
| DocumentRoot de la API a `public/` | mismos vhosts | Que el código no sea servible | — |
| Secretos a `/etc/recarga.do/api.env` (`0640 root:www-data`) | archivo nuevo | Corrige C-06 para la API v1 | El legado sigue con sus secretos en el webroot (ver `MIGRATION.md` R-01) |

### Base de datos

| Cambio | Motivo | Reversible |
|---|---|---|
| `CREATE TABLE api_idempotency_keys` | Idempotencia (C-03) | Sí |
| `CREATE TABLE api_rate_counters` | Rate limiting | Sí |
| `CREATE TABLE api_audit_log` | Auditoría | Sí |

Estrictamente aditivo. Ninguna tabla existente fue alterada ni eliminada. Rollback
documentado en `api/database/migrations/2026_08_12_000001_api_v1_tables.sql`.

### API v1 — implementado

- Núcleo: front controller, router, pipeline de middleware, respuesta normalizada,
  logging estructurado con redacción de secretos, `request_id` propagado.
- Autenticación por `api_key`/`api_secret` sobre `api_tokens`, con identidad derivada
  siempre del token (corrige **C-01**).
- Rate limiting atómico por token y ventana de un minuto.
- Idempotencia obligatoria en operaciones financieras (corrige **C-03**).
- `BalanceService`: reserva/confirmación/liberación con `UPDATE` atómico condicional y
  asiento contable en la misma transacción (corrige **C-02**, **C-05** y **M-02**).
- `RechargeService`: dos transacciones cortas con la llamada al proveedor en medio;
  `UNKNOWN` produce `PENDING` con el importe retenido, nunca `FAILED`.
- `MidasRedClient`: TLS verificado, timeouts de 5 s/30 s, `xid` derivado de la clave de
  idempotencia, sin reintentos automáticos en operaciones financieras (corrige **A-03**).
- Sandbox determinista para empresas con `ambiente = development`.
- Endpoints: `/v1/health`, `/v1/info`, `/v1/health/deep`, `/v1/account`, `/v1/balance`,
  `/v1/categories`, `/v1/services`, `/v1/services/{id}/packages`, `/v1/recharges`,
  `/v1/transactions`, `/v1/transactions/{id}`, `/v1/transactions/{id}/receipt`.

### Documentación

`README.md` · `SYSTEM_ANALYSIS.md` · `SECURITY_AUDIT.md` · `BUSINESS_RULES.md` ·
`ARCHITECTURE.md` · `API.md` · `DEPLOYMENT.md` · `MIGRATION.md` · `database/schema.md`

### Sistema existente

**Sin cambios.** No se modificó ningún archivo de `/var/www/html/recargas/`.

---

## Pendiente

| Elemento | Fase |
|---|---|
| Pruebas de integración y concurrencia sobre cuenta sandbox autorizada | 8 |
| `bin/reconcile.php` y `bin/purge.php` + cron | 7 |
| `POST /v1/transactions/{id}/reverse` | 7 |
| Pago de facturas (`/v1/service-payments`, `/v1/invoices`) | 7 |
| Webhooks salientes hacia clientes | 7 |
| `openapi.yaml` | 10 |
| Ejemplos en JavaScript, PHP y Python | 10 |
| Cálculo de comisiones — requiere validación financiera | — |
| Análisis de performance sobre endpoints reales | 9 |