Panoramica API

URL di base

https://api.factum.pyragogy.org

⬇ Scarica OpenAPI Spec (JSON)

openapi.json

Scarica Postman Collection (JSON) Apri in Postman

postman_collection.json

Importabile in Postman, Insomnia, Bruno

L’API è basata su FastAPI/OpenAPI. Il deployment su marketplace è un canale di distribuzione proxy; l’URL pubblico e l’iniezione dell’autenticazione non corrispondono necessariamente al contratto API d’origine.

Autenticazione

Gli endpoint business richiedono:

X-API-Key: <la-tua-chiave-api>

Il backend è fail-closed: una chiave mancante o non valida restituisce 401 Unauthorized. Il confronto usa secrets.compare_digest.

Endpoint pubblici:

• GET /health
• GET /status

Sorgenti richiesta

POST /v1/parse accetta esattamente una sorgente:

Campo	Tipo	Obbligatorio	Note
job_id	UUID	XOR	Job restituito da /v1/uploads
text	string	XOR	Input stateless, scope richiesta
doc_type	enum	no	auto, fattura, f24, generico; default auto
async_mode	boolean	no	Modalità async; non valida con text
callback_url	URL HTTP	no	Solo con async_mode=true

job_id e text sono mutuamente esclusivi — uno dei due deve essere presente.

Upload

POST /v1/uploads accetta un singolo campo multipart:

file=<XML o PDF>

Non esiste un campo filename separato nel contratto backend; FastAPI riceve il nome file come metadata UploadFile.filename.

Il limite di trasporto e semantico è 10 MiB (max_body_bytes e max_upload_bytes). Le classi documentali supportate sono FatturaPA XML e fattura PDF.

💨 Latenze di elaborazione (misurate)

Latenza end-to-end, dal momento in cui il documento entra nell’API alla risposta completa. Scala logaritmica: i percorsi deterministici rispondono in millisecondi, il percorso LLM in secondi.

Percorso	Latenza misurata	Motore	Note
Estrazione a regole (in-memory)	~0.03 ms (P50)	Deterministico	Nessun LLM
HTTP API — 1 richiesta	~2.5 ms (P50)	Deterministico	Benchmark stack reale
FatturaPA XML — end-to-end	~12 ms	Deterministico	Consigliato per integrazioni
PDF testuale (estrazione + LLM)	~10–15 s	LLM (deepseek-v3)	Margine di miglioramento in roadmap
PDF scansionato	non supportato	—	HTTP 422 scanned_document

Cosa significa per te

• Integrazioni XML (FatturaPA): percorso deterministico, ~12 ms, nessun LLM. È la via maestra consigliata: bassa latenza, costo stabile, risultato garantito dalla quadratura verificata (totale ≈ imponibile + IVA).
• PDF testuale: supportato, ma il percorso LLM richiede ~10–15 s. Il margine di miglioramento su questa latenza è in roadmap — resta un percorso valido per documenti non strutturati (fatture estere, F24, testi liberi).
• PDF scansionati (senza testo selezionabile): rifiutati con 422 (scanned_document). È una scelta architetturale dichiarata: Factum elabora de documenti digitali, non immagini. La latenza di ogni percorso è misurata e monitorata via Prometheus.

Raccomandazione: per integrazioni di produzione usa FatturaPA XML — la latenza è ~12 ms e il risultato è deterministico. Usa il percorso testo/PDF solo quando il documento non è disponibile in formato XML.

Rate limiting

Il rate limiting è configurabile tramite impostazioni d’ambiente. Quando attivato (header X-Tier: free | basic | pro), il middleware può emettere 429 Too Many Requests.

Limiti correnti (da app/services/ratelimit.py):

Tier	Limite	Finestra
free	60 req/min	1 min
basic	100 req/min	1 min
pro	1000 req/min	1 min

Livelli di risposta

Esistono due contratti distinti:

1. DocumentResponse — metadata di ingestion/job restituiti da /v1/uploads e /v1/uploads/{job_id}.
2. ParseResponse — metadata di esecuzione del parsing più result: DocumentEnvelope | null.

DocumentEnvelope v2 è il risultato strutturato canonico dentro ParseResponse.result. Vedi Schemi.

Request ID

Il backend accetta correntemente X-Request-Id su POST /v1/uploads e lo usa come valore instance RFC 7807 quando viene generato un errore upload.

Un header X-Request-ID globale in risposta non è attualmente implementato su tutte le rotte. Non documentarlo come garanzia universale finché il backend non aggiunge e testa quel middleware.

Questo è debito documentale intenzionale, non una funzionalità inventata.