AlertaSubastas

npx add-mcp 'https://alertasubastas.com/mcp'

API de AlertaSubastas — v1

Estado: en desarrollo. Los endpoints descritos son funcionales pero el servicio aún no está lanzado comercialmente; los límites y planes pueden cambiar.

API REST para buscar subastas públicas de España (BOE judiciales, notariales, Seguridad Social, Hacienda/AEAT, ayuntamientos, diputaciones y otras administraciones) y descargar el detalle completo de cada bien subastado.

El flujo típico tiene dos pasos: POST /bienes/search devuelve los IDs de bien que encajan con tus filtros, y GET /bienes/{id} devuelve el detalle completo de cada uno. Los endpoints de metadatos te dan los valores exactos que aceptan los filtros.

Todas las respuestas son JSON UTF-8.

Versión markdown de esta documentación (para desarrolladores y agentes IA): /api/docs.md

https://alertasubastas.com/api/v1

Autenticación

Toda petición requiere una API key en el header Authorization.

• La key se genera en el panel /admin/api (vale con un plan Personal, Profesional, Empresa o API; cada uno con sus cupos).
• Puedes tener hasta 10 keys a la vez, cada una con su nombre, permisos (lectura y escritura, o solo lectura) y caducidad opcional (30, 90 o 365 días). Se crean y se revocan en Tu cuenta, apartado «Conectar por MCP». Regenerar la key desde el panel del API revoca todas.
• La key solo se muestra una vez al crearla (en el servidor solo se guarda su hash).
• Sin header, key desconocida, revocada o caducada → 401 invalid_key. Key de solo lectura en un POST, PUT o DELETE → 403 insufficient_scope. Sin un plan activo que incluya el API → 403 subscription_expired (la key no se borra: al re-contratar vuelve a funcionar).

Authorization: Bearer asapi_<48 caracteres hex>

curl -s https://alertasubastas.com/api/v1/usage \
  -H "Authorization: Bearer $API_KEY"

Cuotas y límites

Límite	Valor	Detalle
Rate limit	60 req/min	Por cliente y endpoint. Al superarlo: 429 rate_limited con header Retry-After.
Búsquedas/mes	según plan	Personal 50, Profesional 200 y Empresa 300 (con plan API también, el mayor). Lo que consultas en la web no cuenta. Reset el día 1 de cada mes natural. Agotada: 429 search_quota_exceeded.
Bienes/mes	según plan	Personal 50, Profesional 200 y Empresa 300. Cuota de bienes únicos nuevos de subastas no finalizadas (activas, suspendidas y próxima apertura). El histórico es de por vida: re-descargar un bien ya consumido en cualquier mes anterior es gratis. Agotada: 429 bien_quota_exceeded.
Finalizadas/mes	según plan	Bienes únicos nuevos de subastas finalizadas o canceladas: 500. Mismo histórico de por vida. Agotada: 429 finalizadas_quota_exceeded.

Paginación gratis: repetir la misma búsqueda (mismo q + filtros + orden; page se ignora en la comparación) dentro de una ventana de 60 minutos no consume cuota. Pasada la ventana, la misma búsqueda vuelve a contar. Solo consumen las respuestas 200.

Los endpoints de metadatos, /usage, /lotes/{id} y /subastas/{id} no consumen cuota (sí rate limit).

X-Quota-Searches-Used / X-Quota-Searches-Limit
X-Quota-Bienes-Used   / X-Quota-Bienes-Limit
X-Quota-Finalizadas-Used / X-Quota-Finalizadas-Limit
X-RateLimit-Remaining

Errores

Formato uniforme en todos los endpoints.

HTTP	error	Cuándo
401	invalid_key	Sin header Authorization, key desconocida o revocada.
403	subscription_expired	Key válida pero sin un plan activo que incluya el API.
400	invalid_request	Parámetro, filtro o valor no soportado (no consume cuota).
404	not_found	Bien, lote, subasta o provincia inexistente (no consume cuota).
429	rate_limited	Más de 60 req/min en el endpoint (header Retry-After).
429	search_quota_exceeded	Cuota mensual de búsquedas agotada.
429	bien_quota_exceeded	Cuota mensual de bienes nuevos agotada.
429	finalizadas_quota_exceeded	Cuota mensual de bienes nuevos de subastas finalizadas agotada.
503	search_unavailable	Error temporal del buscador; reintenta más tarde (no consume cuota).

{
  "error": "invalid_request",
  "message": "unknown filter 'precio'"
}

Cambios recientes

