Codes

codes abstrae el catálogo de normativas. Cada code es un cuerpo normativo (CTE DB-HE, RITE, PGOU Sevilla) que agrupa una o varias versiones (documents). Internamente corresponde a las tablas collections y documents de la base de datos.

Base URL: /api/v1/codes

Valores de referencia

`normative_scope`

Valor	Descripción
`national`	Normativa estatal (CTE, RITE, LOE)
`regional`	Normativa autonómica
`provincial`	Planes provinciales
`municipal`	Ordenanzas municipales
`sectorial`	Normativa que cruza límites administrativos (Ley de Costas)
`supramunicipal`	Mancomunidades, áreas metropolitanas
`european`	Directivas UE

`status` de versiones

Valor	Descripción
`active`	En vigor
`repealed`	Derogada
`draft`	Borrador
`in_progress`	En tramitación

GET /api/v1/codes/search

GET Buscar normativas

Búsqueda paginada de normativas por título, ámbito o etiqueta. Útil para explorar el catálogo sin conocer el slug exacto.

Parámetros de query

Parámetro	Tipo	Por defecto	Descripción
`q`	string	—	Búsqueda parcial por título (insensible a mayúsculas)
`normative_scope`	string	—	Filtra por ámbito
`tag`	string	—	Filtra las normativas que contengan esta etiqueta
`page`	integer	`1`	Número de página (base 1)
`page_size`	integer	`20`	Resultados por página. Máximo `50`

Cabeceras

Cabecera	Requerida	Descripción
`Authorization`	Sí	`Bearer sk-normatia-xxxxx`

Ejemplo de request

GET /api/v1/codes/search?q=accesibilidad&normative_scope=regional
Authorization: Bearer sk-normatia-xxxxx

Respuesta `200`

