Factum Parse API

Parsing fiscale: 100% zero retention. Non salviamo niente, non mandiamo nulla in chiaro, non addestriamo nulla sui tuoi dati.

Prova gratis su Zyla API Hub API Reference Pack occasionale €9,99

Cosa facciamo e cosa no

Un parser fiscale. Non un archivio. Non un magazzino dati. Non un motore di training.

Fa.

Estrae fatture, F24 e documenti fiscali — XML FatturaPA, PDF testuale, testo libero — in JSON strutturato e validato, con quadratura verificata.
Pseudonimizza ogni dato sensibile (22 categorie) prima di ogni chiamata AI. Il modello vede placeholder, mai i tuoi dati.
Elabora 100% in RAM: zero scrittura su disco, zero retention, zero training sui tuoi documenti.
Risponde deterministico sull’XML in ~12 ms, senza toccare nessun modello.

Non fa.

Non fa OCR. Un PDF scansionato viene rifiutato con un errore pulito (HTTP 422). Non inventiamo testo che non c’è.
Non manda dati in chiaro a nessun modello. Se la pseudonimizzazione non è disponibile, il sistema si ferma (HTTP 503). Mai un degrado.
Non conserva nulla. Dopo la risposta, del tuo documento non esiste più nulla: né file, né dizionario, né log dei contenuti.

Se ti serve questo, in un minuto lo provi. Se non ti serve, non ti abbiamo fatto perdere tempo.

⚡️ Quickstart — Prima chiamata in < 60s

Invia un payload testuale (fattura, F24, testo libero) e ottieni un DocumentEnvelope v2 strutturato. Autenticazione: header X-API-Key.

Prima chiamata rapida Raw Text / JSON — testa l’endpoint in 30 secondi con un payload testuale. Per flussi di produzione con PDF/XML/multipart, vedi Riferimento endpoint.

curl -X POST https://api.factum.pyragogy.org/v1/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Fattura n. 2026/001 del 15/03/2026. Cedente: ACME S.r.l. — Via Roma 1, Milano. P.IVA IT01234567890. Cliente: Mario Rossi. Totale documento: € 1.220,00. Imponibile: € 1.000,00. IVA 22%: € 220,00.",
    "doc_type": "auto"
  }'

import httpx

payload = {
    "text": "Fattura n. 2026/001. Cedente: ACME S.r.l. Totale: € 1.220,00.",
    "doc_type": "auto",
}

resp = httpx.post(
    "https://api.factum.pyragogy.org/v1/parse",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json=payload,
)
resp.raise_for_status()
print(resp.json())

// Replace with your actual API key
const API_KEY = "YOUR_API_KEY";

const response = await fetch("https://api.factum.pyragogy.org/v1/parse", {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Fattura n. 2026/001. Cedente: ACME S.r.l. Totale: € 1.220,00.",
    doc_type: "auto",
  }),
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    body := []byte(`{"text":"Fattura n. 2026/001. Cedente: ACME S.r.l. Totale: € 1.220,00.","doc_type":"auto"}`)
    req, _ := http.NewRequest("POST", "https://api.factum.pyragogy.org/v1/parse", bytes.NewReader(body))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    fmt.Println(res.Status)
}

<?php
$apiKey = 'YOUR_API_KEY'; // Sostituisci con la tua chiave
$ch = curl_init('https://api.factum.pyragogy.org/v1/parse');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'text' => 'Fattura n. 2026/001. Cedente: ACME S.r.l. Totale: € 1.220,00.',
        'doc_type' => 'auto',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
curl_close($ch);
echo $response;

⚡

Consigliato per integrazioni di produzione: FatturaPA XML. Percorso deterministico: ~12 ms end-to-end, nessun LLM, costo stabile. Il percorso PDF testuale estrae con LLM in ~10–15 s (margine di miglioramento in roadmap); i PDF scansionati non sono supportati (HTTP 422). Dettagli e grafico: Latenze di elaborazione.

🧪 Prova rapida nel browser

Inserisci la tua X-API-Key e un estratto di documento per testare l’endpoint direttamente dal browser. La risposta viene visualizzata con syntax highlighting.

🔑 X-API-Key

🎯 Preset rapidi

📄 Testo documento

📋 Tipo documento

Mostra payload pseudonimizzato (Rizzo PII)

🛡️ Payload pseudonimizzato (inviato all’LLM)

📦 Risposta JSON

⚠️ Esecuzione dimostrativa con rate-limiting. La chiave non viene memorizzata né inviata a terze parti.

Risposta — `ParseResponse` con `DocumentEnvelope v2`

{
  "job_id": "3f2b5e6a-0000-4000-8000-000000000001",
  "status": "done",
  "document_type": "invoice",
  "provider_used": "fast-path",
  "prompt_version": "fast-path-v1",
  "confidence": 1.0,
  "cost_usd": 0.0,
  "tokens": 0,
  "fallbacks": [],
  "content_hash": "a1b2c3d4e5f67890abcdef1234567890abcdef12",
  "result": {
    "schema_version": "2.0",
    "document_type": "invoice",
    "meta": {
      "confidence": 1.0,
      "provider": "fast-path",
      "prompt_version": "fast-path-v1"
    },
    "payload": {
      "kind": "invoice",
      "dati_trasmissione": {
        "IdTrasmittente": { "IdPaese": "IT", "IdCodice": "01234567890" }
      },
      "cedente_prestatore": {
        "Denominazione": "ACME S.r.l.",
        "Indirizzo": "Via Roma 1, Milano",
        "PartitaIVA": "IT01234567890"
      },
      "cessionario_committente": {
        "Denominazione": "Mario Rossi"
      },
      "corpi": [
        {
          "DatiGenerali": {},
          "DatiBeniServizi": {
            "DettaglioLinee": [
              { "Descrizione": "Servizio di consulenza", "PrezzoTotale": 1000.00 }
            ]
          }
        }
      ]
    }
  },
  "error": null
}

