Documentación API REST

Bienvenido a la documentación oficial de la API REST de CONTROLATOR.ES. Esta API te permite integrar todas las funcionalidades de la plataforma en tus aplicaciones y sistemas externos.

Características principales

• RESTful - Arquitectura REST estándar con verbos HTTP semánticos
• JSON - Todas las peticiones y respuestas en formato JSON
• Autenticación JWT - Tokens Bearer seguros para autenticación
• CRUD completo - Crear, Leer, Actualizar y Eliminar en todos los módulos
• Paginación - Soporte para limit/offset en listados
• Filtros - Búsqueda y filtrado avanzado por campos

Autenticación

La API utiliza autenticación basada en tokens JWT. Para acceder a los endpoints protegidos, debes incluir el token en el header Authorization de cada petición.

Formato de Respuestas

Todas las respuestas de la API siguen un formato JSON estándar:

Respuesta Exitosa

{
  "success": true,
  "data": {
    // Datos de la respuesta
  }
}

Respuesta de Error

{
  "success": false,
  "error": "Descripción del error"
}

Códigos de Error HTTP

POST /auth/login

curl -X POST https://controlator.es/api.php/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "tu_contraseña"
  }'

{
  "success": true,
  "data": {
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...",
    "user": {
      "id": "USR-2026-00001",
      "username": "admin",
      "nombre": "Administrador Sistema",
      "rol": "superadmin"
    }
  }
}

POST /auth/logout

curl -X POST https://controlator.es/api.php/auth/logout \
  -H "Authorization: Bearer tu_token_aqui"

{
  "success": true,
  "data": {
    "message": "Sesión cerrada exitosamente"
  }
}

GET /me

curl -X GET https://controlator.es/api.php/me \
  -H "Authorization: Bearer tu_token_aqui"

{
  "success": true,
  "data": {
    "_id": "USR-2026-00001",
    "username": "admin",
    "nombre": "Administrador Sistema",
    "rol": "superadmin",
    "email": "admin@municipio.es",
    "_created": "2026-01-01 10:00:00"
  }
}

Módulo: Denuncias

El módulo de denuncias permite gestionar todas las denuncias ciudadanas. Incluye información del denunciante, hechos denunciados y seguimiento del estado.

Estructura de Datos

curl -X POST https://controlator.es/api.php/denuncias \
  -H "Authorization: Bearer tu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "denunciante_nombre": "María García López",
    "denunciante_dni": "12345678A",
    "denunciante_telefono": "666777888",
    "denunciante_email": "maria@example.com",
    "tipo": "hurto",
    "fecha_hechos": "2026-01-12 14:30:00",
    "lugar_hechos": "Plaza Mayor, 5",
    "descripcion": "Sustracción de bolso en la vía pública",
    "estado": "pendiente",
    "prioridad": "media"
  }'

Módulo: Sanciones

Gestión de sanciones de tráfico y ordenanza municipal. Control del estado de tramitación y pagos.

Estructura de Datos

{
  "tipo": "trafico",
  "expediente": "2026/T/00123",
  "infractor_nombre": "Pedro Martínez Ruiz",
  "infractor_dni": "87654321B",
  "vehiculo_matricula": "1234ABC",
  "fecha_infraccion": "2026-01-12 16:45:00",
  "lugar_infraccion": "Calle Mayor, km 2",
  "infraccion_codigo": "80.1",
  "infraccion_descripcion": "Exceso de velocidad (20-30 km/h)",
  "importe": 100.00,
  "importe_reducido": 50.00,
  "puntos_carnet": 2,
  "estado": "borrador",
  "agente_denunciante": "PER-2026-00005"
}

Módulo: Atestados

Documentación de procedimientos judiciales. Incluye diligencias, pruebas y remisión a juzgado.

Campos Principales

• _id: ATE-2026-00001
• tipo: penal, civil, contencioso
• juzgado: Juzgado de destino
• fecha_remision: Fecha de envío al juzgado
• imputados: Array con datos de imputados
• victimas: Array con datos de víctimas
• diligencias: Array con diligencias practicadas
• documentos_adjuntos: Pruebas documentales

Módulo: Personal

Gestión de la plantilla municipal: datos personales, escalas, destinos, formación y permisos.

Estructura de Datos

Módulo: Vehículos

Control del parque móvil: vehículos oficiales, mantenimiento, asignaciones y consumos.

Campos Principales

• _id: VEH-2026-00001
• matricula: Matrícula del vehículo
• marca, modelo: Identificación del vehículo
• tipo: patrulla, moto, furgon, todoterreno
• bastidor: Número de bastidor
• km_actuales: Kilometraje actual
• fecha_matriculacion: Fecha de matriculación
• fecha_itv: Próxima ITV
• estado: operativo, taller, baja
• asignado_a: ID del agente asignado

