Caso de migración de servicios catastrales
Una plataforma proptech no suele fallar porque le falte una pantalla. Falla cuando una búsqueda de inmueble tarda, devuelve campos inconsistentes o se rompe al cambiar una dependencia externa. Este caso de migración de servicios catastrales muestra un patrón habitual: sustituir una integración directa con servicios SOAP/XML por una capa REST con respuestas JSON predecibles.
El punto de partida era conocido para muchos equipos que trabajan con información territorial española. La aplicación necesitaba localizar municipios, normalizar direcciones, consultar referencias catastrales y enriquecer fichas de inmuebles. La integración heredada cumplía su función en escenarios simples, pero arrastraba una deuda técnica cada vez más visible: XML extenso, contratos difíciles de interpretar, tratamiento irregular de errores y lógica de transformación repartida entre backend, frontend y procesos batch.
El objetivo no era cambiar de tecnología por moda. Era reducir el tiempo de integración, evitar incidencias repetitivas y dejar una base que permitiera incorporar nuevas consultas sin reescribir la aplicación.
El problema antes de la migración
El sistema original consumía varios servicios con estructuras y convenciones distintas. Para obtener un dato útil para el producto, el equipo debía construir peticiones XML, gestionar namespaces, interpretar respuestas anidadas y convertir campos a un modelo interno. Una consulta que en la interfaz parecía sencilla podía requerir varias llamadas y bastante código defensivo.
La dificultad real aparecía en los bordes. Una dirección podía llegar incompleta, una calle podía tener varias denominaciones válidas o la respuesta podía no incluir un campo esperado. Cada variación obligaba a añadir excepciones. Con el tiempo, la capa de integración dejó de ser una pieza aislada: empezó a condicionar los plazos de producto.
También había un problema de observabilidad. Cuando un usuario reportaba que una referencia no aparecía, era costoso identificar si el origen estaba en la entrada introducida, la transformación XML, el servicio remoto o la serialización final. Sin un registro claro por petición, depurar incidencias significaba reproducir el caso manualmente y revisar logs poco legibles.
Para un equipo que mantiene un CRM inmobiliario, un valorador automático o un visor GIS, ese coste no es menor. Cada hora destinada a interpretar una respuesta heredada es una hora que no se dedica a reglas de negocio, calidad del dato o experiencia de usuario.
Caso de migración de servicios: el enfoque correcto
La migración se planteó como una sustitución progresiva, no como un corte total. Intentar reemplazar todas las consultas a la vez habría elevado el riesgo: demasiados flujos de negocio, demasiadas dependencias y poca capacidad para comparar resultados en producción.
El primer paso fue inventariar las operaciones existentes. No bastaba con listar endpoints. Había que responder a tres preguntas: qué datos consume realmente el producto, en qué pantallas o procesos se usan y qué comportamiento espera cada consumidor cuando no hay coincidencia.
Por ejemplo, una búsqueda de dirección y una validación previa a una tasación no comparten necesariamente el mismo contrato. La primera puede admitir sugerencias y resultados parciales. La segunda necesita criterios más estrictos, trazabilidad y una respuesta inequívoca. Definir estos casos evitó trasladar la complejidad antigua a una API nueva con otro formato.
A continuación, el equipo creó un modelo canónico para la aplicación. En lugar de exponer directamente las peculiaridades de cada proveedor al resto del sistema, definió entidades claras: provincia, municipio, vía, dirección, inmueble, referencia catastral y coordenadas. Cada entidad tenía tipos consistentes, nombres estables y reglas explícitas para valores ausentes.
Ese modelo permitió que los clientes internos trabajaran con un contrato parecido a este:
```json { "municipio": "Madrid", "provincia": "Madrid", "direccion": "Calle de Ejemplo 12", "referenciaCatastral": "0000000VK4700S0000AB", "coordenadas": { "latitud": 40.4168, "longitud": -3.7038 } } ```
El valor no está solo en que JSON sea más cómodo de leer que XML. Está en que un contrato de este tipo se integra de forma natural en un backend Node.js, Java o .NET, en una aplicación móvil y en una herramienta de análisis. Reduce adaptadores, simplifica pruebas y hace que los errores sean comprensibles para más perfiles del equipo.
Migrar por flujos, no por endpoints
La primera funcionalidad migrada fue la búsqueda de direcciones. Era visible para el usuario, tenía un volumen alto y concentraba muchas de las incidencias. Se mantuvo la integración anterior como respaldo temporal, pero las consultas REST se ejecutaban en paralelo en un conjunto controlado de peticiones.
La comparación no se limitó a comprobar si ambas fuentes devolvían algo. Se midieron coincidencias por municipio, calidad de las sugerencias, tiempo de respuesta, campos ausentes y tratamiento de caracteres especiales. Esto reveló diferencias legítimas que, sin una fase paralela, se habrían interpretado como errores de la nueva implementación.
Después se migró la consulta por referencia catastral. Aquí la prioridad era la precisión. La nueva capa validaba el formato de entrada antes de realizar la petición y devolvía errores con una estructura uniforme. En vez de enviar una excepción genérica al frontend, el cliente podía distinguir entre referencia inválida, inmueble no encontrado, parámetro incompleto o error temporal del servicio.
La tercera fase incorporó conversiones de coordenadas y enriquecimiento geográfico para el visor cartográfico. Al estar apoyada en el mismo modelo de datos, esta parte requirió menos trabajo de integración del previsto. Esa es una ventaja de diseñar primero los contratos: cada nueva capacidad reutiliza convenciones ya conocidas.
Qué cambió en la implementación
La capa moderna se consumía con autenticación mediante API key y peticiones HTTP estándar. Esto eliminó gran parte de la configuración específica que exigía el cliente SOAP y permitió centralizar credenciales por entorno. Desarrollo, preproducción y producción podían usar la misma estrategia de integración sin duplicar lógica.
El equipo también estableció límites de tiempo, reintentos controlados y caché para consultas que no necesitaban frescura absoluta. No todos los datos catastrales tienen el mismo patrón de uso. Un listado de provincias puede almacenarse durante mucho tiempo, mientras que una consulta vinculada a un flujo crítico merece una política de reintento más cuidadosa. Aplicar la misma caché a todo habría sido un error.
La documentación interactiva tuvo un papel operativo, no decorativo. Los desarrolladores verificaban parámetros y respuestas antes de escribir código, mientras producto podía validar si el dato disponible resolvía un caso de uso concreto. Con una colección de pruebas reutilizable, la incorporación de nuevos miembros al equipo dejó de depender de documentación interna desactualizada.
En una implementación con CatastroAPI, esta capa REST ofrece precisamente ese cambio de contexto: endpoints orientados a recursos, JSON estructurado, autenticación directa y herramientas de prueba pensadas para flujos modernos. No elimina la necesidad de validar datos en tu dominio, pero evita que cada equipo tenga que reconstruir esa traducción desde SOAP/XML.
Resultados y concesiones técnicas
Tras la migración, el principal resultado fue la reducción de complejidad acumulada. Las pantallas dejaron de depender de transformaciones específicas de XML y los procesos batch pudieron reutilizar los mismos clientes que la aplicación principal. Las incidencias seguían existiendo, porque los datos territoriales tienen casos ambiguos, pero eran más rápidas de clasificar y resolver.
La velocidad de desarrollo también mejoró. Añadir una búsqueda por municipio o enriquecer una ficha con coordenadas dejó de requerir semanas de exploración de contratos heredados. El equipo podía probar una petición, revisar una respuesta JSON y convertirla a su modelo de dominio con pocas líneas de código.
Hay concesiones. Una API intermedia introduce una dependencia adicional y obliga a definir bien cuotas, monitorización y comportamiento ante caídas. Si el volumen es muy alto, conviene diseñar caché, colas o precarga de catálogos. Si una decisión regulatoria exige conservar la respuesta original, hay que guardar evidencia y metadatos de consulta. La migración no sustituye la arquitectura: permite dedicar la arquitectura a los problemas que sí son propios del producto.
Cómo saber si debes iniciar la migración
La señal más clara es que el equipo habla más de formatos que de funcionalidades. Si los tickets incluyen namespaces, parseadores XML, respuestas no documentadas o excepciones imposibles de reproducir, la integración ya está frenando al negocio.
También conviene actuar cuando diferentes productos de la empresa implementan su propia conexión catastral. Esa duplicación termina produciendo resultados distintos para la misma dirección, credenciales dispersas y costes de mantenimiento que nadie ve hasta que llega una incidencia importante.
Empieza por el flujo con mayor impacto y menor ambigüedad: una consulta por referencia, un selector geográfico o una búsqueda de dirección. Define el contrato que necesita tu producto, ejecuta pruebas en paralelo y mide diferencias antes de retirar el sistema anterior. No hace falta una reescritura heroica para salir de SOAP.
La mejor migración es la que deja al equipo con menos código accidental y más tiempo para construir funciones que el usuario sí percibe. Cuando consultar datos catastrales vuelve a ser una petición HTTP entendible, el dato deja de ser un bloqueo y pasa a ser una pieza útil del producto.