• Octubre 2026 (11ª tanda): el servidor MCP se conecta también con tu cuenta de AlertaSubastas (OAuth 2.1), sin copiar una key.
• Octubre 2026 (10ª tanda): nuevo POST /sugerencias (tool MCP enviar_sugerencia): mejoras, errores y datos que faltan, por email al equipo. Las búsquedas del MCP sin resultados lo recuerdan en sugerencia.
• Octubre 2026 (9ª tanda): GET /favoritas añade a cada favorita titulo, subasta (grupo, estado y fecha de fin) y consultada, y el filtro subasta (activas, proximas, finalizadas). La búsqueda y /codigo devuelven consultadas: los ids cuya ficha ya consultaste, que no gastan cuota.
• Octubre 2026 (8ª tanda): la búsqueda acepta comarca y los grupos de tipo_bien (inmuebles, muebles, todos), como el listado. Las alertas aceptan marca, superficie y bienes_lote. /provincias/{slug}/municipios devuelve también las comarcas y /opciones, los tipo_bien_grupos.
• Octubre 2026 (7ª tanda): el detalle del bien añade similares y valor_mercado. Nuevos GET /codigo (por referencia catastral, IDUFIR / CRU, id del BOE…), GET /ayuda (conceptos explicados por la ayuda) y POST /alertas/previsualizar (tools MCP buscar_por_codigo, explicar_concepto y alertas_previsualizar).
• Octubre 2026 (6ª tanda): el detalle del bien añade url y resumen en la raíz. Nuevo GET /planes (tool MCP ver_planes).
• Octubre 2026 (5ª tanda): endpoints de alertas y favoritas, con el plan web, la prueba o un plan API. Nuevo servidor MCP en https://alertasubastas.com/mcp.
• Octubre 2026 (4ª tanda): el detalle añade lote.BIENES (IDs de los bienes del mismo lote). Nuevos GET /lotes/{id} (bienes del lote) y GET /subastas/{id} (lotes de la subasta), sin cuota.
• Octubre 2026 (3ª tanda): PUJA.estado = "sin_pujas" queda solo para los estados 2 y 6. Las subastas canceladas (4) y suspendidas (5) pasan a desconocida, en el detalle y en el filtro pujas.
• Octubre 2026 (2ª tanda): bien.ESTADO y lote.ESTADO pasan a objeto { codigo, slug, nombre }, y el filtro estado acepta esos mismos slugs (además de los agregados de siempre). El filtro puja: {min,max} se retira y lo sustituye pujas, con los mismos valores que PUJA.estado del detalle más con_pujas. /opciones añade estado y pujas.
• Octubre 2026: nuevo campo bien.FECHA_ACTUALIZACION (último cambio de estado de la subasta o del lote), filtro fecha_actualizacion (acepta fecha y hora con zona horaria) y órdenes fecha_actualizacion_asc / _desc con desempate por id, para sincronizar cambios sin volver a descargarlo todo.
• Septiembre 2026 (2ª tanda): la PUJA distingue importe_no_publicado (la fuente confirma pujas sin publicar importe). Las fechas con hora pasan a ISO 8601 con zona horaria de Madrid. La geolocalización se unifica en GEO { lat, lng, nivel } — absorbe LAT_LNG y NIVEL_GEO, con nivel legible (portal / calle / municipio).
• Septiembre 2026: bien.PUJA y lote.PUJA pasan a objeto { estado, importe } con la puja secreta explícita. Coordenadas solo en LAT_LNG (retirados LAT y LNG sueltos). Los campos exclusivos de inmuebles y de vehículos solo se sirven en su tipo de bien. Textos descriptivos en minúsculas y REF_CATASTRAL siempre en mayúsculas. CLASE_SUBASTA (antes CLASSUBASTA) y PROCEDIMIENTO pasan a objeto { codigo, slug, nombre }; retirado ORIGEN (código interno); /opciones añade slug a clase y procedimiento.
• Agosto 2026: normalización del detalle (ausentes → null, objetos CARGAS / SITUACION_POSESORIA / VISITABLE). Estados celebrandose y proximas en la búsqueda. Error 503 search_unavailable.

POST Buscar bienes

/api/v1/bienes/search

Busca bienes y devuelve solo sus IDs, 100 por página. Todos los campos del body son opcionales: {} devuelve todo el índice.

Campo	Tipo	Descripción
q	string ≤ 200	Texto libre: busca en título, descripciones, calle, referencias catastral/registral, marca/modelo/matrícula…
filtros	object	Filtros estructurados, ver tabla siguiente.
orden	string	Ver valores de orden. Sin orden: relevancia del buscador.
page	int 1–100	Profundidad máxima 10.000 resultados; afina los filtros para conjuntos mayores.

Filtros

Filtro	Tipo	Descripción
provincia	string	Slug ("a-coruna") o nombre exacto ("A Coruña"). Lista completa en GET /provincias.
municipio	string	Nombre exacto del municipio tal como lo devuelve GET /provincias/{slug}/municipios.
comarca	string	Slug de comarca ("maresme-barcelona"), tal como lo devuelve GET /provincias/{slug}/municipios (comarcas).
tipo_bien	string	Slug del tipo de bien ("vivienda", "garaje" …), o un grupo como en el listado: "inmuebles", "muebles" o "todos" (sin filtro de tipo). Lista con etiquetas en GET /opciones.
estado	string	"activas" (en curso; incluye suspendidas), "celebrandose" (en curso, excluyendo suspendidas), "finalizadas" (incluye canceladas), "proximas" (en próxima apertura, aún sin fecha de celebración; requiere un plan que incluya la funcionalidad, si no devuelve error), "suspendidas" o "canceladas". O un estado concreto: cualquier slug de la tabla de estados ("activa_con_pujas", "suspendida" …), el mismo que devuelve bien.ESTADO.slug en el detalle. "proxima_apertura" requiere el mismo plan que "proximas".
clase_subasta	int	Origen de la subasta; códigos y nombres abajo y en GET /opciones.
procedimiento	int	Tipo de procedimiento; códigos y nombres abajo y en GET /opciones.
valoracion	{min,max}	Valor de subasta en euros. Basta uno de los dos límites.
pujas	string	Estado de la puja, con los mismos valores que bien.PUJA.estado del detalle (la puja del bien, no la del lote): "importe", "importe_no_publicado", "secreta", "sin_pujas" o "desconocida"; además "con_pujas" (hay pujas, con o sin importe publicado). Se combina con estado (Y). Sustituye al antiguo puja: {min,max}, retirado.
deposito	{min,max}	Depósito requerido en euros.
vivienda_habitual	string	Si el inmueble es la vivienda habitual del deudor, según el BOE: "si", "no" o "desconocido" (inmueble sin el dato). Solo aplica a inmuebles: con cualquier valor quedan fuera los muebles. Corresponde a bien.VIVIENDA_HABITUAL del detalle (true / false / null).
reclamada	{min,max}	Cantidad reclamada en euros: la del lote o, si no la hay, la de toda la subasta (si la deuda es de toda la subasta, cada bien cuenta con la deuda total aunque la subasta tenga varios lotes). min y max incluidos; basta uno de los dos. Aplica a todos los tipos de bien. Con el filtro quedan fuera los bienes sin cantidad reclamada (0 o menos de 100 €; la mayoría de AEAT y Seguridad Social). Tramos sugeridos en /opciones (reclamada.tramos).
marca	string	Marca del vehículo, como slug ("renault", "mercedes-benz"). La lista viva de slugs y nombres está en /opciones (marcas). Solo los vehículos tienen marca: con cualquier valor quedan fuera los demás bienes.
superficie	object	{min, max} en m² según catastro (enteros 1..999999): superficie construida; en solares y fincas rústicas, superficie de la parcela. min incluido y max excluido (min <= x < max); basta uno de los dos y min debe ser menor que max. Solo inmuebles; quedan fuera los bienes sin dato catastral. Tramos sugeridos por tipo de bien en /opciones (superficie.tramos_por_tipo).
bienes_lote	string	Número de bienes del lote al que pertenece el bien: "uno" (lote de un solo bien) o "varios" (lote de dos o más). Quedan fuera los lotes sin el dato.
fecha_celebracion	{desde,hasta}	Fechas YYYY-MM-DD; hasta inclusivo (fin de día). Fecha de conclusión de la subasta.
fecha_insercion	{desde,hasta}	Fecha de publicación del bien en AlertaSubastas. Útil para consumir novedades de forma incremental.
fecha_actualizacion	{desde,hasta}	Fecha y hora del último cambio de estado de la subasta o de su lote (publicación, apertura, primera puja, suspensión, reanudación, cancelación, finalización). Acepta YYYY-MM-DD o fecha y hora ISO 8601 (2026-10-06T15:30:00+02:00; sin zona horaria se toma la de Madrid): puedes pasar tal cual un FECHA_ACTUALIZACION recibido. desde y hasta con hora son exactos e inclusivos. Ver sincronización de cambios.

