# OTP por WhatsApp falla en desarrollo por verificación TLS de cURL

- **Código:** BUG-007
- **Tipo:** bugfix
- **Estado:** en curso

## Objetivo

Restaurar el envío del código OTP por WhatsApp en el entorno local/desarrollo de nuevo ingreso, alineando la verificación TLS de cURL con el patrón que ya usa `GoHighLevelClient` para desarrollo y pruebas. El objetivo es que los dos flujos de OTP (postulación nueva y retorno de una postulación existente) vuelvan a entregar el código sin debilitar la seguridad en producción.

## Alcance

- Incluye: ajustar únicamente el despacho HTTP de `Paso0::enviarWhatsappOtp()` para desactivar la verificación TLS cuando `ENVIRONMENT` sea `development` o `testing`.
- Incluye: mantener la verificación TLS estricta en `production`.
- Incluye: verificación manual (smoke test) de los dos flujos de OTP por WhatsApp y del canal correo sin cambios.
- Incluye: dejar constancia de que el payload, el template, las credenciales y los mensajes de usuario no se modifican.
- No incluye: corregir los campos `messaging_account_id` o `recipient_type` del payload. Se mantienen como están por decisión del usuario; si Meta devuelve un `400` después de restaurar TLS, se atenderá en un bugfix separado.
- No incluye: fallback automático a correo, cambios en el texto del error, cambios en `OtpInscripcion`, rutas, filtros, sesión o base de datos.
- No incluye: modificar `IpgBdv2` ni otras integraciones con cURL.
- No incluye: agregar pruebas automatizadas ni scripts de verificación. La verificación será manual por decisión explícita del usuario.

## Problema

En el Paso 0 de nuevo ingreso, al elegir la validación OTP por WhatsApp (canal `1`), el código no llega y la interfaz muestra:

> No se pudo generar el código de verificación: No se pudo entregar el mensaje por WhatsApp.

El mismo flujo por correo (canal `0`) sí entrega el código. El defecto se reproduce tanto en la postulación nueva (`solicitarOtpNuevo`) como en el retorno de una cédula ya registrada (`consultarCedula`), porque ambos terminan en `Paso0::enviarWhatsappOtp()`.

La evidencia del log local es:

```text
ERROR - 2026-10-28 21:31:44 --> Error Meta WhatsApp OTP [584*********] HTTP 0 SSL certificate problem: unable to get local issuer certificate:
```

El fallo existe en entornos donde PHP/cURL no tiene un almacén de CA configurado. En esta máquina, `curl.cainfo`, `openssl.cafile` y `openssl.capath` están vacíos con PHP 8.0.30 (WAMP), por lo que la conexión TLS a `graph.facebook.com` falla antes de llegar a Meta. El defecto está presente desde la introducción del envío por WhatsApp (commit `100e410`) en cualquier entorno sin CA configurado.

## Impacto

- **Usuarios afectados:** solo el entorno local/desarrollo del equipo. Producción no está afectada según la confirmación del usuario; el envío funcionó en el equipo de quien programó la integración.
- **Procesos:** impide probar y validar el canal WhatsApp del OTP de nuevo ingreso en local; el canal correo sigue operativo.
- **Datos y pagos:** sin impacto. El OTP generado se invalida al fallar el despacho y no se alteran inscripciones, pagos ni estados.
- **Gravedad:** media para el desarrollo y QA, nula para producción.
- **Clasificación:** **bugfix**, no hotfix, porque no hay afectación confirmada a usuarios reales en producción.

## Reproducción

1. Confirmar que el `.env` local tiene `CI_ENVIRONMENT = development`.
2. Iniciar la aplicación en local (`php spark serve --port 8080` o el virtual host de WAMP).
3. Abrir el flujo de nuevo ingreso y llegar al Paso 0.
4. Introducir una cédula que no tenga postulación o una que ya la tenga, y seleccionar la opción de validación por WhatsApp.
5. Confirmar que el número de prueba tiene formato internacional con código de país (por ejemplo, `58...`).
6. Enviar la solicitud.
7. **Resultado actual:** la petición responde `500` con `No se pudo generar el código de verificación: No se pudo entregar el mensaje por WhatsApp.` y en `writable/logs/` aparece `HTTP 0 SSL certificate problem: unable to get local issuer certificate`.
8. **Comprobación de causa:** ejecutar `php -r "echo ini_get('curl.cainfo').PHP_EOL; echo ini_get('openssl.cafile').PHP_EOL;"` y verificar que ambas salidas están vacías.

