Leggere un documento e restituire i campi, non un discorso.

Cosa fa

Tre capacità, un solo contratto:

• Legge — documento in entrata, testo in markdown con le tabelle ricostruite.
• Estrae — documento più uno schema di campi (o un tipo noto, per esempio la bolletta italiana di luce e gas), campi in JSON con una confidenza per campo.
• Descrive — immagine in entrata, descrizione in parole; il ramo che non identifica le persone.

Formati: PDF con strato testo, PDF scansionati, immagini di scansione e foto da telefono (prospettiva, ombre, pieghe, compressione). La foto è l'esame difficile, ed è quello su cui ci misuriamo.

La regola che ci distingue: mai un valore inventato

Ogni campo passa per un validatore deterministico prima di uscire: POD e PDR, codice fiscale e partita IVA con la cifra di controllo, IBAN con il modulo 97, coerenza delle date del periodo, somma delle fasce F1+F2+F3 uguale al totale, imponibile più IVA uguale al totale da pagare. Un campo che non passa torna null, il suo nome entra nella lista da_verificare e motivi dice con quale controllo è caduto: non torna mai un valore verosimile e sbagliato. L'errore che costa di più, in un processo automatico, è quello dato per certo.

Sovranità, in concreto

• I documenti restano sulle macchine di Agile; nessun inoltro a servizi di terzi.
• Nei registri non entra il contenuto, e i registri sono due: nel log del fronte, di ogni lavoro, restano solo impronta del file (sha256 troncato), numero di pagine e millisecondi; nel registro delle operazioni restano solo chi, quando e cosa (tenant, licenze, chiavi, motori). Di un documento servito, nel deposito, resta un numero in fattura — non una riga.
• Il fronte e il motore sono separati: si aggiunge capacità aggiungendo motori, e per chi chiama non cambia nulla — stesso nome, stesso contratto, stessa chiave.

Per chi

• Aziende che ricevono documenti e oggi li ribattono a mano: bollette di energia, certificati, cedolini, fatture, contratti, verbali.
• Prodotti che hanno bisogno della vista: un gestionale che deve leggere l'allegato appena arrivato, un'app che fa scattare la foto al cliente e vuole i campi subito.
• Terzi, con API a licenza: chi integra AgilePixel nel proprio prodotto e a sua volta serve i propri clienti. La licenza è del cliente che paga, i suoi clienti sono sotto-tenant, e la misura d'uso è per licenza.

Chi chiama non ha bisogno di sapere dove gira il motore, né di cambiare qualcosa quando i motori diventano due o dieci.

Piani

Una licenza per tenant, con piano, ambiti, quota mensile, limite al minuto e scadenza. Le chiavi API stanno sotto la licenza: si emettono, si ruotano e si revocano dalla console del tenant senza toccare la licenza.

Quote e limiti sopra sono quelli che il servizio applica davvero, non un depliant. Il prezzo su richiesta vale per tutti e tre i piani: si concorda con Agile insieme al volume atteso e al livello di servizio. Superata la quota la licenza non si rompe: risponde quota_superata, con il conteggio del mese in dettaglio. Il limite al minuto si conta a minuto d'orologio, non su una finestra che scorre: a cavallo di due minuti possono passare fino al doppio delle richieste dichiarate in pochi secondi.

Il limite al minuto è un tetto su di te, non un posto riservato. I posti di lavoro — quanti documenti il servizio tiene in lavorazione e quanti ne tiene in attesa — sono del servizio e si dividono con tutti gli altri clienti: la coda non sa di chi è il lavoro. Perciò coda_piena (503) può arrivarti per il traffico di un altro cliente, con la tua quota intera e alla tua prima richiesta del minuto. Non è un guasto e non ti costa quota: è un 503 e si ritenta, con attesa che raddoppia. Misurato dal vivo il 3/10/2026 con due clienti veri: il secondo, che aveva fatto una sola richiesta, ha preso coda_piena in 55 ms senza consumare quota, e la porta gli è restata chiusa 18,6 secondi, il tempo dei lavori che aveva davanti. Quanta coda spetti a ciascun cliente è una scelta ancora aperta: quando ci sarà un numero, questa riga lo dirà. I dettagli in API.md, limiti e regole.