Clase de subasta

Código	Origen
2	BOE judiciales
3	Notariales
4	Diputaciones
5	Ayuntamientos
6	Consejos comarcales
7	Seguridad Social
11	Agencias tributarias autonómicas
12	Hacienda (AEAT)
13	Administraciones generales

Procedimiento

Código	Procedimiento
1	Subasta administrativa
2	Adjudicación directa
3	Concurso
4	Judicial en vía de apremio
5	Judicial voluntaria
6	Notarial en venta extrajudicial
7	Notarial voluntaria
8	Judicial concursal
9	Recaudación tributaria
10	Subasta administrativa
11	Notarial hipotecaria
12	Notarial otras
13	Administrativa general

Orden

Valor	Ordena por
fecha_celebracion_asc	Fecha de conclusión de la subasta, la más próxima primero.
fecha_celebracion_desc	Fecha de conclusión de la subasta, la más lejana primero.
fecha_insercion_asc	Fecha de publicación en AlertaSubastas, la más antigua primero.
fecha_insercion_desc	Fecha de publicación en AlertaSubastas, la más reciente primero.
fecha_actualizacion_asc / _desc	Fecha del último cambio de estado, ascendente / descendente; desempate estable por id.
valoracion_asc / _desc	Valor de subasta, ascendente / descendente.
puja_asc / _desc	Puja actual, ascendente / descendente.
deposito_asc / _desc	Depósito requerido, ascendente / descendente.

Sincronización de cambios

Para mantener al día una copia de los bienes que ya tienes, sin volver a descargarlo todo:

1. Apunta la hora actual antes de buscar.
2. Busca con filtros.fecha_actualizacion.desde = la hora apuntada en la ejecución anterior menos 15 minutos y orden: "fecha_actualizacion_asc". El margen cubre los cambios que tardan unos minutos en llegar al buscador; los IDs repetidos entre ejecuciones se descartan por id.
3. Si hay más de 100 resultados, no pidas page: 2: si un bien cambia mientras paginas, pasa al final del orden y otro podría quedarse sin salir. Repite la búsqueda con desde = el FECHA_ACTUALIZACION del último resultado recibido (inclusivo) y descarta los IDs ya vistos, hasta que una búsqueda devuelva menos de 100. Solo si los 100 resultados comparten exactamente la misma FECHA_ACTUALIZACION (la repetición devolvería los mismos), pide page: 2, 3 … de esa búsqueda hasta que la fecha cambie.
4. Descarga el detalle de los IDs devueltos: los que ya tenías no consumen cuota.
5. Guarda la hora apuntada en el paso 1 para la próxima ejecución.

Si al pedir un ID de tu copia recibes 404, el bien ya no se publica: dalo de baja (el 404 no consume cuota).

FECHA_ACTUALIZACION avanza cuando cambia el estado de la subasta o de su lote, en el momento en que el cambio llega a nuestro índice; con el margen del paso 2 no se pierden cambios entre ejecuciones. No avanza por correcciones de texto ni por cambios de importe o de fecha sin cambio de estado: una prórroga sin suspensión no la mueve, y de las pujas solo se detecta la primera.

curl -s https://alertasubastas.com/api/v1/bienes/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "atico terraza",
    "filtros": {
      "provincia": "barcelona",
      "tipo_bien": "vivienda",
      "estado": "activas",
      "valoracion": { "min": 50000, "max": 300000 }
    },
    "orden": "fecha_celebracion_asc",
    "page": 1
  }'

{
  "total": 1543,
  "page": 1,
  "per_page": 100,
  "ids": ["0x33E17A2F...", "0x91B2C4D8..."],
  "consultadas": ["0x91B2C4D8..."],
  "cuota_busquedas": { "usadas": 12, "cuota": 500 }
}

consultadas: los ids de la página cuya ficha ya has consultado; volver a pedirlos no gasta cuota.

GET Detalle de un bien

/api/v1/bienes/{id}

{id} es un valor del array ids de la búsqueda (formato 0x + hex). Devuelve un objeto JSON plano con todos los datos del bien, su lote y su subasta.

La respuesta se agrupa por entidad: ID en la raíz y los objetos bien, lote y subasta. En la raíz van también url (la ficha en alertasubastas.com) y resumen, una frase lista para citar con el título, el origen, el estado y la fecha, el valor, la puja (y su % sobre el valor; en lotes de varios bienes, la puja del lote), los m² y si es un lote compuesto. similares lista hasta 9 subastas parecidas (id, finalizada, distancia_km), las mismas que la ficha web, y valor_mercado la estimación de Idealista por la referencia catastral (venta y alquiler_mes con precio, min y max, fecha, fuente), o null si no la hay. En zonas con poca actividad inmobiliaria Idealista no valora el inmueble: entonces valor_mercado trae el precio medio de la zona por la superficie, con aproximado: true y min y max a null.

Valores ausentes y estados

