Catálogos

Dos grupos de endpoints. Qué contiene cada catálogo y cómo se usa está en la sección catálogos.

	Consulta básica	Administración
Rutas	`/v1/instituciones`, `/v1/tipos-inmueble`	`/v1/catalogos/…`
Scope	`avaluos:read`	`catalogos:read` / `catalogos:write`
Filas	Sólo activas	Todas, incluidas las inactivas
Campos	Los necesarios para un selector	La fila completa

GET/v1/institucionesavaluos:read

Catálogo de instituciones válidas

GET/v1/tipos-inmuebleavaluos:read

Catálogo de tipos de inmueble válidos

GET/v1/catalogos/institucionescatalogos:read

Instituciones, fila completa (incluye inactivas)

POST/v1/catalogos/institucionescatalogos:write

Alta de institución

PATCH/v1/catalogos/instituciones/{id}catalogos:write

Edición de institución

DELETE/v1/catalogos/instituciones/{id}catalogos:write

Baja lógica de institución

GET/v1/catalogos/tipos-inmueblecatalogos:read

Tipos de inmueble, fila completa (incluye inactivos)

POST/v1/catalogos/tipos-inmueblecatalogos:write

Alta de tipo de inmueble

PATCH/v1/catalogos/tipos-inmueble/{id}catalogos:write

Edición de tipo de inmueble

DELETE/v1/catalogos/tipos-inmueble/{id}catalogos:write

Baja lógica de tipo de inmueble

GET/v1/catalogos/reglascatalogos:read

Catálogo de reglas (filtrable por etapa y estado)

POST/v1/catalogos/reglascatalogos:write

Alta de regla

GET/v1/catalogos/reglas/{codigo}catalogos:read

Una regla por su código

PATCH/v1/catalogos/reglas/{codigo}catalogos:write

Edición de regla

DELETE/v1/catalogos/reglas/{codigo}catalogos:write

Retira una regla

GET/v1/catalogos/seccionescatalogos:read

Catálogo de secciones (filtrable por tipo y estado)

POST/v1/catalogos/seccionescatalogos:write

Alta de sección

GET/v1/catalogos/secciones/{id}catalogos:read

Una sección por su id

PATCH/v1/catalogos/secciones/{id}catalogos:write

Edición de sección

DELETE/v1/catalogos/secciones/{id}catalogos:write

Baja lógica de sección

Consulta básica

Instituciones activas

GET/v1/institucionesavaluos:read

Catálogo de instituciones válidas

Instituciones activas, ordenadas por codigo. Los valores de institution deben pertenecer a este catálogo; de lo contrario POST /v1/avaluos responde 422.

La lista puede tardar hasta 60 s en reflejar un cambio hecho en el catálogo.

Petición

curl "$API_URL/v1/instituciones" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Catálogo de instituciones.

[
  {
    "clave": "040012",
    "codigo": "BBVA",
    "nombre": "BBVA México"
  },
  {
    "clave": "040014",
    "codigo": "SANTANDER",
    "nombre": "Santander"
  }
]

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Tipos de inmueble activos

GET/v1/tipos-inmuebleavaluos:read

Catálogo de tipos de inmueble válidos

Tipos de inmueble activos, ordenados por codigo. Los valores de property_type deben pertenecer a este catálogo; de lo contrario POST /v1/avaluos responde 422.

La lista puede tardar hasta 60 s en reflejar un cambio hecho en el catálogo.

Petición

curl "$API_URL/v1/tipos-inmueble" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Catálogo de tipos de inmueble.

[
  {
    "clave": 2,
    "codigo": "CASA_HABITACION",
    "nombre": "Casa habitación",
    "categoria": "vivienda",
    "n8n_scraping_type": "casa"
  },
  {
    "clave": 7,
    "codigo": "OTRO",
    "nombre": "Otro",
    "categoria": "otro",
    "n8n_scraping_type": null
  }
]

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Instituciones

Listar instituciones

GET/v1/catalogos/institucionescatalogos:read

Instituciones, fila completa (incluye inactivas)

