Guía de referencia catastral en JSON para APIs

Un formulario de alta de inmueble, un CRM de tasaciones o un visor GIS suelen fallar en el mismo punto: alguien introduce una referencia catastral y el sistema recibe un dato difícil de comprobar, enriquecer o relacionar. Esta guía de referencia catastral JSON explica cómo tratar ese identificador como lo que es: una pieza de datos estructurada que debe circular por una API moderna, no un texto opaco atrapado en XML.

La referencia catastral permite identificar un bien inmueble dentro del Catastro. Para un producto digital, no basta con mostrarla en pantalla. Hay que validarla, consultar el inmueble asociado, cruzarla con dirección y coordenadas, registrar la trazabilidad de la consulta y devolver errores que el equipo pueda resolver sin interpretar respuestas SOAP.

Qué debe resolver una integración de referencia catastral JSON

Una referencia catastral española se expresa habitualmente con 20 caracteres alfanuméricos. En aplicaciones de proptech, administración pública, valoración o gestión patrimonial, conviene conservar siempre el valor original recibido y, en paralelo, trabajar con una versión normalizada: sin espacios, en mayúsculas y con una validación de formato previa.

La validación local ahorra llamadas innecesarias, pero no sustituye la consulta de datos oficiales. Una cadena puede tener 20 caracteres y seguir siendo incorrecta, estar desactualizada o no devolver el inmueble que el usuario esperaba. La API debe ser la fuente de confirmación para producción.

Una respuesta JSON útil no se limita a devolver la referencia. Debe permitir al consumidor saber qué se ha resuelto, con qué calidad y cómo continuar el flujo. Como mínimo, el contrato debería exponer el identificador consultado, la referencia normalizada, el tipo de resultado, la dirección estructurada y la localización geográfica cuando esté disponible.

```json { "reference": "9872023VH5797S0001WX", "status": "found", "property": { "address": { "street_type": "CL", "street_name": "MAYOR", "number": "18", "postal_code": "28013", "municipality": "MADRID", "province": "MADRID" }, "coordinates": { "latitude": 40.4168, "longitude": -3.7038 } } } ```

El ejemplo ilustra un punto clave: el frontend no debería tener que desmontar descripciones de dirección ni deducir campos a partir de un texto libre. Separar vía, número, municipio, provincia y código postal facilita filtros, mapas, reglas de negocio y conciliación con registros internos.

La estructura de la referencia no es un modelo de negocio

Los 20 caracteres de una referencia catastral incorporan elementos de identificación y control. Es tentador partirlos en bloques y utilizarlos para inferir provincia, parcela, inmueble o ubicación. Puede ser útil para diagnósticos técnicos, pero es una mala base para reglas críticas de producto.

El significado operativo de determinados bloques depende del tipo de inmueble, de los datos disponibles y de la casuística catastral. Una referencia de un piso urbano no se consume igual que la de una finca rústica o un elemento con división horizontal. Además, la referencia identifica el objeto catastral, no acredita por sí sola titularidad, cargas, disponibilidad comercial ni correspondencia exacta con la información registral.

Por eso, una buena integración separa tres capas. La primera es sintáctica: longitud, caracteres permitidos y normalización. La segunda es catastral: existencia de la referencia y atributos devueltos por la consulta. La tercera pertenece a tu dominio: si ese inmueble puede entrar en una operación, asignarse a un cliente, tasarse o publicarse en un marketplace.

Evitar esta separación genera errores clásicos. Por ejemplo, bloquear una solicitud porque la dirección escrita por el usuario no coincide literalmente con la dirección catastral, o asumir que una coordenada resuelta es suficiente para decidir una zona comercial. La dirección puede venir abreviada, el portal puede tener formatos distintos y las coordenadas pueden requerir una transformación de sistema antes de dibujarse en el mapa de tu aplicación.

Diseño de una consulta REST que el equipo pueda mantener

Para un consumidor de API, el flujo ideal es directo: autenticarse con una API key, enviar la referencia como parámetro, recibir JSON consistente y distinguir con claridad entre un resultado válido, una entrada inválida y una incidencia temporal del proveedor.

Un patrón de petición puede ser este:

```http GET /properties/by-cadastral-reference/9872023VH5797S0001WX X-API-Key: tu_api_key Accept: application/json ```

El nombre concreto del recurso puede variar, pero la semántica debe mantenerse. No mezcles la búsqueda por dirección y la búsqueda por referencia en un único endpoint ambiguo. La referencia es una consulta exacta. La dirección, en cambio, suele ser una búsqueda con candidatos y requiere manejar coincidencias parciales, variantes de calle y numeración incompleta.

También merece la pena diseñar una taxonomía de errores corta y predecible. Un `400` puede indicar una referencia con formato inválido; un `404`, que no se ha encontrado resultado; un `401` o `403`, un problema de autenticación o permisos; y un `429`, que se ha superado el límite de peticiones. Los `5xx` deben reservarse para fallos del servicio, no para datos introducidos incorrectamente.