• Ausente = null, siempre. Todas las claves del set de su tipo de bien están presentes en cada respuesta; un dato que la fuente no informó llega como null (nunca "", "NULL", "No consta" ni centinelas como -1). Los objetos de estado (CARGAS, PUJA, SITUACION_POSESORIA, VISITABLE) son la excepción: nunca son null, expresan la ausencia con su estado (desconocido / desconocida). El resto de campos-objeto (GEO, CLASE_SUBASTA, PROCEDIMIENTO) sí puede ser null.
• Campos por tipo de bien. Los campos exclusivos de inmuebles (RESTO_NUMERO, GEO, REF_CATASTRAL, IDUFIR, REF_REGISTRAL, INSCRIPCION, TITULO_JURIDICO, VIVIENDA_HABITUAL, SITUACION_POSESORIA) solo aparecen en tipos de inmueble; los de vehículo (MARCA, MODELO, BASTIDOR, MATRICULA, FECHA_MATRICULACION, FECHA_ADQUISICION) solo en vehiculo, buques y aeronaves. Fuera de su tipo, la clave no está presente. La dirección (CALLE / NUMERO / CP), VISITABLE y las cargas se sirven en todos los tipos.
• Textos en minúsculas. DESCRIPCION, INFO_ADICIONAL, CARGAS_DESC, TITULO_JURIDICO, MARCA, MODELO y los detalle de los objetos se sirven en minúsculas (mismo criterio que la ficha web). Los identificadores (MATRICULA, BASTIDOR, referencias) conservan su formato; REF_CATASTRAL va siempre en mayúsculas.
• Fechas. Las fechas con hora van en ISO 8601 con la zona horaria de Madrid (2026-09-14T18:00:00+02:00); las fechas sin hora (FECHA_PUBLICACION, fechas de vehículo), como YYYY-MM-DD.
• Los campos con semántica de varios estados (CARGAS, SITUACION_POSESORIA, VISITABLE y la PUJA de bien y lote) son objetos con un campo estado cerrado — no hace falta parsear texto.
• TRAMOS, TASACION y PRECIO_MINIMO: null = desconocido; > 0 = importe. El valor 0 es ambiguo en las subastas del BOE (puede significar "no hay" o que la fuente publicó "no consta"); trátalo como no concluyente. En los lotes de subastas BOE con varios bienes, el dato puede existir a nivel de subasta: si lote.TRAMOS es null, consulta subasta.TRAMOS.
• Búsqueda vs. detalle: los filtros de la búsqueda operan sobre los valores tal como están indexados (sin esta normalización); un filtro valoracion.min = 0 puede devolver bienes cuyo detalle muestre VALOR: null.

Objeto bien

Campo	Descripción
TITULO	Título del bien.
DESCRIPCION	Descripción publicada por la fuente.
INFO_ADICIONAL	Información adicional de la fuente.
TIPO_BIEN	Tipo de bien (slug).
CALLE / NUMERO / CP	Dirección (en muebles, la ubicación del depósito si consta).
RESTO_NUMERO	Piso, puerta, escalera… (solo inmuebles).
PROVINCIA / MUNICIPIO	Nombre de la provincia y del municipio.
GEO	Geolocalización: objeto { lat, lng, nivel }; nivel indica la precisión — portal (número de calle exacto), calle, municipio (centroide) o null (desconocida). GEO es null si no hay coordenadas (solo inmuebles).
VALOR	Valor de subasta del bien (importe de referencia de salida). null si la fuente no lo informó.
PUJA	Objeto { "estado", "importe" }, ver tabla de estados abajo.
DEPOSITO	Depósito requerido para participar (0 = sin depósito).
ESTADO	Estado consolidado del bien: objeto { codigo, slug, nombre } (tabla abajo).
FECHA_ACTUALIZACION	Fecha y hora del último cambio de estado de la subasta o de su lote; sin cambios, la de publicación. Ver sincronización de cambios.
CARGAS	Objeto { "estado", "importe" }, ver tabla de estados abajo.
CARGAS_DESC	Descripción textual de las cargas publicada por la fuente (null si no hay).
TITULO_JURIDICO / INSCRIPCION	Título jurídico e inscripción registral.
REF_CATASTRAL / IDUFIR / REF_REGISTRAL	Referencias catastral y registrales.
VIVIENDA_HABITUAL	true / false / null (no consta).
SITUACION_POSESORIA	Objeto { "estado", "detalle" }, ver tabla de estados abajo.
VISITABLE	Objeto { "visitable": true|false|null, "detalle" } (detalle: horarios o instrucciones de visita en texto libre).
MARCA, MODELO, BASTIDOR, MATRICULA, FECHA_MATRICULACION, FECHA_ADQUISICION	Datos de vehículo (solo vehiculo, buques y aeronaves).

Estados de bien.CARGAS

estado	importe	Significado
importe	número	Importe de las cargas comunicado por la fuente.
sin_cargas_declaradas	0	La fuente (Hacienda / Seguridad Social) declara que el bien no tiene cargas. Se recomienda verificarlo en la nota simple registral antes de pujar.
ver_descripcion	null	La fuente no da importe; el detalle textual está en CARGAS_DESC.
desconocido	null	Sin información de cargas.

Estados de bien.SITUACION_POSESORIA

detalle: texto libre adicional de la fuente, o null.

estado	Significado
sin_ocupantes	Sin ocupantes.
ocupantes_con_derecho	Ocupantes con derecho de permanencia.
ocupantes_sin_derecho	Ocupantes sin derecho de permanencia.
ocupante_desconocido	Hay ocupante, sin identificar su título.
desconocido	No consta. Si la fuente publicó un texto no clasificable, llega íntegro en detalle.

Estados de PUJA

Mismo objeto en bien y lote.

estado	importe	Significado
importe	número	Puja más alta del bien/lote.
importe_no_publicado	null	La fuente confirma que hay pujas (estados 3 y 7) pero no publica el importe.
secreta	null	Subasta de puja secreta (estados 0 y 9): las pujas no son públicas.
sin_pujas	null	Sin pujas (estados 2 y 6).
desconocida	null	Sin información de puja. Incluye las subastas canceladas (4) y suspendidas (5).

Los mismos valores sirven en el filtro pujas de la búsqueda, que filtra por la PUJA del bien.

Objeto lote

