DOCUMENTAZIONE API

VeritasOS API v1

API REST per la validazione crittografica di documenti AI. Ogni chiamata restituisce un risk score, una lista di anomalie normative e un certificato vrt: verificabile pubblicamente.

Base URL: https://veritas-os.it/api/v1/
Tutte le risposte sono in JSON. Tutti i timestamp sono in UTC ISO 8601.

🏦

Bancario

MiFID II, Basilea IV, Banca d'Italia, credit scoring AI

🛡️

Assicurativo

IVASS, Solvency II, IDD, underwriting AI

🏛️

CAD, AgID, Codice Appalti D.Lgs. 36/2023, ANAC

⚖️

Legale

Contratti, NDA, pareri legali, GDPR compliance

🏥

Sanitario

MDR, AIFA, ISS, AI in diagnostica

🏢

Corporate

M&A, governance, D.Lgs. 231/2001, whistleblowing

Autenticazione

Usa la tua API Key nell'header Authorization di ogni richiesta. Genera le chiavi dalla dashboard → API Keys.

Header richiesto

Authorization: Bearer vrt_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le API key iniziano sempre con vrt_live_sk_. Non condividerle mai e non includerle nel codice frontend.

POST /validate_text.php

Valida un testo direttamente. Ideale per documenti già estratti o generati da AI. Restituisce il risultato in modo sincrono.

POST https://veritas-os.it/api/v1/validate_text.php

Body: application/json

Parametri

Campo	Tipo	Descrizione
text *	string	Testo del documento da validare (max 8.000 caratteri)
filename	string	Nome file — usato per rilevare il tipo automaticamente (es. "contratto.txt", "polizza.pdf")
api_key	string	Alternativa all'header Authorization (meno sicuro)

curl

curl -X POST https://veritas-os.it/api/v1/validate_text.php \
  -H "Authorization: Bearer vrt_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "CONTRATTO DI FORNITURA\n\nTra Acme S.r.l. e Beta S.p.A....",
    "filename": "contratto_fornitura.txt"
  }'

Risposta

{
  "id": "val_a1b2c3d4e5f6",
  "status": "validated",
  "risk_score": 65,
  "risk_level": "HIGH",
  "summary": "Il contratto presenta 3 violazioni normative significative.",
  "flags": [
    {
      "type": "outdated_reference",
      "detail": "D.Lgs. 196/2003 è abrogato dal 25/5/2018",
      "severity": "high",
      "article": "GDPR Art. 94",
      "points": 25
    }
  ],
  "recommendation": "Sostituire il riferimento a D.Lgs. 196/2003 con GDPR Reg. UE 2016/679.",
  "certificate": {
    "id": "vrt:a1b2c3d4",
    "hash": "sha256:1b0e1455c3207240b7b96106bb06c0d93eb1a740513c8af1ea2d12300b82fd8f",
    "verify_url": "https://veritas-os.it/verify.php?id=vrt:a1b2c3d4",
    "issued_at": "2026-03-22T03:45:10Z"
  },
  "model": "gpt-4o-mini",
  "processing_ms": 4230
}

POST /api_batch.php — Batch Validation

Valida fino a 50 documenti in una sola chiamata. Risposta sincrona con tutti i risultati. Webhook opzionale al completamento.

POST https://veritas-os.it/api/v1/batch

curl — batch file upload

curl -X POST https://veritas-os.it/api/v1/batch \
  -H "Authorization: Bearer vrt_live_sk_..." \
  -F "documents[][email protected]" \
  -F "documents[][email protected]" \
  -F "documents[][email protected]" \
  -F "webhook_url=https://tuosito.it/webhook"

curl — batch testi JSON

curl -X POST https://veritas-os.it/api/v1/batch \
  -H "Authorization: Bearer vrt_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"texts":[{"text":"Contratto...","filename":"c1.txt"},{"text":"Polizza...","filename":"c2.txt"}]}'

Risposta JSON

{
  "success": true,
  "batch_id": 42,
  "total": 3, "processed": 3, "failed": 0,
  "cost_eur": 0.00,
  "results": [
    {
      "filename": "contratto1.pdf",
      "status": "validated",
      "risk_score": 72,
      "risk_level": "HIGH",
      "cert_id": "vrt:a1b2c3d4",
      "cert_url": "https://veritas-os.it/verify.php?id=vrt:a1b2c3d4",
      "cost_eur": 0.00
    }
  ],
  "status_url": "https://veritas-os.it/api/v1/batch?batch_id=42"
}

Controlla stato batch (GET)

curl https://veritas-os.it/api/v1/batch?batch_id=42 \
  -H "Authorization: Bearer vrt_live_sk_..."

🏦 Esempi Settore Bancario

Il motore di validazione riconosce automaticamente documenti con terminologia MiFID II, Basilea IV e Banca d'Italia e applica il prompt specializzato bancario.

I documenti con termini come "adeguatezza", "portafoglio titoli", "requisiti patrimoniali", "credit scoring" attivano automaticamente il profilo bancario con controlli specifici per MiFID II Art. 25, CRR III e Circolare Banca d'Italia 285.

Caso d'uso: Validazione contratto MiFID II

Python

# Validazione contratto MiFID II con VeritasOS Python SDK
from veritas_os import VeritasOS

client = VeritasOS(api_key="vrt_live_sk_...")

# Valida contratto di investimento
result = client.validate_text(
    text=contratto_mifid_text,
    filename="contratto_investimento_mifid.txt"
)

