Especificación de API REST

JavaScript / Node.js

// Autenticación
const axios = require('axios');
const API_URL = 'https://municipio.ayuntamientosmart.com/api/v1';

async function login(usuario, password) {
  const response = await axios.post(`${API_URL}/auth/login`, {
    usuario,
    password
  });
  return response.data.data.token;
}

// Listar denuncias
async function getDenuncias(token) {
  const response = await axios.get(`${API_URL}/denuncias`, {
    headers: {
      'Authorization': `Bearer ${token}`
    },
    params: {
      tipo: 'hechos',
      limit: 50
    }
  });
  return response.data.data;
}

// Uso
const token = await login('agente123', 'password');
const denuncias = await getDenuncias(token);
console.log(denuncias);

Python

import requests
import json

API_URL = 'https://municipio.ayuntamientosmart.com/api/v1'

# Autenticación
def login(usuario, password):
    response = requests.post(
        f'{API_URL}/auth/login',
        json={'usuario': usuario, 'password': password}
    )
    return response.json()['data']['token']

# Crear denuncia
def crear_denuncia(token, datos):
    response = requests.post(
        f'{API_URL}/denuncias',
        headers={'Authorization': f'Bearer {token}'},
        json=datos
    )
    return response.json()

# Uso
token = login('agente123', 'password')
denuncia = crear_denuncia(token, {
    'tipo': 'perdida',
    'denunciante': {
        'dni': '12345678A',
        'nombre': 'Juan López',
        'telefono': '666123456'
    },
    'hechos': {
        'fecha': '2026-01-10',
        'lugar': 'Plaza España',
        'descripcion': 'Pérdida de cartera'
    }
})
print(denuncia)

PHP

<?php
$API_URL = 'https://municipio.ayuntamientosmart.com/api/v1';

// Autenticación
function login($usuario, $password) {
    global $API_URL;
    $ch = curl_init("$API_URL/auth/login");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'usuario' => $usuario,
        'password' => $password
    ]));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    $data = json_decode($response, true);
    return $data['data']['token'];
}

// Consultar vehículo
function consultarVehiculo($token, $matricula) {
    global $API_URL;
    $ch = curl_init("$API_URL/vehiculos/dgt/$matricula");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    return json_decode($response, true);
}

// Uso
$token = login('agente123', 'password');
$vehiculo = consultarVehiculo($token, '1234ABC');
print_r($vehiculo);
?>

cURL (línea de comandos)

# Autenticación
curl -X POST https://municipio.ayuntamientosmart.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"usuario":"agente123","password":"password"}'

# Guardar token
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Listar denuncias
curl -X GET "https://municipio.ayuntamientosmart.com/api/v1/denuncias?limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Crear denuncia
curl -X POST https://municipio.ayuntamientosmart.com/api/v1/denuncias \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @denuncia.json

Límites por usuario

Cada token JWT tiene los siguientes límites:

• 1000 peticiones/hora para endpoints de lectura (GET)
• 100 peticiones/hora para endpoints de escritura (POST, PUT, PATCH, DELETE)
• 10 peticiones/minuto para consultas a DGT (endpoints /vehiculos/dgt/*)

Si se excede el límite, la API devuelve código 429 Too Many Requests con una cabecera Retry-After indicando cuántos segundos esperar.

Cabeceras de rate limit

Cada respuesta incluye cabeceras informativas:

• X-RateLimit-Limit: Límite total de peticiones
• X-RateLimit-Remaining: Peticiones restantes en el periodo actual
• X-RateLimit-Reset: Timestamp Unix cuando se resetea el contador

Monitorice estas cabeceras para evitar alcanzar el límite.

Límites aumentados

Si necesita límites superiores para integraciones críticas o con alto volumen, contacte con soporte técnico. Es posible aumentar los límites previa justificación y análisis de impacto en el sistema.

Configuración de webhooks

Desde el panel de administración, puede configurar URLs de webhook que serán invocadas cuando ocurran eventos específicos. Configure:

• URL de destino (debe ser HTTPS)
• Eventos a escuchar (denuncia.creada, sancion.pagada, etc.)
• Secret para validar la firma HMAC de las peticiones

Eventos disponibles

Eventos que pueden suscribirse:

• denuncia.creada
• denuncia.modificada
• denuncia.eliminada
• sancion.creada
• sancion.pagada
• sancion.alegacion_presentada
• atestado.creado
• atestado.enviado_lexnet

Formato de payload

Cuando ocurre un evento, se envía un POST a la URL configurada con JSON:

{
  "event": "denuncia.creada",
  "timestamp": "2026-01-10T15:30:00Z",
  "data": {
    "id": "DEN-2026-00123",
    /* ... datos del objeto ... */
  }
}

La petición incluye cabecera X-Webhook-Signature con firma HMAC-SHA256 del payload usando el secret configurado.

Validación de firma

Para verificar que el webhook proviene realmente del sistema:

const crypto = require('crypto');

function validarWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}

Versión actual

La versión actual es v1 (disponible en /api/v1/). Esta versión se mantendrá estable y compatible hacia atrás. Cualquier cambio que rompa compatibilidad se publicará como una nueva versión (v2, v3, etc.).

Cambios compatibles

Se consideran cambios compatibles (pueden hacerse en la misma versión):

• Añadir nuevos endpoints
• Añadir nuevos campos opcionales en las respuestas
• Añadir nuevos parámetros opcionales en las peticiones
• Añadir nuevos códigos de error

Cambios incompatibles

Cambios que requieren nueva versión:

• Eliminar o renombrar endpoints
• Eliminar campos de las respuestas
• Cambiar tipos de datos de campos existentes
• Hacer obligatorios parámetros que eran opcionales
• Cambiar el comportamiento de endpoints existentes

Deprecaciones

Antes de eliminar funcionalidad en una nueva versión, se marcará como deprecada en la versión actual durante al menos 6 meses. Las funcionalidades deprecadas incluirán una cabecera de respuesta Warning indicándolo.

HTTPS obligatorio

Todas las peticiones deben realizarse por HTTPS (TLS 1.3). Las peticiones HTTP son rechazadas con error 403. Los certificados SSL son validados, no se admiten certificados autofirmados.

Autenticación JWT

Los tokens JWT están firmados con algoritmo HS256 usando clave secreta de 256 bits almacenada de forma segura. Cada token incluye claims: usuario id, rol, permisos, fecha de expiración. Los tokens no pueden modificarse sin invalidar la firma.

Control de permisos

Cada endpoint requiere permisos específicos. El token JWT incluye los permisos del usuario. Si intenta acceder a un endpoint sin permisos, recibe 403 Forbidden. Los permisos se comprueban en cada petición contra el sistema RBAC.

Auditoría completa

Todas las peticiones a la API se registran en el log de auditoría con: usuario, endpoint, parámetros, IP origen, timestamp, resultado. Los logs se conservan 3 años según ENS. Pueden consultarse desde el panel de administración.

Protección contra ataques

Implementado:

• Rate limiting para prevenir abuso
• Validación de input contra inyecciones SQL, XSS, etc.
• Sanitización de parámetros
• Protección CSRF no necesaria (autenticación stateless con JWT)
• Cabeceras de seguridad: HSTS, X-Content-Type-Options, X-Frame-Options