"Arquitectura aberta" é unha desas frases que aparecen en todas as propostas comerciais de software para o sector público. Pero, na práctica, o que recibe o cliente pode variar enormemente: desde un endpoint xenérico mal documentado ata unha API completa con SDK en varias linguaxes. En Labrax temos unha visión moi concreta do que significa que un software sexa realmente integrable, e este artigo describe esa visión.
O problema de fondo: o legado do sector público
Unha administración pública mediana pode ter entre 15 e 40 sistemas operativos en produción á vez: xestor de expedientes, plataforma de notificacións, sistemas de pagamento, padrón, sede electrónica, intranet corporativa, sistemas de RRHH, CRM cidadán, plataformas verticais para áreas concretas... Cando un novo software se incorpora ao ecosistema, a pregunta que importa non é se é bo, senón se é capaz de convivir.
A convivencia ten dúas dimensións:
- Recibir datos dos sistemas existentes (consultar o padrón, validar a identidade, ler expedientes).
- Enviar datos aos sistemas existentes (publicar notificacións, rexistrar entradas na sede, alimentar o CRM).
Ambas as direccións requiren API. Se un software non expón API, está a obrigar o cliente a vivir nunha illa. Se a expón pero non a documenta, está a finxir que é integrable cando en realidade non o é.
O noso estándar: REST + OpenAPI 3.0
Todos os nosos produtos expoñen unha API REST con especificación OpenAPI 3.0. Isto significa que:
- A estrutura é predicible (verbos HTTP estándar, códigos de estado correctos, respostas en JSON).
- A documentación está versionada como código, xerada desde o propio código fonte, sen posibilidade de diverxencia entre o documentado e o real.
- Calquera cliente pode usar ferramentas estándar (Postman, Insomnia, Swagger UI) para explorar e probar a API.
- Pódense xerar SDK automaticamente en calquera linguaxe a partir do ficheiro OpenAPI.
Autenticación: OAuth2 con JWT
O fluxo estándar é OAuth2 Client Credentials para integracións máquina a máquina e Authorization Code con PKCE para os fluxos nos que haxa un usuario humano implicado. Os tokens son JWT de caducidade curta (1 hora) e refresh tokens con rotación.
Para as administracións públicas hai un matiz importante: os sistemas que requiren identidade dixital cualificada (Cl@ve, FNMT, certificados) conéctanse a través da sede electrónica do cliente, non da nosa API directa. A nosa API delega a autenticación no xestor de identidade corporativo.
Versionado: semver e compatibilidade cara atrás
A API versiónase con semver explícito no URL (/api/v1/recursos). Cando se introduce un cambio que rompe a compatibilidade, sobe a versión maior (v2) e a v1 mantense operativa durante polo menos 24 meses para dar tempo aos clientes a migrar.
As modificacións aditivas (novos campos, novos endpoints, novos códigos de erro) non rompen a compatibilidade e non implican cambio de versión. Isto permite que o software evolucione sen obrigar os clientes a actualizar as súas integracións constantemente.
Patróns de integración habituais
Consulta de datos en tempo real
É o patrón máis simple. O cliente fai unha petición GET e nós respondemos cos datos. Recomendado para datos pequenos, consultas puntuais e casos nos que a latencia importa.
Exemplo: comprobar se unha matrícula ten autorización ZBE activa.
Webhooks para notificacións
Cando o cliente quere reaccionar a eventos no noso sistema (unha nova denuncia, unha autorización vencida), non debe facer polling. Configuramos un webhook: cando ocorre o evento, o noso sistema fai unha petición HTTP POST ao endpoint do cliente coa información estruturada.
Isto require que o cliente teña un endpoint exposto e asinado criptograficamente para validar que a chamada vén realmente de nós.
Importación masiva (bulk operations)
Para cargas iniciais ou sincronizacións periódicas, as API por rexistro son ineficientes. Expoñemos endpoints de bulk que aceptan ata 1.000 rexistros por petición e devolven un identificador de operación que o cliente pode consultar despois para ver o estado.
Eventos en streaming (Server-Sent Events)
Para os casos nos que o cliente necesita observar cambios en tempo real (como un cadro de mando que mostra denuncias en directo), expoñemos endpoints SSE. Máis lixeiros que WebSockets e compatibles con calquera proxy HTTP estándar.
Idempotencia: o detalle que evita os problemas máis caros
As API públicas no sector público teñen un problema específico: as redes das administracións adoitan ter firewalls agresivos, proxies inestables e conexións intermitentes. Unha operación POST pode fallar a metade do proceso e o cliente non sabe se chegou ao servidor ou non.
A solución é a idempotencia: cada operación de creación leva unha clave única (Idempotency-Key) xerada polo cliente. Se o cliente reintenta a mesma operación coa mesma clave, o servidor recoñece que xa a procesou e devolve a resposta orixinal sen duplicar a acción.
Isto evita o problema das "denuncias duplicadas" ou das "autorizacións triplicadas" cando hai reintentos por timeout.
Documentación: o factor máis descoidado
Unha API sen boa documentación é basicamente unha API que non existe. O noso estándar inclúe:
- Especificación OpenAPI 3.0 completa, navegable con Swagger UI ou Redoc.
- Exemplos de petición e resposta para cada endpoint, con datos representativos.
- Titoriais de inicio rápido para os fluxos máis habituais (autenticación, primeira consulta, xestión de erros).
- Códigos de erro documentados con descrición e acción recomendada.
- Guías de integración específicas para sistemas habituais no sector público.
- Postman collections exportables para comezar a probar inmediatamente.
- Sandbox público onde se pode probar a API sen impacto en produción.
Erros estruturados
Os erros seguen o formato RFC 7807 (Problem Details for HTTP APIs). En lugar de devolver unha mensaxe libre, devolvemos un obxecto estruturado:
{ "type": "https://labrax.es/errors/authorization-not-found", "title": "Autorización non atopada", "status": 404, "detail": "A matrícula 1234ABC non ten autorización vixente.", "instance": "/api/v1/authorizations?plate=1234ABC" }
Isto permite que os clientes xestionen os erros de forma programática, distinguindo entre tipos diferentes de fallo (autenticación, validación, recurso non atopado, conflito, erro interno) e reaccionando adecuadamente.
Compatibilidade co Esquema Nacional de Seguridade
As nosas API cumpren os requisitos do ENS Alto:
- Cifrado TLS 1.3 obrigatorio (TLS 1.2 mínimo en compatibilidade).
- Logs de auditoría de todas as operacións, conservados durante 24 meses.
- Identificación inequívoca do usuario ou sistema que realiza cada operación.
- Trazabilidade dos cambios de estado en calquera recurso.
- Cifrado de datos persoais en repouso (AES-256).
O que lles pedimos aos clientes
A integración funciona en dúas direccións. Para que funcione ben, tamén lle pedimos ao cliente:
- Dispor dun equipo técnico (interno ou externo) que entenda HTTP e JSON.
- Contornos de probas separados de produción.
- Xestión correcta de reintentos e erros transitorios.
- Non almacenar credenciais no código fonte.
Se a túa organización está a avaliar unha integración cos nosos produtos ou tes dúbidas sobre como enfocala, podemos facer unha análise técnica gratuíta antes do despregamento.