Campo	Descripción
ID	ID del lote.
NUMERO	Número de lote dentro de la subasta.
TOTAL_BIENES	Bienes que contiene el lote.
URL	URL del lote en la fuente oficial.
TASACION	Valor de tasación del lote (ver la nota sobre el 0 en valores ausentes y estados).
TRAMOS	Tramo entre pujas (incremento mínimo) del lote. null = desconocido; puede estar a nivel de subasta.
RECLAMADA	Cantidad reclamada (la deuda que origina la subasta) a nivel de lote.
PRECIO_MINIMO	Precio mínimo de adjudicación del lote. null = desconocido.
PUJA	Objeto { "estado", "importe" }, misma tabla de estados que bien.PUJA.
ESTADO	Estado del lote: objeto { codigo, slug, nombre } (tabla abajo), o null si la fuente no lo informa.
ESTADO_FECHA	Fecha del último cambio de estado del lote.
BIENES	IDs de todos los bienes del lote, incluido este (se adjudican juntos). Mismas exclusiones que la búsqueda.
DESCRIPCION / INFO_ADICIONAL	Textos del lote.

Objeto subasta

Campo	Descripción
ID	ID interno de la subasta.
IDSUBASTA	ID oficial de la subasta (ej. BOE SUB-XX-…).
IDSUBASTA2	Segundo identificador (expediente judicial/SS; en otras fuentes, nombre del organismo).
URL	URL oficial de la subasta en la fuente.
ID_ANUNCIO	Referencia del anuncio en el BOE.
TOTAL_LOTES	Número de lotes de la subasta.
CLASE_SUBASTA	Origen de la subasta: objeto { codigo, slug, nombre } (códigos 2–13, tabla en la búsqueda).
PROCEDIMIENTO	Procedimiento: objeto { codigo, slug, nombre } (códigos 1–13, tabla en la búsqueda).
TASACION / TRAMOS / RECLAMADA	Tasación, tramo entre pujas y cantidad reclamada a nivel de subasta.
PUJA	Importe de puja comunicado por la fuente en la última actualización de estado (null si no lo ha comunicado).
FECHA_PUBLICACION	Fecha de publicación en AlertaSubastas. Útil para sincronización incremental.
FECHA_FIN_CELEB	Fecha de conclusión/celebración de la subasta. null en las subastas en próxima apertura (estado 50), que aún no la tienen fijada.
ESTADO_FECHA	Fecha de la última actualización de estado desde la fuente oficial.
REANUDACION	Fecha de reanudación, si la subasta estuvo suspendida y se retomó.

Estados (ESTADO)

bien.ESTADO y lote.ESTADO son objetos { "codigo", "slug", "nombre" }. El slug de bien.ESTADO se puede pasar tal cual al filtro estado de la búsqueda. El filtro trabaja sobre el estado del bien: el de su lote puede ser distinto y no sirve para filtrar.

codigo	slug	nombre
0	finalizada_secreta	Finalizada puja secreta
1	finalizada	Finalizada
2	finalizada_sin_pujas	Finalizada sin pujas
3	finalizada_con_pujas	Finalizada con pujas
4	cancelada	Cancelada
5	suspendida	Suspendida
6	activa_sin_pujas	Activa sin pujas
7	activa_con_pujas	Activa con pujas
8	activa	Activa
9	activa_secreta	Activa puja secreta
50	proxima_apertura	Próxima apertura

Consumo: la primera descarga de un bien gasta 1 de la cuota mensual; repetir un bien ya descargado (este mes o cualquier mes anterior) es gratis. Errores propios: 400 invalid_request (id malformado), 404 not_found (bien inexistente u oculto; no consume cuota).

curl -s https://alertasubastas.com/api/v1/bienes/0x33E17A2F... \
  -H "Authorization: Bearer $API_KEY"

{
  "ID": "0x33E17A2F...",
  "bien": {
    "TITULO": "Vivienda en Sabadell",
    "TIPO_BIEN": "vivienda",
    "PROVINCIA": "Barcelona", "MUNICIPIO": "Sabadell",
    "CALLE": "Carrer Major", "NUMERO": "12",
    "RESTO_NUMERO": "2º 1ª", "CP": "08201",
    "GEO": { "lat": 41.54, "lng": 2.10,
             "nivel": "portal" },
    "VALOR": 185000, "DEPOSITO": 9250,
    "ESTADO": { "codigo": 7, "slug": "activa_con_pujas",
                "nombre": "Activa con pujas" },
    "FECHA_ACTUALIZACION": "2026-07-03T09:12:40+02:00",
    "PUJA": { "estado": "importe",
              "importe": 92500 },
    "REF_CATASTRAL": "1234567AB1234C0001DE",
    "CARGAS": { "estado": "ver_descripcion",
                "importe": null },
    "CARGAS_DESC": "hipoteca a favor de ...",
    "VIVIENDA_HABITUAL": false,
    "SITUACION_POSESORIA": {
      "estado": "sin_ocupantes", "detalle": null },
    "VISITABLE": { "visitable": null, "detalle": null },
    "...": "..."
  },
  "lote": {
    "ID": "0x44F2...", "NUMERO": 1,
    "TOTAL_BIENES": 1, "BIENES": ["0x33E17A2F..."],
    "TASACION": 185000,
    "ESTADO": { "codigo": 7, "slug": "activa_con_pujas",
                "nombre": "Activa con pujas" },
    "PUJA": { "estado": "importe",
              "importe": 92500 },
    "...": "..."
  },
  "subasta": {
    "ID": "0x55A9...", "IDSUBASTA": "SUB-JA-2026-1234",
    "URL": "https://subastas.boe.es/...",
    "TOTAL_LOTES": 1,
    "FECHA_PUBLICACION": "2026-07-01",
    "FECHA_FIN_CELEB": "2026-09-10T18:00:00+02:00",
    "...": "..."
  }
}

GET Bienes de un lote

/api/v1/lotes/{id}

IDs de los bienes de un lote: se adjudican juntos. {id} es lote.ID del detalle de un bien. Devuelve también la subasta a la que pertenece.

No consume cuota (sí rate limit, en su propio grupo de 60 req/min junto con /subastas). Solo da IDs: los datos de cada bien están en su detalle.

Mismas exclusiones que la búsqueda: no aparecen bienes ocultos, ni los de próxima apertura sin un plan que la incluya. Lote inexistente o sin bienes visibles → 404 not_found; id malformado → 400 invalid_request.

{
  "ID": "0x44F2...",
  "SUBASTA_ID": "0x55A9...",
  "BIENES": ["0x33E17A2F...", "0x91B2C4D8..."]
}