Documentazione API

Il contratto è versionato e pubblicato: /openapi.json (OpenAPI), la guida per chi integra è in API.md, e le pagine di prova interattive stanno su /documentazione. Gli errori hanno un nome stabile (per esempio chiave_sconosciuta, quota_superata, nessun_motore_disponibile): si programma contro il nome, non contro il testo.

Una chiamata

curl -X POST https://api.agilepixel.agile.software/v1/documenti/estrai \
  -H "Authorization: Bearer <chiave>" \
  -F "documento=@bolletta.pdf" \
  -F "tipo=bolletta_luce"

La risposta

{
  "lavoro": "lav_9f2c41d7a3b05e62",
  "motore": "motore-1",
  "pagine": 2,
  "ms": 1840,
  "ms_fronte": 1902,
  "campi": {
    "pod":                  "IT001E12345678",
    "periodo_dal":          "2026-07-01",
    "periodo_al":           "2026-08-31",
    "consumo_totale":       412.0,
    "totale_da_pagare":     118.34,
    "potenza_impegnata_kw": null
  },
  "confidenze": {
    "pod":                  0.99,
    "periodo_dal":          0.98,
    "periodo_al":           0.98,
    "consumo_totale":       0.97,
    "totale_da_pagare":     0.96,
    "potenza_impegnata_kw": null
  },
  "da_verificare": ["potenza_impegnata_kw"],
  "motivi": { "potenza_impegnata_kw": ["potenza_implausibile"] }
}

L'ultimo campo è il punto: il motore aveva letto una potenza impossibile per un'utenza domestica, e il servizio la azzera e lo dice invece di consegnare un numero verosimile e sbagliato. La stessa chiamata su /v1/documenti/leggi restituisce il testo, su /v1/immagini/descrivi la descrizione.

Chiavi e uso

Il tenant governa le sue chiavi da /console/licenze: emissione, rotazione con 24 ore di grazia sulla chiave vecchia (il tempo di aggiornare i sistemi senza un minuto di buco) e revoca immediata. Il consumo si legge da /console/licenze/{id}/uso, mese per mese, in pagine e immagini.

Confronto col leader

Ci misuriamo su un banco a due bracci: le stesse pagine passano dal nostro motore e dal leader di mercato, e si confrontano i campi con la verità a terra. Le celle qui sotto le riempie il banco: nessun numero di qualità è scritto a mano su questa pagina, e finché una misura non esiste la cella dice «non ancora misurato». Il metro e gli obiettivi sono pubblici nel nostro documento di target; i numeri pubblicati dai fornitori terzi non li spacciamo per nostre misure.

Come si legge: solo pagine sintetiche, mai documenti di clienti; la verità a terra è generata insieme alle pagine, quindi è esatta al centesimo; tolleranza zero sugli importi; il braccio del leader gira sulle stesse pagine nello stesso giro. Quando una riga cambia, cambia perché il banco è girato di nuovo.

Stato del servizio

Lo stato qui sopra è quello vero, letto nel momento in cui questa pagina è stata composta, dallo stesso /health che usano i nostri sistemi. Quando non c'è un motore pronto il servizio lo dice: non esiste un «tutto bene» di cortesia.

Richiedi una licenza

Lascia due righe: rispondiamo all'indirizzo che indichi, con il piano adatto al volume e il prezzo. Chiediamo solo quello che serve per rispondere.

Il modulo funziona senza JavaScript. Il servizio risponde con un numero di richiesta: conservalo, è il riferimento della pratica. C'è un limite di richieste per indirizzo di rete, per tenere fuori gli automi.