# Configuración e Instalación de la API de Nequi

## Archivos Creados

1. **`api/nequi_api.php`** - Endpoint principal de la API de Nequi
2. **`api/nequi_setup.sql`** - Script SQL para crear la tabla de autenticación
3. **`api/nequi.txt`** - Documentación de la API (ya existía)

## Requisitos Previos

### 1. Generar Claves JWT (Requerido)

El sistema necesita un par de claves RSA para generar y validar tokens JWT. Ya existe `public_key.pem`, pero falta `private_key.pem`.

**Generar las claves:**

```bash
# En el directorio api/
# Generar clave privada (si no existe)
openssl genrsa -out private_key.pem 2048

# Generar clave pública desde la privada (si no existe)
openssl rsa -in private_key.pem -pubout -out public_key.pem
```

**IMPORTANTE:** 
- Mantener `private_key.pem` seguro y NO incluirlo en control de versiones
- Añadir `private_key.pem` al archivo `.gitignore`

### 2. Crear Tabla de Autenticación

Ejecutar el script SQL:

```bash
# Desde MySQL
mysql -u usuario -p nombre_base_datos < api/nequi_setup.sql
```

O ejecutar el contenido de `nequi_setup.sql` directamente en phpMyAdmin.

### 3. Crear Usuario de Nequi

Usar el siguiente script PHP para crear un usuario de prueba:

```php
<?php
require_once 'clases/class_conexion.php';

$conn = new conexionDB("operacion");

// Datos del usuario
$nit = '900123456';  // Cambiar por el NIT real
$usuario = 'nequi_user';  // Cambiar por el usuario real
$password = 'password_seguro';  // Cambiar por la contraseña real

// Hashear la contraseña
$password_hash = password_hash($password, PASSWORD_DEFAULT);

// Insertar usuario
$sql = "INSERT INTO grt_integracion_nequi (nit, usuario, password, activo) 
        VALUES (:nit, :usuario, :password, 1)";

$params = [
    'nit' => $nit,
    'usuario' => $usuario,
    'password' => $password_hash
];

try {
    $result = $conn->operacion($sql, $params);
    echo "Usuario creado exitosamente\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
```

### 4. Crear Carpeta de Uploads

```bash
# Crear carpeta para archivos de Nequi
mkdir -p uploads/nequi
chmod 777 uploads/nequi
```

## Uso de la API

### Autenticación (GET)

**Endpoint:** `https://tu-servidor.com/api/nequi_api.php`

**Método:** GET

**Proceso:**
1. Nequi envía credenciales a este endpoint
2. El endpoint llama internamente a `http://www.gcm.garantiascomunitarias.com/api/login`
3. El sistema GCM valida las credenciales
4. Si es válido, retorna el token JWT generado por GCM

**Body (JSON):**
```json
{
  "user": "nombre_usuario",
  "password": "contraseña"
}
```

**Respuesta Exitosa (200):**
```json
{
  "status": 200,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

**Respuesta Error (400):**
```json
{
  "status": 400,
  "error": "invalid_client"
}
```

### Reporte de Desembolso (POST)

**Endpoint:** `https://tu-servidor.com/api/nequi_api.php`

**Método:** POST

**Headers:**
```
Authentication-Type: bearer <token_obtenido_en_autenticacion>
Content-Type: application/json
```

**Body (JSON):** Ver `nequi.txt` líneas 46-92 para la lista completa de campos

**Respuesta Exitosa (200):**
```json
{
  "status": "200",
  "message": "Datos ingresados exitosamente!"
}
```

**Respuesta Error (400):**
```json
{
  "status": "400",
  "message": "Descripción del error"
}
```

## Mapeo de Campos

El endpoint mapea automáticamente los 92 campos de Nequi al formato interno del sistema:

| Campo Nequi | Campo Sistema |
|-------------|---------------|
| Numero de Convenio | convenio |
| Tipo de identificación | tipo_identificacion |
| Identificación del cliente | nit_cc |
| ... | ... |

Ver `nequi_api.php` líneas 108-152 para el mapeo completo.

## Pruebas con cURL

### 1. Obtener Token

```bash
curl -X GET https://tu-servidor.com/api/nequi_api.php \
  -H "Content-Type: application/json" \
  -d '{
    "user": "nequi_user",
    "password": "password_seguro"
  }'
```

### 2. Enviar Desembolso

```bash
curl -X POST https://tu-servidor.com/api/nequi_api.php \
  -H "Authentication-Type: bearer TU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d @datos_desembolso.json
```

## Notas Importantes

1. **Seguridad**: La clave privada `private_key.pem` es crítica para la seguridad. Nunca compartirla.

2. **Tokens**: Los tokens JWT expiran en 24 horas. Los clientes deben renovar el token periódicamente.

3. **Archivos**: Los archivos FileDto se guardan en `uploads/nequi/` con el formato:
   - `nequi_{numero_credito}_{timestamp}.{extension}`

4. **Logs**: Los errores y actividades se registran según el sistema de logging existente.

5. **CORS**: El endpoint permite peticiones desde cualquier origen (`Access-Control-Allow-Origin: *`). Ajustar según necesidades de seguridad.

## Solución de Problemas

### Error: "Token inválido"
- Verificar que las claves pública y privada coincidan
- Verificar que el token no haya expirado

### Error: "invalid_client"
- Verificar credenciales en la base de datos
- Verificar que el usuario esté activo (`activo = 1`)

### Error al guardar archivo
- Verificar permisos en la carpeta `uploads/nequi/`
- Verificar que el base64 sea válido

## Contacto

Para soporte técnico, contactar al equipo de desarrollo.