Especificación de API REST

Capítulo 1: Introducción a la API

La API REST de ayuntamientosmart.com proporciona acceso programático a las principales funcionalidades del sistema. Está diseñada siguiendo los principios REST (Representational State Transfer) y utiliza los métodos HTTP estándar:

• GET: Consultar recursos existentes
• POST: Crear nuevos recursos
• PUT: Actualizar recursos existentes (reemplazo completo)
• PATCH: Actualizar recursos existentes (modificación parcial)
• DELETE: Eliminar recursos

Todas las peticiones y respuestas utilizan formato JSON. Las fechas se expresan en formato ISO 8601 (YYYY-MM-DDTHH:mm:ss). Los errores devuelven códigos HTTP estándar (400, 401, 403, 404, 500) con un objeto JSON descriptivo.

Capítulo 2: Autenticación

La API utiliza autenticación basada en JWT (JSON Web Tokens). El flujo de autenticación es:

Obtención del token

Endpoint: POST /api/v1/auth/login

{
  "usuario": "agente123",
  "password": "mi_password_segura"
}

Respuesta exitosa (200 OK):

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2026-01-11T15:30:00",
    "usuario": {
      "id": "usr-123",
      "nombre": "Juan Pérez",
      "rol": "agente"
    }
  }
}

Uso del token

Una vez obtenido el token, debe incluirse en todas las peticiones en la cabecera Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Renovación del token

Los tokens expiran a las 24 horas. Puede renovarse sin necesidad de reautenticarse:

Endpoint: POST /api/v1/auth/refresh

Incluya el token actual en la cabecera Authorization. Devolverá un nuevo token con 24 horas adicionales de validez.

Capítulo 3: Formato de respuestas

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

Respuesta exitosa

{
  "success": true,
  "data": { /* Datos solicitados */ },
  "meta": { /* Metadatos opcionales: paginación, totales, etc. */ }
}

Respuesta de error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Descripción legible del error",
    "details": { /* Detalles específicos del error */ }
  }
}

Códigos HTTP

• 200 OK: Petición exitosa
• 201 Created: Recurso creado exitosamente
• 204 No Content: Operación exitosa sin datos de respuesta
• 400 Bad Request: Error en los parámetros enviados
• 401 Unauthorized: Token no válido o ausente
• 403 Forbidden: Token válido pero sin permisos para la operación
• 404 Not Found: Recurso no encontrado
• 409 Conflict: Conflicto con el estado actual (ej: duplicados)
• 422 Unprocessable Entity: Error de validación de datos
• 429 Too Many Requests: Límite de peticiones excedido
• 500 Internal Server Error: Error del servidor

Capítulo 4: Endpoints de Denuncias

Listar denuncias

GET /api/v1/denuncias

Parámetros query opcionales:

• page: Número de página (default: 1)
• limit: Registros por página (default: 20, max: 100)
• tipo: Filtrar por tipo (hechos, perdida, trafico)
• estado: Filtrar por estado (borrador, registrada, archivada)
• desde: Fecha desde (YYYY-MM-DD)
• hasta: Fecha hasta (YYYY-MM-DD)

Ejemplo:

GET /api/v1/denuncias?tipo=hechos&desde=2026-01-01&limit=50

Respuesta:

{
  "success": true,
  "data": [
    {
      "id": "DEN-2026-00001",
      "tipo": "hechos",
      "fecha": "2026-01-10T10:30:00",
      "denunciante": {
        "nombre": "María García",
        "dni": "12345678A"
      },
      "hechos": "Hurto de móvil en vía pública",
      "estado": "registrada"
    },
    /* ... más denuncias ... */
  ],
  "meta": {
    "total": 250,
    "page": 1,
    "limit": 50,
    "pages": 5
  }
}

Obtener una denuncia específica

GET /api/v1/denuncias/{id}

Ejemplo:

GET /api/v1/denuncias/DEN-2026-00001

