TaxHarvest API

Sistema RAG per il diritto italiano ed europeo + UAE. Ricerca ibrida (vector HNSW + FTS + reranker) su 648.000+ documenti normativi e giurisprudenziali italiani + UE + UAE + internazionali, sintesi con pipeline anti-hallucination 9-stage, 65 codici indicizzati article-by-article, 67 fonti auto-scraping (61 IT + 6 UAE).

Stats live (20 mag 2026)

Base URL

https://bancadati.doczoom.ai

Quick start (cURL)

curl -X POST https://bancadati.doczoom.ai/api/doczoom/answer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Soglia forfettario 2026?", "top_k": 10}'

UI standalone disponibili

Recent updates

• v25.115 (1 giu 2026): Entity-match SQL disattivato (retrieval più veloce) — A/B test: lo stadio entity-match contribuiva 0 chunk ai risultati finali, aggiungeva 8-27s di latenza e rompeva il reranker Voyage. Disattivato (la NER resta attiva per entities_found). Moduli pesanti come consulente-lavoro da ~28s a ~2s.
• v25.114 (1 giu 2026): Audit 67 fonti + 15 moduli · recall "Per fonte" + pulizia corpus — testate tutte le fonti e i moduli esposti. Rimosse dal picker corte_costituzionale (3.808 doc erano pagine di blocco anti-bot, non sentenze — purgati) e dogi (0 doc) → GET /api/sources ora ritorna 67 fonti utili. Ricerca filtrata per fonte: per filtri selettivi (≤ 10.000 doc) la NN ora è esatta within-source (recall perfetto, risolve fonti di nicchia che potevano tornare 0 risultati); le mega-fonti restano su HNSW.
• v25.113 (1 giu 2026): statement_timeout sulla ricerca vettoriale — tetto di 60s (env VECTOR_SEARCH_TIMEOUT_S) sulle query vettoriali: una query cold che sfora viene troncata e degrada con grazia (l'API abstiene) invece di causare timeout/saturazione pool.
• v25.112 (1 giu 2026): Fix indice HNSW (ricerca filtrata 10-40× più veloce) — le query filtrate per modulo/fonte ora usano correttamente l'indice HNSW (era ignorato per un mismatch di predicato sull'indice parziale): da 32-85s a 0,2-6s a regime.
• v25.110 (1 giu 2026): ⬇ Download PDF / Word dal viewer /doc/{id} — nuovo bottone "Scarica" (stile Glass, dropdown no-JS) nel lettore: GET /doc/{id}/download?format=pdf oppure ?format=docx. Il documento viene generato server-side con la formattazione del design system DocZoom (titolo serif editoriale, accento clay, intestazione con estremi + metadati, corpo giustificato, footer con fonte ufficiale + disclaimer + rif., paginazione per le sentenze lunghe). PDF via reportlab, Word via python-docx. Pubblico (no API key), come il viewer.
• v25.109 (31 mag 2026): 📄 Document viewer /doc/{id} + campi viewer_url/doc_id nelle response — fix UX sulle fonti Cassazione. Il link che davamo all'utente era la SPA ItalGiure https://www.italgiure.giustizia.it/sncass/#id=<solr_id>: un hash-fragment client-side che NON fa deep-link → l'utente atterrava sulla maschera di ricerca e doveva reinserire a mano il codice della sentenza (~340K sentenze, ~100% del corpus Cassazione). Dal Solr scarichiamo solo il testo OCR (nei chunks), non il PDF.
  
  Soluzione: nuovo lettore pubblico GET /doc/{id} (no API key, contenuti legali pubblici) che ricostruisce il testo completo dai chunks (de-overlap), con intestazione ufficiale (es. Corte di Cassazione · Sez. III · Sent. n. 18633/2026, Pres./Rel.) e link alla fonte ufficiale in fondo. Le response di /query, /answer, /retrieve-legal e /reference ora espongono per ogni source doc_id + viewer_url (es. https://bancadati.doczoom.ai/doc/665989): url resta la fonte ufficiale, usa viewer_url come target del bottone "Apri fonte". Funziona per tutte le fonti (Cassazione, Normattiva, AdE, UAE, …). Aggiunto indice idx_documents_url per il lookup batch url→id.
• v25.105 (25 mag 2026): ⚡ Fast-path jurisprudence lookup (200ms vs 43s) + fix "cassa→imprese minori" bug — bug critico rilevato: query "Cass. 11431/2026" non ritornava la sentenza pur essendo in DB. Cause: (1) la substring "cassa" dentro "Cassazione" triggerava espansione errata cassa→imprese minori; (2) doc_ref_patterns in rag.py copriva solo prassi AdE + leggi, nessun pattern per Cassazione/TAR/CdS/Corte Cost; (3) hybrid search impiega 41-170s su 3.92M chunks → watchdog 40s skip rag.multi_search → reference matching mai applicato.
  
  Fix applicati: (1) Discriminazione cassa vs Cassazione: se query contiene \bcassazion[ie]\b o \bcass\. o \bcass\s+(pen|civ|cost|sent|ord|sez|s\.u\.), skip cassa da fiscal_terms + concept_thresholds. (2) Estesa doc_ref_patterns con 4 nuovi regex (cassazione, tar, cds, corte_cost) + source_filter applicato in SQL. (3) NEW: Jurisprudence fast-path in /api/doczoom/query: PRIMA di hybrid, verifica match regex sentenza/numero/anno; se sì, SQL diretto su title + source = ANY(...) → return immediato con top_score=1.0, shortcut=jurisprudence_lookup, latency 200-250ms (vs 43-170s precedente). Pattern coperti: Cass. 11431/2026, Cassazione Penale Ordinanza n. 11432/2026, TAR Roma 12345/2024, CdS 1234/2024, Corte Cost. 209/2022.
  
  Verifica live: query "Cass. 11431/2026" ora ritorna in 237ms con top_score=1.0, top chunk = "Cassazione Penale Ordinanza n. 11431/2026" (doc 81817).
• v25.104 (20 mag 2026): ⚖️ 13 endpoint giurisprudenza dedicati + fix bug authority filter — aggiunto shortcut REST per ogni fonte giurisprudenziale: /api/cassazione (336K), /api/cassazione/{n}/{anno} (lookup), /api/tar (242K), /api/consiglio-stato (20K), /api/corte-costituzionale (3.8K), /api/cgue (1.4K), /api/cedu, /api/giustizia-tributaria, /api/abf, /api/agcm, /api/agcom, /api/sentenze-uae (102), /api/adgm (80), /api/difc (22). Inoltre fix bug /api/legal-judgments?authority=…: il parametro veniva ignorato e tornava sempre giustizia_amministrativa. Ora authority è documentato + mappato su _AUTHORITY_MAP (20 slug supportati) + risposta espone sources_searched per trasparenza. _JUDGMENT_SOURCES_IT esteso da 5 a 15 fonti (aggiunte CGUE, CEDU, ABF, AGCM, AGCOM, ANAC, Banca Italia, IVASS, Consob, EPO BoA — prima invisibili al browsing).
• v25.103 (20 mag 2026): 👔 3 moduli "per profilo professionale" (commercialista, tributarista, consulente-lavoro) — estensione di modules.yaml con 3 macro-moduli pensati per selezione rapida nel picker Studio. Coesistono con i 10 moduli per materia (Civile, Tributario, Penale…) e con le 66 collections L1-L3 (per profili granulari). Esempio uso: commercialista → modulo macro generalista (fiscale + societario + bilancio + lavoro base); tributarista → focused su contenzioso tributario + penale tributario; consulente-lavoro → lavoro + previdenza + sicurezza + immigrazione. Totale moduli ora: 18 (10 IT materia + 3 IT professione + 5 UAE). GET /api/modules e filtro modules=[…] in /answer//query li espongono nativamente.
• v25.102 (20 mag 2026): 📊 Modules Baseline Benchmark + UI /benchmark — eseguito retrieval-only benchmark sui 15 moduli (10 IT + 5 UAE), 150 query × modulo = 2.250 query totali in 9h41m. Findings principali: UAE cluster 0.752-0.778 con 100% success rate (Voyage-3-large 1024d top quality); IT range 0.500 (ip, gap corpus reale) → 0.850 (penale, reference matching codificato). Mean IT 0.636 vs Mean UAE 0.770 → conferma valore upgrade embedding IT. Nuova UI drill-down con tutte le 2.250 query visibili, filtri search/diff/conf, sort multi-colonna. Risultati in eval/results/baseline_20260519_224355/. Costo run: ~$0.45.
• v25.101 (20 mag 2026): 📡 Norm Alerts + scheduler harmonization 1×/day + 11 sub-collections + api-docs full audit — nuova feature notifiche normative (8 endpoint + UI standalone): 6 sub_type (source/module/collection/keyword/reference/country), scan-on-poll architecture, backfill 7-day per UX iniziale. Scheduler ricalibrato da 38 a 59 entry, ognuna 1×/day spread su 24h UTC (aggiunte 26 fonti IT precedentemente non-scheduled). 11 sub-collections L3 nuove (7 commercialista + 4 tributarista). Full audit api-docs 2026-05-20: 12 drift fixati (12 endpoint nuovi documentati, /answer parameter table espansa 4→11 campi, architecture diagram 6→9 stage, numeri 215K→648K docs, version drift v25.86→v25.100).
• v25.100 (18 mag 2026): 🔗 Slug allineati DZ CODES_CATALOG (fix codici "non trovati") — estesa IT_UI_METADATA da 16 a 58 codici per coprire l'intera hardcoded CODES_CATALOG di doczoom-studio. Bug pre-v25.100: per i 48 codici non in IT_UI_METADATA, l'endpoint auto-generava slug lunghi (es. preleggi-disposizioni-sulla-legge-in-generale), ma DZ ha findCodeBySlug hardcoded che cerca preleggi breve → empty state nella detail page. Ora gli slug TaxHarvest matchano 1:1 quelli DZ: preleggi, jobs_act, tu_espropriazioni, cod_pari_opportunita, tu_immigrazione, cod_antimafia, ecc. Restano 6 codici minori in TaxHarvest ma non ancora in DZ CODES_CATALOG (testo-unico-infortuni-lavoro-dpr-1124-1965, ordinamento-giurisdizione-tributaria, ecc.) — questi sono "extra" che DZ può aggiungere quando vuole.
• v25.99 (18 mag 2026): 📖 /api/legal-codes DZ drop-in + UAE document detail fix — refactor di /api/legal-codes per matchare lo shape che il frontend DocZoom già usa per CODES_CATALOG hardcoded: {slug, name, shortName, description, category, articles, taxharvestSource, taxharvestCategory}. Eliminata la necessità di hardcoding lato DZ: const catalog = (await fetch(...)).categories è drop-in con il map/filter esistente.
  Per country=IT: 64 codici Normattiva con UI metadata curated per i 16 core (CC, CPC, CP, CPP, TUIR, TUF, TUB, IVA, Statuto Contribuente, CCII, Cod. Assicurazioni, Cod. Consumo, Costituzione, ecc.). Per country=AE: 4 catalog entries (DIFC Laws 144 · ADGM Regulations 57 · CBUAE Federal Decree-Laws 190 · FTA Public Clarifications 343).
  Fix critico: GET /api/document/{id} ora legge da chunks_uae (Voyage 1024d) per docs UAE invece di chunks. Drawer DocZoom mostra correttamente full_text per leggi UAE (es. DIFC Arbitration Law → 44 chunks, 59.5K char).
• v25.98 (18 mag 2026): 📖 /api/legal-codes + /api/legal-judgments (country-aware) — 2 nuovi endpoint per le tab "Codici" e "Sentenze" di DocZoom. Country-aware (IT/AE), stessa shape per entrambi i paesi. Eliminano l'hardcoding lato frontend (CODES_CATALOG IT-only, sources=['cassazione'] fisso).
  GET /api/legal-codes?country=IT → 64 codici Normattiva.
  GET /api/legal-codes?country=AE → 734 voci (DIFC Laws + ADGM Regulations + CBUAE Federal Decree-Laws + FTA Guides).
  GET /api/legal-judgments?country=AE → 102 judgments (80 ADGM + 22 DIFC) con court/year/case_number/parties parsed on-the-fly da slug.
  GET /api/legal-judgments?country=IT&court=Cassazione&year=2025 → filter su 336K sentenze IT con paginazione. UAE judgment parsing: slug pattern ADGM-ADGMCFI-2025-262 → {court:"ADGM CFI", year:2025, case_number:"ADGMCFI-2025-262", parties:["X","Y"]}.
• v25.97 (18 mag 2026): 🔍 GET /api/sources enriched — risposta ora include per ogni source: country (IT/AE), doc_count (live count), modules (lista moduli di appartenenza), registered_scraper (bool). Nuovi query params ?country=IT|AE|all e ?module={id} per filtering server-side. Permette a DocZoom di mostrare il picker fonte-singola filtrato per paese o modulo senza enumerare lato client. Backward compat preservata: chiave "sources" rimane lista di stringhe per i client v1.
• v25.96 (18 mag 2026): 📚 Modules full coverage audit — 0 codici orfani — audit completo del corpus 67 fonti / 64 codici normattiva. Pre-audit: 5 sources orfane (gazzetta_ufficiale, eur_lex, eurlex, eiopa, istat) + 28 codici normattiva orfani + 3 cassazione macro_area orfani. Post-audit: SOLO istat (2 docs, marginale) escluso. Aggiunti cross-cut gazzetta_ufficiale + eur_lex + eurlex a tutti i 10 moduli IT. Aggiunti 13 codici genuinamente mancanti (Cod. Assicurazioni Private, CAD, Antimafia, CPP Minorile, TU Pubblico Impiego, Cod. Terzo Settore, ecc.). Fix 10+ string-mismatch alias (DB "Codice del Processo Tributario" vs YAML "Processo tributario"). Coverage doc-count post-fix: amministrativo 110K→285K, privacy 600→11K, lavoro 12K→33K, bancario 6K→26K. Nuovo endpoint GET /api/countries per Settings DocZoom (lista paesi + statistiche, no hardcoding). Benchmark discriminazione: 13/44 primary > distractor (+3 vs v25.95), 0 risposte identiche.
• v25.95 (18 mag 2026): 📚 Module filter sub-source granularità — metadata-aware predicate (cassazione macro_area + normattiva codice) applicato pre-truncation. Internal top_k boost (×3, cap 60) per assorbire i drop. Batch SQL enrichment per i record da reference/article match che non portano doc_metadata. Case-insensitive match. "Untagged fallback" per le 199K cassazione storiche senza macro_area (recall > precision). Live discrimination verified: licenziamento → lavoro=1, tributario=2, civile=0; GDPR art 6 → privacy=1, civile/lavoro/tributario=0; accertamento DPR 600 → tributario=4, civile/lavoro=0.
• v25.94 (18 mag 2026): 🇦🇪 +5 moduli UAE + cross-country validator — aggiunti 5 moduli UAE (uae-tax, uae-banking-amlcft, uae-difc, uae-adgm, uae-common-law) che si applicano alla pipeline UAE isolata (Voyage-3-large + chunks_uae). Aggiunto campo country: IT|AE a ogni modulo nel YAML, e validator cross-country in /api/doczoom/query: se i moduli scelti appartengono a un country diverso da quello del request → HTTP 400 module_country_mismatch. Nuovo query param ?country=IT|AE|all su GET /api/modules. Totale moduli ora: 15 (10 IT + 5 UAE).
• v25.93 (18 mag 2026): 📚 10 moduli macro-area Lexroom-style — nuovo sistema di filtraggio per macro-area giuridica cross-source. Definiti 10 moduli (diritto-civile, diritto-tributario, privacy-data-protection, diritto-bancario, diritto-del-lavoro, diritto-societario, diritto-di-famiglia, diritto-amministrativo, ip-proprieta-intellettuale, diritto-penale) in modules.yaml. Ogni modulo è una lista di filtri (source + metadata predicate, es. cassazione.macro_area="tributario", normattiva.codice="TUIR"). Nuovi endpoint: GET /api/modules + GET /api/modules/<id> con live doc_counts per source. Nuovo body field modules: list[str] su POST /api/doczoom/query. Defensive post-filter garantisce che chunks non appartenenti al modulo vengano droppati prima della response. Differenza da collections: moduli = macro-aree pure (giuridiche), collections = profili professionali / temi commerciali. Possono coesistere.
• v25.92 (18 mag 2026): 🇦🇪 UAE final: FTA round 2 completato (522→836 docs) — FTA Public Clarifications cresciuto da 29→343 docs / 622→8.988 chunks dopo secondo bootstrap (timeout 5h, finito in 27min). Pipeline OCR ha gestito bulletins VAT/CT/Excise rasterizzate. 34 PDF rifiutati (text vuoto / ZIP files erroneamente serviti come PDF). UAE corpus finale: 836 docs / 28.379 chunks su 6 sources. Restano bloccate solo eLaws (TCP IP block) e FSRA (text empty upstream).
• v25.91 (18 mag 2026): 🇦🇪 UAE full PDF coverage (413→522 docs, 6/8 sources) — ADGM-Courts (80 docs / 2.976 chunks via OCR Tesseract) + FTA Public Clarifications (29 docs / 622 chunks) importati. ADGM-Courts ha 146 Print-to-PDF judgments rasterizzati, processati in 38 min totali (vs stima 10-20h: cap 30 pp/PDF a DPI 120 sufficiente per la maggior parte dei judgments). Test live retrieval OK su tutti 6 sources con top scores 0.74-0.80. FTA round 2 in BG (5h timeout) per i 126 bulletins rimanenti.
• v25.90 (18 mag 2026): 🇦🇪 UAE corpus expansion (212→413 docs) — nuovo common/pdf_extract.py in legal-sources-overlay/: pipeline a 3 livelli pypdfium2 streaming → pdfplumber fallback → Tesseract OCR (poppler + pytesseract) per PDF rasterizzati. Cap OCR a 30 pp/PDF + DPI 120 per limitare tempi. Cache PDF a /tmp/uae_pdf_cache/<sha256>. Nuove fonti importate: uae_adgm_legislation (57 docs / 2K chunks — ADGM Courts Regulations + Abu Dhabi laws) + uae_difc_legislation (144 docs / 9.7K chunks — DIFC Arbitration / Common Reporting / Companies / Contract Law). Container taxharvest-api memory bumped 2→4G dopo OOM kill durante Voyage multiprocessing embed. FTA + ADGM-Courts in overnight OCR.
• v25.89 (18 mag 2026): 🇦🇪 UAE corpus + country isolation — nuovo param country ISO-2 (default ["IT"], opzionale ["AE"]) su /api/doczoom/query. Tabella separata chunks_uae con embedding Voyage-3-large 1024d (legal-domain). Import iniziale: 190 docs CBUAE (AML/CFT, Federal Decree-Laws, regolamenti) + 22 DIFC Courts judgments. Pipeline UAE: voyage embed → HNSW search → top-K, p50 500ms. Validazione fail-fast: country diverso da IT/AE → HTTP 400 unsupported_country. Roadmap: FTA Public Clarifications, ADGM Courts/Legislation, DIFC Legislation, eLaws (PDF extractor in dev).
• v25.86 (14 mag 2026): +30 sub_area routing per /retrieve-legal — 7 practice_areas / 42 routings totali. Coverage istituti civili (compravendita, mutuo, fideiussione, locazione comm./abit., mandato, comodato, appalto, assicurazione, donazione, successioni, condominio, revocatoria, resp. EC), lavoro (mobbing, trasferimento azienda), tributario (accertamento, contenzioso, IVA), penale (reati tributari, bancarotta, 231), amministrativo (urbanistica, concorrenza), corporate (cessione SRL, op. straordinarie, DD M&A), privacy (GDPR compliance, data breach). Nuovo endpoint GET /api/doczoom/practice-areas espone tassonomia live.
• v25.83: meta-handler conservativo — solo saluti + identita. Drop falsi positivi su query legali con "costi" / "privacy".
• v25.80: /retrieve-legal con must_include anchor, authority_mix, MMR diversity, score_breakdown, exclude_authorities, validation fail-fast HTTP 400.
• v25.77: nuovo endpoint /retrieve-legal con practice_area routing.
• v25.74 (mag 2026): 15 nuove fonti EU + IT + intl (+928 docs) — EBA, EIOPA, ESMA, AMLA, FSB, IASB, BIS BCBS, UIF, AgID, IVASS, INAIL, MLPS, ANAC, ADM, ARERA.
• v25.66: pulizia metadata XML residui in chunks di sentenze TAR/CdS, miglior qualità retrieval su modulo amministrativo.
• v25.55-60: supporto query in inglese su atti UE (GDPR / AI Act / NIS / EPO / HUDOC) con risposta nella stessa lingua. Fix parser Solr Cassazione (text/plain content-type).
• v25.43-54: 6 nuovi scraper — Borsa Italiana regolamenti, EPO Boards of Appeal Case Law 2025, HUDOC CEDU landmark v Italy, Negoziazione Assistita art-by-art, AGCM bollettini settimanali. Privacy boost: EDPB, atti UE Cyber/Data Act, TRIPS WTO, Convenzione Aja, CEDU IT. EUR-Lex 38 atti art-by-art.
• v25.36-42: NIS 2 + DORA + GDPR + CNF Codice Deontologico + Convenzione ONU Diritti Fanciullo indicizzati art-by-art. cassazione_macro_aree applicate ai moduli L1 (riduzione rumore). 14 nuovi moduli L1 (Lexroom-style) in collections.yaml.
• v25.18-35: pipeline anti-allucinazione 9-stage (Citation Guard + LLM Judge V2 + Re-prompt automatico + factuality soft flag). Hallucination rate residuo ~1%. Endpoint /api/doczoom/articles per fetch deterministico articoli. Flag prefer_speed=true per skip re-prompt (latency ridotta). collections param su /answer per pre-filter retrieval domain-specific.

Authentication

Tutti gli endpoint richiedono una API key passata nell'header X-API-Key. Le richieste senza key valida ricevono 401 Unauthorized.

X-API-Key: th_live_xxxxxxxxxxxxxxxxxxxxxxxx

Architecture

Ogni chiamata /api/doczoom/answer attraversa una pipeline a 9 stage con macchina anti-allucinazione (Citation Guard + LLM Judge V2 + Re-prompt automatico + Factuality soft flag). Latency p50 15-25s end-to-end (cache hit ~100ms). Per pipeline retrieval-only (/api/doczoom/query): 1-5s IT, 500-800ms UAE.

Note: gli stage 0-2 sono fast-path (bypassano retrieval/LLM se applicabili). Lo stage 6 (Citation Guard) opera prima del Judge V2 per ridurre falsi positivi. Lo stage 9 (Factuality soft flag) usa lo stesso fact extractor del Citation Guard ma come segnale all'utente, non come blocco. Pipeline retrieval-only (/api/doczoom/query) salta stage 5-9 (no LLM).

Componenti

Errors & Rate limits

Risposte di errore in formato JSON con campi error e detail.

Rate limit

Default 60 richieste/minuto per IP. Per limiti più alti contatta il team.

DocZoom Answer

End-to-end RAG: retrieval ibrido + cross-encoder rerank + LLM synthesis. Restituisce una risposta sintetica + lista fonti citabili. Endpoint principale per il frontend DocZoom.

Request body

Example request

curl -X POST https://bancadati.doczoom.ai/api/doczoom/answer \
  -H "X-API-Key: $TAXHARVEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Qual è la soglia forfettario 2026?",
    "top_k": 10,
    "profile": "Commercialista",
    "materia": "IVA"
  }'