XML deterministico Le fatture elettroniche strutturate passano per il fast-path deterministico — nessun token LLM consumato.

🔐 Sicurezza e Zero Data Retention (ZDR)

Flusso architetturale

Legenda: linea verde = fast-path deterministico (XML FatturaPA/UBL), linea gialla = percorso LLM (PDF/testo, pseudonimizzato via Rizzo).

Basato su Rizzo PII — Engine Privacy Open Source

Basato su Rizzo PII — Engine Privacy Open Source

Rizzo PII è il nostro engine open-source per la sanitizzazione deterministica di informazioni personali in memoria volatile, integrato come layer di sanitizzazione in-memory prima dell’elaborazione dello schema. Per deployment self-hosted/enterprise è configurabile come sidecar dedicato nella stessa VPC.

Latenza sub-millisecondo: sanitizzazione PII in RAM volatile, zero I/O su disco.
22 categorie PII: mascheramento regex & pattern-based per Codice Fiscale, IBAN, numeri di telefono, email, partite IVA, e altre 17 categorie documentali.
Trasparenza verificabile: codice aperto su GitHub, audit-ready per DPO/GDPR.
Fail-closed: sidecar irraggiungibile → HTTP 503. Nessun testo in chiaro all’LLM.

La matrice completa dei controlli GDPR (Art. 5, 25, 28, 32) è nella pagina dedicata Compliance (GDPR). I controlli chiave:

Minimizzazione: RAM-only per POST /v1/parse con text — nessuna persistenza su DB.
Pseudonimizzazione: Rizzo PII prima di ogni chiamata LLM — 22 categorie sostituite in-RAM.
Fail-closed: Rizzo irraggiungibile → 503. Nessun testo in chiaro all’LLM.
Autenticazione: X-API-Key con secrets.compare_digest(). Chiave assente → 401.

Fail-closed Se il sidecar Rizzo non è raggiungibile → HTTP 503. Il sistema non degrada mai a testo scoperto.

💰 Canali di acquisto

Factum Parse è disponibile su due canali, a seconda delle tue esigenze.

📡 Zyla API Hub — abbonamento (consigliato)

Tier	Prezzo / mese	Richieste / mese	Rate limit	Ideale per
Basic	$24.99	2.000	60 req/min	Test, volumi bassi
Pro	$49.99	5.000	120 req/min	Produzione, volumi medi
ProPlus	$99.99	15.000	180 req/min	Volumi medio-alti
Premium	$199.99	40.000	240 req/min	Produzione intensiva
Elite	$499.99	120.000	240 req/min	Volumi alti
Ultimate	$999.99	300.000	240 req/min	Enterprise

✓ Nessun costo fisso: un cliente Basic paga $24.99 e ha 2.000 richieste.
✓ La chiave API viene generata automaticamente alla sottoscrizione.
✓ Zyla gestisce pagamenti, fatturazione, rate limiting e crediti per tier.

➡️ Abbonati su Zyla API Hub

🍋 Lemon Squeezy — pack una tantum

Per chi usa Factum ogni tanto e non vuole un abbonamento:

Prodotto	Prezzo	Elaborazioni
Pack 100 documenti	€9,99 una tantum	100 elaborazioni

Nessun rinnovo automatico. La License Key viene attivata alla conferma dell’ordine e vale fino a esaurimento chiamate.

➡️ Acquista pack 100 doc — €9,99

Superficie API

Metodo	Route	Auth	Scopo
`GET`	`/health`	—	Sonda di liveness
`GET`	`/status`	—	Stato operativo pubblico
`POST`	`/v1/parse`	`X-API-Key`	Parsing sincrono (XML/PDF/text)
`POST`	`/v1/uploads`	`X-API-Key`	Ingest asincrono (file pesanti)
`GET`	`/v1/uploads/{job_id}`	`X-API-Key`	Polling risultato

Tutti gli errori seguono RFC 7807 (application/problem+json). Vedi Errori e Rate Limit.

⬇ Specifica OpenAPI (JSON)

/openapi.jsonImportabile in Postman, Insomnia, generatori SDK

⬇ Raccolta Postman (JSON)

▶️ Apri in Postman

/postman_collection.json7 endpoint, 7 esempi, preconfigurato

Niente JSON piatto Ogni risposta è un DocumentEnvelope v2 validato da Pydantic con unione discriminata sul campo kind.

Inizia in 3 minuti

Abbonati su Zyla (free trial incluso) o acquista il pack LS per uso occasionale
Copia la tua API Key dal marketplace / email di conferma
Invia il tuo primo documento — ricevi un envelope strutturato in < 1 secondo

💬 Supporto & Contatti

Per supporto tecnico, contratti enterprise e informazioni commerciali:

Email: info@pyragogy.org
GitHub Issues: factum-community — segnalazioni bug, richieste parser, discussioni
Documentazione: docs.factum.pyragogy.org