{"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"]},"IaeTarifa":{"type":"object","properties":{"seccion":{"type":"number","example":1},"codigo":{"type":"string","example":"121.1"},"codigo_integro":{"type":"string","example":"Epígrafe 121.1"},"nivel":{"type":"string","enum":["agrupacion","grupo","epigrafe"]},"titulo":{"type":"string"},"cuota_municipal_eur":{"type":"number","nullable":true},"cuota_provincial_eur":{"type":"number","nullable":true},"cuota_nacional_eur":{"type":"number","nullable":true},"nota":{"type":"string","nullable":true},"boe_id":{"type":"string"},"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":["seccion","codigo","codigo_integro","nivel","titulo","cuota_municipal_eur","cuota_provincial_eur","cuota_nacional_eur","nota","boe_id","source_anchor"]},"IaeTarifaList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IaeTarifa"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["data","pagination"]},"IaeTarifaElemento":{"type":"object","properties":{"id":{"type":"number"},"seccion":{"type":"number"},"codigo":{"type":"string"},"orden":{"type":"number"},"concepto":{"type":"string"},"importe_municipal_eur":{"type":"number","nullable":true},"importe_provincial_eur":{"type":"number","nullable":true},"importe_nacional_eur":{"type":"number","nullable":true}},"required":["id","seccion","codigo","orden","concepto","importe_municipal_eur","importe_provincial_eur","importe_nacional_eur"]},"IaeTarifaDetail":{"allOf":[{"$ref":"#/components/schemas/IaeTarifa"},{"type":"object","properties":{"elementos":{"type":"array","items":{"$ref":"#/components/schemas/IaeTarifaElemento"}}},"required":["elementos"]}]},"IaeTarifaAmbiguo":{"type":"object","properties":{"error":{"type":"string"},"ambiguo":{"type":"boolean","enum":[true]},"codigo":{"type":"string"},"secciones":{"type":"array","items":{"type":"number"},"example":[1,2,3]}},"required":["error","ambiguo","codigo","secciones"]},"IaePasoCalculo":{"type":"object","properties":{"paso":{"type":"number"},"concepto":{"type":"string"},"formula":{"type":"string"},"entradas":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true},{"nullable":true}]}},"resultado":{"type":"number","nullable":true},"articulo":{"type":"string"},"boeId":{"type":"string"},"sourceAnchor":{"type":"string"}},"required":["paso","concepto","formula","entradas","resultado","articulo","boeId","sourceAnchor"]},"IaeCuotaResult":{"type":"object","properties":{"resultado":{"type":"object","properties":{"exento":{"type":"boolean"},"motivoExencion":{"type":"string","nullable":true},"cuotaTarifa":{"type":"number"},"coeficientePonderacion":{"type":"number","nullable":true},"cuotaPonderada":{"type":"number","nullable":true},"cuotaSituacion":{"type":"number","nullable":true},"bonificacion":{"type":"number","nullable":true},"recargoProvincial":{"type":"number","nullable":true},"cuotaTotal":{"type":"number"}},"required":["exento","motivoExencion","cuotaTarifa","coeficientePonderacion","cuotaPonderada","cuotaSituacion","bonificacion","recargoProvincial","cuotaTotal"]},"pasos":{"type":"array","items":{"$ref":"#/components/schemas/IaePasoCalculo"}},"avisos":{"type":"array","items":{"type":"string"}},"version":{"type":"string"}},"required":["resultado","pasos","avisos","version"]},"IaeCuotaInput":{"type":"object","properties":{"tipoCuota":{"type":"string","enum":["municipal","provincial","nacional"],"description":"Ámbito de la cuota (art. 85 TRLRHL)."},"cuotaTarifa":{"type":"number","minimum":0,"description":"Cuota de tarifa (Anexo I), ya resuelta por el cliente. >= 0.","example":29995.6},"incn":{"type":"number","nullable":true,"description":"Importe neto de la cifra de negocios; null = \"sin cifra\".","example":3000000},"esPersonaFisica":{"type":"boolean"},"periodosDesdeInicio":{"type":"integer","minimum":0,"description":"0 o 1 → exención de inicio de actividad (art. 82.1.b) TRLRHL). Entero >= 0.","example":5},"coeficienteSituacion":{"type":"number","minimum":0.4,"maximum":3.8,"description":"Art. 87 TRLRHL, 0,4–3,8. Solo aplicable a cuotas municipales.","example":1.68},"bonificacionPct":{"type":"number","minimum":0,"maximum":100,"description":"Art. 88 TRLRHL, 0–100."},"recargoProvincialPct":{"type":"number","minimum":0,"maximum":40,"description":"Art. 134 TRLRHL, 0–40. Solo aplicable a cuotas municipales."},"ejercicio":{"type":"integer","description":"Ejercicio de los coeficientes de ponderación art. 86 (default: último disponible).","example":2026}},"required":["tipoCuota","cuotaTarifa","incn","esPersonaFisica","periodosDesdeInicio"]},"RetencionPasoCalculo":{"type":"object","properties":{"paso":{"type":"integer"},"concepto":{"type":"string"},"formula":{"type":"string"},"entradas":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true},{"nullable":true}]}},"resultado":{"type":"number","nullable":true},"articulo":{"type":"string"},"boeId":{"type":"string"},"sourceAnchor":{"type":"string"}},"required":["paso","concepto","formula","entradas","resultado","articulo","boeId","sourceAnchor"]},"RetencionCalculoResult":{"type":"object","properties":{"aviso":{"type":"string","description":"Aviso legal obligatorio."},"version":{"type":"string","example":"2026-01"},"ejercicio":{"type":"integer"},"fecha":{"type":"string","nullable":true,"description":"La fecha de anclaje enviada, o null."},"resultado":{"type":"object","properties":{"base":{"type":"number","description":"BASE para calcular el tipo de retención."},"minimoPersonalFamiliar":{"type":"number","description":"MINPERFA."},"cuotaRetencion":{"type":"number","description":"CUOTA — derivada de TABLA 2; el servicio de la AEAT no la devuelve."},"tipoRetencion":{"type":"number","description":"TIPO, en porcentaje."},"importeAnual":{"type":"number","description":"IMPORTE anual de retenciones e ingresos a cuenta."},"exento":{"type":"boolean","description":"TABLA 1 (art. 81.1 RIRPF) excluye al perceptor de la obligación de retener."}},"required":["base","minimoPersonalFamiliar","cuotaRetencion","tipoRetencion","importeAnual"]},"pasos":{"type":"array","items":{"$ref":"#/components/schemas/RetencionPasoCalculo"},"description":"Traza de auditoría completa, un paso por operación del ALGORITMO."},"avisos":{"type":"array","items":{"type":"string"},"description":"Avisos calculados por el motor: divergencias deliberadas respecto de una lectura literal de la norma, regímenes territoriales aplicados, etc. Distintos del `aviso` legal."}},"required":["aviso","version","ejercicio","fecha","resultado","pasos","avisos"]},"RetencionValidacionErrores":{"type":"object","properties":{"error":{"type":"string"},"aviso":{"type":"string"},"errores":{"type":"array","items":{"type":"object","properties":{"codigo":{"type":"integer","description":"Nº de la validación en la sección C del ALGORITMO (1-80); 0 = comprobación propia del motor."},"mensaje":{"type":"string","description":"Mensaje literal del ALGORITMO."},"campo":{"type":"string","description":"Campo de entrada afectado.","example":"nif"}},"required":["codigo","mensaje","campo"]}}},"required":["error","aviso","errores"]},"RetencionDescendiente":{"type":"object","properties":{"anioNac":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"AÑODES — año de nacimiento (> 0; no se admiten filas en blanco).","example":2020},"adopcion":{"type":"integer","description":"AÑOADOP — año de adopción/acogimiento."},"computoPorEntero":{"type":"boolean","description":"PORENTERO."},"discapacidad":{"type":"string","enum":["SIN DISCAPACIDAD","DE33A65","DESDE65"],"description":"DISCADES."},"movilidadReducida":{"type":"boolean","description":"MOVILDES."}},"required":["anioNac"]},"RetencionAscendiente":{"type":"object","properties":{"anioNac":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"AÑOAS — año de nacimiento (> 0; no se admiten filas en blanco).","example":1945},"convivencia":{"type":"integer","description":"CONVIVENCIA — nº de personas con las que convive (1-9).","example":1},"discapacidad":{"type":"string","enum":["SIN DISCAPACIDAD","DE33A65","DESDE65"],"description":"DISCAS."},"movilidadReducida":{"type":"boolean","description":"MOVILAS."}},"required":["anioNac","convivencia"]},"RetencionCalculoInput":{"type":"object","properties":{"fecha":{"type":"string","description":"Fecha (AAAA-MM-DD) que fija la versión del ALGORITMO a aplicar. Ausente = la versión en vigor hoy. Una fecha sin versión registrada devuelve 404, nunca la versión más reciente.","example":"2026-03-01"},"nif":{"type":"string","description":"NIF de persona física del perceptor.","example":"45000019J"},"anioPer":{"type":"integer","description":"AÑOPER — año de nacimiento del perceptor.","example":1985},"situFam":{"type":"integer","description":"SITUFAM — 1, 2 o 3 (0 = no consignada).","example":3},"nifCon":{"type":"string","description":"NIFCON — obligatorio si situFam = 2."},"discapacitado":{"type":"boolean","description":"DISCAPACITADO."},"discaPer":{"type":"string","enum":["SIN DISCAPACIDAD","DE33A65","DESDE65"],"description":"DISCAPER."},"movilPer":{"type":"boolean","description":"MOVILPER."},"resiCeMe":{"type":"boolean","description":"RESICEME — residencia en Ceuta o Melilla."},"situPer":{"type":"string","enum":["","ACTIVO","PENSIONISTA","DESEMPLEADO","OTRA SITUACIÓN"],"description":"SITUPER.","example":"ACTIVO"},"contrato":{"type":"string","enum":["","GENERAL","INFERIORAÑO","ESPECIAL","MANUALES"],"description":"CONTRATO — obligatorio si situPer = ACTIVO.","example":"GENERAL"},"movil":{"type":"boolean","description":"MOVIL — movilidad geográfica."},"descendientes":{"type":"array","items":{"$ref":"#/components/schemas/RetencionDescendiente"},"description":"Máx. 16 filas."},"ascendientes":{"type":"array","items":{"$ref":"#/components/schemas/RetencionAscendiente"},"description":"Máx. 6 filas."},"retrib":{"type":"number","description":"RETRIB — retribuciones totales íntegras.","example":30000},"irregular1":{"type":"number","description":"Reducciones art. 18.2 LIRPF."},"irregular2":{"type":"number","description":"Reducciones art. 18.3 y DD.TT. 11ª/12ª LIRPF."},"cotizaciones":{"type":"number","description":"Gastos deducibles art. 19.2 a)/b)/c)."},"renCeMe":{"type":"boolean","description":"RENCEME."},"conyuge":{"type":"number","description":"Pensión compensatoria al cónyuge."},"anualidades":{"type":"number","description":"Anualidades por alimentos a los hijos."},"presViv":{"type":"boolean","description":"PRESVIV — pagos por préstamos de vivienda (mod. 145)."},"regularizacion":{"type":"boolean","description":"REGULARIZACION."},"percibido":{"type":"number","description":"PERCIBIDO."},"retenido":{"type":"number","description":"RETENIDO."},"retribA":{"type":"number","description":"RETRIBA."},"importeA":{"type":"number","description":"IMPORTEA."},"renCeMeA":{"type":"boolean","description":"RENCEMEA."},"baseA":{"type":"number","description":"BASEA."},"minPerFaA":{"type":"number","description":"MINPERFAA."},"tipoA":{"type":"number","description":"TIPOA."},"minorado":{"type":"boolean","description":"MINORADO."},"minoPagoA":{"type":"number","description":"MINOPAGOA."},"causa1":{"type":"boolean"},"causa2":{"type":"boolean"},"causa3":{"type":"boolean"},"causa4":{"type":"boolean"},"causa5":{"type":"boolean"},"causa6":{"type":"boolean"},"causa7":{"type":"boolean"},"causa8":{"type":"boolean"},"causa9":{"type":"boolean"},"causa10":{"type":"boolean"},"causa11":{"type":"boolean"}},"required":["nif","anioPer","situFam","situPer","descendientes","ascendientes","retrib","regularizacion"]},"RetencionVersion":{"type":"object","properties":{"id":{"type":"string","example":"2026-01"},"ejercicio":{"type":"integer","example":2026},"valid_from":{"type":"string","example":"2026-01-01"},"valid_to":{"type":"string","nullable":true},"spec_url":{"type":"string"},"spec_version":{"type":"string","nullable":true,"example":"ALGORITMO_2026 - sin ILP (26.12.2025)"},"notas":{"type":"string","nullable":true}},"required":["id","ejercicio","valid_from","valid_to","spec_url","spec_version","notas"]},"RetencionVersionList":{"type":"object","properties":{"aviso":{"type":"string","description":"Aviso legal obligatorio; presente en toda respuesta."},"data":{"type":"array","items":{"$ref":"#/components/schemas/RetencionVersion"}},"count":{"type":"integer"}},"required":["aviso","data","count"]},"RetencionEscalaTramo":{"type":"object","properties":{"version_id":{"type":"string"},"orden":{"type":"integer"},"base_desde":{"type":"number"},"cuota_integra":{"type":"number"},"resto_hasta":{"type":"number","nullable":true,"description":"null en el último tramo (\"en adelante\")."},"tipo_pct":{"type":"number"},"verification_status":{"type":"string"}},"required":["version_id","orden","base_desde","cuota_integra","resto_hasta","tipo_pct"]},"RetencionMinimo":{"type":"object","properties":{"version_id":{"type":"string"},"concepto":{"type":"string","example":"descendientes"},"subtipo":{"type":"string","example":"menor_3_anios"},"importe":{"type":"number"},"condiciones":{"nullable":true},"articulo":{"type":"string","nullable":true},"verification_status":{"type":"string"}},"required":["version_id","concepto","subtipo","importe","articulo"]},"RetencionParametro":{"type":"object","properties":{"version_id":{"type":"string"},"clave":{"type":"string","example":"tipo_minimo_art86_2_especial"},"valor":{"nullable":true,"description":"Escalar o tabla (jsonb). Interpretar SIEMPRE junto a `unidad`."},"unidad":{"type":"string","nullable":true,"description":"EUR | porcentaje | coeficiente | …","example":"porcentaje"},"articulo":{"type":"string","nullable":true}},"required":["version_id","clave","unidad","articulo"]},"RetencionParametrosBundle":{"type":"object","properties":{"aviso":{"type":"string"},"nota_citas":{"type":"string","description":"Las citas de artículo de mínimos y parámetros están transcritas de la especificación de la AEAT y no verificadas contra el texto consolidado de la LIRPF/RIRPF."},"version":{"$ref":"#/components/schemas/RetencionVersion"},"escalas":{"type":"array","items":{"$ref":"#/components/schemas/RetencionEscalaTramo"}},"minimos":{"type":"array","items":{"$ref":"#/components/schemas/RetencionMinimo"}},"parametros":{"type":"array","items":{"$ref":"#/components/schemas/RetencionParametro"}}},"required":["aviso","nota_citas","version","escalas","minimos","parametros"]},"RetencionTipoFijo":{"type":"object","properties":{"version_id":{"type":"string"},"supuesto":{"type":"string","example":"profesionales_general"},"tipo_pct":{"type":"number","example":15},"descripcion":{"type":"string"},"articulo":{"type":"string","example":"art. 95.1 RIRPF"},"verification_status":{"type":"string"}},"required":["version_id","supuesto","tipo_pct","descripcion","articulo"]},"RetencionTiposList":{"type":"object","properties":{"aviso":{"type":"string"},"alcance":{"type":"string","description":"Alcance declarado de la lista: subconjunto citado de los supuestos más comunes. NO es un catálogo completo de los tipos fijos del IRPF."},"version":{"type":"string"},"notas_version":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/RetencionTipoFijo"}},"count":{"type":"integer"}},"required":["aviso","alcance","version","notas_version","data","count"]},"CteEstructuraBloque":{"type":"object","properties":{"bloque_id":{"type":"string"},"titulo":{"type":"string","nullable":true}},"required":["bloque_id","titulo"]},"CteEstructuraParte1":{"type":"object","properties":{"boe_id":{"type":"string"},"bloques":{"type":"array","items":{"$ref":"#/components/schemas/CteEstructuraBloque"}}},"required":["boe_id","bloques"],"description":"Present only when ?db is omitted (the full-tree request)."},"CteEstructuraSeccionNode":{"type":"object","properties":{"seccion_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"orden":{"type":"integer"},"nivel":{"type":"integer"},"titulo":{"type":"string"},"tipo":{"type":"string"},"contiene_tablas":{"type":"boolean"},"contiene_figuras":{"type":"boolean"}},"required":["seccion_id","parent_id","orden","nivel","titulo","tipo","contiene_tablas","contiene_figuras"]},"CteEstructuraDocumento":{"type":"object","properties":{"db_codigo":{"type":"string"},"nombre":{"type":"string"},"version_label":{"type":"string"},"fecha_consolidacion":{"type":"string"},"secciones":{"type":"array","items":{"$ref":"#/components/schemas/CteEstructuraSeccionNode"}}},"required":["db_codigo","nombre","version_label","fecha_consolidacion","secciones"]},"CteEstructura":{"type":"object","properties":{"parte1":{"$ref":"#/components/schemas/CteEstructuraParte1"},"documentos":{"type":"array","items":{"$ref":"#/components/schemas/CteEstructuraDocumento"}},"aviso":{"type":"string","description":"Aviso legal obligatorio: texto consolidado no oficial."}},"required":["documentos","aviso"]},"CteError":{"type":"object","properties":{"error":{"type":"string"},"aviso":{"type":"string","description":"Present on every Parte II 404 (Ruling R18); absent on the Parte I not-found fallback."}},"required":["error"]},"CteSeccionListRow":{"type":"object","properties":{"db_codigo":{"type":"string"},"seccion_id":{"type":"string"},"titulo":{"type":"string"},"nivel":{"type":"integer"},"tipo":{"type":"string"},"snippet":{"type":"string","nullable":true,"description":"NULL (never an empty string) for a container node whose contenido_md is NULL."},"contiene_tablas":{"type":"boolean"},"contiene_figuras":{"type":"boolean"},"verification_status":{"type":"string","enum":["unverified","verified","flagged"]},"verification_note":{"type":"string","nullable":true,"description":"'verified' denotes structural checks only (contenido no vacío, procedencia registrada, parent_id válido, sección reclamada por el manifiesto, contiene_tablas coincide) over text no human has reviewed — never a human-verified claim. This note is what states that; always show it alongside verification_status."}},"required":["db_codigo","seccion_id","titulo","nivel","tipo","snippet","contiene_tablas","contiene_figuras","verification_status","verification_note"]},"CteSeccionList":{"type":"object","properties":{"aviso":{"type":"string","description":"Aviso legal obligatorio: texto consolidado no oficial."},"data":{"type":"array","items":{"$ref":"#/components/schemas/CteSeccionListRow"}},"pagination":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"},"count":{"type":"number"}},"required":["limit","offset","count"]}},"required":["aviso","data","pagination"]},"CteDocumentoRef":{"type":"object","nullable":true,"properties":{"db_codigo":{"type":"string","example":"SI"},"nombre":{"type":"string"},"version_label":{"type":"string"},"fecha_consolidacion":{"type":"string"}},"required":["db_codigo","nombre","version_label","fecha_consolidacion"]},"CteHijo":{"type":"object","properties":{"seccion_id":{"type":"string"},"titulo":{"type":"string"},"orden":{"type":"integer"},"nivel":{"type":"integer"}},"required":["seccion_id","titulo","orden","nivel"]},"CteFuente":{"type":"object","properties":{"boe_id":{"type":"string","example":"BOE-A-2019-3384"},"disposicion":{"type":"string"},"rol":{"type":"string"},"fecha_publicacion":{"type":"string","nullable":true},"fecha_aplicacion":{"type":"string","nullable":true},"nota":{"type":"string","nullable":true}},"required":["boe_id","disposicion","rol","fecha_publicacion","fecha_aplicacion","nota"]},"CteSeccion":{"type":"object","properties":{"db_codigo":{"type":"string","example":"SI"},"seccion_id":{"type":"string","example":"SI1"},"parent_id":{"type":"string","nullable":true},"orden":{"type":"integer"},"nivel":{"type":"integer"},"titulo":{"type":"string"},"tipo":{"type":"string"},"contenido_md":{"type":"string","nullable":true},"contiene_tablas":{"type":"boolean"},"contiene_figuras":{"type":"boolean"},"boe_id":{"type":"string"},"source_anchor":{"type":"string","nullable":true},"verification_status":{"type":"string","enum":["unverified","verified","flagged"]},"documento":{"$ref":"#/components/schemas/CteDocumentoRef"},"hijos":{"type":"array","items":{"$ref":"#/components/schemas/CteHijo"}},"fuentes":{"type":"array","items":{"$ref":"#/components/schemas/CteFuente"}},"aviso":{"type":"string","description":"Aviso legal obligatorio: texto consolidado no oficial."}},"required":["db_codigo","seccion_id","parent_id","orden","nivel","titulo","tipo","contenido_md","contiene_tablas","contiene_figuras","boe_id","source_anchor","verification_status","documento","hijos","fuentes","aviso"]},"CteVigenciaNorma":{"type":"object","nullable":true,"properties":{"boe_id":{"type":"string"},"estado":{"type":"string","nullable":true},"estatus_derogacion":{"type":"string","nullable":true},"boe_fecha_actualizacion":{"type":"string","nullable":true}},"required":["boe_id","estado","estatus_derogacion","boe_fecha_actualizacion"]},"CteVigenciaFuente":{"allOf":[{"$ref":"#/components/schemas/CteFuente"},{"type":"object","properties":{"partes":{"type":"string","nullable":true},"orden":{"type":"integer"}},"required":["partes","orden"]}]},"CteVigenciaDocumento":{"type":"object","properties":{"db_codigo":{"type":"string"},"nombre":{"type":"string"},"version_label":{"type":"string"},"fecha_consolidacion":{"type":"string"},"fuentes":{"type":"array","items":{"$ref":"#/components/schemas/CteVigenciaFuente"}}},"required":["db_codigo","nombre","version_label","fecha_consolidacion","fuentes"]},"CteVigencia":{"type":"object","properties":{"norma":{"$ref":"#/components/schemas/CteVigenciaNorma"},"documentos":{"type":"array","items":{"$ref":"#/components/schemas/CteVigenciaDocumento"}},"aviso":{"type":"string","description":"Aviso legal obligatorio: texto consolidado no oficial."}},"required":["norma","documentos","aviso"]}},"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"}}}}}}},"/v1/iae/tarifas":{"get":{"summary":"List IAE tarifas","description":"Paginated list of IAE (Impuesto sobre Actividades Económicas) tarifas from the Anexo I of RDLeg 1175/1990. Filter by full-text query on título, nivel (agrupación|grupo|epígrafe), or Sección (1|2|3).","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":"Full-text search on título (spanish config).","example":"comercio al por menor"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["agrupacion","grupo","epigrafe"],"description":"Filter by nivel."},"required":false,"name":"nivel","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":3,"description":"Filter by Sección del Anexo I (1, 2 o 3).","example":1},"required":false,"name":"seccion","in":"query"}],"responses":{"200":{"description":"Paginated list of IAE tarifas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IaeTarifaList"}}}},"400":{"description":"Invalid seccion value (not 1, 2 or 3).","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/iae/tarifas/{codigo}":{"get":{"summary":"Get an IAE tarifa by código","description":"Returns the full IAE tarifa (Anexo I, RDLeg 1175/1990) for a código, including its elementos (per-unit / tiered cuota lines). IAE códigos are NOT unique — 65+ códigos repeat across more than one Anexo I Sección (e.g. \"011\" names three unrelated activities). Pass ?seccion= to disambiguate. An ambiguous request without ?seccion= returns 409 naming the matching Secciones — never a guessed default.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","example":"011"},"required":true,"name":"codigo","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":3,"description":"Sección del Anexo I (1, 2 o 3) to disambiguate.","example":1},"required":false,"name":"seccion","in":"query"}],"responses":{"200":{"description":"The IAE tarifa with its elementos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IaeTarifaDetail"}}}},"400":{"description":"Invalid seccion value (not 1, 2 or 3).","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 tarifa found for that código / sección.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Ambiguous código: matches more than one Sección. Retry with ?seccion=.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IaeTarifaAmbiguo"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/iae/cuota":{"post":{"summary":"Calculate the IAE cuota","description":"Calculates the IAE (Impuesto sobre Actividades Económicas) cuota through the full legal chain — exención (art. 82), cuota de tarifa (art. 85), coeficiente de ponderación (art. 86), coeficiente de situación (art. 87, municipal only), bonificación (art. 88) and recargo provincial (art. 134, municipal only) — returning every intermediate paso for audit. Input-dependent: never cached.","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IaeCuotaInput"}}}},"responses":{"200":{"description":"The calculated cuota with its full step-by-step audit trail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IaeCuotaResult"}}}},"400":{"description":"Invalid body, tipoCuota, or an out-of-range coeficienteSituacion/bonificacionPct/recargoProvincialPct.","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 coeficientes de ponderación (art. 86) seeded for the requested ejercicio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/retenciones/calculo":{"post":{"summary":"Calculate the IRPF withholding rate on employment income","description":"Runs AEAT's published ALGORITMO for retenciones a cuenta del IRPF sobre rendimientos del trabajo end to end — cómputo de descendientes y ascendientes, rendimiento neto y reducciones, mínimo personal y familiar, base, cuota (escala del art. 101.1 LIRPF), tipos mínimos del art. 86.2 RIRPF and, where requested, the regularización of art. 87 — returning every intermediate paso for audit.\n\nBody field names are the ALGORITMO's own variable names, so each maps one-to-one to the published \"DATOS DE ENTRADA\" tables.\n\nOptional `fecha` (AAAA-MM-DD) pins the parameter version in force on that date; a date with no registered version returns 404 and never falls back to the newest parameter set. Validation failures return 400 with the COMPLETE list of incidencias, each carrying the ALGORITMO's own numbered message. Input-dependent: never cached. Orientativo — see the `aviso` on every response.","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionCalculoInput"}}}},"responses":{"200":{"description":"The withholding rate with its full step-by-step audit trail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionCalculoResult"}}}},"400":{"description":"Malformed body, wrongly typed field, or input rejected by the ALGORITMO validations (all incidencias returned at once).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionValidacionErrores"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No ALGORITMO version registered for the requested fecha.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/retenciones/versiones":{"get":{"summary":"List the AEAT ALGORITMO spec versions","description":"The registry of AEAT ALGORITMO specification versions and the period each one covers. `valid_to: null` means currently in force. AEAT has published mid-year specs before (two separate 2025 ones), so there can be more than one version per ejercicio — resolve the applicable one here and pin it with `fecha` on the other retenciones endpoints.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"The version registry, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionVersionList"}}}},"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/retenciones/parametros":{"get":{"summary":"Get the parameter set of an ALGORITMO version","description":"The escala del art. 101.1 LIRPF, the mínimos personales y familiares and the key/value parámetros of one ALGORITMO version.\n\n⚠️ `retencion_parametros` mixes two percentage conventions on purpose: `limite_art85_3_porcentaje` is stored as a `coeficiente` (0,43) while `tipo_maximo_art87_5_regularizacion` is stored as a `porcentaje` (47). Always read `valor` together with `unidad`.\n\nThe `articulo` citations on mínimos and parámetros are transcribed from the AEAT specification and have not been verified against the consolidated LIRPF/RIRPF text — see `nota_citas`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Pin the version in force on this date (default: today).","example":"2026-03-01"},"required":false,"name":"fecha","in":"query"}],"responses":{"200":{"description":"Escalas, mínimos and parámetros of the resolved version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionParametrosBundle"}}}},"400":{"description":"Malformed fecha (expected AAAA-MM-DD).","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 ALGORITMO version registered for the requested fecha.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/retenciones/tipos":{"get":{"summary":"List flat-rate IRPF withholding supuestos (cited subset)","description":"The flat-rate (\"tipos fijos\") side of IRPF withholding — profesionales, capital mobiliario, arrendamientos de inmuebles urbanos, administradores, actividades agrícolas y ganaderas, cursos y conferencias, propiedad intelectual — each row cited to its RIRPF/LIRPF article.\n\n⚠️ Deliberately NON-EXHAUSTIVE: a subset covering the common supuestos, not a complete catálogo of every Spanish withholding case. The response states its own scope in `alcance`, and `notas_version` enumerates what is expressly left out (premios del art. 99, IIC del art. 97, the 60 % Ceuta y Melilla reductions, …). Do not treat an absent supuesto as \"no withholding applies\".","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Pin the version in force on this date (default: today).","example":"2026-03-01"},"required":false,"name":"fecha","in":"query"},{"schema":{"type":"string","description":"Exact supuesto key filter.","example":"profesionales_general"},"required":false,"name":"supuesto","in":"query"}],"responses":{"200":{"description":"The cited subset of flat-rate supuestos for the resolved version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetencionTiposList"}}}},"400":{"description":"Malformed fecha (expected AAAA-MM-DD).","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 ALGORITMO version registered for the requested fecha.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cte/estructura":{"get":{"summary":"Get the full CTE tree (Parte I bloques + Parte II secciones)","description":"Without `?db`: Parte I (articulado) bloque list plus every Parte II Documento Básico's sección tree. With `?db`: only that one Documento Básico (no `parte1` key). Parte II is vendored/consolidated, not official BOE text — every response, success or 404, carries the mandatory `aviso`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Documento Básico code, e.g. 'SI', 'SUA-1'. Uppercased before validation.","example":"SI"},"required":false,"name":"db","in":"query"}],"responses":{"200":{"description":"The CTE tree (or one Documento Básico when ?db is given).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteEstructura"}}}},"400":{"description":"Malformed db (expected uppercase letters, optionally with a suffix, e.g. 'SI', 'SUA-1').","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 Documento Básico found for the given db.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cte/secciones":{"get":{"summary":"List/search CTE secciones (Documentos Básicos, Parte II)","description":"Paginated, full-text-searchable list of CTE secciones across all Documentos Básicos, or restricted to one via `?db`. `snippet` is NULL (never an empty string) for a container node whose contenido_md is NULL. Parte II is vendored/consolidated, not official BOE text — the response carries the mandatory `aviso`.","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":"Full-text search on título/contenido_md (spanish config).","example":"protección frente al ruido"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Documento Básico code, e.g. 'SI', 'SUA-1'. Uppercased before validation.","example":"SI"},"required":false,"name":"db","in":"query"}],"responses":{"200":{"description":"Paginated list of CTE secciones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteSeccionList"}}}},"400":{"description":"Malformed db (expected uppercase letters, optionally with a suffix, e.g. 'SI', 'SUA-1').","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/cte/secciones/{db}/{seccion}":{"get":{"summary":"Get one CTE sección (Documento Básico, Parte II)","description":"Full detail of one sección — documento header, contenido_md, the BOE fuentes that compose it, its hijos (child secciones) — for a (db, seccion) pair. Parte II is vendored/consolidated, not official BOE text — every response, success or 404, carries the mandatory `aviso`.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Documento Básico code, e.g. 'SI', 'SUA-1'. Uppercased before validation.","example":"SI"},"required":true,"name":"db","in":"path"},{"schema":{"type":"string","description":"Sección id within the Documento Básico (not format-restricted).","example":"SI1"},"required":true,"name":"seccion","in":"path"}],"responses":{"200":{"description":"The sección with its fuentes and hijos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteSeccion"}}}},"400":{"description":"Malformed db (expected uppercase letters, optionally with a suffix, e.g. 'SI', 'SUA-1').","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 sección found for that (db, seccion) pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteError"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cte/articulo/{numero}":{"get":{"summary":"Get a CTE Parte I artículo (official BOE consolidated text)","description":"Full point-in-time Parte I (articulado, artículos 1-15 of RD 314/2006) via the same versioning engine as GET /v1/norms/{boe_id}/versions. Unlike every other CTE endpoint, this is OFFICIAL BOE consolidated text and never carries the \"no oficial\" aviso.","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Artículo number, 1-15 (Parte I articulado only).","example":"1"},"required":true,"name":"numero","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 for the artículo (default: current in force).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormVersions"}}}},"400":{"description":"Invalid numero (must be an integer 1-15) or malformed on date.","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 norm found for the underlying CTE boe_id (defensive; not expected in practice).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cte/vigencia":{"get":{"summary":"Get CTE vigencia (Parte I norma status + Parte II composition manifest)","description":"Norma-level vigencia for Parte I (estado, estatus_derogacion, última actualización BOE) plus, per Documento Básico, the BOE disposiciones that compose its current Parte II consolidation. Parte II is vendored/consolidated, not official BOE text — the response carries the mandatory `aviso`.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"CTE vigencia: norma status plus per-Documento-Básico composition manifest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteVigencia"}}}},"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"}}}}}}}}}