import requests, os

resp = requests.post(
    "https://bancadati.doczoom.ai/api/doczoom/answer",
    headers={"X-API-Key": os.environ["TAXHARVEST_API_KEY"]},
    json={
        "query": "Qual è la soglia forfettario 2025?",
        "top_k": 15,
    },
    timeout=120,
)
data = resp.json()
print(data["answer"])

const resp = await fetch("https://bancadati.doczoom.ai/api/doczoom/answer", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TAXHARVEST_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Qual è la soglia forfettario 2025?",
    top_k: 15,
  }),
});
const data = await resp.json();
console.log(data.answer);

Response

{
  "query": "Qual è la soglia forfettario 2025?",
  "answer": "La soglia per il regime forfettario 2025 è di **85.000 €** di ricavi/compensi (Legge di Bilancio 2025, L. 207/2024). Il superamento oltre 100.000 € comporta uscita immediata dall'IVA forfettario.",
  "sources": [
    {
      "title": "INPS Circolare n. 27 del 30/01/2025",
      "url": "https://www.inps.it/...",
      "source": "inps_circolari",
      "doc_type": "circolare",
      "relevance_score": 0.92
    }
  ],
  "chunks": [/* 15 chunks completi con testo, citazione formale, autorità */],
  "confidence_level": "high",
  "top_score": 0.92,
  "needs_verification": false,
  "has_ai_summary": false,
  "timing_ms": {
    "embedding_ms": 200,
    "vector_search_ms": 800,
    "rerank_ms": 350,
    "llm_ms": 2500,
    "total_ms": 8500
  }
}