if result.is_high_risk:
    print(f"⚠ ALTO RISCHIO: score {result.risk_score}/100")
    for flag in result.flags:
        print(f"  - {flag.type}: {flag.detail}")
        print(f"    Riferimento: {flag.article}")
else:
    print(f"✓ Conforme — certificato: {result.certificate.id}")

Anomalie tipiche rilevate nei documenti bancari

Tipo Anomalia	Severità	Riferimento
mifid_violation	HIGH +25pt	Mancata valutazione adeguatezza/appropriatezza — MiFID II Art. 25
capital_requirement_error	HIGH +25pt	Calcolo errato requisiti patrimoniali — CRR III Reg. UE 2019/876
unregulated_guarantee	HIGH +25pt	Garanzia rendimento/capitale senza prospetto — TUF Art. 94
ai_credit_scoring_gap	MEDIUM +15pt	AI per credit scoring senza human oversight — EU AI Act Art. 14
gdpr_profiling	MEDIUM +15pt	Profiling creditizio senza base giuridica — GDPR Art. 22

🛡️ Esempi Settore Assicurativo

Rilevamento automatico per documenti con terminologia IVASS, Solvency II, IDD. Controlli specifici su polizze, IPID e underwriting AI.

JavaScript — validazione polizza RC

const { VeritasOS } = require('./veritas-os');
const client = new VeritasOS({ apiKey: 'vrt_live_sk_...' });

// Valida polizza RC professionale
const result = await client.validateText(
  polizzaText,
  'polizza_rc_professionale.txt'
);

// Aggiungi a Google Sheets tramite webhook
await client.createWebhook(
  'https://hooks.zapier.com/hooks/catch/...',
  ['validation.completed', 'risk.critical'],
  50 // solo score >= 50
);

Anomalie tipiche rilevate nelle polizze

Tipo Anomalia	Severità	Riferimento
ivass_violation	HIGH +25pt	Violazione obblighi informativi — Reg. IVASS n. 41/2018
misleading_coverage	HIGH +25pt	"Copertura totale" senza esclusioni elencate — IDD Art. 17
prescription_error	MEDIUM +15pt	Termine prescrizione sinistri errato — Art. 2952 c.c.
ai_underwriting_risk	MEDIUM +15pt	AI per underwriting senza trasparenza — EU AI Act Art. 13
idd_breach	MEDIUM +15pt	IPID mancante o incompleto — IDD Art. 20

🏛️ Esempi Pubblica Amministrazione

Supporto completo per il nuovo Codice Appalti D.Lgs. 36/2023, CAD e linee guida AgID sull'AI nella PA.

Python — batch validazione bandi di gara

# Valida un batch di bandi di gara
client = VeritasOS(api_key="vrt_live_sk_...")

bandi = [
    {"text": bando1_text, "filename": "bando_it_2026.txt"},
    {"text": bando2_text, "filename": "capitolato_servizi.txt"},
]

batch = client.validate_batch(bandi)
print(f"Validati: {batch.succeeded}/{batch.total}")

for result in batch.results:
    if result['status'] == 'validated':
        print(f"📋 {result['filename']}: {result['risk_score']}/100")
        if result['risk_score'] >= 50:
            print(f"   ⚠ {result['issues_count']} anomalie")

Anomalie tipiche nei documenti PA

Tipo Anomalia	Severità	Riferimento
appalti_error	HIGH +25pt	Soglie o criteri aggiudicazione errati — D.Lgs. 36/2023
dpo_missing	HIGH +25pt	DPO obbligatorio non nominato — GDPR Art. 37
ai_pa_gap	MEDIUM +15pt	AI senza trasparenza verso cittadini — EU AI Act Art. 13
anticorruzione_gap	MEDIUM +15pt	Piano anticorruzione mancante — L. 190/2012
cad_violation	MEDIUM +15pt	Documento digitale non conforme — D.Lgs. 82/2005

Python SDK

Installa con: pip install requests — poi scarica veritas_os.py nella tua directory.

Uso base

from veritas_os import VeritasOS

client = VeritasOS(api_key="vrt_live_sk_...")

# Valida testo
result = client.validate_text("testo del documento", "doc.txt")
print(result.risk_score, result.risk_level)
print(result.certificate.verify_url)

# Batch
batch = client.validate_batch([
    {"text": "doc1", "filename": "contratto.txt"},
    {"text": "doc2", "filename": "polizza.txt"},
])
print(f"{batch.succeeded}/{batch.total} validati")

JavaScript / Node.js SDK

Scarica veritas-os.js e importalo nel tuo progetto. Funziona sia in Node.js che nel browser.

Node.js

const { VeritasOS } = require('./veritas-os');
const client = new VeritasOS({ apiKey: 'vrt_live_sk_...' });

const result = await client.validateText(text, 'documento.txt');
console.log(result.riskScore, result.riskLevel);
console.log(result.certificate.verifyUrl);

Codici di Errore

Codice HTTP	Errore	Soluzione
401	API key mancante o non valida	Verifica l'header Authorization e che la chiave sia attiva
422	Parametri non validi	Controlla che il campo "text" sia presente e abbia almeno 30 caratteri
429	Rate limit superato	Aspetta 60 secondi. Piano API Scale: contatta supporto per aumentare i limiti
500	Errore interno	Riprova dopo 30 secondi. Se persiste: [email protected]

Pronto a integrare VeritasOS?

14 giorni gratuiti, nessuna carta richiesta.

Inizia Trial Gratuito →