El cuerpo de error importa tanto como el código HTTP. Un mensaje como `invalid_reference_format` permite al frontend traducir la causa y al backend registrarla sin lógica frágil basada en frases humanas.

```json { "error": { "code": "invalid_reference_format", "message": "La referencia catastral debe contener 20 caracteres alfanuméricos.", "request_id": "req_8f31c2" } } ```

El `request_id` es especialmente valioso en integraciones B2B. Cuando un cliente abre una incidencia con una hora aproximada y una referencia concreta, el equipo puede localizar la petición en el monitor de actividad sin reconstruir toda la secuencia desde logs dispersos.

Normalizar antes de consultar, conservar después

No obligues al usuario a conocer el formato interno del Catastro. Acepta entradas con espacios o minúsculas si el contexto lo justifica, normalízalas en el borde de tu aplicación y muestra el resultado estandarizado tras una consulta satisfactoria.

Una función básica puede eliminar espacios, convertir a mayúsculas y verificar la expresión permitida. Aun así, no añadas validaciones locales que rechacen casos reales por exceso de celo. Una regla que solo comprueba 20 caracteres alfanuméricos es razonable; una regla que intenta reconstruir toda la semántica del identificador suele introducir falsos negativos.

```javascript function normalizeCadastralReference(value) { const reference = String(value || "") .replace(/\s+/g, "") .toUpperCase();

if (!/^[A-Z0-9]{20}$/.test(reference)) { throw new Error("invalid_reference_format"); }

return reference; } ```

Guarda dos valores cuando haya intervención humana: `reference_input`, para auditoría y soporte, y `reference_normalized`, para índices, deduplicación y consultas. Si el usuario corrigió un carácter, ese detalle puede explicar por qué una operación inicial no encontró el inmueble.

De la respuesta catastral al caso de uso real

La referencia catastral JSON cobra valor cuando reduce pasos dentro de un flujo concreto. En una plataforma de valoración, la referencia puede disparar la precarga de dirección y coordenadas, evitando que un analista copie datos manualmente. En un CRM inmobiliario, puede servir para detectar registros duplicados incluso si dos agentes escribieron la calle de forma distinta.

En un visor GIS, el dato relevante puede ser la geometría o la conversión de coordenadas a WGS84 para situar el inmueble en un mapa web. En software municipal, la consulta puede alimentar validaciones de expediente, sin convertir el Catastro en una base de datos local difícil de actualizar. Cada caso consume una parte distinta del mismo resultado, de modo que devolver campos bien definidos es más útil que entregar una respuesta documental extensa.

Aquí aparece un compromiso práctico: no todos los datos deben consultarse en tiempo real. Para una pantalla de autocompletado, una llamada inmediata tiene sentido. Para informes masivos o procesos nocturnos, conviene aplicar colas, límites de concurrencia, reintentos con espera progresiva y una caché con una política de caducidad explícita. La vigencia adecuada depende del riesgo de trabajar con información no actualizada y de las condiciones de uso aplicables a la fuente de datos.

No caches únicamente el JSON completo. Registra también la fecha de consulta, la versión de tu esquema y el estado de resolución. Así puedes migrar el modelo, detectar campos ausentes y decidir qué registros requieren refresco sin reprocesar todo el inventario.

Evitar que SOAP/XML contamine el resto del producto

El coste de una integración heredada rara vez está solo en la primera llamada. Aparece meses después, cuando un desarrollador debe interpretar nodos XML con espacios de nombres, tratar campos opcionales inconsistentes o mantener transformaciones que nadie documentó. Convertir una respuesta externa a JSON en un único adaptador reduce esa deuda, pero una API REST que ya entregue un esquema claro elimina una capa completa de fragilidad.

CatastroAPI está orientada precisamente a ese modelo: consultas de datos catastrales mediante endpoints REST, autenticación con API key y respuestas JSON preparadas para integrarse en aplicaciones web, móviles, GIS o CRM. El objetivo no es ocultar la complejidad del dato, sino dejarla donde corresponde: fuera de la lógica diaria de tu producto.

Antes de pasar a producción, prueba referencias válidas, formatos inválidos, resultados no encontrados, tiempos de espera y respuestas con campos opcionales. Mide además cuántas consultas se resuelven en el primer intento y cuántos usuarios abandonan el formulario por una referencia mal introducida. Esas métricas revelan si necesitas mejorar la interfaz, no solo la API.

Una integración útil termina cuando una referencia introducida por una persona se convierte, en segundos y con trazabilidad, en datos que otro sistema puede usar sin interpretar formatos heredados. Empieza por un contrato JSON pequeño, explícito y fácil de probar; después amplíalo solo cuando el caso de uso lo exija.