Response fields

DocZoom Retrieve-Legal RACCOMANDATO · v25.86

Endpoint legale strutturato per chat avvocato/commercialista. Estende /retrieve con practice_area + sub_area routing dedicato per materia: forza norme base, filtra Cassazione per macro_area, applica must_include anchor sui ~10 articoli canonici dell'istituto.

Tassonomia practice_area / sub_area (42 routings, v25.86)

Per la lista live + dettaglio routing usa GET /api/doczoom/practice-areas.

Ogni practice_area accetta anche sub_area: null per il routing generico (vedi /api/doczoom/practice-areas per dettagli).

Request body

Esempio — Mutuo / usura

curl -X POST https://bancadati.doczoom.ai/api/doczoom/retrieve-legal \
  -H "X-API-Key: $TAXHARVEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Verifica tasso usurario mutuo ipotecario 2015 TAEG soglia",
    "practice_area": "civile",
    "sub_area": "mutuo",
    "top_k": 10
  }'

Ritorna 5+ chunks: Art. 1813 (nozione mutuo), Art. 1815 (interessi usurari), Art. 1819 (restituzione rateale), Art. 1820 (mancato pagamento) + Cassazione bancaria macro_area=banca_finanza.

Esempio — Locazione commerciale 6+6

POST /api/doczoom/retrieve-legal
{
  "query": "Locatore vuole rifiutare primo rinnovo 6 anni per uso diretto come studio professionale, art 29 indennità avviamento",
  "practice_area": "civile",
  "sub_area": "locazione_commerciale",
  "explain": true
}

Ritorna anchor injection di 6 articoli L. 392/1978 (artt. 27, 28, 29, 31, 34, 35) con score 0.99 garantito + Cassazione locazione.

Response (DoczoomRetrieveLegalResponse)

Stessa struttura di /retrieve + campi legal:

Validation errors

HTTP 400 se practice_area non valida:

{
  "detail": {
    "error": "invalid_practice_area",
    "value": "non_esistente",
    "valid": ["amministrativo", "civile", "corporate", "lavoro", "penale", "privacy", "tributario"],
    "hint": "Vedi GET /api/doczoom/practice-areas"
  }
}

HTTP 404 se must_include_mode="strict" + 0 anchor risolti.

Practice Areas (tassonomia) v25.86