GET Lotes de una subasta

/api/v1/subastas/{id}

IDs de los lotes de una subasta, en el orden de la subasta. {id} es subasta.ID del detalle de un bien (o SUBASTA_ID de un lote). Para los bienes de cada lote, usa GET /lotes/{id}.

No consume cuota (sí rate limit, mismo grupo que /lotes). Solo aparecen los lotes con algún bien visible. Subasta inexistente o sin bienes visibles → 404 not_found.

{
  "ID": "0x55A9...",
  "LOTES": ["0x44F2...", "0x7C10..."]
}

GET Buscar por código

/api/v1/codigo?q=

Busca bienes por un identificador: referencia catastral, IDUFIR / CRU, referencia registral, id de subasta del BOE (SUB-…), id de la Seguridad Social o la AEAT, anuncio del BOE, bastidor o matrícula. Espacios, guiones y barras dan igual; q necesita al menos 5 letras o cifras. Devuelve hasta 10 ids (los más recientes) y en qué campo coincide cada uno. No consume cuota (rate limit de búsquedas).

{
  "q": "SUB-JA-2025-123456",
  "total": 1,
  "ids": [ "0x33E17A2F..." ],
  "resultados": [ { "id": "0x33E17A2F...", "campo": "ID BOE", "valor": "SUB-JA-2025-123456", "finalizada": false } ]
}

GET Provincias

/api/v1/provincias

Lista de provincias con su slug y el nombre exacto tal como está indexado. Cualquiera de los dos vale para el filtro provincia de la búsqueda. No consume cuota.

curl -s https://alertasubastas.com/api/v1/provincias \
  -H "Authorization: Bearer $API_KEY"

{
  "provincias": [
    { "slug": "a-coruna",  "nombre": "A Coruña" },
    { "slug": "alava",     "nombre": "Álava" },
    { "slug": "barcelona", "nombre": "Barcelona" },
    { "...": "..." }
  ]
}

GET Municipios de una provincia

/api/v1/provincias/{slug}/municipios

Municipios con subastas de la provincia indicada (por slug o nombre) y sus comarcas. Los municipios son los nombres exactos que acepta el filtro municipio; el slug de cada comarca es el valor del filtro comarca. Provincia desconocida → 404 not_found. No consume cuota.

curl -s https://alertasubastas.com/api/v1/provincias/barcelona/municipios \
  -H "Authorization: Bearer $API_KEY"

{
  "provincia": { "slug": "barcelona", "nombre": "Barcelona" },
  "municipios": [
    "Badalona",
    "Barcelona",
    "Sabadell",
    "Terrassa",
    "..."
  ],
  "comarcas": [
    { "slug": "maresme-barcelona", "nombre": "Maresme" },
    { "...": "..." }
  ]
}

GET Opciones de filtros

/api/v1/opciones

Valores admitidos por los filtros tipo_bien (slug + nombre legible, y sus grupos en tipo_bien_grupos), clase_subasta, procedimiento y estado (código + slug + nombre), los valores de pujas, vivienda_habitual y bienes_lote, los tramos de superficie por tipo de bien, la lista de marcas (slug + nombre), los tramos sugeridos de reclamada y los valores de orden con su explicación. Es la fuente viva de las tablas de esta documentación. No consume cuota.

curl -s https://alertasubastas.com/api/v1/opciones \
  -H "Authorization: Bearer $API_KEY"

{
  "tipo_bien": [
    { "slug": "vivienda", "nombre": "Vivienda" },
    { "slug": "garaje",   "nombre": "Garaje" },
    { "...": "..." }
  ],
  "tipo_bien_grupos": [
    { "slug": "inmuebles", "nombre": "Todos los inmuebles" },
    { "...": "..." }
  ],
  "clase_subasta": [
    { "codigo": 2, "slug": "boe-judiciales",
      "nombre": "BOE Judiciales" },
    { "...": "..." }
  ],
  "procedimiento": [
    { "codigo": 4, "slug": "judicial-en-via-de-apremio",
      "nombre": "Judicial en via de apremio" },
    { "...": "..." }
  ],
  "estado": [
    { "codigo": 5, "slug": "suspendida",
      "nombre": "Suspendida" },
    { "...": "..." }
  ],
  "pujas": [ "importe", "importe_no_publicado", "secreta",
             "sin_pujas", "desconocida", "con_pujas" ],
  "orden": [
    { "valor": "fecha_celebracion_asc",
      "descripcion": "Fecha de conclusión de la subasta, la más próxima primero" },
    { "...": "..." }
  ]
}

GET Explicar un concepto

/api/v1/ayuda?q=

Los 3 artículos de la ayuda de AlertaSubastas que mejor explican un concepto o una duda (depósito, cargas, cesión de remate, posesión, pujas, alertas…), con su texto y su URL. Acepta la pregunta en lenguaje natural (q, de 2 a 200 caracteres). No exige plan ni consume cuota (rate limit de lecturas de alertas y favoritas).

{
  "q": "¿puedo ceder el remate?",
  "articulos": [ { "id": 221, "titulo": "¿Qué es la cesión de remate?", "url": "https://alertasubastas.com/ayuda/subastas-publicas/…",
                   "texto": "La cesión de remate en el marco de una subasta pública consiste en…", "recurso": "alertasubastas://ayuda/221" } ],
  "nota": "Artículos de la ayuda de AlertaSubastas, del más al menos relacionado con la pregunta; cada uno con su url."
}

GET Consumo

/api/v1/usage

Estado de cuotas del mes en curso. No consume cuota (sí cuenta para el rate limit).

Buenas prácticas para clientes automatizados

• Cachea los detalles descargados: re-pedir un bien ya consumido es gratis, pero gasta rate limit.
• Para sincronización incremental, filtra por fecha_actualizacion.desde con la hora de tu última ejecución: trae los bienes nuevos y los que han cambiado de estado (ver sincronización de cambios).
• Pagina dentro de la ventana de 60 minutos para no consumir búsquedas extra.
• Respeta Retry-After en los 429 y los headers X-Quota-* para autorregularte.

