Projects — Contexto de proyecto

Projects

En Normatia el alcance normativo se define por proyecto: cada uno lleva su municipio, sus normativas aplicables, sus documentos, la memoria de datos de obra y los cálculos guardados. Estos dos endpoints son los que dan acceso a ese contexto.

Endpoint	Método	Descripción
/api/v1/projects	GET	Proyectos a los que el usuario tiene acceso
/api/v1/project/info	GET	Contexto completo de un proyecto

Ninguno consume cuota: pertenecen al grupo data de rate limiting (60 req/min).

Autenticación

Authorization: Bearer sk-normatia-...

---

Listar proyectos

GET /api/v1/projects

Devuelve los proyectos del usuario, resueltos a través de su organización. Es la forma de obtener el project_id que se pasa a POST /api/v2/ask y a /api/v1/project/info.

Response

Campo	Tipo	Descripción
projects	array	Proyectos accesibles
total	integer	Número de proyectos

projects[]

Campo	Tipo	Descripción
project_id	string	Identificador del proyecto
name	string	Nombre del proyecto
description	string	Descripción, si la tiene
geo_id	string	Identificador geográfico
location	string	Municipio o territorio
collection_count	integer	Normativas seleccionadas
file_count	integer	Documentos subidos
is_active	boolean	Proyecto activo del usuario: el que se usa cuando no se pasa project_id

Ejemplo

{
  "projects": [
    {
      "project_id": "3f8c1a90-5b2e-4d77-9d21-0e5f4a6c8b13",
      "name": "Rehabilitación Calle Mayor",
      "description": "Rehabilitación integral de edificio residencial",
      "geo_id": "ES-28079",
      "location": "Madrid",
      "collection_count": 12,
      "file_count": 3,
      "is_active": true
    },
    {
      "project_id": "c41d7b02-9a3f-4e18-b6cd-2f70e1a95d44",
      "name": "Nave industrial Zona Franca",
      "geo_id": "ES-08019",
      "location": "Barcelona",
      "collection_count": 9,
      "file_count": 0,
      "is_active": false
    }
  ],
  "total": 2
}

---

Contexto de un proyecto

GET /api/v1/project/info

Devuelve todo el contexto que el motor agéntico tiene inyectado cuando responde: ubicación y datos técnicos del territorio, normativa aplicable con su versión vigente, normativa aplicable que el proyecto no ha seleccionado, documentos subidos y generados, memoria de obra y cálculos guardados.

Query params

Parámetro	Tipo	Requerido	Descripción
project_id	uuid	—	Proyecto sobre el que informar. Si se omite, el proyecto activo del usuario

Response

Campo	Tipo	Descripción
project_id	string	Proyecto realmente resuelto
name	string	Nombre del proyecto
is_active	boolean	Si es el proyecto activo del usuario en la web
project_description	string	Descripción del proyecto
geo_context	object	Ubicación y datos técnicos del territorio
collection_count	integer	Normativas seleccionadas
file_count	integer	Documentos subidos
files	string[]	Nombres de los documentos subidos
collections	array	Normativa aplicable seleccionada
unselected_collections	array	Normativa aplicable al territorio no seleccionada en el proyecto
generated_documents	array	Documentos generados por el asistente (última versión de cada uno)
memory	array	Datos de obra que el usuario ha aportado
calculations	array	Cálculos guardados con las calculadoras de Normatia
available_calculators	array	Calculadoras que el usuario puede rellenar

geo_context

Campo	Descripción
geo_id	Identificador geográfico
name	Municipio
level	Nivel territorial
ancestors	Jerarquía territorial (provincia, comunidad, país)
climate_zone	Zona climática
tech_data_summary	Resumen legible de los datos técnicos: zona climática, viento, nieve, sísmica, altitud…

collections[]

Campo	Descripción
slug	Identificador de la normativa
title	Título
scope	Ámbito normativo (estatal, autonomica, municipal…)
scope_label	Ámbito en formato legible
version	Versión vigente. Es la única respuesta válida a qué edición se aplica

unselected_collections[] usa slug, title y scope. Son normativas que Normatia tiene para ese territorio pero que el proyecto no ha activado: las consultas no las encontrarán hasta que el usuario las seleccione.

memory[]

Campo	Descripción
key	Identificador del dato
label	Nombre legible
value	Valor
unit	Unidad, si aplica
source	De dónde salió el dato

calculations[]

Campo	Descripción
calculation_id	Identificador del cálculo
calculator_id	Calculadora que lo produjo
name	Nombre del cálculo
summary	Resumen del resultado
compliant	Si el resultado cumple la normativa

generated_documents[] devuelve titulo, tipo y version. available_calculators[] devuelve calculator_id y title.

Note

Cada sección tiene un tope para que el payload no crezca sin control: 25 datos de memoria, 30 cálculos y 30 documentos generados. Las secciones de apoyo se degradan a lista vacía si fallan — la ubicación y la normativa nunca se pierden por eso.

Ejemplo

GET /api/v1/project/info?project_id=3f8c1a90-5b2e-4d77-9d21-0e5f4a6c8b13

{
  "project_id": "3f8c1a90-5b2e-4d77-9d21-0e5f4a6c8b13",
  "name": "Rehabilitación Calle Mayor",
  "is_active": true,
  "project_description": "Rehabilitación integral de edificio residencial",
  "geo_context": {
    "geo_id": "ES-28079",
    "name": "Madrid",
    "level": "municipality",
    "ancestors": "Madrid > Comunidad de Madrid > España",
    "climate_zone": "D3",
    "tech_data_summary": "Zona climática: D3\nAltitud: 667 m\nZona eólica: A"
  },
  "collection_count": 12,
  "file_count": 1,
  "files": ["Memoria de carpintería.pdf"],
  "collections": [
    {
      "slug": "cte-db-he",
      "title": "CTE DB-HE Ahorro de Energía",
      "scope": "estatal",
      "scope_label": "Estatal",
      "version": "2022"
    }
  ],
  "unselected_collections": [
    {
      "slug": "pgoum-madrid",
      "title": "Plan General de Ordenación Urbana de Madrid",
      "scope": "municipal"
    }
  ],
  "generated_documents": [
    { "titulo": "Memoria justificativa DB-HE", "tipo": "memoria", "version": 3 }
  ],
  "memory": [
    {
      "key": "tipo_intervencion",
      "label": "Tipo de intervención",
      "value": "Rehabilitación",
      "unit": null,
      "source": "usuario"
    }
  ],
  "calculations": [
    {
      "calculation_id": "9a2e...",
      "calculator_id": "transmitancia-cerramientos",
      "name": "Fachada tipo F1",
      "summary": "U = 0,28 W/m²K",
      "compliant": true
    }
  ],
  "available_calculators": [
    { "calculator_id": "transmitancia-cerramientos", "title": "Transmitancia de cerramientos" }
  ]
}

Errores

Status	Código	Condición
400	no_active_project	No se pasó project_id y el usuario no tiene proyecto activo
404	project_not_found	El proyecto no existe o el usuario no tiene acceso

Un proyecto de otra organización y uno inexistente devuelven exactamente el mismo 404: una respuesta idéntica evita confirmar que un identificador ajeno es real.