Lista live di tutti i routings disponibili per /retrieve-legal. Use case: client carica all'avvio + cache, popola sub_area picker UI + classifier client-side.

Response

{
  "total_areas": 7,
  "total_routings": 42,
  "valid_slugs": ["amministrativo", "civile", "corporate", "lavoro", "penale", "privacy", "tributario"],

  "practice_areas": [
    {
      "practice_area": "civile",
      "sub_areas": ["mutuo", "fideiussione", "locazione_commerciale", null, ...],
      "routings": [
        {
          "sub_area": "mutuo",
          "slug": "civile__mutuo",
          "name": "Civile — Mutuo (artt. 1813-1822 c.c.)",
          "sources": ["normattiva", "cassazione"],
          "normattiva_codici": ["Codice Civile", "TUB - Testo Unico Bancario"],
          "cassazione_macro_aree": ["banca_finanza", "contratti_obbligazioni"],
          "must_include_defaults": ["Art. 1813 Codice Civile", "Art. 1815 Codice Civile", ...],
          "default_authority_mix": { "norms": 5, "case_law": 5, "practice": 0 }
        },
        /* ... altre routings ... */
      ]
    },
    /* ... altre 6 practice_areas ... */
  ]
}

Pattern d'uso — Client classifier

# 1. Bootstrap all'avvio (1 volta, cacheable)
PRACTICE_AREAS = requests.get(
    f"{TAXHARVEST_BASE}/api/doczoom/practice-areas",
    headers={"X-API-Key": KEY},
).json()
VALID_SLUGS = set(PRACTICE_AREAS["valid_slugs"])

# 2. Classifier rule-based client-side
CLASSIFIER_PATTERNS = [
    (r"\b(?:mutuo|TAEG|usura|tasso\s+soglia)\b", "civile", "mutuo"),
    (r"\b(?:fideiussor|fideiussione|art\s+1936|art\s+1957)\b", "civile", "fideiussione"),
    (r"\b(?:locazione|6\+6|L\.\s*392|equo\s+canone)\b", "civile", "locazione_commerciale"),
    (r"\b(?:patto\s+(?:di\s+)?non\s+concorrenza|art\s+2125)\b", "lavoro", "patto_non_concorrenza"),
    (r"\b(?:demansionamento|dequalifica|art\s+2103)\b", "lavoro", "mobbing_demansionamento"),
    (r"\b(?:DD|due\s+diligence|M&A|cessione\s+quote|SPA)\b", "corporate", "due_diligence"),
    (r"\b(?:GDPR|consenso|DPO|art\s+37\s+GDPR)\b", "privacy", "gdpr_compliance"),
    # ... 35+ pattern (vedi /practice-areas per lista completa)
]

def classify(query: str) -> tuple[str | None, str | None]:
    for pat, pa, sa in CLASSIFIER_PATTERNS:
        if re.search(pat, query, re.IGNORECASE):
            return pa, sa
    return None, None

# 3. Chiamata corretta a /retrieve-legal
pa, sa = classify(user_query)
resp = requests.post(
    f"{TAXHARVEST_BASE}/api/doczoom/retrieve-legal",
    headers={"X-API-Key": KEY},
    json={
        "query": user_query,
        "practice_area": pa,  # <-- CRITICO
        "sub_area": sa,        # <-- CRITICO
        "top_k": 12,
    },
).json()

Lista completa sub_areas (42 routings)

DocZoom Retrieve BYOL · v25.75

Endpoint dedicato Bring Your Own LLM. Stessa engine di /query ma con default ottimizzati per consumo LLM downstream: top_k=15, min_relevance=0.4, context_format=llm_xml, group_by_document=true. Quello che serve a DocZoom per ricevere chunks pre-filtrati e generare la risposta col proprio LLM.

Differenze rispetto a /query

Example — call diretto

curl -X POST https://bancadati.doczoom.ai/api/doczoom/retrieve \
  -H "X-API-Key: $TAXHARVEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "patto di non concorrenza durata e corrispettivo",
    "sources": ["normattiva", "cassazione"]
  }'

Context output format = llm_xml (default)

Il campo context viene popolato in formato XML ottimizzato per Claude/GPT tool use:

<sources>
  <source id="1">
    <citation>Art. 2125 Codice Civile</citation>
    <title>Codice Civile — Art. 2125 Patto di non concorrenza</title>
    <url>https://www.normattiva.it/...</url>
    <type>normattiva/articolo_codice</type>
    <relevance>0.92</relevance>
    <text>Il patto con il quale si limita lo svolgimento dell'attività del prestatore di lavoro, per il tempo successivo alla cessazione del contratto, è nullo se non risulta da atto scritto, se non è pattuito un corrispettivo a favore del prestatore di lavoro e se il vincolo non è contenuto entro determinati limiti di oggetto, di tempo e di luogo. La durata del vincolo non può essere superiore a cinque anni, se si tratta di dirigenti, e a tre anni negli altri casi. [...]</text>
  </source>

  <source id="2">
    <citation>Cass. Civ. Sez. Lav. n. 17/2018</citation>
    <title>Cassazione — Requisiti validità patto non concorrenza</title>
    <url>https://www.italgiure.giustizia.it/...</url>
    <type>cassazione/sentenza</type>
    <relevance>0.85</relevance>
    <text>Il corrispettivo del patto di non concorrenza deve essere determinato o determinabile e non meramente simbolico. [...]</text>
  </source>
</sources>

Pattern Anthropic Claude — call diretto

# 1. Retrieve da TaxHarvest
chunks_resp = requests.post(
    "https://bancadati.doczoom.ai/api/doczoom/retrieve",
    headers={"X-API-Key": TAXHARVEST_KEY},
    json={"query": user_question},
).json()

# 2. Costruisci system prompt per Claude
system_msg = f"""Sei un assistente legale italiano. Rispondi citando SOLO le fonti seguenti.
Usa il formato [^N] dove N è l'id della source.

{chunks_resp['context']}

REGOLE:
- Cita ogni claim con riferimento esatto
- NON inventare numeri di sentenze o articoli non presenti
- Se le fonti non bastano, dillo esplicitamente"""

# 3. Chiama il TUO LLM (Anthropic Claude, OpenAI GPT, ...)
from anthropic import Anthropic
client = Anthropic()
answer = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    system=system_msg,
    messages=[{"role": "user", "content": user_question}],
)

# 4. Componi response finale
return {
    "answer": answer.content[0].text,
    "sources": chunks_resp["sources"],
    "chunks_used": chunks_resp["chunks"],
    "confidence": chunks_resp["confidence_level"],
}

Risposta

Stesso schema di /query (DoczoomQueryResponse). Il valore di context varia in base a context_format.

DocZoom Query BYOL · low-level

Retrieve-only endpoint ottimizzato per Bring Your Own LLM: ricerca ibrida + reranking + filtering + ranking applicati, ma senza synthesis. Il client riceve chunks ben filtrati e li passa al proprio LLM per generare la risposta. Più veloce di /answer (~3–8s vs 15–25s).

Cosa è già applicato sui chunks ritornati

• Hybrid search: vector HNSW + FTS italiano + entities + ontology
• Cross-encoder reranker: top 50 candidati → top 15 con scoring multilingue
• Junk filtering: rimossi chunks <80 char, firme digitali, numeri pagina, chunks con <30% caratteri alfabetici
• Title-aware boost: query con riferimenti normativi (es. "L. 392/1978 art. 27") boostano i chunks con quel numero/anno nel titolo (anti fake-match)
• Source hierarchy boost: Cass. SU > Cass. > Normattiva > AdE circolari
• Vigenza penalty: atti abrogati downgradati (−0.10)
• Dedup per URL + top-K cap
• Confidence layer: high (top ≥ 0.7) / medium / low / no_results

Request body

Example — BYOL flow completo

curl -X POST https://bancadati.doczoom.ai/api/doczoom/query \
  -H "X-API-Key: $TAXHARVEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ravvedimento operoso entro 90 giorni aliquota",
    "top_k": 15,
    "sources": ["normattiva", "ade_circolari"],
    "min_relevance": 0.4
  }'

Example — UAE corpus query (v25.89)

curl -X POST https://bancadati.doczoom.ai/api/doczoom/query \
  -H "X-API-Key: $TAXHARVEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "anti-money laundering CBUAE suspicious transactions reporting",
    "country": ["AE"],
    "top_k": 5
  }'

Response identica come schema (chunks + sources + confidence). Differenze: timing_ms.country = "AE", timing_ms.embedding_model = "voyage-3-large", chunk.source.source ∈ {"uae_cbuae", "uae_difc"}. Niente meta-handler / niente factuality judge / niente reranker (pipeline UAE isolata).

Response schema