Módulo: Sala 092

Registro de llamadas al 092: incidencias ciudadanas, emergencias y despacho de servicios.

Campos Principales

• _id: 092-2026-00001
• numero_llamada: Teléfono del llamante (cifrado)
• fecha_hora_entrada: Timestamp de la llamada
• tipo_incidencia: urgente, normal, informacion
• categoria: trafico, seguridad_ciudadana, ruidos, etc.
• descripcion: Motivo de la llamada
• ubicacion: Lugar de la incidencia
• operador: ID del operador que atiende
• patrulla_asignada: Unidad despachada
• estado: pendiente, en_curso, resuelta
• resultado: Resolución de la incidencia

Módulo: Turnos

Planificación de turnos y servicios. Control de presencia y horas trabajadas.

Campos Principales

• _id: TUR-2026-00001
• agente_id: ID del agente
• fecha: Fecha del turno
• tipo_turno: mañana, tarde, noche
• hora_inicio, hora_fin: Horario del turno
• servicio: patrulla, oficina, sala092, trafico
• vehiculo_asignado: Vehículo si aplica
• compañero: ID del compañero de patrulla
• estado: planificado, confirmado, realizado, ausencia

Módulo: Equipamiento

Inventario de material municipal: armas, chalecos, radios, uniformes, etc.

Campos Principales

• _id: EQU-2026-00001
• tipo: arma, chaleco, radio, uniforme, informatico
• nombre: Nombre del equipamiento
• numero_serie: Número de serie si aplica
• marca, modelo: Identificación
• estado: disponible, asignado, mantenimiento, baja
• asignado_a: ID del agente asignado
• fecha_asignacion: Fecha de asignación
• ubicacion: Ubicación física
• observaciones: Notas adicionales

GET /{módulo} - Listar Registros

curl -X GET "https://controlator.es/api.php/denuncias?limit=20&offset=0&estado=pendiente" \
  -H "Authorization: Bearer tu_token_aqui"

{
  "success": true,
  "data": {
    "records": [
      {
        "_id": "DEN-2026-00001",
        "denunciante_nombre": "Juan Pérez",
        "denunciante_dni": "12345678A",
        "tipo": "hurto",
        "estado": "pendiente",
        "_created": "2026-01-12 10:30:00"
      }
    ],
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

GET /{módulo}/:id - Obtener por ID

curl -X GET https://controlator.es/api.php/denuncias/DEN-2026-00001 \
  -H "Authorization: Bearer tu_token_aqui"

{
  "success": true,
  "data": {
    "_id": "DEN-2026-00001",
    "denunciante_nombre": "Juan Pérez",
    "denunciante_dni": "12345678A",
    "denunciante_telefono": "666555444",
    "tipo": "hurto",
    "fecha_hechos": "2026-01-12 10:30:00",
    "lugar_hechos": "Plaza Mayor",
    "descripcion": "Sustracción de cartera",
    "estado": "investigacion",
    "agente_asignado": "PER-2026-00003",
    "_created": "2026-01-12 11:00:00",
    "_modified": "2026-01-12 15:30:00"
  }
}

{
  "success": false,
  "error": "Registro no encontrado"
}

POST /{módulo} - Crear Registro

curl -X POST https://controlator.es/api.php/denuncias \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "denunciante_nombre": "María García López",
    "denunciante_dni": "87654321B",
    "denunciante_telefono": "677888999",
    "denunciante_email": "maria@example.com",
    "tipo": "robo",
    "fecha_hechos": "2026-01-12 18:00:00",
    "lugar_hechos": "Calle Principal, 42",
    "descripcion": "Robo con fuerza en las cosas en vivienda. Acceso por ventana lateral.",
    "estado": "pendiente",
    "prioridad": "alta"
  }'

{
  "success": true,
  "data": {
    "_id": "DEN-2026-00045",
    "denunciante_nombre": "María García López",
    "denunciante_dni": "87654321B",
    "denunciante_telefono": "677888999",
    "denunciante_email": "maria@example.com",
    "tipo": "robo",
    "fecha_hechos": "2026-01-12 18:00:00",
    "lugar_hechos": "Calle Principal, 42",
    "descripcion": "Robo con fuerza en las cosas en vivienda. Acceso por ventana lateral.",
    "estado": "pendiente",
    "prioridad": "alta",
    "_created": "2026-01-12 19:15:23",
    "_created_by": "USR-2026-00001",
    "_modified": "2026-01-12 19:15:23",
    "_modified_by": "USR-2026-00001",
    "_version": 1
  }
}

{
  "success": false,
  "error": "Datos requeridos"
}

PUT /{módulo}/:id - Actualizar Registro

curl -X PUT https://controlator.es/api.php/denuncias/DEN-2026-00045 \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "investigacion",
    "agente_asignado": "PER-2026-00007",
    "observaciones": "Asignada a la unidad de investigación. Solicitar grabaciones CCTV de la zona."
  }'