## Comportamiento esperado

- Al elegir WhatsApp, el sistema genera el OTP y lo entrega mediante la API de Meta.
- La interfaz redirige a `/inscripciones/nuevo-ingreso/otp` y el usuario recibe el mensaje con el código.
- El canal correo sigue funcionando igual.
- En `production`, la verificación TLS se mantiene activa y no se aceptan certificados inválidos.
- No cambian mensajes, payload, template, credenciales, rutas ni reglas de negocio.

## Causa raíz (hipótesis)

**Confirmada por evidencia de log y reproducción local.**

`Paso0::enviarWhatsappOtp()` (`app/Controllers/Inscripciones/NuevoIngreso/Paso0.php:798`) usa cURL directo sin configurar una CA de confianza:

- `curl_init()` y `curl_setopt_array()` en `Paso0.php:833-843` no definen `CURLOPT_CAINFO` ni ajustan la verificación TLS.
- El PHP local (WAMP 8.0.30) no tiene `curl.cainfo` ni `openssl.cafile`, por lo que OpenSSL no encuentra la CA raíz.
- `curl_exec()` devuelve `false` con error `SSL certificate problem: unable to get local issuer certificate` y `CURLINFO_HTTP_CODE` queda en `0`.
- El bloque `Paso0.php:850-853` interpreta cualquier estado fuera de `2xx` (incluido `0`, que es un fallo de transporte) como rechazo de Meta y lanza el mensaje genérico.

