{"openapi":"3.0.0","info":{"title":"NormativaAPI","version":"1.0.0","description":"API de normativa fiscal y legal española con verificación anti-alucinación, búsqueda semántica y series temporales de hechos fiscales. Datos reutilizados bajo RISP; la versión oficial prevalece."},"servers":[{"url":"https://www.normativaapi.es/api","description":"Production"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Norm":{"type":"object","properties":{"boe_id":{"type":"string"},"titulo":{"type":"string","nullable":true},"norma_corta":{"type":"string","nullable":true},"rango":{"type":"string","nullable":true},"fecha_disposicion":{"type":"string","nullable":true},"vigencia_desde":{"type":"string","nullable":true},"estado":{"type":"string","nullable":true},"estatus_derogacion":{"type":"string","nullable":true},"estado_consolidacion":{"type":"string","nullable":true},"boe_fecha_actualizacion":{"type":"string","nullable":true},"ultima_revision_boe":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true}},"required":["boe_id","titulo","norma_corta","rango","fecha_disposicion","vigencia_desde","estado","estatus_derogacion","estado_consolidacion","boe_fecha_actualizacion","ultima_revision_boe","url","created_at"]},"NormList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Norm"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"NormVersionBlock":{"type":"object","properties":{"id":{"type":"string"},"bloque_id":{"type":"string"},"bloque_titulo":{"type":"string","nullable":true},"version_idx":{"type":"number","nullable":true},"id_norma_modificadora":{"type":"string","nullable":true},"fecha_vigencia":{"type":"string"},"valid_to":{"type":"string","nullable":true},"texto_html":{"type":"string","nullable":true}},"required":["id","bloque_id","bloque_titulo","version_idx","id_norma_modificadora","fecha_vigencia","valid_to","texto_html"]},"NormVersions":{"type":"object","properties":{"norm":{"type":"object","properties":{"boe_id":{"type":"string","example":"BOE-A-1992-28740"},"titulo":{"type":"string","nullable":true},"norma_corta":{"type":"string","nullable":true},"rango":{"type":"string","nullable":true},"fecha_disposicion":{"type":"string","nullable":true},"vigencia_desde":{"type":"string","nullable":true},"estado":{"type":"string","nullable":true},"ultima_revision_boe":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["boe_id","titulo","norma_corta","rango","fecha_disposicion","vigencia_desde","estado","ultima_revision_boe","url"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/NormVersionBlock"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["norm","data","pagination"]},"FiscalFact":{"type":"object","properties":{"id":{"type":"string","nullable":true},"fact_domain":{"type":"string"},"fact_key":{"type":"string"},"valor":{"nullable":true},"boe_id":{"type":"string","nullable":true},"norm_version_id":{"type":"string","nullable":true},"bloque_id":{"type":"string","nullable":true},"version_idx":{"type":"number","nullable":true},"articulo":{"type":"string","nullable":true},"valid_from":{"type":"string","nullable":true},"valid_to":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"vigente":{"type":"boolean","nullable":true}},"required":["fact_domain","fact_key","boe_id","valid_from","valid_to"]},"FiscalFactList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FiscalFact"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"FactHistoryEntry":{"allOf":[{"$ref":"#/components/schemas/FiscalFact"},{"type":"object","properties":{"id_norma_modificadora":{"type":"string","nullable":true}}}]},"FactHistory":{"type":"object","properties":{"fact_domain":{"type":"string"},"fact_key":{"type":"string"},"history":{"type":"array","items":{"$ref":"#/components/schemas/FactHistoryEntry"}}},"required":["fact_domain","fact_key","history"]},"Region":{"type":"object","properties":{"code":{"type":"string","description":"Two-letter CCAA code.","example":"MD"},"name":{"type":"string","description":"Region name in Spanish.","example":"Comunidad de Madrid"}},"required":["code","name"]},"RegionList":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}},"required":["regions"]},"SearchDiagnostics":{"type":"object","properties":{"best_similarity":{"type":"number","nullable":true,"description":"Best cosine similarity found ignoring the threshold; null if nothing matched at all."},"reason":{"type":"string","enum":["below_threshold","no_documents_for_source","unknown"]},"hint":{"type":"string"}},"required":["best_similarity","reason"],"description":"Present only when `count` is 0: explains why (too-strict threshold, over-narrow source, or a garbled/mis-encoded query)."},"SearchHit":{"type":"object","properties":{"id":{"type":"string"},"document_id":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"chunk_index":{"type":"number","nullable":true},"content":{"type":"string","nullable":true},"section_path":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"metadata":{"nullable":true},"similarity":{"type":"number"}},"required":["id","document_id","source","external_id","title","source_url","chunk_index","content","section_path","source_anchor","similarity"]},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"number","description":"Number of hits returned (length of `data`)."},"applied":{"type":"object","properties":{"source":{"type":"string","nullable":true},"top_k":{"type":"number"},"threshold":{"type":"number"}},"required":["source","top_k","threshold"],"description":"The filters actually applied (defaults filled in), so an empty result is interpretable."},"diagnostics":{"$ref":"#/components/schemas/SearchDiagnostics"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}}},"required":["query","count","applied","data"]},"DocumentChunk":{"type":"object","properties":{"id":{"type":"string"},"document_id":{"type":"string"},"chunk_index":{"type":"number","nullable":true},"content":{"type":"string","nullable":true},"content_tokens":{"type":"number","nullable":true},"section_path":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"metadata":{"nullable":true}},"required":["id","document_id","chunk_index","content","content_tokens","section_path","source_anchor"]},"Document":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"source_url":{"type":"string","nullable":true},"doc_type":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true},"content_hash":{"type":"string","nullable":true},"last_ingested_at":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/DocumentChunk"}}},"required":["id","source","external_id","title","source_url","doc_type","published_at","content_hash","last_ingested_at","created_at"]},"Change":{"type":"object","properties":{"id":{"type":"string"},"boe_id":{"type":"string","nullable":true},"tipo":{"type":"string","nullable":true},"detalle":{"nullable":true},"detected_at":{"type":"string","nullable":true},"acknowledged":{"type":"boolean","nullable":true}},"required":["id","boe_id","tipo","detected_at","acknowledged"]},"ChangeList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Change"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"VerifyResponse":{"type":"object","properties":{"claim":{"type":"string"},"claim_matches":{"type":"boolean"},"vigente":{"type":"boolean","nullable":true},"valor_correcto":{"nullable":true},"boe_id":{"type":"string","nullable":true},"valid_from":{"type":"string","nullable":true},"fuente":{"type":"object","properties":{"sourceName":{"type":"string"},"sourceUrl":{"type":"string"},"boeId":{"type":"string","nullable":true}},"required":["sourceName","sourceUrl"]},"note":{"type":"string"}},"required":["claim","claim_matches","vigente","boe_id","valid_from","fuente"]},"VerifyRequest":{"type":"object","properties":{"claim":{"type":"string","minLength":1,"description":"The factual claim to verify, in natural language.","example":"El IVA general en España es del 21%"},"domain":{"type":"string","description":"Fiscal fact domain.","example":"iva"},"key":{"type":"string","description":"Fiscal fact key.","example":"tipo_general"},"on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"As-of date (YYYY-MM-DD). Default: today."}},"required":["claim"]},"Consulta":{"type":"object","properties":{"id":{"type":"number","nullable":true},"petete_doc_id":{"type":"number","nullable":true},"numero":{"type":"string"},"tab":{"type":"number","nullable":true},"tipo":{"type":"string"},"fecha":{"type":"string","nullable":true},"organo":{"type":"string","nullable":true},"normativa":{"type":"string","nullable":true},"normas_citadas":{"type":"array","items":{"type":"string"}},"codes_iae":{"type":"array","items":{"type":"string"}},"hechos":{"type":"string","nullable":true},"cuestion":{"type":"string","nullable":true},"contestacion":{"type":"string"},"document_id":{"type":"string","nullable":true},"content_hash":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["numero","tipo","fecha","organo","normativa","hechos","cuestion","contestacion"]},"ConsultaList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Consulta"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"ModulosActividad":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"iae_code":{"type":"string"},"slug":{"type":"string"},"nombre":{"type":"string","nullable":true},"categoria":{"type":"string","nullable":true},"special_correction_type":{"type":"string","nullable":true},"cuota_trimestral_iva_pct":{"type":"number","nullable":true},"cuota_minima_iva_pct":{"type":"number","nullable":true},"magnitudes":{"nullable":true},"excess_threshold_eur":{"type":"number","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","ejercicio","iae_code","slug","nombre","categoria","special_correction_type","cuota_trimestral_iva_pct","cuota_minima_iva_pct","excess_threshold_eur","source_anchor"]},"ModulosList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ModulosActividad"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"ModulosIrpf":{"type":"object","properties":{"modulo_num":{"type":"number"},"definicion":{"type":"string","nullable":true},"unidad":{"type":"string","nullable":true},"rendimiento_anual_unidad":{"type":"number","nullable":true},"nota":{"type":"string","nullable":true}},"required":["modulo_num","definicion","unidad","rendimiento_anual_unidad","nota"]},"ModulosIva":{"type":"object","properties":{"modulo_num":{"type":"number"},"definicion":{"type":"string","nullable":true},"unidad":{"type":"string","nullable":true},"cuota_devengada_unidad":{"type":"number","nullable":true},"nota":{"type":"string","nullable":true}},"required":["modulo_num","definicion","unidad","cuota_devengada_unidad","nota"]},"ModulosDetail":{"type":"object","properties":{"ejercicio":{"type":"number"},"orden":{"type":"object","properties":{"ejercicio":{"type":"number"},"boe_id":{"type":"string","nullable":true},"titulo":{"type":"string","nullable":true},"fecha_orden":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["ejercicio","boe_id","titulo","fecha_orden","published_at","source_anchor"]},"actividad":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"iae_code":{"type":"string"},"slug":{"type":"string"},"nombre":{"type":"string","nullable":true},"categoria":{"type":"string","nullable":true},"special_correction_type":{"type":"string","nullable":true},"cuota_trimestral_iva_pct":{"type":"number","nullable":true},"cuota_minima_iva_pct":{"type":"number","nullable":true},"excess_threshold_eur":{"type":"number","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","ejercicio","iae_code","slug","nombre","categoria","special_correction_type","cuota_trimestral_iva_pct","cuota_minima_iva_pct","excess_threshold_eur","source_anchor"]},"modulos_irpf":{"type":"array","items":{"$ref":"#/components/schemas/ModulosIrpf"}},"modulos_iva":{"type":"array","items":{"$ref":"#/components/schemas/ModulosIva"}},"magnitudes":{"nullable":true},"umbrales_generales":{"nullable":true},"indices_correctores":{"nullable":true}},"required":["ejercicio","orden","actividad","modulos_irpf","modulos_iva"]},"Modelo":{"type":"object","properties":{"numero":{"type":"string"},"nombre":{"type":"string"},"impuesto":{"type":"string","nullable":true},"periodicidad":{"type":"string","nullable":true},"naturaleza":{"type":"string","nullable":true},"orden_aprobacion":{"type":"string","nullable":true},"sede_url":{"type":"string","nullable":true},"descripcion":{"type":"string","nullable":true}},"required":["numero","nombre","impuesto","periodicidad","naturaleza","orden_aprobacion","sede_url","descripcion"]},"ModeloList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Modelo"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"Plazo":{"type":"object","properties":{"id":{"type":"number"},"modelo":{"type":"string"},"periodo":{"type":"string"},"ejercicio":{"type":"number"},"fecha_limite":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"feed_label":{"type":"string","nullable":true},"titulo":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","modelo","periodo","ejercicio","fecha_limite","feed_label","titulo","source_anchor"]},"ModeloDetail":{"allOf":[{"$ref":"#/components/schemas/Modelo"},{"type":"object","properties":{"plazos":{"type":"array","items":{"$ref":"#/components/schemas/Plazo"}}},"required":["plazos"]}]},"Casilla":{"type":"object","properties":{"id":{"type":"number"},"modelo":{"type":"string"},"casilla":{"type":"string"},"ejercicio":{"type":"number"},"etiqueta":{"type":"string"},"apartado":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","modelo","casilla","ejercicio","etiqueta","apartado","source_anchor"]},"ModeloCasillas":{"allOf":[{"$ref":"#/components/schemas/Modelo"},{"type":"object","properties":{"casillas":{"type":"array","items":{"$ref":"#/components/schemas/Casilla"}}},"required":["casillas"]}]},"PlazosList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Plazo"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"Resolucion":{"type":"object","properties":{"id":{"type":"number","nullable":true},"teac_doc_id":{"type":"string","nullable":true},"numero":{"type":"string"},"numero_slug":{"type":"string"},"criterio_num":{"type":"number","nullable":true},"calificacion":{"type":"string","nullable":true},"es_unif_criterio":{"type":"boolean"},"fecha":{"type":"string","nullable":true},"organo":{"type":"string","nullable":true},"asunto":{"type":"string","nullable":true},"conceptos":{"type":"array","items":{"type":"string"}},"normas_citadas":{"type":"array","items":{"type":"string"}},"criterio":{"type":"string","nullable":true},"texto":{"type":"string","nullable":true},"document_id":{"type":"string","nullable":true},"content_hash":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["numero","numero_slug"]},"ResolucionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Resolucion"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"EmpresaActo":{"type":"object","properties":{"id":{"type":"number"},"borme_external_id":{"type":"string","nullable":true},"registro_num":{"type":"string","nullable":true},"company_hoja":{"type":"string","nullable":true},"denominacion":{"type":"string","nullable":true},"provincia":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true},"acto_types":{"type":"array","items":{"type":"string"}},"capital_eur":{"type":"number","nullable":true},"objeto_social":{"type":"string","nullable":true},"cnae_codes":{"type":"array","items":{"type":"string"}},"domicilio":{"type":"string","nullable":true},"socio_unico":{"type":"string","nullable":true},"cargos":{"nullable":true},"datos_registrales":{"nullable":true},"raw_text":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"content_hash":{"type":"string","nullable":true}},"required":["id","borme_external_id","registro_num","company_hoja","denominacion","provincia","published_at","acto_types","capital_eur","objeto_social","cnae_codes","domicilio","socio_unico","raw_text","source_anchor","content_hash"]},"EmpresaList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmpresaActo"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"ResolucionDetail":{"type":"object","properties":{"numero":{"type":"string"},"numero_slug":{"type":"string"},"criterios":{"type":"array","items":{"$ref":"#/components/schemas/Resolucion"}}},"required":["numero","numero_slug","criterios"]},"Empresa":{"type":"object","properties":{"hoja":{"type":"string"},"denominacion":{"type":"string","nullable":true},"provincia":{"type":"string","nullable":true},"first_seen":{"type":"string","nullable":true},"last_seen":{"type":"string","nullable":true},"actos":{"type":"array","items":{"$ref":"#/components/schemas/EmpresaActo"}}},"required":["hoja","denominacion","provincia","first_seen","last_seen","actos"]},"EmpresaStats":{"type":"object","properties":{"group_by":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"group":{"type":"string","nullable":true},"count":{"type":"number"}},"required":["group","count"]}}},"required":["group_by","data"]},"CotizacionBase":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"regimen":{"type":"string","nullable":true},"grupo":{"type":"number","nullable":true},"categoria":{"type":"string","nullable":true},"periodicidad":{"type":"string","nullable":true},"base_minima":{"type":"number","nullable":true},"base_maxima":{"type":"number","nullable":true},"nota":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","ejercicio","regimen","grupo","categoria","periodicidad","base_minima","base_maxima","nota","source_anchor"]},"CotizacionTipo":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"regimen":{"type":"string","nullable":true},"concepto":{"type":"string","nullable":true},"tipo_total":{"type":"number","nullable":true},"tipo_empresa":{"type":"number","nullable":true},"tipo_trabajador":{"type":"number","nullable":true},"base_aplicacion":{"type":"string","nullable":true},"nota":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","ejercicio","regimen","concepto","tipo_total","tipo_empresa","tipo_trabajador","base_aplicacion","nota","source_anchor"]},"CotizacionDetail":{"type":"object","properties":{"ejercicio":{"type":"number"},"orden":{"type":"object","properties":{"ejercicio":{"type":"number"},"boe_id":{"type":"string","nullable":true},"orden":{"type":"string","nullable":true},"titulo":{"type":"string","nullable":true},"fecha_orden":{"type":"string","nullable":true},"vigencia_desde":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["ejercicio","boe_id","orden","titulo","fecha_orden","vigencia_desde","source_anchor"]},"bases":{"type":"array","items":{"$ref":"#/components/schemas/CotizacionBase"}},"tipos":{"type":"array","items":{"$ref":"#/components/schemas/CotizacionTipo"}},"parametros":{"nullable":true}},"required":["ejercicio","orden","bases","tipos"]},"Bonificacion":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"codigo":{"type":"string"},"nombre":{"type":"string","nullable":true},"colectivo":{"type":"string","nullable":true},"tipo_bonificacion":{"type":"string","nullable":true},"importe":{"type":"number","nullable":true},"duracion_meses":{"type":"number","nullable":true},"requisitos":{"type":"string","nullable":true},"normativa":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"verification_status":{"type":"string","nullable":true},"verification_confidence":{"type":"number","nullable":true},"verification_note":{"type":"string","nullable":true},"verified_at":{"type":"string","nullable":true}},"required":["id","ejercicio","codigo","nombre","colectivo","tipo_bonificacion","importe","duracion_meses","requisitos","normativa","source_anchor"]},"BonificacionesList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bonificacion"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"TarifaAtEp":{"type":"object","properties":{"id":{"type":"number"},"ejercicio":{"type":"number"},"cnae_code":{"type":"string"},"descripcion":{"type":"string","nullable":true},"tipo_it":{"type":"number","nullable":true},"tipo_ims":{"type":"number","nullable":true},"tipo_total":{"type":"number","nullable":true},"nota":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"verification_status":{"type":"string","nullable":true},"verification_confidence":{"type":"number","nullable":true},"verification_note":{"type":"string","nullable":true},"verified_at":{"type":"string","nullable":true}},"required":["id","ejercicio","cnae_code","descripcion","tipo_it","tipo_ims","tipo_total","nota","source_anchor"]},"TarifaAtEpList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TarifaAtEp"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"IsdList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"region_code":{"type":"string"},"ejercicio":{"type":"number"},"max_bonificacion":{"type":"number","nullable":true},"tiene_99":{"type":"boolean"}},"required":["region_code","ejercicio","max_bonificacion","tiene_99"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"IsdDetail":{"type":"object","properties":{"region_code":{"type":"string"},"ejercicio":{"type":"number"},"normativa":{"type":"object","properties":{"region_code":{"type":"string"},"ejercicio":{"type":"number"},"ley_autonomica":{"type":"string","nullable":true},"vigencia_desde":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true},"nota":{"type":"string","nullable":true}},"required":["region_code","ejercicio","ley_autonomica","vigencia_desde","source_anchor","nota"]},"tarifa":{"type":"array","nullable":true,"items":{"type":"object","properties":{"base_hasta":{"type":"number","nullable":true},"cuota_integra":{"type":"number","nullable":true},"resto_base_hasta":{"type":"number","nullable":true},"tipo_porcentaje":{"type":"number","nullable":true}},"required":["base_hasta","cuota_integra","resto_base_hasta","tipo_porcentaje"]}},"coeficientes":{"type":"array","nullable":true,"items":{"type":"object","properties":{"grupo":{"type":"string","nullable":true},"patrimonio_desde":{"type":"number","nullable":true},"patrimonio_hasta":{"type":"number","nullable":true},"coeficiente":{"type":"number","nullable":true}},"required":["grupo","patrimonio_desde","patrimonio_hasta","coeficiente"]}},"reducciones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"region_code":{"type":"string"},"ejercicio":{"type":"number"},"modalidad":{"type":"string"},"codigo":{"type":"string"},"nombre":{"type":"string"},"grupo":{"type":"string","nullable":true},"tipo":{"type":"string"},"importe":{"type":"number","nullable":true},"porcentaje":{"type":"number","nullable":true},"limite":{"type":"number","nullable":true},"requisitos":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","region_code","ejercicio","modalidad","codigo","nombre","grupo","tipo","importe","porcentaje","limite","requisitos","source_anchor"]}},"bonificaciones":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"region_code":{"type":"string"},"ejercicio":{"type":"number"},"modalidad":{"type":"string"},"codigo":{"type":"string"},"nombre":{"type":"string"},"grupo":{"type":"string","nullable":true},"porcentaje":{"type":"number","nullable":true},"limite":{"type":"number","nullable":true},"requisitos":{"type":"string","nullable":true},"source_anchor":{"type":"string","nullable":true}},"required":["id","region_code","ejercicio","modalidad","codigo","nombre","grupo","porcentaje","limite","requisitos","source_anchor"]}}},"required":["region_code","ejercicio","normativa","tarifa","coeficientes","reducciones","bonificaciones"]},"Subvencion":{"type":"object","properties":{"codigo_bdns":{"type":"string"},"titulo":{"type":"string","nullable":true},"finalidad":{"type":"string","nullable":true},"organo":{"type":"string","nullable":true},"nivel1":{"type":"string","nullable":true},"importe":{"type":"number","nullable":true},"fecha_recepcion":{"type":"string","nullable":true},"fecha_apertura":{"type":"string","nullable":true},"fecha_cierre":{"type":"string","nullable":true},"abierto":{"type":"boolean","nullable":true},"estado":{"type":"string","nullable":true},"tipo_convocatoria":{"type":"string","nullable":true},"sectores":{"nullable":true},"cnae_secciones":{"type":"array","nullable":true,"items":{"type":"string"}},"tipos_beneficiarios":{"type":"array","nullable":true,"items":{"type":"string"}},"instrumentos":{"type":"array","nullable":true,"items":{"type":"string"}},"regiones":{"type":"array","nullable":true,"items":{"type":"string"}},"es_para_empresas":{"type":"boolean","nullable":true},"url_bases":{"type":"string","nullable":true},"url_oficial":{"type":"string","nullable":true},"content_hash":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["codigo_bdns","titulo","finalidad","organo","nivel1","importe","fecha_recepcion","fecha_apertura","fecha_cierre","abierto","estado","tipo_convocatoria","cnae_secciones","tipos_beneficiarios","instrumentos","regiones","es_para_empresas","url_bases","url_oficial","content_hash","created_at","updated_at"]},"SubvencionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subvencion"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"Indicador":{"type":"object","properties":{"serie":{"type":"string","example":"D_1T9L0008"},"serie_nombre":{"type":"string"},"fecha":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"valor":{"type":"number"},"unidad":{"type":"string"},"fetched_at":{"type":"string","nullable":true}},"required":["serie","serie_nombre","fecha","valor","unidad","fetched_at"]},"IndicadorList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Indicador"}},"count":{"type":"number"}},"required":["data","count"]},"DeudorLookup":{"type":"object","properties":{"nif":{"type":"string"},"aparece":{"type":"boolean"},"importe_eur":{"type":"number"},"edicion":{"type":"string"},"fecha_publicacion":{"type":"string"},"fuente":{"type":"string","enum":["AEAT art. 95 bis LGT"]},"nota":{"type":"string"}},"required":["nif","aparece","edicion","fecha_publicacion","fuente","nota"]}},"parameters":{}},"paths":{"/v1/norms":{"get":{"summary":"List norms","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of norms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/norms/{boe_id}":{"get":{"summary":"Get a norm by BOE id","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"BOE-A-2006-20764"},"required":true,"name":"boe_id","in":"path"}],"responses":{"200":{"description":"The norm.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Norm"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Norm not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/norms/{boe_id}/versions":{"get":{"summary":"Get consolidated law-text version blocks for a norm","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"BOE-A-1992-28740"},"required":true,"name":"boe_id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Point-in-time: blocks in force on this date (default: current in force)."},"required":false,"name":"on","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Return ALL version blocks (in-force + superseded) instead of only in-force. Overrides on."},"required":false,"name":"all","in":"query"}],"responses":{"200":{"description":"Version blocks (default: current in force).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormVersions"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Norm not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fiscal-facts":{"get":{"summary":"List fiscal facts","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by domain."},"required":false,"name":"domain","in":"query"}],"responses":{"200":{"description":"Paginated list of fiscal facts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalFactList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fiscal-facts/{domain}/{key}":{"get":{"summary":"Point-in-time fiscal fact","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"domain","in":"path"},{"schema":{"type":"string"},"required":true,"name":"key","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"As-of date (default today)."},"required":false,"name":"on","in":"query"},{"schema":{"type":"string","description":"CCAA region code (e.g. MD, CT, AN). See /v1/regions for valid values."},"required":false,"name":"region","in":"query"}],"responses":{"200":{"description":"The fact as of the given date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalFact"}}}},"400":{"description":"Invalid date or region code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No fact for that domain/key/date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fiscal-facts/{domain}/{key}/history":{"get":{"summary":"Full fiscal-fact timeline","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"domain","in":"path"},{"schema":{"type":"string"},"required":true,"name":"key","in":"path"},{"schema":{"type":"string","description":"CCAA region code (e.g. MD, CT, AN). See /v1/regions for valid values."},"required":false,"name":"region","in":"query"}],"responses":{"200":{"description":"Full temporal series for the fact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactHistory"}}}},"400":{"description":"Invalid region code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/regions":{"get":{"summary":"List CCAA region codes","description":"Discovery endpoint — returns the 15 valid CCAA (Comunidades Autónomas) region codes and names that can be passed as `?region=` to fiscal-fact endpoints for autonomic-tax data.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of all valid CCAA region codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"get":{"summary":"Semantic search","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"The query text."},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter results by source corpus. Valid values: boe, aeat, dgt, modulos, teac.","example":"teac"},"required":false,"name":"source","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"top_k","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"maximum":1},"required":false,"name":"threshold","in":"query"}],"responses":{"200":{"description":"Ranked semantic matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"Missing query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{id}":{"get":{"summary":"Get a document","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Document UUID."},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Include the document chunks."},"required":false,"name":"include_chunks","in":"query"}],"responses":{"200":{"description":"The document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Document not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/changes":{"get":{"summary":"Recent change feed","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Most-recent-first change feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verify":{"post":{"summary":"Anti-hallucination fact-check","description":"Deterministic lookup + numeric compare against the canonical fiscal fact. No LLM. Returns the authoritative value and whether the claim matches.","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Missing domain/key or invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No fact for that domain/key/date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/consultas":{"get":{"summary":"List DGT consultas","description":"Paginated list of DGT (Dirección General de Tributos) binding and non-binding tax opinions. Filter by tipo, IAE code, or year.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by tipo (vinculante | general).","example":"vinculante"},"required":false,"name":"tipo","in":"query"},{"schema":{"type":"string","description":"Filter by IAE epígrafe code.","example":"685"},"required":false,"name":"iae","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Filter by year of the consulta.","example":2020},"required":false,"name":"year","in":"query"}],"responses":{"200":{"description":"Paginated list of DGT consultas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultaList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/consultas/{numero}":{"get":{"summary":"Get a DGT consulta by numero","description":"Returns the full text of a DGT tax opinion (hechos, cuestión, contestación) by its reference number.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"V0019-20"},"required":true,"name":"numero","in":"path"}],"responses":{"200":{"description":"The consulta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Consulta"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Consulta not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/modulos":{"get":{"summary":"List módulos actividades","description":"Paginated list of AEAT estimación-objetiva (módulos) activities, keyed by IAE code, for a given ejercicio. Filter by ejercicio or categoría.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2026},"required":false,"name":"ejercicio","in":"query"},{"schema":{"type":"string","description":"Filter by categoría.","example":"comercio"},"required":false,"name":"categoria","in":"query"}],"responses":{"200":{"description":"Paginated list of módulos actividades.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModulosList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/modulos/{iae}":{"get":{"summary":"Get módulos for an IAE activity","description":"Point-in-time denormalized blob for one IAE activity: the Orden provenance, the activity, its IRPF + IVA módulos, exclusion magnitudes, general thresholds, and corrector indices. Activities that share an IAE code (variants) are disambiguated with ?slug=; without it, the base (non-variant) activity is returned.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"419.1"},"required":true,"name":"iae","in":"path"},{"schema":{"type":"string","description":"Disambiguate a variant activity sharing this IAE code."},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"As-of date (YYYY-MM-DD); resolves the ejercicio. Default: today."},"required":false,"name":"on","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (alternative to ?on=).","example":2026},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"The módulos blob for the activity, anchored to the resolved ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModulosDetail"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No módulos activity for that IAE code / ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/modelos":{"get":{"summary":"List modelos","description":"Paginated catalog of AEAT tax forms (modelos). Filter by impuesto or periodicidad.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by impuesto (e.g. IVA, IRPF).","example":"IVA"},"required":false,"name":"impuesto","in":"query"},{"schema":{"type":"string","description":"Filter by periodicidad (e.g. mensual, trimestral).","example":"trimestral"},"required":false,"name":"periodicidad","in":"query"}],"responses":{"200":{"description":"Paginated list of modelos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeloList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/modelos/{numero}":{"get":{"summary":"Get a modelo by número","description":"Returns the full catalog entry for an AEAT tax form, including its structured filing deadlines (plazos). Filter plazos by ?ejercicio= to scope to a specific tax year.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"303"},"required":true,"name":"numero","in":"path"},{"schema":{"type":"integer","nullable":true,"description":"Tax year to filter plazos (default: all years).","example":2025},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"The modelo with its plazos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeloDetail"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Modelo not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/modelos/{numero}/casillas":{"get":{"summary":"Get casillas for a modelo","description":"Returns the visual casillas (numbered form boxes) and their semantic labels for an AEAT tax form. Filter by ?ejercicio= to scope to a specific tax year.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"303"},"required":true,"name":"numero","in":"path"},{"schema":{"type":"integer","nullable":true,"description":"Tax year of the casilla layout (default: all years).","example":2026},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"The modelo with its casillas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeloCasillas"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Modelo not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plazos":{"get":{"summary":"List filing deadlines","description":"Paginated list of AEAT filing deadlines (plazos). Filter by modelo, date range, or ejercicio.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by modelo número.","example":"303"},"required":false,"name":"modelo","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter plazos with fecha_limite >= from (YYYY-MM-DD).","example":"2025-01-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter plazos with fecha_limite <= to (YYYY-MM-DD).","example":"2025-12-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Filter by tax year.","example":2025},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"Paginated list of filing deadlines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlazosList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/resoluciones":{"get":{"summary":"List TEAC resoluciones","description":"Paginated list of TEAC (Tribunal Económico-Administrativo Central) doctrine criterios from the DYCTEA database. Each row is one criterio of one resolution. Filter by concepto, norma citada, year, or unificación de criterio.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by concepto (array-contains on conceptos[]).","example":"IVA"},"required":false,"name":"concepto","in":"query"},{"schema":{"type":"string","description":"Filter by norma citada (array-contains on normas_citadas[]).","example":"BOE-A-1992-28740"},"required":false,"name":"norma","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Filter by year of the resolution fecha.","example":2024},"required":false,"name":"year","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by es_unif_criterio (true = unificación de criterio only)."},"required":false,"name":"unif","in":"query"}],"responses":{"200":{"description":"Paginated list of TEAC resolution criterios.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolucionList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/empresas":{"get":{"summary":"List BORME actos","description":"Paginated list of BORME (Boletín Oficial del Registro Mercantil) actos. Filter by provincia, CNAE code, acto type, company name (denominación), or publication date range.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by provincia (e.g. MADRID).","example":"MADRID"},"required":false,"name":"provincia","in":"query"},{"schema":{"type":"string","description":"Filter by CNAE code (e.g. 6920).","example":"6920"},"required":false,"name":"cnae","in":"query"},{"schema":{"type":"string","description":"Filter by acto type (e.g. constitucion).","example":"constitucion"},"required":false,"name":"acto","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter actos published on or after this date (YYYY-MM-DD).","example":"2024-01-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter actos published on or before this date (YYYY-MM-DD).","example":"2024-12-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","description":"Filter by company name (denominación social). Matches on a normalized-exact match OR a real trigram similarity hit — never returns a non-matching company.","example":"ACME S.L."},"required":false,"name":"denominacion","in":"query"}],"responses":{"200":{"description":"Paginated list of BORME actos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmpresaList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/resoluciones/{numero}":{"get":{"summary":"Get a TEAC resolucion by numero","description":"Returns all criterios of one TEAC resolution by its numero_slug (slashes replaced with dashes, e.g. 00-01267-2025-00-00). Also accepts a raw numero with slashes. Returns 404 when not found.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"00-01267-2025-00-00"},"required":true,"name":"numero","in":"path"}],"responses":{"200":{"description":"The resolution with all its criterios.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolucionDetail"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resolution not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/empresas/{hoja}":{"get":{"summary":"Get a empresa by hoja registral","description":"Returns the full history of BORME actos for one empresa, identified by its hoja registral (e.g. M-853607), including first/last inscription dates and all actos.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"M-853607"},"required":true,"name":"hoja","in":"path"}],"responses":{"200":{"description":"The empresa with its actos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Empresa"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Empresa not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/empresas/stats":{"get":{"summary":"BORME aggregate statistics","description":"Aggregated BORME acto counts grouped by month, provincia, or CNAE code. Accepts the same filters as the list endpoint.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter by acto type.","example":"constitucion"},"required":false,"name":"acto","in":"query"},{"schema":{"type":"string","description":"Filter by CNAE code.","example":"6920"},"required":false,"name":"cnae","in":"query"},{"schema":{"type":"string","description":"Filter by provincia.","example":"MADRID"},"required":false,"name":"provincia","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter published_at >= from (YYYY-MM-DD).","example":"2024-01-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter published_at <= to (YYYY-MM-DD).","example":"2024-12-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["month","provincia","cnae"],"description":"Dimension to group by (default: month).","example":"month"},"required":false,"name":"group_by","in":"query"}],"responses":{"200":{"description":"Aggregated BORME statistics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmpresaStats"}}}},"400":{"description":"Invalid group_by value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cotizacion":{"get":{"summary":"Get Seguridad Social contribution bases & rates","description":"Régimen General contribution data for an ejercicio: bases de cotización por grupo, tipos de cotización (empresa/trabajador split), convenio especial, topes and the cotización adicional de solidaridad — from the annual Orden de cotización (BOE). Defaults to the latest ejercicio.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2026},"required":false,"name":"ejercicio","in":"query"},{"schema":{"type":"string","description":"Filter bases+tipos by régimen.","example":"general"},"required":false,"name":"regimen","in":"query"}],"responses":{"200":{"description":"The cotización blob for the resolved ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotizacionDetail"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No cotización data for that ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cotizacion/bonificaciones":{"get":{"summary":"List Seguridad Social contribution bonificaciones","description":"Paginated list of bonificaciones a la cotización (Seguridad Social contribution incentives) from RDL 1/2023 and concordant legislation. Filterable by colectivo beneficiario and ejercicio. Defaults to the latest ejercicio. Ordered by código ASC.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2026},"required":false,"name":"ejercicio","in":"query"},{"schema":{"type":"string","description":"Filter by colectivo beneficiario.","example":"jovenes_30"},"required":false,"name":"colectivo","in":"query"}],"responses":{"200":{"description":"Paginated list of bonificaciones a la cotización.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BonificacionesList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cotizacion/tarifa-at-ep":{"get":{"summary":"List AT/EP tarifa de primas","description":"Paginated list of Seguridad Social accidentes de trabajo y enfermedades profesionales (AT/EP) tarifa de primas per CNAE-2025 code, per the Disposición adicional 61ª del TRLGSS. Defaults to the latest ejercicio. Ordered by CNAE code ASC.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2026},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"Paginated list of AT/EP tarifa de primas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TarifaAtEpList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cotizacion/tarifa-at-ep/{cnae}":{"get":{"summary":"Get AT/EP tarifa for a CNAE code","description":"Returns the AT/EP (accidentes de trabajo y enfermedades profesionales) tarifa de primas — tipos IT, IMS, and Total — for a specific CNAE-2025 code, per the Disposición adicional 61ª del TRLGSS. Returns 404 when no matching entry is found for the given CNAE.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"0111"},"required":true,"name":"cnae","in":"path"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2026},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"The AT/EP tarifa for the CNAE code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TarifaAtEp"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No AT/EP tarifa found for that CNAE code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/isd":{"get":{"summary":"List ISD summaries by CCAA","description":"Paginated list of Impuesto sobre Sucesiones y Donaciones (ISD) data, one row per CCAA for the given ejercicio (default: latest available). Includes region code, ejercicio, maximum bonificación percentage, and whether a 99% bonificación applies.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2025},"required":false,"name":"ejercicio","in":"query"}],"responses":{"200":{"description":"Paginated list of ISD CCAA summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsdList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/isd/{region}":{"get":{"summary":"Get ISD data for a CCAA","description":"Returns the full ISD (Impuesto sobre Sucesiones y Donaciones) data for one CCAA, identified by its two-letter region code (e.g. \"MD\" = Comunidad de Madrid, \"CT\" = Cataluña). Includes the normativa autonómica, tarifa, coeficientes multiplicadores, reducciones, and bonificaciones. Filter by ejercicio (default: latest) and modalidad (sucesiones | donaciones | ambos).","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Two-letter CCAA region code. See /v1/regions.","example":"MD"},"required":true,"name":"region","in":"path"},{"schema":{"type":"integer","nullable":true,"description":"Tax year (default: latest available).","example":2025},"required":false,"name":"ejercicio","in":"query"},{"schema":{"type":"string","enum":["sucesiones","donaciones","ambos"],"description":"Filter reducciones/bonificaciones by modalidad.","example":"sucesiones"},"required":false,"name":"modalidad","in":"query"}],"responses":{"200":{"description":"The ISD blob for the region and ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsdDetail"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No ISD data found for that region / ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subvenciones":{"get":{"summary":"List BDNS subvenciones","description":"Paginated list of public subvenciones (grants) from the Base de Datos Nacional de Subvenciones (BDNS / SNPSAP). Filter by CNAE section, region, estado, or limit to convocatorias for empresas.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Max rows to return (1-100).","example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Rows to skip (pagination).","example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by CNAE section code.","example":"4711"},"required":false,"name":"cnae","in":"query"},{"schema":{"type":"string","description":"Filter by region code (e.g. ES-MD).","example":"ES-MD"},"required":false,"name":"region","in":"query"},{"schema":{"type":"string","description":"Filter by estado (e.g. abierta, cerrada).","example":"abierta"},"required":false,"name":"estado","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Limit to convocatorias for empresas (es_para_empresas = true)."},"required":false,"name":"solo_empresas","in":"query"}],"responses":{"200":{"description":"Paginated list of BDNS subvenciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubvencionList"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subvenciones/{id}":{"get":{"summary":"Get a BDNS subvención by codigo_bdns","description":"Returns the full detail of one BDNS subvención (grant) by its codigo_bdns identifier. Returns 404 when not found.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"BDNS codigo_bdns identifier.","example":"722365"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The subvención.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subvencion"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Subvención not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/indicadores":{"get":{"summary":"List Banco de España (BdE) official rates","description":"List of official interest-rate indicators published by the Banco de España: interés legal, interés de demora a efectos tributarios, interés de demora en operaciones comerciales, and euríbor a un año. History back to 1973 (be1901.csv backfill) plus a weekly refresh of the current value (favoritas API). Free tier — no plan required.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter by BdE series code.","example":"D_1T9L0008"},"required":false,"name":"serie","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter fecha >= from (YYYY-MM-DD).","example":"2025-01-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filter fecha <= to (YYYY-MM-DD).","example":"2025-12-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"List of BdE official rate observations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndicadorList"}}}},"400":{"description":"Invalid from/to date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/deudores/{nif}":{"get":{"summary":"Look up a single NIF in the AEAT deudores publication (art. 95 bis LGT)","description":"Point lookup ONLY — there is no list variant of this endpoint, by design (art. 95 bis.4 LGT). Returns whether the given NIF appears in the AEAT \"Listado de deudores a la Hacienda Pública\" (juridical persons only), and the outstanding importe when it does. Requires a paid plan (Profesional or higher). A well-formed but absent NIF returns 200 with `aparece: false` — never a 404 (no key-existence oracle). A malformed NIF returns 400.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"9-character NIF/CIF.","example":"B67455105"},"required":true,"name":"nif","in":"path"}],"responses":{"200":{"description":"Lookup result (aparece true/false).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeudorLookup"}}}},"400":{"description":"Malformed NIF.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Requires a paid plan (Profesional or higher).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}