{
  "success": true,
  "data": {
    "_id": "DEN-2026-00045",
    "denunciante_nombre": "María García López",
    "denunciante_dni": "87654321B",
    "tipo": "robo",
    "estado": "investigacion",
    "agente_asignado": "PER-2026-00007",
    "observaciones": "Asignada a la unidad de investigación. Solicitar grabaciones CCTV de la zona.",
    "_created": "2026-01-12 19:15:23",
    "_created_by": "USR-2026-00001",
    "_modified": "2026-01-12 21:45:00",
    "_modified_by": "USR-2026-00003",
    "_version": 2
  }
}

{
  "success": false,
  "error": "Registro no encontrado"
}

DELETE /{módulo}/:id - Eliminar Registro

curl -X DELETE https://controlator.es/api.php/denuncias/DEN-2026-00045 \
  -H "Authorization: Bearer tu_token_aqui"

{
  "success": true,
  "data": {
    "message": "Registro eliminado exitosamente"
  }
}

{
  "success": false,
  "error": "Sin permisos para esta operación"
}

Paginación y Filtros Avanzados

La API soporta paginación y filtrado avanzado en todos los endpoints de listado.

Parámetros de Paginación

Filtros Dinámicos

Puedes filtrar por cualquier campo del registro añadiéndolo como parámetro query:

# Filtrar denuncias por estado
curl "https://controlator.es/api.php/denuncias?estado=pendiente" \
  -H "Authorization: Bearer tu_token"

# Filtrar sanciones por tipo y estado
curl "https://controlator.es/api.php/sanciones?tipo=trafico&estado=firme" \
  -H "Authorization: Bearer tu_token"

# Filtrar personal por escala
curl "https://controlator.es/api.php/personal?escala=oficial&situacion=activo" \
  -H "Authorization: Bearer tu_token"

# Combinar paginación y filtros
curl "https://controlator.es/api.php/denuncias?estado=investigacion&limit=50&offset=100" \
  -H "Authorization: Bearer tu_token"

Cálculo de Páginas

// Ejemplo de paginación en JavaScript
const perPage = 20;
let currentPage = 1;

async function loadPage(page) {
  const offset = (page - 1) * perPage;
  const response = await fetch(
    `https://controlator.es/api.php/denuncias?limit=${perPage}&offset=${offset}`,
    { headers: { 'Authorization': `Bearer ${token}` }}
  );
  const data = await response.json();

  const totalPages = Math.ceil(data.data.total / perPage);
  console.log(`Página ${page} de ${totalPages}`);

  return data.data.records;
}

Sistema de Permisos

La API implementa un sistema RBAC (Role-Based Access Control) con 6 roles predefinidos y permisos granulares.

Roles del Sistema

Formato de Permisos

Los permisos siguen el formato {módulo}.{acción}:

• denuncias.ver - Ver denuncias
• denuncias.crear - Crear denuncias
• denuncias.editar - Editar denuncias
• denuncias.eliminar - Eliminar denuncias
• denuncias.* - Todos los permisos del módulo
• *.* - Todos los permisos del sistema

Mapeo de Operaciones HTTP a Permisos

Seguridad y Cumplimiento Normativo

La API implementa múltiples capas de seguridad para cumplir con ENS, RGPD y LO 7/2021.

Cifrado de Datos Sensibles

Los campos sensibles se cifran automáticamente con AES-256-GCM:

• DNI/NIE (denunciante, infractor, personal)
• Teléfonos de contacto
• Direcciones y domicilios
• Datos médicos si aplica
• Información bancaria

Auditoría y Trazabilidad

Todas las operaciones quedan registradas en el log de auditoría:

• Usuario que realiza la operación (_created_by, _modified_by)
• Fecha y hora exacta de cada cambio
• Versión del registro (_version)
• Hash SHA-256 de integridad (_hash)
• Soft delete con marca temporal (_deleted)

Tokens de Autenticación

• Validez: 7 días desde la emisión
• Almacenamiento: Nunca almacenes tokens en localStorage en frontend, usa sessionStorage o cookies HttpOnly
• Renovación: Solicita nuevo token con /auth/login cuando expire
• Cierre de sesión: Invalida el token con /auth/logout

Buenas Prácticas de Seguridad

