"Arquitectura abierta" es una de esas frases que aparecen en todas las propuestas comerciales de software para sector público. Pero en la práctica, lo que el cliente recibe puede variar enormemente: desde un endpoint genérico mal documentado hasta una API completa con SDKs en varios lenguajes. En Labrax tenemos una visión muy concreta de lo que significa que un software sea realmente integrable, y este artículo describe esa visión.
El problema de fondo: el legacy del sector público
Una administración pública mediana puede tener entre 15 y 40 sistemas operativos en producción a la vez: gestor de expedientes, plataforma de notificaciones, sistemas de pago, padrón, sede electrónica, intranet corporativa, sistemas de RRHH, CRM ciudadano, plataformas verticales para áreas concretas... Cuando un nuevo software se incorpora al ecosistema, la pregunta que importa no es si es bueno, sino si es capaz de convivir.
La convivencia tiene dos dimensiones:
- Recibir datos de los sistemas existentes (consultar padrón, validar identidad, leer expedientes).
- Enviar datos a los sistemas existentes (publicar notificaciones, registrar entradas en la sede, alimentar al CRM).
Ambas direcciones requieren APIs. Si un software no expone API, está obligando al cliente a vivir en una isla. Si la expone pero no la documenta, está fingiendo que es integrable cuando en realidad no lo es.
Nuestro estándar: REST + OpenAPI 3.0
Todos nuestros productos exponen una API REST con especificación OpenAPI 3.0. Esto significa que:
- La estructura es predecible (verbos HTTP estándar, códigos de estado correctos, respuestas en JSON).
- La documentación está versionada como código, generada desde el propio código fuente, sin posibilidad de divergencia entre lo documentado y lo real.
- Cualquier cliente puede usar herramientas estándar (Postman, Insomnia, Swagger UI) para explorar y probar la API.
- Se pueden generar SDKs automáticamente en cualquier lenguaje a partir del archivo OpenAPI.
Autenticación: OAuth2 con JWT
El flujo estándar es OAuth2 Client Credentials para integraciones máquina-a-máquina y Authorization Code con PKCE para flujos donde haya un usuario humano implicado. Los tokens son JWT con caducidad corta (1 hora) y refresh tokens con rotación.
Para administraciones públicas hay un matiz importante: los sistemas que requieren identidad digital cualificada (Cl@ve, FNMT, certificados) se conectan a través de la sede electrónica del cliente, no de nuestra API directa. Nuestra API delega la autenticación al gestor de identidad corporativo.
Versionado: semver y compatibilidad hacia atrás
La API se versiona con semver explícito en la URL (/api/v1/recursos). Cuando se introduce un cambio que rompe compatibilidad, sube la versión mayor (v2) y la v1 se mantiene operativa durante al menos 24 meses para dar tiempo a los clientes a migrar.
Las modificaciones aditivas (nuevos campos, nuevos endpoints, nuevos códigos de error) no rompen compatibilidad y no implican cambio de versión. Esto permite que el software evolucione sin obligar a los clientes a actualizar sus integraciones constantemente.
Patrones de integración habituales
Consulta de datos en tiempo real
Es el patrón más simple. El cliente hace una petición GET, nosotros respondemos con los datos. Recomendado para datos pequeños, consultas puntuales y casos donde la latencia importa.
Ejemplo: comprobar si una matrícula tiene autorización ZBE activa.
Webhooks para notificaciones
Cuando el cliente quiere reaccionar a eventos en nuestro sistema (una nueva denuncia, una autorización vencida), no debe hacer polling. Configurarmos un webhook: cuando ocurre el evento, nuestro sistema hace una petición HTTP POST al endpoint del cliente con la información estructurada.
Esto requiere que el cliente tenga un endpoint expuesto y firmado criptográficamente para validar que la llamada viene realmente de nosotros.
Importación masiva (bulk operations)
Para cargas iniciales o sincronizaciones periódicas, las APIs por registro son ineficientes. Exponemos endpoints de bulk que aceptan hasta 1.000 registros por petición y devuelven un identificador de operación que el cliente puede consultar después para ver el estado.
Eventos en streaming (Server-Sent Events)
Para casos donde el cliente necesita observar cambios en tiempo real (como un cuadro de mando que muestra denuncias en vivo), exponemos endpoints SSE. Más ligeros que WebSockets y compatibles con cualquier proxy HTTP estándar.
Idempotencia: el detalle que evita los problemas más caros
Las APIs públicas en sector público tienen un problema específico: las redes de las administraciones suelen tener firewalls agresivos, proxies inestables y conexiones intermitentes. Una operación POST puede fallar a mitad de proceso y el cliente no sabe si ha llegado al servidor o no.
La solución es idempotencia: cada operación de creación lleva una clave única (Idempotency-Key) generada por el cliente. Si el cliente reintenta la misma operación con la misma clave, el servidor reconoce que ya la procesó y devuelve la respuesta original sin duplicar la acción.
Esto evita el problema de "denuncias duplicadas" o "autorizaciones triplicadas" cuando hay reintento por timeout.
Documentación: el factor que más se descuida
Una API sin buena documentación es básicamente una API que no existe. Nuestro estándar incluye:
- Especificación OpenAPI 3.0 completa, navegable con Swagger UI o Redoc.
- Ejemplos de petición y respuesta para cada endpoint, con datos representativos.
- Tutoriales de inicio rápido para los flujos más habituales (autenticación, primera consulta, manejo de errores).
- Códigos de error documentados con descripción y acción recomendada.
- Guías de integración específicas para sistemas habituales en sector público.
- Postman collections exportables para empezar a probar inmediatamente.
- Sandbox público donde se puede probar la API sin impacto en producción.
Errores estructurados
Los errores siguen el formato RFC 7807 (Problem Details for HTTP APIs). En lugar de devolver un mensaje libre, devolvemos un objeto estructurado:
{ "type": "https://labrax.es/errors/authorization-not-found", "title": "Autorización no encontrada", "status": 404, "detail": "La matrícula 1234ABC no tiene autorización vigente.", "instance": "/api/v1/authorizations?plate=1234ABC" }
Esto permite que los clientes manejen los errores de forma programática, distinguiendo entre tipos diferentes de fallo (autenticación, validación, recurso no encontrado, conflicto, error interno) y reaccionando apropiadamente.
Compatibilidad con el Esquema Nacional de Seguridad
Nuestras APIs cumplen los requisitos del ENS Alto:
- Cifrado TLS 1.3 obligatorio (TLS 1.2 mínimo en compatibilidad).
- Logs de auditoría de todas las operaciones, conservados durante 24 meses.
- Identificación inequívoca del usuario o sistema que realiza cada operación.
- Trazabilidad de cambios de estado en cualquier recurso.
- Cifrado de datos personales en reposo (AES-256).
Lo que pedimos a los clientes
La integración funciona en dos direcciones. Para que funcione bien, también pedimos al cliente:
- Disponer de un equipo técnico (interno o externo) que entienda HTTP y JSON.
- Entornos de pruebas separados de producción.
- Manejo correcto de reintentos y errores transitorios.
- No almacenar credenciales en el código fuente.
Si tu organización está evaluando una integración con nuestros productos o tienes dudas sobre cómo enfocarla, podemos hacer un análisis técnico gratuito antes del despliegue.