Devuelve todos los detalles de la denuncia incluyendo denunciante, denunciados, testigos, adjuntos, historial de cambios.

Crear una denuncia

POST /api/v1/denuncias

Body JSON:

{
  "tipo": "perdida",
  "denunciante": {
    "dni": "12345678A",
    "nombre": "Juan López",
    "telefono": "666123456",
    "email": "juan@example.com",
    "direccion": "Calle Mayor 1, 28001 Madrid"
  },
  "hechos": {
    "fecha": "2026-01-10",
    "hora": "14:30",
    "lugar": "Plaza España, Madrid",
    "descripcion": "Extravié mi cartera con DNI y tarjetas bancarias"
  },
  "objetos_perdidos": [
    {
      "tipo": "documento",
      "descripcion": "DNI 12345678A"
    },
    {
      "tipo": "otro",
      "descripcion": "Cartera de piel negra con tarjetas Visa y Mastercard"
    }
  ]
}

Respuesta (201 Created):

{
  "success": true,
  "data": {
    "id": "DEN-2026-00125",
    "fecha_creacion": "2026-01-10T15:45:00",
    "estado": "registrada"
  }
}

Actualizar una denuncia

PATCH /api/v1/denuncias/{id}

Solo pueden actualizarse denuncias en estado 'borrador'. Body JSON con los campos a modificar.

Eliminar una denuncia

DELETE /api/v1/denuncias/{id}

Marca la denuncia como eliminada (soft delete). Requiere permiso especial.

Capítulo 5: Endpoints de Sanciones

Listar sanciones

GET /api/v1/sanciones

Parámetros query similares a denuncias más:

• matricula: Filtrar por matrícula de vehículo
• dni_conductor: Filtrar por DNI del conductor
• calificacion: leve, grave, muy_grave
• pagada: true/false

Obtener una sanción

GET /api/v1/sanciones/{id}

Crear una sanción

POST /api/v1/sanciones

Body JSON:

{
  "tipo": "in_situ",
  "vehiculo": {
    "matricula": "1234ABC"
  },
  "conductor": {
    "dni": "98765432B",
    "permiso": "ES987654321"
  },
  "infraccion": {
    "codigo": "3.1",
    "fecha": "2026-01-10",
    "hora": "16:30",
    "lugar": "Calle Alcalá 100, Madrid",
    "descripcion": "Circular por sentido contrario"
  },
  "agente": "TIP123"
}

El sistema consulta automáticamente DGT para validar vehículo y conductor, calcula importe y puntos según la infracción, y genera el boletín.

Registrar pago de sanción

POST /api/v1/sanciones/{id}/pagos

Body JSON:

{
  "fecha": "2026-01-15",
  "importe": 100.00,
  "forma_pago": "tarjeta",
  "referencia": "OP123456789"
}

Capítulo 6: Endpoints de Vehículos

Consultar vehículo en DGT

GET /api/v1/vehiculos/dgt/{matricula}

Consulta en tiempo real los datos del vehículo en la DGT. Requiere integración TESTRA activa.

Respuesta:

{
  "success": true,
  "data": {
    "matricula": "1234ABC",
    "marca": "SEAT",
    "modelo": "IBIZA",
    "bastidor": "VF1XXXXXXXXXXXX",
    "fecha_matriculacion": "2020-05-15",
    "titular": {
      "nombre": "JOSE MARTINEZ GARCIA",
      "dni": "11223344X",
      "direccion": "CALLE EJEMPLO 1, 28001 MADRID"
    },
    "itv": {
      "fecha_ultima": "2025-05-10",
      "resultado": "FAVORABLE",
      "fecha_caducidad": "2027-05-10"
    },
    "seguro": {
      "compania": "MAPFRE",
      "poliza": "ES123456789",
      "vigente": true
    }
  }
}

Consultar conductor

GET /api/v1/vehiculos/dgt/conductor/{permiso}

Consulta datos del permiso de conducir en DGT.