{
  "items": [
    {
      "slug": "decreto-293-2009",
      "title": "Decreto 293/2009 — Accesibilidad en Andalucía",
      "short_title": "Decreto Accesibilidad",
      "normative_scope": "regional",
      "tags": ["accesibilidad", "andalucia"]
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

Campos de respuesta

Campo	Tipo	Descripción
`items`	`array`	Lista de normativas de la página
`items[].slug`	`string`	Identificador público de la normativa
`items[].title`	`string`	Título completo
`items[].short_title`	`string \| null`	Título abreviado
`items[].normative_scope`	`string`	Ámbito normativo
`items[].tags`	`string[] \| null`	Etiquetas de búsqueda
`total`	`integer`	Total de resultados
`page`	`integer`	Página actual
`page_size`	`integer`	Resultados en esta página
`total_pages`	`integer`	Total de páginas

GET /api/v1/codes/{slug}

GET Detalle de normativa

Devuelve el detalle completo de una normativa con su historial de versiones. Usa este endpoint para ver qué versiones están disponibles antes de hacer una consulta histórica en /verify.

Parámetros de ruta

Parámetro	Tipo	Descripción
`slug`	string	Slug de la normativa. Ej: `cte-db-he`

Cabeceras

Cabecera	Requerida	Descripción
`Authorization`	Sí	`Bearer sk-normatia-xxxxx`

Ejemplo de request

GET /api/v1/codes/cte-db-he
Authorization: Bearer sk-normatia-xxxxx

Respuesta `200`

{
  "slug": "cte-db-he",
  "title": "CTE DB-HE — Ahorro de Energía",
  "short_title": "CTE DB-HE",
  "normative_scope": "national",
  "description": "Documento Básico que establece las exigencias básicas de ahorro de energía de los edificios.",
  "tags": ["cte", "energia", "edificacion"],
  "country_code": "es",
  "documents": [
    {
      "version": "2022",
      "title": "CTE DB-HE con modificaciones RD 450/2022",
      "status": "active",
      "published_date": "2022-06-27",
      "effective_date": "2022-10-09",
      "is_internal": true
    },
    {
      "version": "2019",
      "title": "CTE DB-HE — Revisión 2019",
      "status": "repealed",
      "published_date": "2019-12-27",
      "effective_date": "2020-06-26",
      "is_internal": true
    }
  ]
}

Campos de respuesta

Campo	Tipo	Descripción
`slug`	`string`	Identificador público
`title`	`string`	Título completo
`short_title`	`string \| null`	Título abreviado
`normative_scope`	`string`	Ámbito normativo
`description`	`string \| null`	Descripción larga
`tags`	`string[] \| null`	Etiquetas
`country_code`	`string`	País al que pertenece (ISO 3166-1 alpha-2)
`documents`	`object[]`	Historial de versiones, activas primero
`documents[].version`	`string`	Identificador de la versión. Usado en `codes[].version` de `/verify`
`documents[].title`	`string`	Título de la versión
`documents[].status`	`string`	`active` \| `repealed` \| `draft` \| `in_progress`
`documents[].published_date`	`string \| null`	Fecha de publicación (`YYYY-MM-DD`)
`documents[].effective_date`	`string \| null`	Fecha de entrada en vigor (`YYYY-MM-DD`)
`documents[].is_internal`	`boolean`	`true` si el contenido está alojado en Normatia y disponible para RAG

Errores

Status	Código	Condición
404	`not_found`	El slug no existe

GET /api/v1/codes/{slug}/latest

GET Versiones vigentes de una normativa

Devuelve todos los documentos en estado active de una normativa, incluyendo su índice de secciones. Devuelve array vacío si no hay versiones activas.

Parámetros de ruta

Parámetro	Tipo	Descripción
`slug`	string	Slug de la normativa. Ej: `cte-db-he`

Cabeceras

Cabecera	Requerida	Descripción
`Authorization`	Sí	`Bearer sk-normatia-xxxxx`

Ejemplo de request

GET /api/v1/codes/cte-db-he/latest
Authorization: Bearer sk-normatia-xxxxx

Respuesta `200`

Devuelve un array de objetos CodeVersionDetailResponse (mismo esquema que el endpoint de versión concreta, ver más abajo).

[
  {
    "slug": "cte-db-he",
    "version": "2022",
    "title": "CTE DB-HE con modificaciones RD 450/2022",
    "status": "active",
    "published_date": "2022-06-27",
    "effective_date": "2022-10-09",
    "is_internal": true,
    "sections": [
      { "slug": "introduccion", "title": "Introducción", "order": 10 },
      { "slug": "he1", "title": "HE 1 — Limitación de la demanda energética", "order": 20 }
    ]
  }
]

GET /api/v1/codes/{slug}/{version}

GET Detalle de versión de normativa

Devuelve el detalle completo de una versión específica, incluyendo su índice de secciones. Útil para conocer el contenido exacto de una versión antes de una consulta histórica o para navegar su estructura.

Parámetros de ruta

Parámetro	Tipo	Descripción
`slug`	string	Slug de la normativa. Ej: `cte-db-he`
`version`	string	Versión (slug del documento). Ej: `2022`

Cabeceras

Cabecera	Requerida	Descripción
`Authorization`	Sí	`Bearer sk-normatia-xxxxx`

Ejemplo de request

GET /api/v1/codes/cte-db-he/2022
Authorization: Bearer sk-normatia-xxxxx

Respuesta `200`

{
  "slug": "cte-db-he",
  "version": "2022",
  "title": "CTE DB-HE con modificaciones RD 450/2022",
  "status": "active",
  "published_date": "2022-06-27",
  "effective_date": "2022-10-09",
  "description": "Revisión completa del documento básico de ahorro de energía.",
  "author": "Ministerio de Transportes, Movilidad y Agenda Urbana",
  "source_url": "https://www.boe.es/eli/es/rd/2022/06/14/450",
  "is_internal": true,
  "sections": [
    { "slug": "introduccion", "title": "Introducción",                                      "order": 10 },
    { "slug": "he1",          "title": "HE 1 — Limitación de la demanda energética",        "order": 20 },
    { "slug": "he2",          "title": "HE 2 — Rendimiento de las instalaciones térmicas",  "order": 30 },
    { "slug": "he3",          "title": "HE 3 — Eficiencia energética de las instalaciones", "order": 40 },
    { "slug": "anejo-a",      "title": "Anejo A — Terminología",                            "order": 50 }
  ]
}

Campos de respuesta

Campo	Tipo	Descripción
`slug`	`string`	Slug de la normativa padre
`version`	`string`	Slug de esta versión
`title`	`string`	Título de esta versión concreta
`status`	`string`	`active` \| `repealed` \| `draft` \| `in_progress`
`published_date`	`string \| null`	Fecha de publicación (`YYYY-MM-DD`)
`effective_date`	`string \| null`	Fecha de entrada en vigor (`YYYY-MM-DD`)
`description`	`string \| null`	Descripción de esta versión
`author`	`string \| null`	Organismo emisor
`source_url`	`string \| null`	URL de la fuente oficial
`is_internal`	`boolean`	`true` si el contenido está alojado en Normatia y disponible para RAG
`sections`	`object[]`	Índice de secciones ordenado
`sections[].slug`	`string`	Slug de la sección (usado como ancla en la web)
`sections[].title`	`string`	Título de la sección
`sections[].order`	`integer`	Orden de presentación

Errores

Status	Código	Condición
404	`not_found`	El slug o la versión no existen

Codes

Valores de referencia

normative_scope

status de versiones

GET /api/v1/codes/search

Parámetros de query

Cabeceras

Ejemplo de request

Respuesta 200

Campos de respuesta

GET /api/v1/codes/{slug}

Parámetros de ruta

Cabeceras

Ejemplo de request

Respuesta 200

Campos de respuesta

Errores

GET /api/v1/codes/{slug}/latest

Parámetros de ruta

Cabeceras

Ejemplo de request

Respuesta 200

GET /api/v1/codes/{slug}/{version}

Parámetros de ruta

Cabeceras

Ejemplo de request

Respuesta 200

Campos de respuesta

Errores

`normative_scope`

`status` de versiones

Respuesta `200`

Respuesta `200`

Respuesta `200`

Respuesta `200`