Todas las instituciones, ordenadas por codigo.

Petición

curl "$API_URL/v1/catalogos/instituciones" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Instituciones del catálogo.

[
  {
    "id": "5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a",
    "clave": "040012",
    "codigo": "BBVA",
    "nombre": "BBVA México",
    "tipo": "financiera",
    "activa": true,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-08-02T09:30:00.000Z"
  }
]

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Crear una institución

POST/v1/catalogos/institucionescatalogos:write

Alta de institución

clave se rellena con ceros a 6 dígitos y codigo se guarda en mayúsculas.

Cuerpo application/json

Campo	Tipo	Descripción
`clave`	string	Clave Banxico, de 1 a 6 dígitos; se rellena con ceros a la izquierda hasta 6.
`codigo`requerido	string	Valor de `institution`; se guarda en mayúsculas. (mín. 2 caracteres, máx. 40 caracteres)
`nombre`requerido	string	(mín. 2 caracteres)
`tipo`requerido	financiera \| otro	—
`activa`	boolean	(por defecto `true`)

Petición

curl -X POST "$API_URL/v1/catalogos/instituciones" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "clave": "40012",
  "codigo": "bbva",
  "nombre": "BBVA México",
  "tipo": "financiera"
}'

Respuesta

201 — Institución creada.

