> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mejores Prácticas y Directrices

> Mejores prácticas de seguridad, rendimiento e integración para la API de Lovi

## Introducción

Esta guía cubre las mejores prácticas de seguridad, optimización del rendimiento y directrices de integración para ayudarte a construir aplicaciones robustas con la API de Lovi.

***

## 🔒 Mejores Prácticas de Seguridad

### Gestión de Claves API

**✅ HAZ:**

* Almacena las claves API en variables de entorno o gestión de configuración segura
* Usa diferentes claves API para diferentes entornos (desarrollo, staging, producción)
* Rota las claves API regularmente (recomendado: cada 90 días)
* Monitoriza el uso de las claves API y configura alertas para actividad inusual
* Usa el principio de mínimo privilegio (claves separadas para diferentes funciones si está disponible)

**❌ NO HAGAS:**

* Codificar claves API en el código fuente o confirmarlas en el control de versiones
* Compartir claves API por email, chat u otros canales no seguros
* Usar claves API de producción en entornos de desarrollo
* Registrar claves API completas en los registros de la aplicación

### Seguridad de Autenticación

```javascript theme={null}
// ✅ Bueno - Almacenar en variables de entorno
const ACCESS_KEY = process.env.LOVI_ACCESS_KEY;

// ❌ Malo - Codificado en el código fuente
const ACCESS_KEY = 'tu-clave-api-real-aqui';
```

### Seguridad de Solicitudes

**Siempre usa HTTPS:**

```javascript theme={null}
// ✅ Bueno - Solo HTTPS
const BASE_URL = 'https://cloud.lovi.ai';

// ❌ Malo - HTTP no seguro
const BASE_URL = 'http://cloud.lovi.ai';
```

**Valida los datos de entrada:**

```javascript theme={null}
function validatePhoneNumber(number) {
  const cleaned = number.replace(/\D/g, '');
  if (!/^\d{10,15}$/.test(cleaned)) {
    throw new Error('Formato de número de teléfono inválido');
  }
  return cleaned;
}
```

***

## ⚡ Optimización del Rendimiento

### Gestión de Conexiones

**Reutiliza conexiones HTTP:**

```javascript theme={null}
const https = require('https');
const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 10
});
```

### Procesamiento por Lotes

**Procesa las notificaciones en lotes:**

```javascript theme={null}
async function sendNotificationsBatch(notifications, batchSize = 10) {
  const results = [];
  for (let i = 0; i < notifications.length; i += batchSize) {
    const batch = notifications.slice(i, i + batchSize);
    const batchPromises = batch.map(notification =>
      sendNotification(notification)
    );
    const batchResults = await Promise.allSettled(batchPromises);
    results.push(...batchResults);
    if (i + batchSize < notifications.length) {
      await sleep(100);
    }
  }
  return results;
}
```

### Estrategias de Caché

**Almacena en caché la información de plantillas:**

```javascript theme={null}
class TemplateCache {
  constructor(ttl = 3600000) {
    this.cache = new Map();
    this.ttl = ttl;
  }
  async getTemplate(templateName) {
    const cached = this.cache.get(templateName);
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }
    const template = await fetchTemplateFromAPI(templateName);
    this.cache.set(templateName, { data: template, timestamp: Date.now() });
    return template;
  }
}
```

***

## 📊 Límites de Tasa y Throttling

### Límites de Tasa

| Operación                  | Límite          | Ventana  |
| -------------------------- | --------------- | -------- |
| Autenticación              | 10 solicitudes  | 1 minuto |
| Notificaciones             | 100 solicitudes | 1 minuto |
| Recuperación de plantillas | 50 solicitudes  | 1 minuto |
| Creación de plantillas     | 5 solicitudes   | 1 hora   |

***

## 🧪 Estrategias de Pruebas

### Pruebas Unitarias

```javascript theme={null}
const mockAPIClient = {
  post: jest.fn()
};

describe('NotificationService', () => {
  test('debe enviar notificación de WhatsApp correctamente', async () => {
    mockAPIClient.post.mockResolvedValue({
      success: true,
      notification_id: 'test-123'
    });

    const service = new NotificationService(mockAPIClient);
    const result = await service.sendWhatsApp({
      phoneNumber: '34666033135',
      templateName: 'welcome',
      contactName: 'Juan García'
    });

    expect(result.success).toBe(true);
    expect(mockAPIClient.post).toHaveBeenCalledWith('/notify', expect.any(Object));
  });
});
```

***

## 🔍 Monitorización y Registro

### Registro Estructurado

```javascript theme={null}
const logger = require('winston');

async function loggedAPICall(endpoint, data) {
  const requestId = generateRequestId();
  logger.info('Solicitud API iniciada', {
    request_id: requestId,
    endpoint: endpoint,
    method: 'POST',
    timestamp: new Date().toISOString()
  });

  try {
    const response = await makeAPICall(endpoint, data);
    logger.info('Solicitud API completada', {
      request_id: requestId,
      status_code: response.status,
      success: true
    });
    return response;
  } catch (error) {
    logger.error('Solicitud API fallida', {
      request_id: requestId,
      error: error.message,
      status_code: error.statusCode
    });
    throw error;
  }
}
```

***

## 🚨 Errores Comunes y Soluciones

### Error: Valores Codificados

```javascript theme={null}
// ❌ Malo
const templateName = 'welcome_template_final_v2';

// ✅ Bueno
const templateName = config.templates.welcome;
```

### Error: Manejo Deficiente de Errores

```javascript theme={null}
// ❌ Malo
try {
  await sendNotification(data);
} catch (error) {
  console.log('Error:', error);
}

// ✅ Bueno
try {
  await sendNotification(data);
} catch (error) {
  logger.error('Notificación fallida', {
    error: error.message,
    data: sanitizeForLog(data),
    stack: error.stack
  });
  throw new NotificationError(
    'Error al enviar la notificación',
    error.statusCode,
    error.requestId
  );
}
```

### Error: Ignorar los Límites de Tasa

```javascript theme={null}
// ❌ Malo - Enviar todo a la vez
notifications.forEach(notification => {
  sendNotification(notification);
});

// ✅ Bueno - Respetar los límites de tasa
await sendNotificationsBatch(notifications, 10);
```

Recuerda: Seguir estas mejores prácticas te ayudará a construir integraciones más confiables, seguras y mantenibles con la API de Lovi.