// ✅ CORRECTO: Almacenamiento seguro del token
sessionStorage.setItem('api_token', token);

// ❌ INCORRECTO: No usar localStorage para tokens
localStorage.setItem('api_token', token);

// ✅ CORRECTO: Validar siempre las respuestas
if (response.success) {
  // Procesar datos
} else {
  // Manejar error
  console.error(response.error);
}

// ✅ CORRECTO: Implementar timeout en peticiones
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);

fetch(url, {
  signal: controller.signal,
  headers: { 'Authorization': `Bearer ${token}` }
}).finally(() => clearTimeout(timeout));

Buenas Prácticas de Desarrollo

1. Manejo de Errores

Implementa siempre un manejo robusto de errores:

async function apiRequest(endpoint, options = {}) {
  try {
    const response = await fetch(`https://controlator.es/api.php${endpoint}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        ...options.headers
      }
    });

    const data = await response.json();

    if (!response.ok) {
      throw new Error(data.error || 'Error en la petición');
    }

    return data.data;
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Petición cancelada por timeout');
    } else if (!navigator.onLine) {
      console.error('Sin conexión a internet');
    } else {
      console.error('Error:', error.message);
    }
    throw error;
  }
}

2. Reintentos con Backoff Exponencial

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

3. Cacheo de Respuestas

Implementa cacheo para reducir peticiones innecesarias:

class APICache {
  constructor(ttl = 60000) {
    this.cache = new Map();
    this.ttl = ttl; // Time to live en ms
  }

  get(key) {
    const item = this.cache.get(key);
    if (!item) return null;

    if (Date.now() > item.expiry) {
      this.cache.delete(key);
      return null;
    }

    return item.value;
  }

  set(key, value) {
    this.cache.set(key, {
      value,
      expiry: Date.now() + this.ttl
    });
  }
}

const cache = new APICache(60000); // Cache de 1 minuto

4. Validación de Datos en Cliente

Valida los datos antes de enviarlos para reducir errores:

function validateDenuncia(data) {
  const errors = [];

  if (!data.denunciante_nombre || data.denunciante_nombre.length < 3) {
    errors.push('Nombre del denunciante requerido');
  }

  if (!/^\d{8}[A-Z]$/.test(data.denunciante_dni)) {
    errors.push('DNI inválido');
  }

  if (!data.descripcion || data.descripcion.length < 20) {
    errors.push('Descripción demasiado corta (mín. 20 caracteres)');
  }

  return errors.length === 0 ? null : errors;
}

5. Paginación Eficiente

class PaginatedRequest {
  constructor(endpoint, perPage = 50) {
    this.endpoint = endpoint;
    this.perPage = perPage;
    this.currentPage = 1;
    this.totalRecords = 0;
  }

  async loadPage(page) {
    const offset = (page - 1) * this.perPage;
    const url = `${this.endpoint}?limit=${this.perPage}&offset=${offset}`;

    const response = await apiRequest(url);
    this.totalRecords = response.total;
    this.currentPage = page;

    return response.records;
  }

  get totalPages() {
    return Math.ceil(this.totalRecords / this.perPage);
  }

  hasNextPage() {
    return this.currentPage < this.totalPages;
  }

  async nextPage() {
    if (!this.hasNextPage()) return null;
    return this.loadPage(this.currentPage + 1);
  }
}

Ejemplos de Código Completos

JavaScript (Fetch API)

// Autenticación
const login = async () => {
  const response = await fetch('https://controlator.es/api.php/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'admin',
      password: 'tu_contraseña'
    })
  });
  const data = await response.json();
  return data.data.token;
};

// Obtener denuncias
const getDenuncias = async (token) => {
  const response = await fetch('https://controlator.es/api.php/denuncias?limit=20', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  const data = await response.json();
  return data.data.records;
};

PHP (cURL)

// Autenticación
$ch = curl_init('https://controlator.es/api.php/auth/login');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'username' => 'admin',
    'password' => 'tu_contraseña'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
$token = $response['data']['token'];

Python (Requests)

import requests

# Autenticación
response = requests.post('https://controlator.es/api.php/auth/login', json={
    'username': 'admin',
    'password': 'tu_contraseña'
})
token = response.json()['data']['token']

# Obtener denuncias
headers = {'Authorization': f'Bearer {token}'}
response = requests.get('https://controlator.es/api.php/denuncias?limit=20', headers=headers)
denuncias = response.json()['data']['records']

Rate Limits

Para garantizar la estabilidad del servicio, la API implementa los siguientes límites:

• 1000 peticiones por hora por token de autenticación
• 50 peticiones por minuto por IP

Cuando se excede el límite, recibirás un error 429 Too Many Requests.