Endpoint REST che prende il catalogo PDF di un fornitore e restituisce le schede prodotto con chiavi sempre uguali — codice, ean, nome, colore, taglia, prezzo, attributi — qualunque intestazione usi il documento. E, sopra a quelle, il pezzo che costa di più scrivere a mano: il corpo già pronto di POST /wp-json/wc/v3/products/batch, con i prodotti a più taglie già nella forma del prodotto variabile.
Questo strumento non è ancora disponibile: lo stiamo preparando con la stessa cura del resto del motore.
Guarda un esempio di risultato
La cosa che non trovi altrove
Un catalogo di abbigliamento scrive le taglie in una cella sola: «S – M – L – XL – XXL – 3XL». Quella cella, nel tuo negozio, è un prodotto variabile con sei variazioni. È il pezzo più lento di ogni import e nessun convertitore PDF lo fa: ti danno il testo, la mappatura la scrivi tu. Qui esce già fatta.
Attenzione a una differenza che vale soldi: «S – 3XL» non è un elenco, è un intervallo — vuol dire dalla S alla 3XL, e le taglie in mezzo il catalogo non le stampa. Espanderlo darebbe due taglie su sei in vendita. Quando i pezzi sono due non espandiamo: il prodotto esce semplice e lo diciamo in taglie_a_intervallo. Da tre in su è un elenco, e l’elenco sta scritto nel documento.
Cosa ricevi, davvero
La riga che leggi per prima, generata dal codice di questa pagina su tre articoli di un catalogo workwear:
3 prodotti pronti per POST /wp-json/wc/v3/ products/batch, senza una riga di mappatura. 2 sono variabili con 12 variazioni di taglia già dichiarate: le celle «S - M - L - XL» del catalogo sono diventate opzioni. 1 articolo scrive un intervallo di taglie invece di un elenco: vedi «taglie_a_intervallo».
E il primo prodotto del payload, così com’è nella risposta:
{
"sku": "E0449BI",
"name": "PIXEL V",
"description": "T-shirt scollo a V",
"regular_price": "6.4",
"type": "variable",
"attributes": [
{ "name": "Taglia",
"variation": true,
"options": ["S","M","L","XL","XXL","3XL"] },
{ "name": "Colore",
"variation": false,
"options": ["BIANCO"] },
{ "name": "Composizione",
"variation": false,
"options": ["100% COTONE SLUB JERSEY"] }
]
}
regular_price è una stringa perché WooCommerce lo dichiara type => string. I nomi dei campi vengono dallo schema di WC_REST_Products_Controller e le intestazioni CSV da wc_importer_default_english_mappings(), che WooCommerce registra come fallback: valgono anche su un negozio in italiano. Accanto al payload la risposta porta controlli — codici duplicati, cifra di controllo EAN che non torna, prezzi che numeri non sono — e l’elenco completo in articoli.
Il contratto tecnico
Asincrono: si crea un lavoro e se ne legge l’esito. Base REST /wp-json/mega-engine/v1/, autenticazione con chiave a scope limitato (header X-ME-API-Key), chiavi conservate solo come hash e revocabili da /app/.
POST /wp-json/mega-engine/v1/jobs
{ "product": "catalog-to-json-api",
"input": { ... },
"idempotency_key": "tuo-id-univoco" }
GET /wp-json/mega-engine/v1/jobs/{uuid}
GET /wp-json/mega-engine/v1/jobs/{uuid}/download
POST /wp-json/mega-engine/v1/jobs/{uuid}/cancel
idempotency_key esiste ed è tua: rimandare la stessa chiamata non crea un secondo lavoro e non addebita due volte. Non c’è ancora un webhook di completamento: oggi si fa polling su GET /jobs/{uuid}. Se il webhook ti serve per decidere, scrivicelo prima di integrare.
Quando si può chiamare
Il motore esiste ed è in produzione — è lo stesso che serve Catalogo → JSON, più il blocco per_piattaforma che solo questo prodotto ha. Quello che non è ancora aperto è la porta: le chiavi API pubbliche sono spente per scelta del gestore, quindi oggi non puoi generare una chiave da /app/ né chiamare l’endpoint. Non è un dettaglio che nascondiamo dopo il pagamento: è il motivo per cui questa pagina non ha ancora un pulsante di acquisto. Se ti serve, scrivi a info.megaengine@gmail.com: apriamo prima a chi lo chiede.
Per chi è
Software house e agenzie e-commerce che popolano WooCommerce, PrestaShop o un PIM partendo dai cataloghi dei fornitori, e che ricevono lo stesso catalogo aggiornato due volte l’anno da venti fornitori diversi. Non è per chi ha un catalogo solo: per quello basta il fratello web, che costa uguale e si usa dal browser.
Limiti, detti prima
Solo PDF con testo selezionabile: DOCX e XLSX non sono accettati, e un catalogo scansionato (pagine che sono immagini) viene rifiutato con il suo codice d’errore, non elaborato a metà. Massimo 15 MB e circa 80 pagine per lavoro: un catalogo da 300 pagine va spezzato in quattro chiamate da 2 crediti l’una. Le immagini dei prodotti non vengono estratte.
Il payload porta 100 prodotti per chiamata, che è il tetto di products/batch: gli altri stanno tutti in articoli, da mandare a blocchi con lo stesso formato. Gli SKU delle singole taglie non ci sono perché il catalogo non li stampa: il documento dà un codice per modello e colore, non uno per taglia. WooCommerce le variazioni le crea lo stesso dalle opzioni dell’attributo.
Su un layout molto grafico il raggruppamento in schede può uscire parziale: quando le righe che consegniamo sono meno di quelle che il documento ha, la risposta lo dichiara e i crediti tornano indietro da soli — quello che perdiamo noi non lo paghi.
Input supportati
Cataloghi in PDF con testo selezionabile (generati digitalmente) fino a 15 MB e circa 80 pagine per elaborazione, con impaginazione tabellare o a schede. I cataloghi scansionati (immagini) non sono ancora supportati: in quel caso l’elaborazione viene segnalata subito come non riuscita e non ti viene addebitato nulla. Un catalogo in parte digitale e in parte scansionato (una pagina fotografata, una tabella misure acquisita con lo scanner) viene invece 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 è in questo risultato, invece di dichiararsi completo. Se invece la parte digitale non contiene tabelle — per esempio è generata al computer solo la copertina, e il resto è tutto scansionato — non resta niente da consegnare: il lavoro viene segnalato come non riuscito, ti diciamo quante pagine su quante erano senza testo selezionabile 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 carica quella. Le 80 pagine sono il tetto massimo, non la regola: quando le righe non stanno in una griglia netta la lettura passa dall’intelligenza artificiale, che riceve al massimo circa 280.000 caratteri di testo — quanto ottanta pagine di media. I due tetti sono tarati per mordere nello stesso punto: misurato l’8 settembre 2026 su dieci documenti di gara italiani veri, è esattamente quanto testo portano ottanta pagine. Solo su un documento molto più fitto della media quel limite arriva prima dell’ottantesima pagina. Il risultato dichiara sempre a quale pagina la lettura si è fermata, e il messaggio ti dice da quale pagina ripartire. Quando il documento prosegue oltre il taglio la parte letta ti viene consegnata lo stesso, con il taglio dichiarato: il lavoro si conclude e i crediti restano spesi, anche se i dati che cercavi stavano oltre. Puoi caricare come lavoro separato un PDF con le sole pagine che ti servono.
C’è una seconda perdita possibile, indipendente da questi due tetti: dentro le pagine lette l’estrazione assistita dall’intelligenza artificiale può smettere di elencare prima della fine, restituendo articoli giusti ma pochi. Ce ne accorgiamo confrontando il risultato consegnato con due letture indipendenti dello stesso documento: la griglia che legge le tabelle riga per riga e, quando la griglia non riconosce la struttura del documento, il conteggio delle righe del testo estratto che hanno la forma di una riga di tabella. Quando una delle due si scosta dal risultato, il file lo dichiara con entrambi i conteggi e si considera incompleto. Non è una garanzia — su un documento fatto in prevalenza di prosa, con qualche tabella dentro, nessuna delle due letture sa dire quante ne dovevano tornare, e una perdita lì non te la segnala nessuno: conta sempre gli articoli del file contro l’originale prima di importarli. Quando succede, però, non lo paghi: quel che manca nel file non stava oltre un limite del documento, lo abbiamo perso noi leggendo le pagine, e i crediti ti tornano indietro da soli. Ricaricare il PDF a blocchi di poche pagine per volta è il modo più efficace per recuperare gli articoli mancanti.
C’è infine un tetto che non riguarda il documento ma la nostra risposta: gli articoli tornano indietro in un’unica risposta del modello, e quella risposta ha uno spazio finito. Un documento che ne contiene moltissime lo esaurisce. Se lo esaurisce prima che ne arrivi una parte utilizzabile, il lavoro viene segnalato come non riuscito, il messaggio ti dice che il documento contiene più voci di quante riusciamo a restituirne in una volta sola e non ti viene addebitato nulla; se lo esaurisce dopo, il risultato ti viene consegnato con il taglio dichiarato fra le note e non lo paghi: a non starci dentro è stata la nostra risposta, non il tuo documento. In entrambi i casi il gesto è lo stesso: caricare il PDF a blocchi di poche pagine per volta.
Quanto costa
2 crediti a lavoro. La ricarica minima è di 4 crediti a 3,90 €, quindi al taglio più piccolo un catalogo costa 1,96 €; a 100 crediti per 49 € scende a 0,98 €. Si paga a lavoro, non a pagina: un catalogo di 80 pagine costa quanto uno di 5. Il primo lavoro sta nei 3 crediti di benvenuto.
Privacy e dati
Il testo estratto dal catalogo viene mandato a OpenAI (Stati Uniti) attraverso i flussi n8n di Mega Engine per ricostruire le schede; il PDF originale non lascia il server. I file si cancellano dopo 14 giorni, i risultati dopo 30. Niente addestramento di modelli sui tuoi documenti. Il dettaglio sta in Trattamento dati & AI. Le chiavi API sono conservate solo come hash.
Due cose che devi sapere se compri per un’azienda: il gestore è persona fisica senza partita IVA e non emette fattura; e non esiste ancora una nomina a responsabile del trattamento (art. 28 GDPR), che ti servirebbe se i cataloghi sono dei tuoi clienti. Se ti servono, scrivi prima di acquistare.
Domande frequenti
In cosa è diverso da «Catalogo → JSON»?
Stesso motore e stesso prezzo. Il fratello web ti dà il file da scaricare; questo ti dà la stessa cosa via REST più il blocco per_piattaforma, cioè il corpo pronto di products/batch con i prodotti variabili già formati. Se apri il browser e scarichi, prendi il fratello: costa uguale.
Estrae anche le immagini dei prodotti?
No: solo dati testuali e numerici. Se ti servono le foto, restano da prendere dal fornitore.
E se il catalogo non viene elaborato?
I crediti vengono riaccreditati e la risposta di errore spiega il motivo. Lo stesso vale quando il risultato è incompleto per colpa nostra.
Il JSON vale anche per Shopify o PrestaShop?
Il blocco per_piattaforma oggi copre solo WooCommerce, perché i nomi dei campi li abbiamo verificati sul suo sorgente. Le chiavi canoniche di articoli sono neutre e si mappano su qualsiasi piattaforma, ma quella mappatura la scrivi tu. Se ti serve Shopify o PrestaShop, chiedicelo: è la prossima cosa da fare.