{
  "query": "ravvedimento operoso entro 90 giorni aliquota",
  "total_results": 15,
  "confidence_level": "high",
  "top_score": 0.87,
  "needs_verification": false,
  "timing_ms": { "hybrid": 1200, "rerank": 340, "total": 1850 },

  "chunks": [
    {
      "text": "Art. 13 — Ravvedimento. 1. La sanzione è ridotta:\na) ad un decimo del minimo nei casi di mancato pagamento del tributo...",
      "source": {
        "title": "D.Lgs. 472/1997 — Art. 13 Ravvedimento",
        "url": "https://www.normattiva.it/atto/caricaDettaglioAtto?atto.dataPubblicazioneGazzetta=1997-12-19&atto.codiceRedazionale=097G0509&art.idArticolo=13",
        "source": "normattiva",
        "doc_type": "decreto_legislativo",
        "relevance_score": 0.87,
        "doc_id": 12345,
        "viewer_url": "https://bancadati.doczoom.ai/doc/12345"
      },
      "formal_citation": "Art. 13 D.Lgs. 472/1997",
      "article_path": "art_13",
      "authority": "Stato",
      "validity": "vigente",
      "document_date": "1997-12-18",
      "category": "legislazione",
      "is_ai_summary": false,
      "chunk_index": 0,
      "entities": [{"type": "norm", "value": "D.Lgs. 472/1997"}]
    },
    /* ... altri 14 chunks ordinati per relevance_score ... */
  ],

  "sources": [
    /* lista deduped delle source (chunks possono condividere stessa source) */
  ],

  "entities_found": [
    { "type": "norm", "value": "D.Lgs. 472/1997", "count": 8 },
    { "type": "percentage", "value": "0.083%", "count": 3 }
  ],

  "concepts_activated": [
    { "concept": "ravvedimento_operoso", "score": 0.92 }
  ],

  "context": "[NORMATTIVA | decreto_legislativo] D.Lgs. 472/1997 — Art. 13 Ravvedimento\nFonte: https://www.normattiva.it/...\nRilevanza: 87%\n---\nArt. 13 — Ravvedimento. 1. La sanzione...\n\n===\n\n[ADE_CIRCOLARI | circolare] Circolare 27/E 2013...\n..."
}

BYOL pattern — sintesi col tuo LLM

Una volta ottenuti i chunks pre-filtrati, costruisci il system prompt del tuo LLM con il campo context (già formattato). Esempio Python con qualsiasi provider:

# 1. Retrieve da TaxHarvest
resp = requests.post(
    "https://bancadati.doczoom.ai/api/doczoom/query",
    headers={"X-API-Key": API_KEY},
    json={
        "query": user_question,
        "top_k": 15,
        "min_relevance": 0.4,  # filtra chunks deboli
    },
).json()

if resp["confidence_level"] == "no_results":
    return resp["no_results_message"]  # "Non ho trovato fonti..."

# 2. Passa al tuo LLM con il context pre-formattato
system = f"""Sei un assistente legale. Rispondi SOLO usando le fonti seguenti.
Cita ogni claim con il riferimento normativo esatto.

FONTI (in ordine di rilevanza):
{resp['context']}"""

answer = your_llm.complete(system=system, user=user_question)

# 3. Componi response finale con citation tracking
return {
    "answer": answer.text,
    "sources": resp["sources"],
    "confidence": resp["confidence_level"],
    "chunks_used": resp["chunks"],
}

Decision matrix dettagliata

DocZoom Stream (SSE)

Streaming Server-Sent Events della risposta LLM. Stessa logica di /answer ma con eventi tipizzati per timeline UI Onyx-like.

Eventi SSE emessi

Request body

Accetta lo stesso schema di /answer (vedi sezione DocZoom Answer). Tutti i field sotto sono supportati anche su /stream.

Use case: Legal Chat con documento allegato

Il client (Plugin DocZoom Word / Legal Chat) ha l'utente che carica un contratto, una circolare aziendale, un parere — qualunque PDF/DOCX che deve essere analizzato contro la banca dati normativa. Pattern corretto: estrai il testo del documento lato client e passalo come document_context, NON comprimerlo dentro la query. La banca dati TaxHarvest viene usata come source/authority retrieval, il LLM ragiona sul documento allegato con il diritto italiano come riferimento.

POST /api/doczoom/stream
{
  "query": "Questa clausola di non concorrenza è valida secondo il diritto italiano?",
  "document_context": "ART. 7 — PATTO DI NON CONCORRENZA\nIl Lavoratore si impegna, per la durata di 36 mesi dalla cessazione del rapporto di lavoro, a non svolgere attività concorrenziale presso aziende del settore alimentare in tutto il territorio della Repubblica Italiana. A titolo di corrispettivo, il Lavoratore percepirà la somma di € 5.000 una tantum alla cessazione del rapporto.\n\n[... resto del contratto ...]",
  "document_name": "contratto_lavoro_mario_rossi.pdf",
  "max_output_tokens": 2048,
  "profile": "Avvocato Civilista",
  "materia": "Lavoro"
}

Il LLM riceverà nel system prompt: "L'utente ha allegato il documento 'contratto_lavoro_mario_rossi.pdf'..." e nel context il testo del contratto + i 10 chunks più rilevanti dalla banca dati (art. 2125 c.c., Cass. 17/2018 sui requisiti, ecc.).

Example (browser, streaming consumption)

