Cómo usar una API catastral sin SOAP ni XML
Un usuario introduce una dirección incompleta en tu aplicación y espera una respuesta inmediata: calle, municipio, código postal, coordenadas y, cuando proceda, referencia catastral. Si tu backend depende directamente de servicios SOAP, XML con estructuras irregulares y validaciones poco transparentes, esa interacción aparentemente simple puede convertirse en días de integración y mantenimiento. Saber cómo usar una API catastral con una capa REST cambia ese escenario: consultas datos oficiales con peticiones HTTP previsibles y respuestas JSON listas para tu producto.
Este enfoque sirve tanto para una plataforma proptech que valida inmuebles como para un CRM que enriquece expedientes, un visor GIS o software municipal. La clave no es solo obtener datos, sino diseñar una integración que sea trazable, tolerante a errores y útil para el flujo real del usuario.
Qué debe resolver una API catastral moderna
El Catastro contiene información territorial y descriptiva esencial, pero el acceso técnico tradicional no fue diseñado pensando en equipos que construyen productos digitales. XML anidado, operaciones SOAP, nombres de campos poco intuitivos y respuestas distintas según la consulta elevan el coste de implementación.
Una API catastral orientada a desarrollo debe normalizar ese acceso. En lugar de interpretar documentos XML en cada llamada, tu aplicación consume recursos claros: provincias, municipios, vías, direcciones, inmuebles, referencias catastrales y conversiones de coordenadas. El resultado debe mantener la procedencia oficial de los datos sin trasladar la complejidad del sistema de origen a tu código.
No todas las integraciones necesitan el mismo nivel de detalle. Un formulario de alta quizá solo requiera autocompletar una dirección. Una herramienta de valoración puede necesitar localizar un inmueble por referencia y recuperar atributos descriptivos. Un GIS, además, suele requerir transformaciones entre coordenadas geográficas y formatos cartográficos. Definir ese caso de uso antes de escribir código evita consumir endpoints que no aportan valor.
Cómo usar una API catastral paso a paso
1. Empieza por la búsqueda que verá el usuario
No arranques con la consulta más compleja. Identifica el primer dato que el usuario conoce y quiere introducir. Normalmente será una provincia y municipio, una dirección o una referencia catastral completa.
En una interfaz de búsqueda de inmuebles, el recorrido habitual es progresivo: primero se selecciona la provincia, después el municipio, luego la vía y finalmente el número o el inmueble. Este patrón reduce consultas ambiguas y permite guiar al usuario con resultados válidos en cada etapa.
Para automatizaciones internas, la referencia catastral suele ser el identificador más eficiente. Si llega desde un CSV, un CRM o un expediente, valida su formato antes de llamar a la API. Así distingues un dato incompleto de un inmueble no encontrado y puedes dar un mensaje operativo al equipo.
2. Configura la autenticación fuera del código
Una API REST moderna suele autenticarse con una clave API. La regla es sencilla: no la incluyas en el frontend, en repositorios ni en capturas de pantalla. Guárdala como variable de entorno o en el gestor de secretos de tu plataforma de despliegue.
Una petición típica puede enviar la clave en una cabecera:
```bash curl -X GET "https://api.tu-proveedor.es/v1/municipios?provincia=28" \ -H "X-API-Key: $CATASTRO_API_KEY" \ -H "Accept: application/json" ```
El nombre exacto de la cabecera y las rutas dependen del proveedor, así que la documentación es la fuente de verdad. Lo relevante es que la autenticación sea consistente entre endpoints y que puedas probarla desde Swagger UI o una colección de Postman antes de integrarla en tu servicio.
3. Construye consultas encadenadas y explícitas
La consulta por dirección suele requerir contexto geográfico. Buscar una calle llamada "Mayor" sin municipio devolvería demasiadas coincidencias o resultados poco útiles. En cambio, una secuencia provincia, municipio, vía y número reduce ambigüedad y facilita el control de errores.
Imagina una respuesta JSON simplificada para una búsqueda de vías:
```json { "data": [ { "id": "280790001", "tipoVia": "CALLE", "nombre": "MAYOR", "municipio": "MADRID", "provincia": "MADRID" } ] } ```
Tu interfaz no necesita exponer todos los campos. Puede mostrar `CALLE MAYOR` al usuario y conservar el identificador de vía internamente para la siguiente consulta. Esa diferencia importa: guardar identificadores estables es más fiable que reconstruir búsquedas a partir de texto libre, tildes o abreviaturas.
4. Trata las respuestas como contratos de datos
Recibir JSON no elimina el trabajo de integración. Define qué campos son obligatorios para tu aplicación, cuáles son opcionales y qué debes hacer cuando no llegan. Una referencia catastral puede estar disponible en una consulta y no en otra; las unidades constructivas o ciertos atributos pueden depender del tipo de inmueble y de la cobertura del dato.
Crea una capa de adaptación entre la respuesta de la API y tu modelo interno. Por ejemplo, convierte los nombres de campos a la convención de tu código, conserva el valor original cuando lo necesites para auditoría y evita que componentes de interfaz dependan directamente del payload externo.
También conviene separar datos de presentación y datos de negocio. Una dirección formateada es útil para una tarjeta visual; provincia, municipio, código de vía y referencia son más adecuados para filtros, deduplicación y reglas internas.
5. Controla errores sin ocultar el contexto
Un `404` no siempre significa que la API haya fallado: puede indicar que la dirección no existe con los parámetros enviados. Un `400` suele apuntar a un formato inválido o un parámetro obligatorio ausente. Un `401` o `403` requiere revisar credenciales, permisos o el entorno desde el que se hace la llamada. Los errores `429` implican que debes respetar límites de uso, y los `5xx` deben tratarse como incidencias temporales del servicio.
No muestres al usuario final un mensaje como "Error 400". Traduce el problema a una acción: "Selecciona un municipio de la lista", "Comprueba el número de portal" o "No hemos encontrado coincidencias exactas". En paralelo, registra el endpoint, el código de estado, un identificador de solicitud y parámetros no sensibles para poder diagnosticar incidencias.
Los reintentos tienen sentido para fallos transitorios, no para todas las respuestas. Reintentar una petición mal formada solo añade tráfico y retrasa la respuesta. Para `502`, `503` o cortes breves de red, aplica reintentos limitados con espera progresiva y un tiempo máximo de espera razonable.
Coordenadas: evita asumir el sistema de referencia
Un error frecuente en proyectos inmobiliarios y GIS es asumir que todas las coordenadas usan el mismo sistema. Un mapa web suele trabajar con longitud y latitud, mientras que fuentes cartográficas y procesos técnicos pueden usar proyecciones distintas. Intercambiar orden, datum o sistema de referencia puede mover un punto cientos de metros o situarlo fuera de la zona esperada.
Si necesitas geolocalizar inmuebles o convertir coordenadas, guarda siempre junto al valor su sistema de referencia. En una API bien planteada, el endpoint de conversión debe exigir o devolver esa información de forma explícita. Valida también rangos plausibles antes de pintar el resultado en el mapa.
La conversión no sustituye a la validación territorial. Si una coordenada resultante pertenece a otro municipio, no des por sentado que el servicio está equivocado. Puede haber un error en el origen, una dirección homónima o una conversión aplicada con el sistema de referencia incorrecto.
Pruebas que ahorran incidencias en producción
Antes de conectar la API a un formulario público, prueba casos reales y casos incómodos. Las direcciones no siempre tienen el patrón calle, número y piso. Hay diseminados, urbanizaciones, portales con letras, vías con nombres similares y registros históricos con abreviaturas.
Prepara al menos estos escenarios de prueba:
- Una dirección urbana completa con resultado único.
- Una vía frecuente que exista en varios municipios.
- Un inmueble consultado por referencia catastral válida.
- Parámetros incompletos, caracteres especiales y formatos incorrectos.
- Una consulta sin resultados y otra que devuelva varias coincidencias.
Mide además el tiempo de respuesta desde el entorno donde vive tu aplicación, no solo desde tu equipo local. La experiencia depende de la latencia, de cómo gestionas el autocompletado y de si disparas una petición por cada pulsación. Añade una espera breve antes de buscar, cancela solicitudes obsoletas y cachea catálogos que cambian poco, como provincias o municipios.
Del prototipo a una integración mantenible
El prototipo suele funcionar con una llamada directa desde un componente. En producción, conviene centralizar las peticiones en un servicio de backend o en una capa específica del cliente, según tu arquitectura. Así controlas la clave API, el límite de peticiones, los reintentos, el registro y la evolución de los modelos de datos en un único lugar.
CatastroAPI está diseñada precisamente para este flujo: endpoints REST, JSON estructurado, autenticación con clave API y herramientas de prueba para pasar de una consulta manual a una integración operativa sin pelear con SOAP. Pero incluso con una capa moderna, el trabajo de producto sigue siendo tuyo: decidir qué pedir, cuándo pedirlo y cómo convertir el dato en una decisión útil para el usuario.
La mejor primera implementación no intenta reproducir todo el Catastro. Resuelve una búsqueda concreta, registra lo que ocurre y mejora desde el uso real. Cuando un dato catastral llega con contexto, formato estable y una interfaz que sabe manejar sus excepciones, deja de ser una dependencia técnica y empieza a mover el flujo de trabajo.