{
  "plan": "API_TEST",
  "periodo": "2026-07",
  "busquedas": { "usadas": 240, "cuota": 500 },
  "bienes": { "usados": 87, "cuota": 100 },
  "finalizadas": { "usadas": 12, "cuota": 500 },
  "rate_limit": { "por_minuto": 60 },
  "suscripcion": { "activa": true, "fin": "2026-12-01 00:00:00" }
}

GET Cuenta

/api/v1/cuenta

Plan de la cuenta (Personal, Profesional o Empresa), cupos del mes usados y disponibles (búsquedas, subastas consultadas, alertas que se pueden crear y favoritas que se pueden guardar), rate limits y enlaces útiles. No exige plan API ni consume cuota (rate limit de lecturas de alertas y favoritas).

{
  "plan": { "web": "PERSONAL_ANUAL_15_48", "prueba": false, "api": null, "activo": true },
  "periodo": "2026-10",
  "busquedas": { "usadas": 12, "cuota": 100 },
  "subastas_consultadas": { "usadas": 30, "cuota": 100 },
  "subastas_finalizadas_consultadas": { "usadas": 12, "cuota": 500 },
  "alertas": { "usadas": 8, "limite": 20, "altas_mes": { "usadas": 2, "limite": 50 }, "nacionales": false, "grupos_tipo_bien": false },
  "favoritas": { "altas_mes": { "usadas": 4, "limite": 10 }, "renovacion": "2026-11-01" },
  "rate_limit": { "bienes_por_minuto": 60, "lecturas_gestion": { "por_minuto": 20, "por_hora": 300 }, "escrituras_gestion": { "por_minuto": 10, "por_hora": 60 } },
  "urls": { "precios": "https://alertasubastas.com/precios", "cuenta": "https://alertasubastas.com/admin/tu-cuenta", "docs": "https://alertasubastas.com/api/docs" }
}

GET Planes

/api/v1/planes

Planes que se pueden contratar, con su precio y sus límites, y los enlaces de registro (prueba gratuita) y de precios. No exige plan ni consume cuota (rate limit de lecturas de alertas y favoritas).

{
  "planes": [ { "id": "INICIA_ANUAL_5_2799", "nombre": "Inicia", "periodo": "anual", "precio": 27.99, "precio_mes": 2.33,
                "limites": { "alertas": 5, "alertas_nacionales": false, "subastas_activas": true, "proxima_apertura": true, "ficha_completa": true,
                             "altas_alertas_mes": 10, "altas_favoritas_mes": 5, "mcp_busquedas_mes": 50, "mcp_subastas_consultadas_mes": 50, "mcp_subastas_finalizadas_mes": 500 } } ],
  "prueba": "Prueba gratuita al registrarse: ficha completa, subastas activas y alertas.",
  "registro": "https://alertasubastas.com/alta-usuario?utm_source=mcp",
  "precios": "https://alertasubastas.com/precios?utm_source=mcp"
}

Alertas

/api/v1/alertas

Gestiona las alertas de tu cuenta. Las coincidencias te llegan por email, como siempre: el API solo las da de alta, las lista, las pausa y las borra.

• Acceso: vale el plan Personal, Profesional, Empresa o un plan API, con los límites de tu plan (si tienes los dos, el mayor). No consume búsquedas ni bienes.
• Rate limit propio: lecturas 20/min y 300/hora; escrituras 10/min y 60/hora.
• Una alerta de otro cliente responde 404 not_found, igual que si no existiera.

Método	Ruta	Qué hace
GET	/alertas	Tus alertas, con limite, usadas y altas_mes.
GET	/alertas/{id}	Una alerta.
POST	/alertas	Crea una alerta: filtros, titulo y envio opcionales. Responde 201.
POST	/alertas/previsualizar	Sin crearla: {"filtros": {…}} → activas (subastas activas que coinciden ahora) y muestra (hasta 5 ids, las más recientes). Mismas validaciones y reglas de plan que crear.
DELETE	/alertas/{id}	Borra la alerta (204).
POST	/alertas/{id}/pausar	Deja de enviar avisos.
POST	/alertas/{id}/reactivar	Vuelve a enviarlos (revalida los límites del plan).
PUT	/alertas/{id}/titulo	{"titulo": "…"}; vacío o null lo borra.

No se pueden editar los filtros: borra la alerta y crea otra.

Filtros de una alerta

Mismos nombres y valores que en la búsqueda:

Filtro	Valor
provincia	Slug o nombre. Sin provincia, la alerta es nacional.
comarca	Slug de comarca de la provincia (comarcas de municipios). Excluyente con municipio.
municipio	Nombre exacto de municipios.
tipo_bien	Obligatorio. Slug de opciones, o un grupo: inmuebles, muebles, todos.
clase_subasta	Un código. Sin él, todas.
procedimiento	Solo con las clases que lo admiten.
valoracion, deposito, reclamada	{min, max}, enteros, min <= max.
vivienda_habitual	si, no o desconocido.
marca	Slug de opciones (marcas). Solo con tipo_bien vehiculo.
superficie	{min, max} en m², enteros 1..999999, min incluido y max excluido. Solo con inmuebles (un tipo de inmueble, inmuebles o todos).
bienes_lote	uno o varios.
texto_incluye, texto_excluye	Hasta 255 caracteres.

Los filtros que solo existen en la búsqueda (estado, pujas, fechas, q) devuelven 400 invalid_request. envio: agrupado (por defecto), individual (no en alertas nacionales) o sin_email.

Límites del plan

HTTP	error	Cuándo
403	plan_requerido	Sin plan ni prueba activos, o tu plan no incluye alertas.
403	limite_alertas	Ya tienes el máximo de alertas del plan (las pausadas cuentan).
403	limite_altas_mes	Has creado por API las alertas del mes de tu plan (Personal 20, Profesional y Empresa 100). Borrar no devuelve el hueco.
403	alerta_avanzada	Alerta nacional o grupo de tipo de bien sin un plan que lo incluya.
409	duplicate	Ya tienes una alerta con los mismos filtros (devuelve su id).

curl -s -X POST https://alertasubastas.com/api/v1/alertas \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filtros": {"provincia": "madrid",
       "tipo_bien": "vivienda",
       "valoracion": {"max": 200000}},
       "titulo": "Pisos Madrid"}'

