Skip to main content

API Reference - Visión General

La API REST de ClickAware proporciona acceso programático completo a todas las funcionalidades de la plataforma, permitiendo integraciones personalizadas y automatización avanzada.

Información General​

Base URL​

https://api.clickaware.es/v1

Autenticación​

Todas las peticiones requieren autenticación mediante Bearer Token JWT:

Authorization: Bearer <jwt_token>

Formato de Respuesta​

Todas las respuestas están en formato JSON con estructura consistente:

{
"success": true,
"data": { ... },
"message": "Operation completed successfully",
"timestamp": "2025-01-01T10:00:00Z"
}

Endpoints Principales​

Autenticación​

POST /auth/login # Iniciar sesión
POST /auth/refresh # Renovar token
POST /auth/logout # Cerrar sesión
POST /auth/forgot-password # Recuperar contraseña

Usuarios​

GET /users # Listar usuarios
POST /users # Crear usuario
GET /users/{id} # Obtener usuario
PUT /users/{id} # Actualizar usuario
DELETE /users/{id} # Eliminar usuario

Campañas de Phishing​

GET /phishing/campaigns # Listar campañas
POST /phishing/campaigns # Crear campaña
GET /phishing/campaigns/{id} # Obtener campaña
PUT /phishing/campaigns/{id} # Actualizar campaña
POST /phishing/send # Enviar simulación
GET /phishing/stats # Estadísticas

Entrenamientos​

GET /training/modules # Módulos disponibles
POST /training/assign # Asignar entrenamiento
GET /training/progress # Progreso de usuario
POST /training/complete # Marcar como completado

Reportes​

GET /reports/dashboard # Métricas del dashboard
GET /reports/users # Reporte de usuarios
GET /reports/campaigns # Reporte de campañas
GET /reports/export # Exportar datos

Códigos de Estado HTTP​

CódigoSignificadoDescripción
200OKPetición exitosa
201CreatedRecurso creado exitosamente
400Bad RequestParámetros inválidos
401UnauthorizedToken inválido o expirado
403ForbiddenSin permisos suficientes
404Not FoundRecurso no encontrado
429Too Many RequestsLímite de tasa excedido
500Internal Server ErrorError del servidor

Rate Limiting​

La API implementa límites de tasa para prevenir abuso:

  • Usuarios estándar: 100 peticiones/minuto
  • Administradores: 500 peticiones/minuto
  • API Keys: 1000 peticiones/minuto

Headers de respuesta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Versionado​

La API utiliza versionado semántico en la URL:

  • v1: Versión actual estable
  • v2: Próxima versión (beta)

Paginación​

Los endpoints que devuelven listas implementan paginación:

GET /users?page=1&limit=50&sort=created_at&order=desc

Respuesta:

{
"success": true,
"data": [...],
"pagination": {
"current_page": 1,
"per_page": 50,
"total": 1250,
"total_pages": 25,
"has_next": true,
"has_prev": false
}
}

Filtrado y Búsqueda​

Filtros Comunes​

GET /users?department=IT&status=active&created_after=2024-01-01

Búsqueda de Texto​

GET /users?search=john.doe&fields=name,email

Ordenamiento​

GET /campaigns?sort=created_at&order=desc

Webhooks​

ClickAware puede enviar notificaciones en tiempo real a tu sistema:

Eventos Disponibles​

  • user.created - Usuario creado
  • campaign.started - Campaña iniciada
  • campaign.completed - Campaña finalizada
  • phishing.clicked - Usuario hizo clic en phishing
  • phishing.reported - Usuario reportó phishing
  • training.completed - Entrenamiento completado

Configuración​

POST /webhooks
{
"url": "https://tu-sistema.com/webhook",
"events": ["phishing.clicked", "training.completed"],
"secret": "tu_secreto_para_verificacion"
}

SDKs Disponibles​

JavaScript/Node.js​

npm install @clickaware/sdk-js
import ClickAware from '@clickaware/sdk-js';

const client = new ClickAware({
apiKey: 'tu_api_key',
baseURL: 'https://api.clickaware.es/v1'
});

const users = await client.users.list();

Python​

pip install clickaware-sdk
from clickaware import ClickAware

client = ClickAware(api_key='tu_api_key')
users = client.users.list()

PHP​

composer require clickaware/sdk-php
use ClickAware\Client;

$client = new Client('tu_api_key');
$users = $client->users()->list();

Ejemplos de Uso​

Crear y Lanzar Campaña​

// 1. Crear campaña
const campaign = await client.campaigns.create({
name: "Campaña Q1 2025",
template_id: "netflix-phishing",
target_users: ["user1@empresa.com", "user2@empresa.com"],
schedule_date: "2025-01-15T09:00:00Z"
});

// 2. Lanzar campaña
await client.campaigns.launch(campaign.id);

// 3. Monitorear resultados
const stats = await client.campaigns.stats(campaign.id);
console.log(`Tasa de clic: ${stats.click_rate}%`);

Automatizar Entrenamientos​

# Obtener usuarios con alto riesgo
high_risk_users = client.users.list(filters={'risk_level': 'high'})

# Asignar entrenamiento específico
for user in high_risk_users:
client.training.assign(
user_id=user.id,
module_id='advanced-phishing-detection',
due_date='2025-02-01'
)

Casos de Uso Comunes​

1. Integración con SIEM​

Exportar eventos de seguridad a tu sistema SIEM:

const events = await client.events.list({
type: 'security',
since: '2025-01-01T00:00:00Z'
});

// Enviar a SIEM
events.forEach(event => {
siem.sendEvent(event);
});

2. Dashboard Personalizado​

Crear dashboards personalizados con métricas en tiempo real:

const metrics = await client.reports.dashboard({
timeframe: 'last_30_days',
departments: ['IT', 'Finance', 'HR']
});

updateDashboard(metrics);

3. Automatización de Respuesta​

Responder automáticamente a incidentes de alto riesgo:

# Webhook handler
@app.route('/webhook', methods=['POST'])
def handle_webhook():
event = request.json

if event['type'] == 'phishing.clicked':
# Usuario de alto riesgo - asignar entrenamiento inmediato
client.training.assign_urgent(
user_id=event['user_id'],
module_id='immediate-security-training'
)

# Notificar al administrador
client.notifications.send_admin_alert(
message=f"Usuario {event['user_email']} hizo clic en phishing",
severity='high'
)

Próximos Pasos​

Explora la documentación detallada de cada endpoint: