"Arquitectura oberta" és una d'aquestes frases que apareixen en totes les propostes comercials de programari per al sector públic. Però, a la pràctica, el que rep el client pot variar enormement: des d'un endpoint genèric mal documentat fins a una API completa amb SDK en diversos llenguatges. A Labrax tenim una visió molt concreta del que vol dir que un programari sigui realment integrable, i aquest article descriu aquesta visió.
El problema de fons: el llegat (legacy) del sector públic
Una administració pública mitjana pot tenir entre 15 i 40 sistemes operatius en producció alhora: gestor d'expedients, plataforma de notificacions, sistemes de pagament, padró, seu electrònica, intranet corporativa, sistemes de RH, CRM ciutadà, plataformes verticals per a àrees concretes... Quan un programari nou s'incorpora a l'ecosistema, la pregunta que importa no és si és bo, sinó si és capaç de conviure-hi.
La convivència té dues dimensions:
- Rebre dades dels sistemes existents (consultar el padró, validar la identitat, llegir expedients).
- Enviar dades als sistemes existents (publicar notificacions, registrar entrades a la seu, alimentar el CRM).
Totes dues direccions requereixen API. Si un programari no exposa cap API, obliga el client a viure en una illa. Si l'exposa però no la documenta, fa veure que és integrable quan en realitat no ho és.
El nostre estàndard: REST + OpenAPI 3.0
Tots els nostres productes exposen una API REST amb especificació OpenAPI 3.0. Això significa que:
- L'estructura és previsible (verbs HTTP estàndard, codis d'estat correctes, respostes en JSON).
- La documentació està versionada com a codi, generada a partir del mateix codi font, sense possibilitat de divergència entre el que es documenta i el que és real.
- Qualsevol client pot utilitzar eines estàndard (Postman, Insomnia, Swagger UI) per explorar i provar l'API.
- Es poden generar SDK automàticament en qualsevol llenguatge a partir del fitxer OpenAPI.
Autenticació: OAuth2 amb JWT
El flux estàndard és OAuth2 Client Credentials per a integracions màquina a màquina i Authorization Code amb PKCE per als fluxos en què intervé un usuari humà. Els tokens són JWT amb caducitat curta (1 hora) i refresh tokens amb rotació.
Per a les administracions públiques hi ha un matís important: els sistemes que requereixen identitat digital qualificada (Cl@ve, FNMT, certificats) es connecten a través de la seu electrònica del client, no directament de la nostra API. La nostra API delega l'autenticació al gestor d'identitat corporatiu.
Versionatge: semver i compatibilitat cap enrere
L'API es versiona amb semver explícit a l'URL (/api/v1/recursos). Quan s'introdueix un canvi que trenca la compatibilitat, puja la versió major (v2) i la v1 es manté operativa durant almenys 24 mesos per donar temps als clients a migrar.
Les modificacions additives (camps nous, endpoints nous, codis d'error nous) no trenquen la compatibilitat i no impliquen canvi de versió. Això permet que el programari evolucioni sense obligar els clients a actualitzar les seves integracions constantment.
Patrons d'integració habituals
Consulta de dades en temps real
És el patró més senzill. El client fa una petició GET i nosaltres responem amb les dades. Recomanat per a dades petites, consultes puntuals i casos en què la latència importa.
Exemple: comprovar si una matrícula té una autorització ZBE activa.
Webhooks per a notificacions
Quan el client vol reaccionar a esdeveniments del nostre sistema (una denúncia nova, una autorització vençuda), no ha de fer polling. Configurem un webhook: quan es produeix l'esdeveniment, el nostre sistema fa una petició HTTP POST a l'endpoint del client amb la informació estructurada.
Això requereix que el client tingui un endpoint exposat i signat criptogràficament per validar que la crida ve realment de nosaltres.
Importació massiva (bulk operations)
Per a càrregues inicials o sincronitzacions periòdiques, les API per registre són ineficients. Exposem endpoints de bulk que accepten fins a 1.000 registres per petició i retornen un identificador d'operació que el client pot consultar després per veure'n l'estat.
Esdeveniments en streaming (Server-Sent Events)
Per als casos en què el client necessita observar canvis en temps real (com un quadre de comandament que mostra denúncies en directe), exposem endpoints SSE. Més lleugers que els WebSockets i compatibles amb qualsevol proxy HTTP estàndard.
Idempotència: el detall que evita els problemes més cars
Les API públiques del sector públic tenen un problema específic: les xarxes de les administracions solen tenir tallafocs agressius, proxies inestables i connexions intermitents. Una operació POST pot fallar a mig procés i el client no sap si ha arribat al servidor o no.
La solució és la idempotència: cada operació de creació porta una clau única (Idempotency-Key) generada pel client. Si el client reintenta la mateixa operació amb la mateixa clau, el servidor reconeix que ja l'ha processada i retorna la resposta original sense duplicar l'acció.
Això evita el problema de les "denúncies duplicades" o les "autoritzacions triplicades" quan hi ha un reintent per temps d'espera esgotat.
Documentació: el factor que més es descuida
Una API sense bona documentació és bàsicament una API que no existeix. El nostre estàndard inclou:
- Especificació OpenAPI 3.0 completa, navegable amb Swagger UI o Redoc.
- Exemples de petició i resposta per a cada endpoint, amb dades representatives.
- Tutorials d'inici ràpid per als fluxos més habituals (autenticació, primera consulta, gestió d'errors).
- Codis d'error documentats amb descripció i acció recomanada.
- Guies d'integració específiques per a sistemes habituals al sector públic.
- Col·leccions de Postman exportables per començar a provar immediatament.
- Entorn de proves (sandbox) públic on es pot provar l'API sense impacte en producció.
Errors estructurats
Els errors segueixen el format RFC 7807 (Problem Details for HTTP APIs). En lloc de retornar un missatge lliure, retornem un objecte estructurat:
{ "type": "https://labrax.es/errors/authorization-not-found", "title": "Autorització no trobada", "status": 404, "detail": "La matrícula 1234ABC no té cap autorització vigent.", "instance": "/api/v1/authorizations?plate=1234ABC" }
Això permet que els clients gestionin els errors de manera programàtica, distingint entre diferents tipus de fallada (autenticació, validació, recurs no trobat, conflicte, error intern) i reaccionant-hi adequadament.
Compatibilitat amb l'Esquema Nacional de Seguretat
Les nostres API compleixen els requisits de l'ENS Alt:
- Xifratge TLS 1.3 obligatori (TLS 1.2 com a mínim per compatibilitat).
- Registres d'auditoria de totes les operacions, conservats durant 24 mesos.
- Identificació inequívoca de l'usuari o sistema que fa cada operació.
- Traçabilitat dels canvis d'estat en qualsevol recurs.
- Xifratge de les dades personals en repòs (AES-256).
El que demanem als clients
La integració funciona en dues direccions. Perquè funcioni bé, també demanem al client:
- Disposar d'un equip tècnic (intern o extern) que entengui HTTP i JSON.
- Entorns de proves separats de producció.
- Gestió correcta dels reintents i dels errors transitoris.
- No emmagatzemar credencials al codi font.
Si la teva organització està avaluant una integració amb els nostres productes o tens dubtes sobre com enfocar-la, podem fer una anàlisi tècnica gratuïta abans del desplegament.