{
  "id": "0x8F9650B2C6EA11F18C80C8034E108F72",
  "titulo": "Pisos Madrid",
  "filtros": { "provincia": "madrid",
               "tipo_bien": "vivienda",
               "valoracion": { "min": null, "max": 200000 } },
  "nacional": false,
  "activa": true,
  "envio": "agrupado",
  "creada": "2026-10-14 12:30:00"
}

Favoritas

/api/v1/favoritas

Método	Ruta	Qué hace
GET	/favoritas	Lista paginada: limit (1..100, por defecto 50), offset, estado (seguimiento) y subasta (activas, proximas, finalizadas) opcionales. Cada favorita trae titulo (completo si la subasta ha finalizado o ya consultaste su ficha; si no, tipo, municipio, m² y fin), subasta (grupo, estado y fin) y consultada. No consume cuota.
POST	/favoritas	{"bien": "0x…" o URL, "comentario": "…"}. 201 si es nueva, 200 si ya lo era.
DELETE	/favoritas/{id_bien}	Quita la favorita (204).
PUT	/favoritas/{id_bien}/comentario	{"comentario": "…"}; vacío lo borra. Máx. 2048 caracteres.
PUT	/favoritas/{id_bien}/estado	nueva, en_revision, interesante, preparando_puja, pujando, adjudicada, finalizada o descartada.

La lista da el id del bien y los datos de la favorita. El detalle del bien se pide con GET /bienes/{id} (consume cuota de bienes solo la primera vez).

Límite mensual de altas por API, según plan: 403 limite_favoritas con limite, usadas y renovacion. Quitar una favorita no devuelve el hueco; volver a añadir en el mismo mes un bien ya contado no cuenta otra vez. POST /favoritas devuelve los headers X-Favoritas-Limit y X-Favoritas-Remaining.

{
  "total": 1, "limit": 50, "offset": 0,
  "favoritas": [
    { "bien": "0x33E17A2F...",
      "url": "https://alertasubastas.com/bien/0x33E17A2F...",
      "comentario": "visitar",
      "estado": "interesante",
      "creada": "2026-10-14 12:31:00" }
  ]
}

POST Sugerencias

/api/v1/sugerencias

Envía al equipo de AlertaSubastas una mejora, un aviso de error o un dato que echas en falta; nos llega por email. Body: tipo (mejora, error o falta_dato), texto (de 3 a 2000 caracteres) y contexto opcional (hasta 500: qué estabas haciendo).

Vale cualquier key, también de solo lectura, y no consume cuota. Máximo 3 por hora y 10 al día (429 con Retry-After).

{ "ok": true, "id": 42, "message": "Gracias: la hemos recibido y la leeremos." }

Servidor MCP

https://alertasubastas.com/mcp

Conecta AlertaSubastas a Claude, ChatGPT y otros asistentes de IA. El servidor MCP ofrece las mismas funciones que este API: cada tool es un endpoint, con los mismos parámetros y la misma respuesta.

• Transporte: Streamable HTTP, sin sesión.
• Con tu cuenta (OAuth 2.1), con plan Personal, Profesional o Empresa: pega la dirección en el asistente. Se abre el login de AlertaSubastas, aceptas los permisos (solo lectura, o lectura y escritura) y el asistente recibe un token: no hace falta copiar ninguna key. Funciona con claude.ai, ChatGPT, Claude Code, Codex y los clientes MCP con OAuth que se registran con CIMD o con registro dinámico (DCR). Metadatos en /.well-known/oauth-protected-resource/mcp y /.well-known/oauth-authorization-server. Las aplicaciones conectadas se ven y se revocan en Tu cuenta.
• Con una key: la misma del API (/admin/api), en el header Authorization: Bearer ….
• Límites: los del API. Con key o con la cuenta conectada, cada tool exige el mismo plan que su endpoint y cuenta en los mismos contadores (búsquedas, bienes, alertas, favoritas y rate limit): usar el API y el MCP a la vez no da más cupo.
• initialize, tools/list y ping tienen un límite propio de 30/min.
• Los errores del API llegan como resultado de la tool con isError: true y el mismo {"error", "message"}. Los headers de cuota del API van en el campo _limites del resultado.

Recursos (se leen sin gastar cuota): alertasubastas://conceptos (glosario de subastas públicas; cada entrada en alertasubastas://ayuda/{id}), alertasubastas://filtros y alertasubastas://provincias. Prompts: crea-alerta y compara-subastas. Las tools llevan anotaciones (readOnlyHint, destructiveHint …) y outputSchema. Ficha del servidor: /.well-known/mcp/server-card.json; contrato OpenAPI 3.1: /api/openapi.json.

Tool	Endpoint
buscar_bienes	POST /bienes/search
ver_bien	GET /bienes/{id}
buscar_por_codigo	GET /codigo?q=
ver_subasta	GET /subastas/{id}
ver_lote	GET /lotes/{id}
listar_provincias	GET /provincias
listar_municipios	GET /provincias/{slug}/municipios
opciones_filtros	GET /opciones
consumo	GET /usage
mi_cuenta	GET /cuenta
explicar_concepto	GET /ayuda?q=
listar_alertas	GET /alertas
ver_alerta	GET /alertas/{id}
alertas_previsualizar	POST /alertas/previsualizar
crear_alerta	POST /alertas
borrar_alerta	DELETE /alertas/{id}
pausar_alerta	POST /alertas/{id}/pausar
reactivar_alerta	POST /alertas/{id}/reactivar
renombrar_alerta	PUT /alertas/{id}/titulo
listar_favoritas	GET /favoritas
anadir_favorita	POST /favoritas
quitar_favorita	DELETE /favoritas/{id_bien}
comentar_favorita	PUT /favoritas/{id_bien}/comentario
estado_favorita	PUT /favoritas/{id_bien}/estado
enviar_sugerencia	POST /sugerencias

claude mcp add --transport http alertasubastas   https://alertasubastas.com/mcp
# después, en Claude Code: /mcp → alertasubastas → Authenticate

claude mcp add --transport http alertasubastas   https://alertasubastas.com/mcp   --header "Authorization: Bearer $API_KEY"

Otros clientes con una key (mcp.json)

{
  "mcpServers": {
    "alertasubastas": {
      "type": "http",
      "url": "https://alertasubastas.com/mcp",
      "headers": { "Authorization": "Bearer asapi_..." }
    }
  }
}