const resp = await fetch("/api/doczoom/stream", {
  method: "POST",
  headers: {"X-API-Key": KEY, "Content-Type": "application/json"},
  body: JSON.stringify({
    query: "È valido il patto di non concorrenza?",
    document_context: contractText,  // estratto lato client da .pdf/.docx
    document_name: "contratto.pdf",
    max_output_tokens: 2048,
  }),
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  // Parse SSE: event: delta\ndata: {"text": "L'art..."}
  const chunk = decoder.decode(value);
  console.log(chunk);
}

DocZoom Reference

Lookup di un riferimento normativo specifico (es. "art. 13 DPR 633/72"). Più preciso di /answer per citazioni dirette.

Request body

Example

curl -X POST https://bancadati.doczoom.ai/api/doczoom/reference \
  -H "X-API-Key: $KEY" \
  -d '{"reference": "L. 392/1978 art. 27"}'
# → "Equo Canone (L. 392/1978) - Art. 27" (1 risultato esatto)

curl -X POST https://bancadati.doczoom.ai/api/doczoom/reference \
  -H "X-API-Key: $KEY" \
  -d '{"reference": "art. 1384 c.c."}'
# → "Codice Civile - Art. 1384 - Riduzione della penale"

DocZoom Articles v25.30

Fetch deterministico di articoli specifici per una legge o un codice. Bypassa completamente il semantic search — ideale per audit di conformità su tipo di contratto noto, dove il client predefinisce una whitelist di articoli imperativi e li fetcha sempre.

Request body

* Almeno uno tra law e codice richiesto.

Response

{
  "law": "L. 392/1978",
  "codice": null,
  "articles_requested": ["27", "32", "34", "36"],
  "found_count": 4,
  "missing_count": 0,
  "articles": [
    {
      "article": "27",
      "found": true,
      "title": "Equo Canone (L. 392/1978) - Art. 27",
      "url": "https://www.brocardi.it/legge-equo-canone/...",
      "source": "normattiva",
      "doc_type": "legge",
      "citation": "art. 27 L. 392/1978",
      "text": "La durata delle locazioni e sublocazioni di immobili urbani non può essere inferiore a sei anni..."
    },
    // ... altri articoli
  ]
}

Examples

# Locazione commerciale: 4 articoli imperativi della L. 392/1978
curl -X POST https://bancadati.doczoom.ai/api/doczoom/articles \
  -H "X-API-Key: $KEY" \
  -d '{"law": "L. 392/1978", "articles": [27, 32, 34, 36]}'

# Codice Civile: clausola penale + illecito + trasferimento azienda
curl -X POST https://bancadati.doczoom.ai/api/doczoom/articles \
  -H "X-API-Key: $KEY" \
  -d '{"codice": "c.c.", "articles": [1384, 2043, 2112]}'

# TUIR articoli (no testo, solo metadata)
curl -X POST https://bancadati.doczoom.ai/api/doczoom/articles \
  -H "X-API-Key: $KEY" \
  -d '{"codice": "TUIR", "articles": [54, 85], "include_text": false}'

Use case principale

Plugin DocZoom Word — audit di conformità contratti. Il Compliance Query Planner predefinisce una whitelist di articoli imperativi per ogni ContractType (es. locazione commerciale = L. 392/1978 art. 27/32/34/36 + art. 1384 c.c.) e fetcha sempre questi via /articles. Risolve il limit di /query sul ranking semantico delle leggi speciali.

Special norm aliases (v25.37)

Norme orizzontali NON ancora indicizzate art-by-art (es. GDPR Reg. UE 2016/679) ritornano una response strutturata invece di matchare per substring fuzzy. Esempio:

curl -X POST https://bancadati.doczoom.ai/api/doczoom/articles \
  -H "X-API-Key: $KEY" \
  -d '{"law": "GDPR", "articles": [6, 7]}'

# Response (no FP su Codice Protezione Civile):
{
  "law": "Reg. UE 2016/679",
  "found_count": 0,
  "missing_count": 2,
  "articles": [
    {"article": "6", "found": false, "_not_indexed": true,
     "_message": "Il Regolamento UE 2016/679 (GDPR) non è ancora indicizzato..."}
  ],
  "_warning": "...usare Codice Privacy nazionale come proxy."
}

Aliases attualmente configurati: GDPR, Reg. UE 2016/679, Regolamento Generale Protezione Dati. Più verranno aggiunti man mano che si trovano gap di indicizzazione.

Garanzie

• Deterministico: stessa request → stesso output. No semantic ranking variability.
• Articoli mancanti ritornano {found: false} invece di errore HTTP — il client può aggregare lo stato.
• Performance: ~50-200ms per request (1 SQL query/articolo).
• Costo: $0 (no LLM, no embedding).

Compliance Contract Types v25.32

Lista dei tipi di contratto curati per il flow audit conformità. Sostituisce hardcoding lato plugin.

Response

{
  "count": 7,
  "contracts": [
    {"type": "locazione-commerciale", "label": "Locazione commerciale (uso non abitativo)", "description": "..."},
    {"type": "locazione-abitativa", "label": "Locazione abitativa", "description": "..."},
    {"type": "lavoro-subordinato", "label": "Contratto di lavoro subordinato", "description": "..."},
    {"type": "patto-non-concorrenza", "label": "Patto di non concorrenza", "description": "..."},
    {"type": "nda-riservatezza", "label": "Accordo di riservatezza (NDA)", "description": "..."},
    {"type": "compravendita-immobile", "label": "Compravendita immobiliare", "description": "..."},
    {"type": "appalto-privato", "label": "Contratto di appalto privato", "description": "..."}
  ]
}

Example

curl https://bancadati.doczoom.ai/api/compliance/contracts \
  -H "X-API-Key: $KEY"

Compliance Contract Detail v25.32 + v25.37

Whitelist imperative_norms (specifiche del tipo contratto) + tipiche_violazioni (checklist) + horizontal_norms (norme cross-cutting che si applicano sempre — GDPR, Codice Consumo, ecc.). Pensato per il flow Conformità del plugin DocZoom Word: il client lo chiama dopo che l'utente ha selezionato il tipo contratto, e ottiene tutti i riferimenti legali da prependere al normativeContext.

Path params

Query params

Response

{
  "type": "locazione-commerciale",
  "label": "Locazione commerciale (uso non abitativo)",
  "description": "Contratto di locazione di immobile urbano adibito ad uso diverso...",
  "imperative_norms": [
    {"law": "L. 392/1978", "articles": [27, 32, 34, 36, 37, 38, 39, 40, 41, 42],
     "tema": "Disciplina locazioni uso diverso: durata, ISTAT, indennità avviamento..."},
    {"codice": "c.c.", "articles": [1384, 1385, 1571, 1573, 1575],
     "tema": "Clausola penale, caparra, nozione locazione, obblighi locatore"}
  ],
  "tipiche_violazioni": [
    "Durata < 6 anni (L. 392 art. 27)",
    "Aggiornamento ISTAT > 75% indice (L. 392 art. 32)",
    "Limitazione/condizionamento del diritto di recesso del conduttore per gravi motivi (L. 392 art. 27 c. 8 — il diritto è inderogabile)",
    "Mancanza informativa privacy / trattamento dati conduttore (GDPR / D.Lgs. 196/2003)",
    ...
  ],
  "horizontal_norms": [   // v25.37 — norme cross-cutting che si applicano a questo tipo
    {
      "key": "gdpr",
      "label": "Privacy / Trattamento dati personali (GDPR)",
      "law": "Reg. UE 2016/679",
      "fallback_codice": "Codice della Privacy",
      "articles": [6, 7, 13, 14, 15, 17, 22, 28, 32, 35, 44],
      "tema": "Basi legali, consenso, informativa, diritti interessato...",
      "indicizzato": false,
      "fallback_indicizzato": true,
      "warning": "GDPR non indicizzato art-by-art; usare Codice Privacy come proxy"
    }
  ],
  "articles": [...]  // se fetch_text=true: imperative + horizontal aggregati con field `category` (imperative|horizontal)
}

Examples

# Lista whitelist (lightweight, no testo articoli)
curl https://bancadati.doczoom.ai/api/compliance/contracts/locazione-commerciale \
  -H "X-API-Key: $KEY"

# Con full articles (testo completo)
curl "https://bancadati.doczoom.ai/api/compliance/contracts/locazione-commerciale?fetch_text=true" \
  -H "X-API-Key: $KEY"

Audit Trending v25.34

Metriche daily aggregate per detection automatica regressioni qualità (hallu rate, judge rate, re-prompt, latency p50/p95). Auto-alert se metrica oggi differisce significativamente dalla media 7 giorni precedenti.

Query params

Response

{
  "days": 14,
  "trending": [
    {
      "day": "2026-05-03",
      "total_queries": 846,
      "hallu_caught_pct": 2.0,
      "judge_issue_pct": 24.7,
      "reprompt_pct": 19.5,
      "tier2_override_pct": 1.2,
      "abstain_pct": 0.0,
      "latency_avg_ms": 38542,
      "latency_p50_ms": 25103,
      "latency_p95_ms": 97104
    },
    ...
  ],
  "alerts": [
    {
      "metric": "latency_p95_ms",
      "today": 97104,
      "avg_prev_7d": 36748,
      "severity": "warning"
    }
  ],
  "summary": {
    "total_calls": 3040,
    "avg_hallu_caught_pct": 2.44,
    "avg_p95_ms": 54834
  }
}

DocZoom Tool

Strumenti real-time (VIES check, ricerca articoli, ecc.). Vedi /api/doczoom/capabilities per la lista completa.

Request body

DocZoom Capabilities

Lista delle capabilities/tools disponibili.

Chat

Chat con context multi-turn. Mantiene history per follow-up domande.

Request

Search (basic)

Endpoint di ricerca legacy. Per nuove integrazioni preferisci /api/doczoom/query.

Sources

Lista delle 61 fonti IT dati disponibili (+ 6 UAE), scrapate automaticamente da scheduler interno. Backend di acquisizione: 3-tier (HTTP proxy interno, Browser rendering, direct fetch).

Inventario completo (counts 13 mag 2026)

Giurisprudenza (610K+ documenti)

Normativa italiana (15K+ articoli)

Normativa UE (1.8K+ documenti)

Prassi fiscale (7.4K+ documenti AdE)

Previdenza & Lavoro (8.2K+ documenti)

Authority indipendenti IT (1.9K+ documenti)

Ministeri & Enti pubblici IT (270+ documenti)

Authority UE (440+ documenti)

Standard-setter internazionali (65+ documenti)

Privacy & GDPR (440+ documenti)

Internazionale & specialistiche (270+ documenti)

Response example

{
  "sources": [
    {"name": "cassazione", "count": 335188},
    {"name": "giustizia_amministrativa", "count": 267795},
    {"name": "normattiva", "count": 14963},
    {"name": "cnel_ccnl", "count": 6762},
    /* ... totale 61 fonti IT (+ 6 UAE), vedi tabella sopra */
  ]
}

Modules (macro-area + profilo) v25.93+25.103 · LEXROOM-STYLE

18 moduli totali: 10 IT macro-area giuridica (Civile, Tributario, Penale, ecc.) + 3 IT per profilo professionale (v25.103: commercialista, tributarista, consulente-lavoro) + 5 UAE. Permettono a DocZoom di filtrare il retrieval senza enumerare manualmente le 67 sources. Per profili più granulari (es. commercialista-iva) usa le 66 collections L1-L3.

Lista i 18 moduli disponibili con id, name, icon, description, filter_count e sources coperte.

Response schema

{
  "modules": [
    {
      "id": "diritto-civile",
      "name": "Diritto Civile",
      "icon": "⚖️",
      "short": "Civile",
      "description": "Codice Civile, CPC, Cassazione civile...",
      "filter_count": 6,
      "sources": ["cassazione", "corte_costituzionale", ...]
    },
    /* ... 10 moduli totali */
  ],
  "count": 18,
  "usage_hint": "Passa modules=['diritto-civile'] o ['commercialista'] a POST /api/doczoom/query"
}

Query params

🇮🇹 Moduli IT per materia giuridica (10, Lexroom-style)

👔 Moduli IT per profilo professionale (3, v25.103)

Macro-moduli che aggregano fonti di più materie secondo le esigenze tipiche del professionista. Per granularità maggiore (sub-tematiche L2/L3) vedi le 66 collections.

🇦🇪 Moduli UAE disponibili (country=AE)

⚠️ Cross-country validation: i moduli UAE richiedono country=["AE"]; i moduli IT richiedono country=["IT"] (o default). Mismatch → HTTP 400 module_country_mismatch.

Esempio cURL

curl https://bancadati.doczoom.ai/api/modules \
  -H "X-API-Key: $TAXHARVEST_API_KEY"

Module Detail (live counts)

Dettaglio di un singolo modulo + count documenti per source (live).

Path params

Response schema

{
  "id": "diritto-tributario",
  "name": "Diritto Tributario",
  "icon": "💶",
  "short": "Tributario",
  "description": "Normativa tributaria nazionale + UE...",
  "filters": [
    {"source": "cassazione", "metadata": {"macro_area": ["tributario"]}},
    {"source": "normattiva", "metadata": {"codice": ["TUIR..."]}},
    /* ... 17 filtri totali */
  ],
  "sources": ["cassazione", "ade_circolari", "ade_interpelli", ...],
  "doc_counts": {
    "cassazione": 71101,
    "corte_costituzionale": 3808,
    "ade_interpelli": 3237,
    /* ... per ogni source */
  },
  "total_docs": 85304
}

Usage in retrieval

Passa modules in POST /api/doczoom/query per filtrare i chunks ai soli source/metadata del modulo:

curl -X POST https://bancadati.doczoom.ai/api/doczoom/query \
  -H "X-API-Key: $TAXHARVEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ravvedimento operoso entro 90 giorni",
    "modules": ["diritto-tributario"],
    "top_k": 10
  }'