{
  "id": "5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a",
  "clave": "040012",
  "codigo": "BBVA",
  "nombre": "BBVA México",
  "tipo": "financiera",
  "activa": true,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe otra institución con ese código (`CODIGO_DUPLICADO`) o con esa clave (`CLAVE_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Editar una institución

PATCH/v1/catalogos/instituciones/{id}catalogos:write

Edición de institución

Envía sólo los campos que cambian; todos son opcionales.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Cuerpo application/json

Campo	Tipo	Descripción
`clave`	string	Clave Banxico, de 1 a 6 dígitos; se rellena con ceros a la izquierda hasta 6.
`codigo`	string	Se guarda en mayúsculas. (mín. 2 caracteres, máx. 40 caracteres)
`nombre`	string	(mín. 2 caracteres)
`tipo`	financiera \| otro	—
`activa`	boolean	—

Petición

curl -X PATCH "$API_URL/v1/catalogos/instituciones/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "nombre": "BBVA México, S.A."
}'

Respuesta

200 — Institución actualizada.

{
  "id": "5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a",
  "clave": "040012",
  "codigo": "BBVA",
  "nombre": "BBVA México, S.A.",
  "tipo": "financiera",
  "activa": true,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). También si el `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una institución con ese `id` (`INSTITUCION_NO_ENCONTRADA`).
`409`	Otra institución ya usa ese código (`CODIGO_DUPLICADO`) o esa clave (`CLAVE_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Dar de baja una institución

DELETE/v1/catalogos/instituciones/{id}catalogos:write

Baja lógica de institución

Marca la institución con activa: false; la fila no se borra y deja de aceptarse en POST /v1/avaluos.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Petición

curl -X DELETE "$API_URL/v1/catalogos/instituciones/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Institución desactivada; devuelve la fila actualizada.

{
  "id": "5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a",
  "clave": "040012",
  "codigo": "BBVA",
  "nombre": "BBVA México",
  "tipo": "financiera",
  "activa": false,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	El `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una institución con ese `id` (`INSTITUCION_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Tipos de inmueble

Listar tipos de inmueble

GET/v1/catalogos/tipos-inmueblecatalogos:read

Tipos de inmueble, fila completa (incluye inactivos)

Todos los tipos de inmueble, ordenados por clave.

Petición

curl "$API_URL/v1/catalogos/tipos-inmueble" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Tipos de inmueble del catálogo.

[
  {
    "id": "7c2e1d0f-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
    "clave": 2,
    "codigo": "CASA_HABITACION",
    "nombre": "Casa habitación",
    "categoria": "vivienda",
    "n8n_scraping_type": "casa",
    "activo": true,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-08-02T09:30:00.000Z"
  }
]

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Crear un tipo de inmueble

POST/v1/catalogos/tipos-inmueblecatalogos:write

Alta de tipo de inmueble

codigo se guarda en mayúsculas.

Cuerpo application/json

Campo	Tipo	Descripción
`clave`requerido	integer	Clave numérica del catálogo SHF. (mín. 1, máx. 7)
`codigo`requerido	string	Valor de `property_type`; se guarda en mayúsculas. (mín. 2 caracteres, máx. 40 caracteres)
`nombre`requerido	string	(mín. 2 caracteres)
`categoria`requerido	terreno \| vivienda \| otro	—
`n8n_scraping_type`	casa \| terreno \| departamento \| mixto \| otro \| null	Tipo de comparables a buscar en la etapa de mercado; null si no aplica.
`activo`	boolean	(por defecto `true`)

Petición

curl -X POST "$API_URL/v1/catalogos/tipos-inmueble" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "clave": 2,
  "codigo": "CASA_HABITACION",
  "nombre": "Casa habitación",
  "categoria": "vivienda",
  "n8n_scraping_type": "casa"
}'

Respuesta

201 — Tipo de inmueble creado.

{
  "id": "7c2e1d0f-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
  "clave": 2,
  "codigo": "CASA_HABITACION",
  "nombre": "Casa habitación",
  "categoria": "vivienda",
  "n8n_scraping_type": "casa",
  "activo": true,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe otro tipo de inmueble con ese código (`CODIGO_DUPLICADO`) o con esa clave (`CLAVE_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Editar un tipo de inmueble

PATCH/v1/catalogos/tipos-inmueble/{id}catalogos:write

Edición de tipo de inmueble

Envía sólo los campos que cambian; todos son opcionales.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Cuerpo application/json

Campo	Tipo	Descripción
`clave`	integer	(mín. 1, máx. 7)
`codigo`	string	Se guarda en mayúsculas. (mín. 2 caracteres, máx. 40 caracteres)
`nombre`	string	(mín. 2 caracteres)
`categoria`	terreno \| vivienda \| otro	—
`n8n_scraping_type`	casa \| terreno \| departamento \| mixto \| otro \| null	—
`activo`	boolean	—

Petición

curl -X PATCH "$API_URL/v1/catalogos/tipos-inmueble/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "nombre": "Casa habitación unifamiliar"
}'

Respuesta

200 — Tipo de inmueble actualizado.

{
  "id": "7c2e1d0f-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
  "clave": 2,
  "codigo": "CASA_HABITACION",
  "nombre": "Casa habitación unifamiliar",
  "categoria": "vivienda",
  "n8n_scraping_type": "casa",
  "activo": true,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). También si el `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe un tipo de inmueble con ese `id` (`TIPO_INMUEBLE_NO_ENCONTRADO`).
`409`	Otro tipo de inmueble ya usa ese código (`CODIGO_DUPLICADO`) o esa clave (`CLAVE_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Dar de baja un tipo de inmueble

DELETE/v1/catalogos/tipos-inmueble/{id}catalogos:write

Baja lógica de tipo de inmueble

Marca el tipo con activo: false; la fila no se borra y deja de aceptarse en POST /v1/avaluos.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Petición

curl -X DELETE "$API_URL/v1/catalogos/tipos-inmueble/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Tipo de inmueble desactivado; devuelve la fila actualizada.

{
  "id": "7c2e1d0f-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
  "clave": 2,
  "codigo": "CASA_HABITACION",
  "nombre": "Casa habitación",
  "categoria": "vivienda",
  "n8n_scraping_type": "casa",
  "activo": false,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	El `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe un tipo de inmueble con ese `id` (`TIPO_INMUEBLE_NO_ENCONTRADO`).
`429`	Se superó el límite de peticiones (rate limit).

Reglas

Listar reglas

GET/v1/catalogos/reglascatalogos:read

Catálogo de reglas (filtrable por etapa y estado)

Reglas ordenadas por codigo_regla.

Parámetros

Campo	Tipo	Descripción
`?etapa`	documental \| datos \| calculos \| mercado \| reglas	En la query. Sólo las reglas de esa etapa.
`?activa`	boolean	En la query. `true` sólo vigentes, `false` sólo retiradas. Sin el filtro devuelve todas.

Petición

curl "$API_URL/v1/catalogos/reglas" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Reglas del catálogo.

[
  {
    "codigo_regla": "MER-005",
    "etapa": "mercado",
    "nombre": "Diferencia > 20% vs unitario de mercado web",
    "descripcion": "El unitario del avalúo se desvía más del umbral respecto al promedio de comparables.",
    "severidad_base": "tecnico",
    "fuente": "SHF",
    "nivel_jerarquia": 1,
    "permite_justificacion": true,
    "persiste_en": "evaluation_errors",
    "activa": true,
    "parametros": {
      "umbral_pct": 20
    },
    "notas": null,
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-08-02T09:30:00.000Z"
  }
]

Errores

HTTP	Cuándo ocurre
`400`	`etapa` no es una etapa válida, `activa` no es `true`/`false` o se envió un parámetro no permitido.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Obtener una regla

GET/v1/catalogos/reglas/{codigo}catalogos:read

Una regla por su código

Parámetros

Campo	Tipo	Descripción
`codigo`requerido	string	En la ruta. Código de la regla, p. ej. `MER-005`. Se acepta en minúsculas (`mer-005`).

Petición

curl "$API_URL/v1/catalogos/reglas/MER-005" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Regla.

{
  "codigo_regla": "MER-005",
  "etapa": "mercado",
  "nombre": "Diferencia > 20% vs unitario de mercado web",
  "descripcion": "El unitario del avalúo se desvía más del umbral respecto al promedio de comparables.",
  "severidad_base": "tecnico",
  "fuente": "SHF",
  "nivel_jerarquia": 1,
  "permite_justificacion": true,
  "persiste_en": "evaluation_errors",
  "activa": true,
  "parametros": {
    "umbral_pct": 20
  },
  "notas": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una regla con ese código (`REGLA_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Crear una regla

POST/v1/catalogos/reglascatalogos:write

Alta de regla

etapa se deriva del prefijo del código y nivel_jerarquia de fuente; no se envían. El código se guarda en mayúsculas y nunca se recicla.

Cuerpo application/json

Campo	Tipo	Descripción
`codigo_regla`requerido	string	Formato `DOC\|DAT\|CAL\|MER\|REG\|SIS-NNN`, sin distinguir mayúsculas; se guarda en mayúsculas. El prefijo fija la etapa.
`nombre`requerido	string	(mín. 3 caracteres)
`descripcion`	string	—
`severidad_base`requerido	critico \| tecnico \| forma	—
`fuente`	SHF \| CNBV \| BANCO \| TVO	—
`permite_justificacion`	boolean	(por defecto `true`)
`persiste_en`	string	(por defecto `"evaluation_errors"`)
`parametros`	object	Umbrales y parámetros propios de la regla.
`notas`	string	—
`activa`	boolean	(por defecto `true`)

Petición

curl -X POST "$API_URL/v1/catalogos/reglas" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "codigo_regla": "MER-005",
  "nombre": "Diferencia > 20% vs unitario de mercado web",
  "severidad_base": "tecnico",
  "fuente": "SHF",
  "parametros": {
    "umbral_pct": 20
  }
}'

Respuesta

201 — Regla creada.

{
  "codigo_regla": "MER-005",
  "etapa": "mercado",
  "nombre": "Diferencia > 20% vs unitario de mercado web",
  "descripcion": "El unitario del avalúo se desvía más del umbral respecto al promedio de comparables.",
  "severidad_base": "tecnico",
  "fuente": "SHF",
  "nivel_jerarquia": 1,
  "permite_justificacion": true,
  "persiste_en": "evaluation_errors",
  "activa": true,
  "parametros": {
    "umbral_pct": 20
  },
  "notas": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). Enviar `etapa` o `nivel_jerarquia` también responde 400.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe una regla con ese código (`REGLA_DUPLICADA`). Si está retirada, reactívala con `PATCH` y `activa: true`.
`429`	Se superó el límite de peticiones (rate limit).

Editar una regla

PATCH/v1/catalogos/reglas/{codigo}catalogos:write

Edición de regla

Envía sólo los campos que cambian; todos son opcionales. codigo_regla no se edita: para cambiarlo, retira la regla y da de alta otra. Cambiar fuente recalcula nivel_jerarquia.

Parámetros

Campo	Tipo	Descripción
`codigo`requerido	string	En la ruta. Código de la regla, p. ej. `MER-005`. Se acepta en minúsculas (`mer-005`).

Cuerpo application/json

Campo	Tipo	Descripción
`nombre`	string	(mín. 3 caracteres)
`descripcion`	string	—
`severidad_base`	critico \| tecnico \| forma	—
`fuente`	SHF \| CNBV \| BANCO \| TVO	—
`permite_justificacion`	boolean	—
`persiste_en`	string	—
`parametros`	object	—
`notas`	string	—
`activa`	boolean	`true` reactiva una regla retirada.

Petición

curl -X PATCH "$API_URL/v1/catalogos/reglas/MER-005" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "severidad_base": "critico",
  "activa": true
}'

Respuesta

200 — Regla actualizada.

{
  "codigo_regla": "MER-005",
  "etapa": "mercado",
  "nombre": "Diferencia > 20% vs unitario de mercado web",
  "descripcion": "El unitario del avalúo se desvía más del umbral respecto al promedio de comparables.",
  "severidad_base": "critico",
  "fuente": "SHF",
  "nivel_jerarquia": 1,
  "permite_justificacion": true,
  "persiste_en": "evaluation_errors",
  "activa": true,
  "parametros": {
    "umbral_pct": 20
  },
  "notas": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). Enviar `codigo_regla`, `etapa` o `nivel_jerarquia` también responde 400.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una regla con ese código (`REGLA_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Retirar una regla

DELETE/v1/catalogos/reglas/{codigo}catalogos:write

Retira una regla

Baja lógica: marca activa: false y devuelve la fila. El código queda reservado y no puede darse de alta otra regla con él.

Parámetros

Campo	Tipo	Descripción
`codigo`requerido	string	En la ruta. Código de la regla, p. ej. `MER-005`. Se acepta en minúsculas (`mer-005`).

Petición

curl -X DELETE "$API_URL/v1/catalogos/reglas/MER-005" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Regla retirada; devuelve la fila actualizada.

{
  "codigo_regla": "MER-005",
  "etapa": "mercado",
  "nombre": "Diferencia > 20% vs unitario de mercado web",
  "descripcion": "El unitario del avalúo se desvía más del umbral respecto al promedio de comparables.",
  "severidad_base": "tecnico",
  "fuente": "SHF",
  "nivel_jerarquia": 1,
  "permite_justificacion": true,
  "persiste_en": "evaluation_errors",
  "activa": false,
  "parametros": {
    "umbral_pct": 20
  },
  "notas": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-08-02T09:30:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una regla con ese código (`REGLA_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Secciones

Listar secciones

GET/v1/catalogos/seccionescatalogos:read

Catálogo de secciones (filtrable por tipo y estado)

Secciones ordenadas por orden y luego por key.

Parámetros

Campo	Tipo	Descripción
`?tipo`	texto \| ocr_documento \| plano \| ocr_imagen \| imagen	En la query. Sólo las secciones de ese tipo.
`?activa`	boolean	En la query. `true` sólo activas, `false` sólo inactivas. Sin el filtro devuelve todas.

Petición

curl "$API_URL/v1/catalogos/secciones" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Secciones del catálogo.

[
  {
    "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
    "key": "cuadro_areas",
    "nombre": "CUADRO DE AREAS",
    "aliases": [
      "CUADRO DE ÁREAS",
      "SUPERFICIES"
    ],
    "tipo": "plano",
    "orden": 12,
    "activa": true,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
]

Errores

HTTP	Cuándo ocurre
`400`	`tipo` no es un tipo válido, `activa` no es `true`/`false` o se envió un parámetro no permitido.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Obtener una sección

GET/v1/catalogos/secciones/{id}catalogos:read

Una sección por su id

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Petición

curl "$API_URL/v1/catalogos/secciones/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Sección.

{
  "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
  "key": "cuadro_areas",
  "nombre": "CUADRO DE AREAS",
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES"
  ],
  "tipo": "plano",
  "orden": 12,
  "activa": true,
  "created_at": "2026-01-15T12:00:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	El `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una sección con ese `id` (`SECCION_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Crear una sección

POST/v1/catalogos/seccionescatalogos:write

Alta de sección

Cuerpo application/json

Campo	Tipo	Descripción
`key`requerido	string	Identificador estable en snake_case (minúsculas, dígitos y `_`).
`nombre`requerido	string	(mín. 2 caracteres)
`aliases`	string[]	Variantes con que la sección aparece en el avalúo; sin repetidos.
`tipo`requerido	texto \| ocr_documento \| plano \| ocr_imagen \| imagen	—
`orden`	integer	Posición de la sección dentro del avalúo. (mín. 1)
`activa`	boolean	(por defecto `true`)

Petición

curl -X POST "$API_URL/v1/catalogos/secciones" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "cuadro_areas",
  "nombre": "CUADRO DE AREAS",
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES"
  ],
  "tipo": "plano",
  "orden": 12
}'

Respuesta

201 — Sección creada.

{
  "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
  "key": "cuadro_areas",
  "nombre": "CUADRO DE AREAS",
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES"
  ],
  "tipo": "plano",
  "orden": 12,
  "activa": true,
  "created_at": "2026-01-15T12:00:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe una sección con esa `key` (`KEY_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Editar una sección

PATCH/v1/catalogos/secciones/{id}catalogos:write

Edición de sección

Envía sólo los campos que cambian; todos son opcionales. key también puede corregirse.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Cuerpo application/json

Campo	Tipo	Descripción
`key`	string	—
`nombre`	string	(mín. 2 caracteres)
`aliases`	string[]	—
`tipo`	texto \| ocr_documento \| plano \| ocr_imagen \| imagen	—
`orden`	integer	(mín. 1)
`activa`	boolean	—

Petición

curl -X PATCH "$API_URL/v1/catalogos/secciones/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES",
    "ÁREAS"
  ]
}'