El proyecto ya resolvió este mismo problema en `GoHighLevelClient` (`app/Libraries/GoHighLevel/GoHighLevelClient.php:38-40`): desactiva `verify` cuando `ENVIRONMENT` es `development` o `testing`, y lo mantiene activo en producción. La corrección debe replicar ese criterio en el cURL de WhatsApp. No se modifica el payload porque la petición nunca llegó a Meta: el fallo ocurre en el handshake TLS.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso0.php` | Agregar en `enviarWhatsappOtp()` la desactivación condicional de `CURLOPT_SSL_VERIFYPEER` y `CURLOPT_SSL_VERIFYHOST` solo para `development`/`testing`, antes de `curl_exec()`. |
| Referencia (sin cambios) | `app/Libraries/GoHighLevel/GoHighLevelClient.php` | Patrón existente del proyecto para desactivar TLS solo en desarrollo/pruebas. No se modifica. |
| Referencia (sin cambios) | `.env` | Debe permanecer con `CI_ENVIRONMENT = development` en local. No se versiona ni se modifica desde este plan. |

No se agregan archivos nuevos.

Orientación de implementación (no implementar en este paso): dentro de `enviarWhatsappOtp()`, antes de `curl_exec()`, agregar un bloque equivalente a:

```php
if (in_array(ENVIRONMENT, ['development', 'testing'], true)) {
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
}
```

La corrección debe cubrir los tres puntos de entrada que llaman a este método (`consultarCedula`, `solicitarOtpNuevo` y `reenviarOtp`) sin duplicar lógica, porque todos pasan por el mismo método.

## Plan de verificación

### Prueba manual (flujo normal)

1. Confirmar en `.env` que `CI_ENVIRONMENT = development`.
2. Anotar la marca de tiempo actual de `writable/logs/` para distinguir los registros nuevos.
3. **Flujo de postulación nueva:** abrir `/inscripciones/nuevo-ingreso`, completar el formulario con un número de prueba con código de país y elegir validación por WhatsApp.
   - Resultado esperado: la petición responde con `status: true`, redirige a `/inscripciones/nuevo-ingreso/otp` y el mensaje llega al número de prueba.
4. **Flujo de retorno:** consultar una cédula con postulación existente, seleccionar WhatsApp y enviar.
   - Resultado esperado: mismo comportamiento del punto 3.
5. **Reenvío:** en la pantalla OTP, esperar el cooldown y usar "Reenviar código".
   - Resultado esperado: el nuevo código llega por WhatsApp.
6. **Canal correo:** repetir el Paso 0 eligiendo correo.
   - Resultado esperado: sin regresiones; el código llega por correo como antes.
7. Revisar `writable/logs/` y confirmar que no aparecen nuevas entradas con `SSL certificate problem` ni `HTTP 0`. Si Meta responde `400`, registrar el cuerpo del error: por decisión de alcance no se corrige el payload en este bugfix.
8. **Guardia de producción:** revisar que la condición use `ENVIRONMENT` y no una bandera fija. Confirmar por inspección que con `CI_ENVIRONMENT = production` las opciones TLS no se desactivan. No ejecutar este cambio contra producción.

### Prueba automatizada / código de verificación

No se incluye código de verificación por decisión explícita del usuario. La verificación es manual (smoke test) desde los flujos reales del Paso 0. El repositorio tiene PHPUnit, pero no existe una prueba de `Paso0` y la suite completa tiene un fallo preexistente en `tests/app/Models/BotChatSystemTest.php`; agregar infraestructura de mocking de cURL excedería este bugfix.

## Riesgos y efectos secundarios

- **Riesgo de seguridad si el entorno se configura mal:** desactivar TLS en `development`/`testing` es aceptable solo en local o pruebas. Si un servidor compartido se despliega con `CI_ENVIRONMENT = development`, quedaría expuesto a interceptación. Verificar el `.env` del servidor antes de desplegar.
- **Alcance del cambio:** se desactivan tanto la verificación del par como la del host, igual que en `GoHighLevelClient`; no se toca producción.
- **Payload no validado:** al no haber llegado nunca a Meta en local, no se sabe si `messaging_account_id`/`recipient_type` son aceptados. Si tras el fix Meta responde `400`, se documentará como bugfix aparte.
- **Credenciales/token:** si el token local está vencido, el fallo cambiará de SSL a `401`/`190`; no es parte de este defecto, pero debe distinguirse al verificar.
- **Logs:** las líneas de log incluyen el número de teléfono y el código OTP. No deben copiarse a documentación, tickets ni commits con datos reales.

## Criterios de finalización

- [ ] En local (`development`), el OTP por WhatsApp se envía en el flujo de postulación nueva.
- [ ] En local, el OTP por WhatsApp se envía en el flujo de retorno de una postulación existente.
- [ ] El reenvío de OTP por WhatsApp funciona tras el cooldown.
- [ ] El canal correo sigue funcionando sin cambios.
- [ ] `writable/logs/` ya no registra `SSL certificate problem` ni `HTTP 0` para el envío de WhatsApp.
- [ ] La verificación TLS permanece activa cuando `ENVIRONMENT` es `production` (confirmado por inspección del código).
- [ ] No se modificaron payload, template, credenciales, mensajes de usuario, rutas ni reglas de negocio.
- [ ] No se agregaron secretos ni datos personales al repositorio.

## Notas del programador

- La causa raíz está confirmada; no se debe "arreglar" desactivando TLS de forma global ni en producción.
- La condición debe evaluarse en tiempo de ejecución con `ENVIRONMENT`, siguiendo el patrón de `GoHighLevelClient.php:39-40`.
- No usar `CURLOPT_SSL_VERIFYPEER => false` sin la guarda de entorno.
- El log actual ya incluye el error de cURL; no es necesario cambiar el mensaje al usuario ni el manejo de excepciones para cerrar este bugfix.
- Si se quiere una solución más portable a futuro (CA bundle por `.env` o `curl.cainfo`), debe tratarse como mejora separada. En este bugfix se prioriza restaurar el flujo local con el patrón ya aceptado por el proyecto.
- No se ejecutó `graphify update` porque este plan no modifica código de la aplicación.