Note: i moduli compongono in OR con sources e collections (più permissive). Un module_id non valido → HTTP 400 unknown_module. Quando country=["AE"], i moduli vengono ignorati (UAE pipeline isolata).

Source Categories

Macro-categorie per una fonte specifica (es. Normattiva → CC, CP, TUIR, ...).

Response (v25.8+)

Per normattiva, ogni categoria contiene un slug stable usabile come parametro filtro:

{
  "source": "normattiva",
  "categories": [
    {"name": "Codice Civile", "slug": "cc", "count": 3029},
    {"name": "TUIR - Testo Unico Imposte sui Redditi", "slug": "tuir", "count": 236},
    /* ... vedi tabella 65 codici sotto */
  ]
}

65 codici Normattiva disponibili (count 13 mag 2026)

Codici fondamentali

Tributario

Bancario, finanziario, assicurazioni

Lavoro

Amministrativo, appalti, edilizia

Penale specialistico

Civile specialistico

Crisi d'impresa, immobiliare, famiglia, immigrazione

Altro

I client possono usare sia lo slug (es. cc) sia il nome canonico (es. "Codice Civile") come parametro category. La response include resolved_category per breadcrumb UI.

Source Documents

Query params

Response field (v25.8)

resolved_category espone il nome canonico matchato (utile per breadcrumb UI quando il client passa uno slug).

Examples

# Slug stable
curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/source/normattiva/documents?category=cc&limit=10"

# Equivalente con nome esteso
curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/source/normattiva/documents?category=Codice%20Civile"

# Atti non codificati (decreto_legislativo, legge, dpr, decreto_legge, ...)
curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/source/normattiva/documents?category=altri"

Document Full (con testo)

Nuovo in v25.8.2: ritorna metadati documento + chunks + full_text. Usato dal frontend DocZoom (Codici Navigator) per renderizzare il testo dell'articolo cliccato. /source/.../documents ritorna solo metadata; questo endpoint fornisce il testo completo.

Path params

Response

{
  "id": 211124,
  "source": "normattiva",
  "doc_type": "altro",
  "title": "Codice di Procedura Penale - Art. 1 - Giurisdizione penale",
  "url": "https://it.wikisource.org/wiki/Codice_di_procedura_penale#Art._1",
  "unique_id": "normattiva::https://it.wikisource.org/...",
  "published_date": "1988-09-22",
  "metadata": {"codice": "Codice di Procedura Penale", "articolo": "1", /* ... */},
  "chunks": [
    {
      "id": 1715309,
      "chunk_index": 0,
      "total_chunks": 1,
      "text": "1. La giurisdizione penale è esercitata dai giudici previsti...",
      "metadata": {"source_summary": "wikisource_verbatim"}
    }
  ],
  "chunks_count": 1,
  "full_text": "1. La giurisdizione penale è esercitata dai giudici..."
}

Examples

# Ottieni full text di un articolo CC
curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/document/211124"

# Pattern frontend: lista → click → fetch full text
const list = await fetch('/api/source/normattiva/documents?category=cc');
const docId = list.documents[0].id;
const full = await fetch(`/api/document/${docId}`);
console.log(full.full_text);  // rendering immediato

Recent Documents

Ultimi documenti importati (cronologia harvest).

Query params

Stats

Statistiche aggregate del database (IT + UAE corpus). I numeri sono live al momento della chiamata.

{
  "total_documents": 648931,
  "total_chunks": 3920561,
  "total_entities": 637000,
  "chunks_uae": 28379,
  "sources": {/* breakdown per source — 67 fonti totali */},
  "last_harvest": "2026-05-20T05:30:00"
}

Per stats per-modulo: GET /api/modules/{id} (con counts live). Per stats per-source: GET /api/sources.

Articles

Lookup diretto di un articolo per numero (es. /api/articles/2473 per art. 2473 CC).

Countries v25.96

Lista paesi supportati dal corpus con stats. Usato da DocZoom Settings per popolare il selettore Country.

Response example

{
  "countries": [
    {"code": "IT", "name": "Italia", "docs": 648095, "sources": 61, "modules": 10},
    {"code": "AE", "name": "United Arab Emirates", "docs": 836, "sources": 6, "modules": 5}
  ]
}

Legal Codes (DocZoom-compatible) v25.98

Lista dei 65 codici Normattiva indicizzati article-by-article, con slug DocZoom-compatible (allineati 1:1 a CODES_CATALOG di doczoom-studio v25.100). Drop-in replacement per la pagina codici DZ.

Response shape

{
  "codes": [
    {
      "slug": "codice-civile",
      "name": "Codice Civile",
      "short": "CC",
      "articles_count": 3029,
      "chunks_count": 3230,
      "category": "civile",
      "description": "Codice civile italiano (R.D. 262/1942)..."
    },
    /* ... 64 più ... */
  ],
  "total": 65
}

Slug allineati (esempi)

Tutti gli slug sono kebab-case deterministici, 1:1 con DZ CODES_CATALOG. Esempi: codice-civile, cpc, cp, cpp, tuir, tub, tuf, preleggi, jobs_act, tu_espropriazioni, cod_pari_opportunita, tu_immigrazione, cod_antimafia, statuto_lavoratori, codice_appalti (D.Lgs. 36/2023), codice_consumo, ecc.

Example

curl -H "X-API-Key: $KEY" https://bancadati.doczoom.ai/api/legal-codes

Legal Judgments (DocZoom-compatible) v25.98

Lista delle fonti giurisprudenziali con conteggi live. Drop-in per la pagina giurisprudenza DZ.

Query params

Response shape

{
  "authorities": [
    {"slug": "cassazione", "name": "Corte di Cassazione", "docs": 336818, "subtypes": ["civile", "penale", "costituzionale"]},
    {"slug": "giustizia_amministrativa", "name": "Giustizia Amministrativa", "docs": 269254, "subtypes": ["tar", "cds", "cga"]}
  ]
}

Reference Lookup

Lookup di un riferimento normativo o giurisprudenziale già normalizzato (es. art-2473-cc, cass-civ-12345-2023, dlgs-74-2000-art-2). Ritorna il documento + chunks principali.

Example

curl -H "X-API-Key: $KEY" \
  https://bancadati.doczoom.ai/api/reference/art-2473-cc

Response shape

{
  "reference": "art-2473-cc",
  "document": {"id": 12345, "title": "Art. 2473 c.c. – Recesso del socio", "source": "normattiva"},
  "chunks": [/* top chunks */]
}

Reference History

Cronologia delle versioni di un riferimento normativo (modifiche, abrogazioni, sostituzioni). Utile per verificare la vigenza di una norma a una data.

Example

curl -H "X-API-Key: $KEY" \
  https://bancadati.doczoom.ai/api/reference/art-18-statuto-lavoratori/history

Reference Cited-By

Lista di documenti (sentenze, circolari, dottrina) che citano il riferimento. Costruito dal knowledge graph delle cross-reference estratte dai chunks.

Example

curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/reference/art-2473-cc/cited-by?limit=20"

Collections — list

Lista delle 66 collections professionali (profili commercialista, tributarista, avvocato civilista, notaio, consulente del lavoro + materie). 21 L1, 27 L2, 18 L3 (v25.101: aggiunte 7 sub-commercialista + 4 sub-tributarista). Cf. taxharvest/collections.yaml.

Profili professionali L1 esposti (7)

Sub-collections commercialista (esempio gerarchia)

L1  commercialista
├── L2  commercialista-fiscale
│   ├── L3  commercialista-dichiarazioni            // v25.101
│   ├── L3  commercialista-contenzioso-tributario   // v25.101
│   ├── L3  commercialista-ravvedimento-sanzioni    // v25.101
│   ├── L3  commercialista-internazionale           // v25.101
│   ├── L3  commercialista-cripto-assets            // v25.101
│   └── L3  commercialista-startup-pmi              // v25.101
├── L2  commercialista-contabile-bilancio
│   └── L3  commercialista-bilanci-revisione        // v25.101
├── L2  commercialista-societario
├── L2  commercialista-crisi-impresa
└── L2  commercialista-lavoro

Response shape

{
  "collections": [
    {
      "slug": "commercialista-fiscale",
      "name": "Commercialista — Fiscale",
      "level": "L1",
      "parent": null,
      "sources": ["ade_circolari", "ade_interpelli", "normattiva", "cassazione"],
      "docs_estimate": 340000
    }
    /* ... */
  ]
}

Collections — tree

Struttura gerarchica L1 → L2 → L3 delle collections, pronta per il widget tree-view di DocZoom Studio.

Collections — detail

Dettaglio di una singola collection: descrizione, sources, normattiva_codici, cassazione_macro_aree, parent/children, doc_count live.

Example

curl -H "X-API-Key: $KEY" \
  https://bancadati.doczoom.ai/api/collections/commercialista-iva

Collections — documents

Documenti appartenenti a una collection. Supporta paginazione (?limit=50&offset=0) e filtri (?source=ade_circolari&year=2026).

