Endpoint REST che riceve un capitolato tecnico o un disciplinare di gara in PDF e restituisce JSON: i requisiti estratti uno per uno, le norme citate, i materiali, le prove — e, in più di quanto faccia lo strumento web, l’albero delle sezioni del documento con numerazione, titoli e numero di pagina, e ogni requisito ancorato al suo § e alla sua pagina. Il dato che il tuo software mostra all’utente porta con sé il punto del PDF da cui viene: CAPO III > 29.2, pagina 24. Costo: 2 crediti per documento (da €0,98 a €1,96 secondo il pacchetto di ricarica).
Questo strumento non è ancora disponibile: lo stiamo preparando con la stessa cura del resto del motore.
Guarda un esempio di risultato
Cosa fa, e cosa aggiunge rispetto allo strumento web
Il motore è lo stesso di Specifica Tecnica → JSON: estrae oggetto, requisiti, norme_citate, materiali, prove_collaudi ed esclusioni. Quello strumento consegna anche la matrice di conformità in Excel, e ha promesso ai suoi clienti che i nomi delle sue chiavi non cambiano: per questo il blocco descritto qui sotto arriva solo su questo canale.
Chi integra un’API su un capitolato ha un problema che l’ufficio tecnico non ha: il dato estratto non gli basta, gli serve rimandare il suo utente al punto del documento. Nella matrice di conformità è la colonna «Evidenza (documento, §)», e sullo strumento web arriva vuota. Qui il blocco sezioni la riempie: la struttura del documento ricostruita dal testo, e per ogni requisito il paragrafo e la pagina in cui si trova. Tutto questo è letto dal documento, non chiesto a un modello: nessuna chiamata IA in più, nessun costo in più, e una sezione che il documento non ha non può comparire.
La conseguenza più utile è un controllo di verità che arriva gratis. Un’ancora si scrive solo se il testo del valore si ritrova nel documento, tollerando i soli andata a capo del PDF. Quando non si ritrova, il valore finisce in senza_ancora con il motivo scritto, invece di prendersi un paragrafo a indovinare: è il modo in cui un requisito riscritto dal modello si fa riconoscere. Misurato su un capitolato pubblico vero: il documento cita UNI EN ISO 9000, e un valore scritto UNI EN ISO 9001 non riceve l’ancora e viene dichiarato.
Il contratto tecnico
L’endpoint pubblico non è ancora aperto (vedi «Stato» in fondo). Il contratto qui sotto è però quello del codice che gira già oggi per lo strumento web, non una bozza: base REST https://megaengine.it/wp-json/mega-engine/v1/, chiavi API a scope limitato conservate solo come hash, modello asincrono — crei un lavoro e leggi l’esito quando è pronto.
# 1. crea il lavoro (multipart, UN file per lavoro)
curl -X POST https://megaengine.it/wp-json/mega-engine/v1/jobs
-H "X-API-Key: $ME_API_KEY"
-F "product=specification-to-json-api"
-F "file=@capitolato.pdf"
# → 201 {"uuid":"7b1e…","status":"queued","credits_charged":2}
# 2. leggi lo stato (polling: non esiste ancora un webhook di completamento)
curl https://megaengine.it/wp-json/mega-engine/v1/jobs/7b1e…
-H "X-API-Key: $ME_API_KEY"
# → {"status":"succeeded","output":{"summary":[…],"preview":[…]}}
# 3. scarica il JSON intero (con `fields` e `sezioni`)
curl -L https://megaengine.it/wp-json/mega-engine/v1/jobs/7b1e…/download
-H "X-API-Key: $ME_API_KEY" -o capitolato.json| Cosa | Valore |
|---|---|
| Autenticazione | X-API-Key: <chiave> oppure Authorization: Bearer <chiave>; chiavi create e revocate da /app/ |
| Creazione lavoro | POST /jobs — multipart, campi product e file |
| Stato ed esito | GET /jobs/<uuid> — in polling: nessun webhook di completamento |
| File del risultato | GET /jobs/<uuid>/download — disponibile 14 giorni |
| Annullamento | POST /jobs/<uuid>/cancel |
| Scheda del prodotto | GET /products/specification-to-json-api |
| Errori | 401 chiave assente o revocata · 402 crediti finiti · 400 file rifiutato (estensione, peso, PDF illeggibile o protetto) · 429 troppe richieste · 5xx guasto nostro: il lavoro fallisce e i crediti tornano |
| Tetti | 50 lavori al giorno per account · 15 MB per file · 80 pagine e ~280.000 caratteri per documento |
| Versione | v1. Non pubblichiamo ancora un impegno scritto di preavviso sulla deprecazione: se ti serve, chiedilo prima di integrare. |
Input supportati
Solo PDF con testo selezionabile, fino a 15 MB, in italiano o in inglese: capitolati speciali d’appalto, disciplinari di gara, capitolati prestazionali, specifiche e schede tecniche. DOCX non è accettato e viene rifiutato con 400: se le tue specifiche girano in Word, convertile in PDF prima di chiamare. I PDF fatti solo di immagini — le scansioni che non sono passate da un OCR — non sono ancora supportati: l’elaborazione si ferma subito, viene segnalata come non riuscita e non ti viene addebitato nulla. I PDF protetti da password vengono rifiutati allo stesso modo: senza la password le pagine non si aprono, l’elaborazione si ferma subito e non ti viene addebitato nulla. Apri il file con la sua password, salvane una copia senza protezione e manda quella. Un documento in parte digitale e in parte scansionato — una pagina fotografata, un allegato firmato a mano — viene elaborato e addebitato, perché il testo delle altre pagine c’è: in quel caso il risultato ti dice quali pagine non contenevano testo selezionabile e che il loro contenuto non è nel file, invece di dichiararsi completo. Se invece da quelle pagine non esce nessuno dei dati che questo endpoint estrae — è il caso della copertina digitale generata dal gestionale sopra un documento fotocopiato — l’elaborazione si ferma, non ti viene addebitato nulla e il messaggio ti dice quante pagine sono immagini: il gesto che sblocca è passare il PDF per un OCR, non caricare un altro file.
Ogni elaborazione legge al massimo le prime 80 pagine e, dentro quelle, circa 280.000 caratteri: i due tetti sono tarati per mordere nello stesso punto. Un capitolato da 300 pagine viene quindi letto in parte, non per intero, e il risultato dichiara sempre a quale pagina la lettura si è fermata (quality.pages_processed su pages_total). Se i dati obbligatori erano tutti dentro le pagine lette il file ti viene consegnato e i crediti restano spesi; se un dato obbligatorio è rimasto oltre il taglio l’elaborazione si ferma e non ti viene addebitato nulla. Per coprire un documento lungo, spezzalo in più PDF e chiama più volte, tenendo in ciascuno anche le pagine iniziali: il blocco sezioni del primo lavoro ti dice dove tagliare con un criterio invece che a occhio.
Il risultato
Il file scaricabile è un JSON con fields — gli stessi campi e gli stessi nomi dello strumento web: oggetto; requisiti (identificativo, testo, parametro, valore, unita_misura, tolleranza); norme_citate (norma, titolo, dove_compare); materiali; prove_collaudi; esclusioni. Una chiave che il documento non riempie arriva a null invece di sparire, quindi il file si mappa una volta sola. Accanto, not_found elenca i campi che il documento non conteneva e quality riporta le pagine elaborate su quelle totali.
E il blocco sezioni, che c’è solo qui:
"sezioni": {
"trovate": 27,
"profondita": 2,
"pagine_lette": 42,
"albero": [ {
"numero": "CAPO III",
"titolo": "DISPOSIZIONI PER L'ESECUZIONE DEL CONTRATTO",
"livello": 1, "pagina": 14,
"figli": [
{ "numero": "29.1", "titolo": "Disposizioni generali",
"livello": 2, "pagina": 24, "figli": [] },
{ "numero": "29.2",
"titolo": "Penali per ritardato adempimento",
"livello": 2, "pagina": 24, "figli": [] } ] } ],
"indice": [ {
"numero": "29.2", "livello": 2, "pagina": 24,
"titolo": "Penali per ritardato adempimento",
"percorso": "CAPO III > 29.2" } ],
"ancore": [ {
"campo": "requisiti", "posizione": 1,
"identificativo": "R-07",
"sezione": "14.2",
"titolo_sezione": "Risoluzione del Contratto",
"percorso": "CAPO II > 14.2",
"pagina": 13 } ],
"senza_ancora": [ {
"campo": "requisiti", "posizione": 0,
"identificativo": "R-11",
"motivo": "il testo di questa voce non si ritrova nel
documento: non e' stato collocato, va verificato a mano." } ],
"come_ricavato": "numerazione, titoli e pagine sono letti dal
testo del documento, non chiesti a un modello. …"
}albero è la struttura annidata, indice la stessa cosa in piano con il percorso già scritto (comodo per una tabella), ancore il collegamento fra ogni valore di lista e la sua sezione, senza_ancora l’elenco dei valori il cui testo non si è ritrovato. Le regole di riconoscimento della numerazione (CAPO, TITOLO, Art. n.n, n.n.n) sono tarate sul comportamento dei documenti italiani veri: un numero in mezzo alla prosa non diventa un capitolo, un importo scritto 500.000 non diventa una sezione, e l’indice in testa al documento non vince sul corpo — la pagina che leggi è quella in cui la sezione comincia davvero, non quella dell’indice.
Quanto ne esce, misurato. Il 28 settembre 2026 su 15 documenti di gara italiani veri (capitolati speciali d’appalto e disciplinari, da 3 a 80 pagine lette): l’albero si ricostruisce su 14 su 15, con da 24 a 131 sezioni per documento e profondità da 1 a 4. Il quindicesimo non è un capitolato ma un listino prezzi: non ha una struttura numerata, e il blocco lo dice con trovate: 0 invece di inventarne una.
Risultato
Requisiti, norme citate, materiali, prove ed esclusioni sono elenchi, e su un elenco lungo il risultato può contenerne solo una parte anche quando la lettura arriva in fondo al documento. Non è il limite di lettura descritto sopra — quello riguarda quante pagine apriamo — ma quante voci l’elaborazione riesce a restituire, e non c’è una soglia fissa da dirti in anticipo. Quando il documento numera le voci — 1), 2), 3) — ce ne accorgiamo e te lo diciamo: il file porta un blocco elenchi_incompleti con la prima voce che manca, e dentro quality il campo complete passa a false. Quando invece il documento le elenca senza numerarle — trattini, puntini, rientri — non abbiamo modo di accorgercene, e un elenco accorciato ti arriva senza nessun avviso. In tutti e due i casi il risultato ti viene consegnato e i crediti restano spesi. Se ti serve l’elenco completo, dividi il documento in più PDF di poche pagine ciascuno, chiamali come lavori separati e unisci i risultati. Per un’integrazione è il limite più importante di questa pagina: leggi sempre quality.complete e non trattare una lista come esaustiva.
Limiti, detti prima
Nessuna quantità e nessun computo metrico. Fino al 28 settembre 2026 questa pagina prometteva «quantità» e «tabelle di quantità»: non era vero e l’abbiamo tolto. I campi estratti sono i sei elencati sopra; un computo metrico estimativo (voce, unità, quantità, prezzo unitario) è un’altra estrazione e non c’è. Se ti serve quella, PDF → Excel lavora sulle tabelle.
Nessun webhook. Fino al 28 settembre 2026 questa pagina diceva che potevi indicarne uno: non esiste, e l’esito si legge in polling su GET /jobs/<uuid>. Preferiamo dirlo che farti progettare l’architettura intorno a una funzione che non c’è.
La classificazione di una frase come «requisito» è in parte un’interpretazione, e su un documento senza numerazione la suddivisione segue i paragrafi: può accorpare o dividere diversamente da come farebbe un tecnico. L’endpoint non esprime giudizi di conformità: dice cosa chiede il documento, non se il tuo prodotto lo soddisfa. Non misuriamo una percentuale di accuratezza e non ne pubblichiamo una: quello che pubblichiamo è il modo di controllare ogni singolo valore, cioè ancore e senza_ancora. Se l’elaborazione fallisce, i crediti vengono riaccreditati automaticamente e la risposta dice il motivo.
Fatturazione. Il gestore è una persona fisica senza partita IVA e non emette fattura. Se la tua azienda ne ha bisogno per mettere il costo in bilancio, scrivici prima di acquistare: non vogliamo che lo scopri dopo.
Privacy e dati
Un capitolato di gara è spesso riservato, e se lo elabori per conto di un tuo cliente la domanda è doppia. Il PDF resta sui nostri server, fuori dal web, e viene cancellato da solo — subito dopo un’elaborazione riuscita, entro pochi giorni negli altri casi. Il testo estratto dal documento, insieme all’elenco dei campi da cercare, viene mandato al modello di OpenAI, passando dal servizio che coordina i lavori (n8n Cloud). OpenAI ha sede negli Stati Uniti: quei dati possono quindi essere trattati anche fuori dall’Unione europea, e nei log di controllo degli abusi di OpenAI possono restare fino a 30 giorni. Non vengono mai usati per addestrare modelli. Il file del risultato resta scaricabile 14 giorni, poi viene eliminato. Il blocco sezioni non passa da nessun modello: è calcolato qui. Tutti i dettagli nella pagina Trattamento dati & AI.
Oggi non firmiamo nomine a responsabile del trattamento (art. 28 GDPR). Se rivendi questa elaborazione ai tuoi clienti e ti serve la catena documentata, non integrarci prima di averne parlato con noi.
Perché questo e non un parser scritto in casa
Il parsing puro di un PDF costa poco e lo fanno bene in molti: le API di document AI generaliste convertono un documento in blocchi di testo e tabelle per pochi centesimi a pagina, e ce n’è anche di gratuite da installare in casa. Quello che nessuna di loro fa è sapere che cos’è un requisito, che cos’è una norma UNI o EN o ISO, e che cos’è un CAPO: restituiscono struttura tipografica, non dati di dominio italiani. Il layer che trasforma 80 pagine di capitolato in requisiti con parametro, valore, unità e norma applicabile — e nell’albero delle sezioni giusto — è esattamente la parte che costa settimane a scrivere e che poi va mantenuta documento dopo documento. Questo endpoint è quella parte, a 2 crediti per documento e senza canone.
Stato
L’accesso programmatico non è ancora aperto al pubblico, per decisione di chi gestisce la piattaforma: il motore di questo prodotto esiste ed è lo stesso che serve lo strumento web, ma l’interruttore delle API pubbliche è spento. Oggi lo stesso lavoro si fa da Specifica Tecnica → JSON, dove ricevi il JSON (senza il blocco sezioni) e la matrice di conformità in Excel. Se ti serve il canale API, scrivici: sapere che c’è qualcuno che lo aspetta è ciò che fa aprire un interruttore.
Domande frequenti
Che differenza c’è con lo strumento web?
Gli stessi sei campi estratti, lo stesso prezzo. Lo strumento web aggiunge la matrice di conformità in Excel, con le colonne Conforme, Valore offerto, Evidenza e Note da compilare a mano. Questo canale aggiunge il blocco sezioni: l’albero del documento e, per ogni requisito, il § e la pagina — cioè la colonna Evidenza già riempita, in forma di dato.
Gestisce un capitolato da 300 pagine?
No, non in un solo lavoro: legge le prime 80 pagine e circa 280.000 caratteri, e lo dichiara nel risultato. Fino al 28 settembre 2026 questa pagina rispondeva «Sì, entro il limite di 15 MB», e non era vero. Per coprire tutto il documento si spezza il PDF e si chiama più volte.
Come faccio a fidarmi dei requisiti estratti?
Non fidandotene, e controllandoli con il file stesso. Ogni requisito che ha un’ancora ha anche il § e la pagina in cui il suo testo è stato ritrovato nel documento: il controllo è un click nel PDF. Quelli che stanno in senza_ancora sono esattamente i valori che il documento non scrive con quelle parole, e sono i primi da guardare.
Quanto costa, in euro?
2 crediti per documento. Un credito costa da €0,98 (ricarica minima, 4 crediti a €3,90) a €0,49 (100 crediti a €49,00): quindi da €1,96 a €0,98 per documento. I 3 crediti di benvenuto di un account nuovo bastano per un documento. Nessun canone, nessun rinnovo automatico.
Cosa succede in caso di errore?
Il lavoro passa a failed, i crediti vengono riaccreditati automaticamente e la risposta indica il motivo. Un file rifiutato all’ingresso (estensione sbagliata, oltre 15 MB, PDF illeggibile o protetto) torna 400 e non viene addebitato affatto.