{"openapi":"3.1.0","info":{"title":"API Radar de Subvenciones — Son Tus Impuestos","version":"1.0.0","description":"API pública para la fiscalización, auditoría y descarga masiva de las concesiones y beneficiarios de la Base de Datos Nacional de Subvenciones (BDNS) de España.","contact":{"name":"Son Tus Impuestos — Auditoría Ciudadana","url":"https://sontusimpuestos.com/radardesubvenciones"},"license":{"name":"Reutilización de Información del Sector Público (Ley 37/2007)","url":"https://www.boe.es/buscar/act.php?id=BOE-A-2007-20063"}},"servers":[{"url":"/api/v1/subvenciones","description":"Servidor principal API Subvenciones v1"}],"paths":{"/beneficiarios":{"get":{"summary":"Listar y filtrar beneficiarios auditados","description":"Devuelve un listado paginado de beneficiarios con métricas agregadas de riesgo, concesiones directas y porcentaje de minimis.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Búsqueda por razón social o nombre"},{"name":"nivelAlerta","in":"query","required":false,"schema":{"type":"string","enum":["ALERTA_ROJA","ALERTA_NARANJA","ALERTA_AMARILLA","NORMAL","TODOS"]},"description":"Nivel de alerta del beneficiario"},{"name":"tipoEntidad","in":"query","required":false,"schema":{"type":"string","enum":["EMPRESAS","PARTIDOS_POLITICOS","PARTICULARES","TODAS"]},"description":"Tipo de entidad jurídica o física"},{"name":"soloDirectas","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filtrar entidades con al menos una concesión directa (a dedo)"},{"name":"cercaMinimis","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filtrar entidades que superan o rozan el 80% del tope minimis"},{"name":"minImporte","in":"query","required":false,"schema":{"type":"number"},"description":"Importe mínimo acumulado en euros"},{"name":"maxImporte","in":"query","required":false,"schema":{"type":"number"},"description":"Importe máximo acumulado en euros"},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["total_importe","concesiones_directas","total_concesiones","porcentaje_minimis","ultima_concesion"],"default":"total_importe"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Listado de beneficiarios obtenido con éxito","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Beneficiario"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/beneficiarios/{id}":{"get":{"summary":"Obtener ficha completa de un beneficiario","description":"Consulta el resumen consolidado y el histórico de concesiones otorgadas.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identificador de persona del beneficiario (id_persona)"}],"responses":{"200":{"description":"Ficha del beneficiario y sus concesiones","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"beneficiario":{"$ref":"#/components/schemas/Beneficiario"},"concesiones":{"type":"array","items":{"$ref":"#/components/schemas/Concesion"}}}}}}}}},"404":{"description":"Beneficiario no encontrado"}}}},"/concesiones":{"get":{"summary":"Listar concesiones individuales de la BDNS","description":"Consulta granular de las 72.000+ concesiones registradas.","parameters":[{"name":"beneficiarioIdPersona","in":"query","required":false,"schema":{"type":"integer"},"description":"Filtrar por id_persona del beneficiario"},{"name":"tipoConvocatoria","in":"query","required":false,"schema":{"type":"string"},"description":"CONCESION_DIRECTA o CONCURRENCIA"},{"name":"esMinimis","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"organo","in":"query","required":false,"schema":{"type":"string"},"description":"Filtrar por órgano concedente (ministerio, CCAA)"},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"minImporte","in":"query","required":false,"schema":{"type":"number"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Listado de concesiones obtenido con éxito","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Concesion"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/concesiones/{id}":{"get":{"summary":"Obtener detalle de una concesión","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID o id_concesion de la BDNS"}],"responses":{"200":{"description":"Concesión encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Concesion"}}}}}},"404":{"description":"Concesión no encontrada"}}}},"/kpis":{"get":{"summary":"KPIs e indicadores globales del Radar de Subvenciones","responses":{"200":{"description":"Métricas globales obtenidas con éxito","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"totalBeneficiarios":{"type":"integer"},"totalImporteAuditado":{"type":"number"},"alertasRojas":{"type":"integer"},"alertasNaranjas":{"type":"integer"},"alertasAmarillas":{"type":"integer"},"cercaLimiteMinimis":{"type":"integer"},"concesionesDirectasImporte":{"type":"number"},"concesionesDirectasConteo":{"type":"integer"}}}}}}}}}}},"/descargas":{"get":{"summary":"Descarga masiva en streaming (CSV, JSON, NDJSON)","parameters":[{"name":"tipo","in":"query","required":false,"schema":{"type":"string","enum":["beneficiarios","concesiones"],"default":"beneficiarios"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","json","ndjson"],"default":"csv"}},{"name":"alerta","in":"query","required":false,"schema":{"type":"string"}},{"name":"soloDirectas","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Descarga de dataset en streaming","content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"string","format":"binary"}},"application/x-ndjson":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"schemas":{"Beneficiario":{"type":"object","properties":{"id_persona":{"type":"integer"},"nombre":{"type":"string"},"tipo":{"type":"string"},"total_importe":{"type":"number"},"total_concesiones":{"type":"integer"},"total_minimis":{"type":"number"},"porcentaje_minimis":{"type":"number"},"concesiones_directas":{"type":"integer"},"importe_directas":{"type":"number"},"max_concesion_directa":{"type":"number"},"administraciones_distintas":{"type":"integer"},"nivel_alerta":{"type":"string"},"tramo_riesgo":{"type":"string"},"es_partido_politico":{"type":"boolean"},"ultima_concesion":{"type":"string","format":"date"},"public_url":{"type":"string"}}},"Concesion":{"type":"object","properties":{"id":{"type":"integer"},"id_concesion":{"type":"integer"},"cod_concesion":{"type":"string"},"fecha_concesion":{"type":"string","format":"date"},"fecha_alta":{"type":"string","nullable":true},"beneficiario_id_persona":{"type":"integer"},"beneficiario_nombre":{"type":"string"},"beneficiario_tipo":{"type":"string"},"importe":{"type":"number"},"ayuda_equivalente":{"type":"number","nullable":true},"instrumento":{"type":"string","nullable":true},"organo_nivel1":{"type":"string","nullable":true},"organo_nivel2":{"type":"string","nullable":true},"convocatoria_titulo":{"type":"string","nullable":true},"numero_convocatoria":{"type":"string","nullable":true},"tipo_convocatoria":{"type":"string","nullable":true},"es_minimis":{"type":"boolean"},"url_bases_reguladoras":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}