Norm Alerts v25.101 · NEW

Sistema di notifiche per cambiamenti normativi. L'utente registra "subscription" (per source, modulo, collection, keyword, reference o country) e l'API genera "events" quando nuovi documenti matchano i criteri. Architettura scan-on-poll: alla GET /api/alerts scan automatico dei documenti creati dopo l'ultima poll della subscription. Idempotente. UI built-in su /alerts.

Lista degli eventi (notifiche) per l'API key corrente. Trigger scan automatico se scan=true (default).

Query params

Response shape

{
  "events": [
    {
      "id": 42,
      "subscription": {"id": 1, "name": "Watch Circolari AdE", "sub_type": "source", "target": "ade_circolari"},
      "document_id": 656712,
      "title": "Circolare 14/E del 2026 — Forfettario 2026",
      "url": "https://...",
      "source": "ade_circolari",
      "country": "IT",
      "created_at": "2026-05-20T08:15:00Z",
      "read_at": null
    }
  ],
  "total": 128,
  "new_events_just_created": 3
}

Norm Alerts — create subscription

Request body

Example

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  https://bancadati.doczoom.ai/api/alerts/subscriptions \
  -d '{"sub_type":"keyword","target":"superbonus","name":"Watch superbonus"}'

Backfill 7-day

Al primo poll dopo la creazione, l'API ritorna anche gli eventi degli ultimi 7 giorni (UX: l'utente vede subito attività). Poi solo eventi nuovi.

Norm Alerts — list subscriptions

Lista delle subscription attive per l'API key. Include conteggio eventi pendenti per ognuna.

Norm Alerts — toggle subscription

Attiva/disattiva una subscription senza eliminarla. Le subscription inattive non generano nuovi eventi.

Norm Alerts — delete subscription

Elimina definitivamente la subscription. Gli eventi storici restano in DB ma non saranno più mostrati.

Norm Alerts — mark event read

Marca un singolo evento come letto (setta read_at = NOW()).

Norm Alerts — mark all read

Marca TUTTI gli eventi pendenti dell'utente come letti. Response: {"marked_read": N}.

Norm Alerts — stats

Response shape

{
  "subscriptions_active": 5,
  "subscriptions_total": 7,
  "events_total": 312,
  "events_unread": 12,
  "last_scan_at": "2026-05-20T08:15:00Z"
}

Audit Stats

Aggregati audit log: tasso abstention, avg top_score, tasso citation hallucinations, success rate retrieval, ultimi N giorni. Endpoint per dashboard interna.

Response shape

{
  "period_days": 7,
  "total_queries": 12483,
  "abstention_rate": 0.034,
  "avg_top_score": 0.71,
  "hallucination_rate": 0.011,
  "reprompt_rate": 0.16,
  "factuality_flag_rate": 0.04
}

Audit Recent

Ultime N entry dell'audit_log (query, top_score, citation_hallucinations, factuality_issues, timing_ms). Per debug e fine-tuning.

Audit Analytics

Aggregati per dimensione (source citata, modulo richiesto, giorno). Restituisce time series + distribuzione.

Scheduler Status v25.101

Stato dello scheduler per ogni source: ultima ingestion, ore da ultima, cron schedule, country, ecc. Tutte le 67 fonti devono apparire con hours_since_last <= 48. Sorgente di verità per "tutte le fonti aggiornate 1×/giorno?".

Response shape

{
  "sources": [
    {
      "source": "ade_circolari",
      "country": "IT",
      "last_doc_at": "2026-05-20T08:15:00Z",
      "hours_since_last": 3,
      "scheduled": true,
      "cron_hint": "daily 08:15 UTC",
      "is_stale": false
    }
    /* ... 66 più ... */
  ],
  "stale_sources": [],
  "stale_threshold_hours": 48
}

Health — Sources freshness

Health check sulle source: ritorna HTTP 200 se tutte le 67 sources hanno ingestion entro 48h, HTTP 207 se 1-2 stale, HTTP 503 se ≥3 stale. Per integrazione UptimeRobot / Healthchecks.io.

Health — Cloudflare Proxy

Stato del Cloudflare Worker proxy per i domini gov bloccati (normattiva.it, gazzettaufficiale.it, italgiure.giustizia.it, giustizia-amministrativa.it, eur-lex.europa.eu). Ritorna HTTP 200 se tutti i 5 domini sono raggiungibili via proxy, 207 se 1-2 down, 503 se ≥3 down.

Response shape

{
  "proxy_url": "https://taxharvest-proxy.dilan-80e.workers.dev",
  "domains": [
    {"domain": "italgiure.giustizia.it", "status": 200, "latency_ms": 340},
    {"domain": "normattiva.it", "status": 200, "latency_ms": 512}
    /* ... */
  ],
  "fail_count": 0,
  "last_check_at": "2026-05-20T06:30:00Z"
}

Tools — list

Schema vivo dei tools real-time disponibili (VIES P.IVA, Codice Fiscale, cambio valuta BCE, ecc.) per il routing di /api/doczoom/tool e /api/tool/{tool_name}. Usato dal frontend per popolare bottoni "verifica P.IVA", "calcola CF", ecc.

Response shape

{
  "tools": [
    {"name": "vies", "label": "Verifica P.IVA UE (VIES)", "params": ["country", "vat_number"]},
    {"name": "codice_fiscale", "label": "Calcolo Codice Fiscale", "params": ["name", "surname", "birth_date", "birth_place", "gender"]},
    {"name": "exchange_rate", "label": "Cambio valuta BCE", "params": ["from", "to", "date"]}
  ]
}

Cassazione — full corpus v25.104

Lista delle sentenze Corte di Cassazione (336.824 docs: civile, penale, costituzionale, relazioni Massimario). Shortcut di GET /api/legal-judgments?authority=cassazione.

Query params

Example

curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/cassazione?court=Civile&year=2024&per_page=10"

Cassazione — lookup specifico

Lookup di una Cassazione specifica per numero+anno. Match su pattern "n. NUMERO/ANNO" nel title. Ritorna lista di match (di solito 1, ma può essere >1 se ci sono ordinanze + sentenze con stesso numero).

Example

curl -H "X-API-Key: $KEY" https://bancadati.doczoom.ai/api/cassazione/12345/2024
# → { numero, anno, matches: [{ id, title, court, year, case_number, ... }] }

404 quando non trovata

HTTP 404
{ "error": "cassazione_not_found", "numero": 99999999, "anno": 2024 }

TAR — Tribunali Amministrativi Regionali

Lista sentenze TAR (242.019 provvedimenti, 30 sedi regionali). Shortcut di ?authority=tar.

Query params

Example

curl -H "X-API-Key: $KEY" \
  "https://bancadati.doczoom.ai/api/tar?sede=ROMA&year=2026&per_page=20"

Consiglio di Stato + CGA + Adunanza Plenaria

Lista decisioni CdS, CGARS e Adunanza Plenaria (~20.575 docs). Shortcut di ?authority=cds.

Example

curl -H "X-API-Key: $KEY" "https://bancadati.doczoom.ai/api/consiglio-stato?year=2026"

Corte Costituzionale

Sentenze, ordinanze, decreti Corte Cost. (3.808 docs). Shortcut di ?authority=corte-costituzionale (alias ?authority=cost).

CGUE — Corte di Giustizia UE

Sentenze + comunicati IT della Corte di Giustizia dell'Unione Europea (1.410 docs).

CEDU — Corte Europea Diritti Umani

Sentenze CEDU (HUDOC) — 9 docs (corpus in espansione).

Giustizia Tributaria + Massimario CGT

Massimario delle Corti di Giustizia Tributaria (1.112 massime). Coverage CGT di primo e secondo grado.

ABF — Arbitro Bancario Finanziario

Decisioni dell'Arbitro Bancario Finanziario (280 docs). Risoluzione stragiudiziale controversie banca-cliente.

AGCM — Antitrust

Bollettini AGCM (808 docs): abuso posizione dominante, intese restrittive, concentrazioni, pratiche commerciali scorrette.

AGCOM — Autorità Comunicazioni

Delibere AGCOM (537 docs): TLC, audiovisivo, postale, copyright digitale.

🇦🇪 Sentenze UAE (ADGM + DIFC combinate)

Lista combinata sentenze UAE court (102 docs: 80 ADGM CFI + 22 DIFC). Shortcut di ?country=AE.

Query params

Example

curl -H "X-API-Key: $KEY" "https://bancadati.doczoom.ai/api/sentenze-uae?per_page=20"

🇦🇪 ADGM — Abu Dhabi Global Market

Sentenze ADGM Courts (80 docs CFI) — Court of First Instance Abu Dhabi Global Market. Common law in lingua inglese. Shortcut di ?authority=adgm&country=AE.

🇦🇪 DIFC — Dubai International Financial Centre

Sentenze DIFC Courts (22 docs) — Court of First Instance + Court of Appeal + Small Claims Tribunal Dubai. Common law in inglese. Shortcut di ?authority=difc&country=AE.

Health Check

Uptime check (no auth richiesta). Latenza tipica ~1ms.

{"status": "ok", "timestamp": "2026-04-29T11:30:00Z"}

System Info

Info sistema (versione, uptime, container memory).