Respuesta

200 — Sección actualizada.

{
  "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
  "key": "cuadro_areas",
  "nombre": "CUADRO DE AREAS",
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES",
    "ÁREAS"
  ],
  "tipo": "plano",
  "orden": 12,
  "activa": true,
  "created_at": "2026-01-15T12:00:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). También si el `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una sección con ese `id` (`SECCION_NO_ENCONTRADA`).
`409`	Otra sección ya usa esa `key` (`KEY_DUPLICADA`).
`429`	Se superó el límite de peticiones (rate limit).

Dar de baja una sección

DELETE/v1/catalogos/secciones/{id}catalogos:write

Baja lógica de sección

Marca la sección con activa: false; la fila no se borra.

Parámetros

Campo	Tipo	Descripción
`id`requerido	uuid	En la ruta. UUID de la fila del catálogo.

Petición

curl -X DELETE "$API_URL/v1/catalogos/secciones/5b1f0c2e-7d4a-4e9b-8a3c-2f6d1e0b9c8a" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Sección desactivada; devuelve la fila actualizada.

{
  "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
  "key": "cuadro_areas",
  "nombre": "CUADRO DE AREAS",
  "aliases": [
    "CUADRO DE ÁREAS",
    "SUPERFICIES"
  ],
  "tipo": "plano",
  "orden": 12,
  "activa": false,
  "created_at": "2026-01-15T12:00:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	El `id` de la ruta no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	No existe una sección con ese `id` (`SECCION_NO_ENCONTRADA`).
`429`	Se superó el límite de peticiones (rate limit).

Catálogos

On this page