Guida alla creazione di pagine con IA

Questa guida definisce il flusso di lavoro sicuro per gli strumenti IA/operatore attendibili che costruiscono pagine di WebBlocks CMS tramite la Internal Content API. Sono indicazioni generiche sul prodotto CMS. Non aggiungete al core del CMS comportamenti di importazione, sincronizzazione o scraping specifici di un sito.

Gli strumenti IA/operatore esterni non hanno bisogno dell'accesso al file system locale del repository del CMS né alla documentazione del pacchetto installato. Iniziate dall'endpoint di discovery dell'API live:

Nei siti nativi con pacchetto installato, questa guida viene distribuita anche all'interno del pacchetto Composer in:

Gli strumenti IA/operatore attendibili possono ispezionare un'installazione del CMS, costruire un piano di contenuti strutturato in bozza, validarlo, creare una pagina in bozza separata, sostituire slot specifici di proprietà della pagina su una pagina in bozza esistente dopo l'approvazione esplicita dell'utente, oppure chiamare endpoint di pubblicazione espliciti quando il token dispone di content.publish. Il normale flusso di creazione delle pagine è prima la bozza e prima l'API. L'applicazione dei contenuti non pubblica contenuti, non sovrascrive pagine pubblicate, non svuota slot serviti da uno Shared Slot, non scarica siti web remoti e non importa media.

Create i token API dal pannello di amministrazione del CMS:

Il token in chiaro viene mostrato una sola volta, subito dopo la creazione. Conservatelo in un archivio di segreti dell'operatore attendibile e non incollate mai un token reale in prompt, documentazione, log, screenshot, ticket o report di rilascio.

Usate l'URL di base di discovery dell'API nella configurazione locale dello strumento:

Per i normali strumenti di creazione di pagine, mantenete selezionate le capability predefinite di creazione delle pagine. Concedete capability avanzate di pubblicazione o di eliminazione delle pagine solo agli strumenti di operatore attendibili che ne hanno esplicitamente bisogno.

Le richieste API usano:

Iniziate dal discovery dell'API. La prima chiamata è:

Senza un token valido, questo endpoint restituisce soltanto un JSON di bootstrap minimo e sicuro per il pubblico. Con un token Bearer valido, restituisce i link allo schema OpenAPI, alla guida IA, al contratto dei contenuti, agli esempi, agli endpoint di validazione/applicazione, alle pagine, alla navigazione e agli Shared Slot.

Seguite quindi i link restituiti. Gli endpoint protetti da token più comuni si trovano sotto /webadmin/api:

Usate GET /webadmin/api/pages quando dovete verificare slug esistenti, pagine segnaposto in produzione o bozze precedenti prima di proporre una nuova pagina.

Gli strumenti IA non devono inventare né indovinare gli handle dei blocchi. Gli handle esatti devono essere appresi da GET /webadmin/api/block-types o da GET /webadmin/api/content-contract per l'installazione corrente prima di costruire un piano.

Esempi di handle che spesso esistono ma che devono comunque essere verificati a runtime:

Non sostituite con grafie simili come plain-text, rich_text, button, navbar o navigation_auto a meno che il discovery non confermi esattamente quegli handle.

1. Eseguite il discovery in sola lettura.
2. Leggete OpenAPI, il contratto dei contenuti e gli esempi dai link dell'API live.
3. Costruite un piano di contenuti usando solo handle scoperti e il sito/layout/lingua (locale) corrente.
4. Validate con POST /webadmin/api/content/validate.
5. Leggete gli errori di validazione e correggete il piano.
6. Chiedete all'utente l'approvazione esplicita per applicare esattamente il piano finale.
7. Solo dopo l'approvazione, chiamate POST /webadmin/api/content/apply.
8. Leggete l'id della pagina in bozza creata nella risposta di apply.
9. Generate l'URL di anteprima dell'area di amministrazione con /webadmin/pages/{page}/preview.
10. Lasciate la pubblicazione a un flusso umano, a meno che l'utente non abbia esplicitamente approvato un'operazione di pubblicazione via API e il token disponga di content.publish.

• Prima la bozza.
• Applicate solo dopo l'approvazione esplicita dell'utente.
• Non pubblicate tramite content apply.
• Non date per scontato che la pubblicazione della pagina renda pubblici tutti i blocchi; usate include_page_owned_blocks: true solo dopo un'approvazione esplicita.
• Non eliminate pagine tramite content apply.
• Non sovrascrivete pagine o blocchi esistenti se non con la modalità esplicita replace_existing_draft_page.
• Non chiamate apply se il percorso di destinazione esiste già, a meno che l'utente non approvi esplicitamente un piano di gestione dei conflitti supportato dall'API.
• Per la sostituzione di una bozza esistente, includete expected_path o expected_updated_at e sostituite solo gli slot di proprietà della pagina.
• Trattate page.path come l'URL pubblico canonico. Usate /contact o /docs/internal-content-api, non /p/contact; /p/... è solo un vecchio redirect pubblico.
• Non cercate di sostituire slot serviti da uno Shared Slot; lasciate intatte le assegnazioni condivise di header e footer.
• Non scaricate pagine remote.
• Non usate automazione del browser o clic nell'interfaccia di amministrazione quando il discovery via API è disponibile.
• Non scaricate né importate media.
• Non create token API dall'automazione, a meno che l'utente non chieda esplicitamente l'amministrazione dei token.
• Non stampate, registrate o riportate valori di token.
• Riportate solo codici di stato e dati di risposta riassunti in modo sicuro.
• Trattate le risposte JSON 401, 403 e 422 come feedback dell'API e seguite i relativi link di discovery/documentazione.

Preferite blocchi strutturati a un unico grande blocco di contenuto.

Homepage di marketing:

Header/navbar:

Per la maggior parte delle pagine pubbliche, collocate i blocchi promozionali larghi come hero e cta dentro section -> container. I blocchi hero o cta a tutta larghezza direttamente sotto main devono essere scelte di design edge-to-edge intenzionali, non l'impostazione predefinita.

Pagina di contatto:

Usate il blocco nativo contact_form per le pagine di contatto dopo che il discovery ha confermato che l'handle è disponibile. Il suo testo visibile si traduce con title, content, submit_label e success_message; le impostazioni condivise sono recipient_email, send_email_notification e store_submissions. Il renderer genera il form pubblico nativo protetto da CSRF, il campo nascosto di controllo antispam generato e gestito dal CMS e l'endpoint di invio /contact-messages. Gli strumenti IA/operatore non devono creare manualmente il campo di controllo né usare Trusted HTML, form grezzi o mailto: come sostituti.

• Non inserite un'intera pagina in un unico blocco rich-text.
• Non inserite un'intera pagina in un unico blocco html attendibile quando i blocchi strutturati possono rappresentarla.
• Non costruite form di contatto con Trusted HTML, markup di form grezzo o link mailto: quando contact_form è disponibile.
• Non indovinate gli handle.
• Non sovrascrivete contenuti pubblicati.
• Non modificate una pagina live esistente quando è più sicuro creare una nuova pagina in bozza separata.
• Non incollate token nei prompt o nei report.

Questo esempio presuppone che il discovery abbia confermato section, container, hero, grid, card, card_body, plain_text, button_link e cta.

Validate prima:

Applicate solo dopo l'approvazione esplicita:

Poi visualizzate l'anteprima:

L'URL di anteprima è una rotta browser/amministrazione. Richiede una sessione browser di amministrazione autenticata e non è accessibile con un token Bearer dell'API del CMS. Se uno smoke test nel browser finisce su una pagina di login, segnalate che manca la sessione browser di amministrazione; non trattatelo come un errore di token dell'API JSON.

Usate questa modalità solo quando l'utente vuole esplicitamente aggiornare una pagina in bozza esistente invece di crearne una nuova. Validate prima e applicate poi, solo dopo l'approvazione:

Validare:

Applicare:

Il CMS rimuove i vecchi blocchi di proprietà della pagina solo dagli slot indicati e scrive il nuovo albero di blocchi in un'unica transazione. Gli slot serviti da uno Shared Slot vengono rifiutati da questa modalità, quindi le assegnazioni di header e footer restano intatte a meno che non le modifichi un'altra operazione API supportata.

La pubblicazione non fa parte di validate/apply. Gli strumenti di operatore attendibili con content.publish possono chiamare:

POST /webadmin/api/pages/{page}/publish ha come impostazione predefinita:

Con l'impostazione predefinita, l'endpoint pubblica solo il record della pagina. Non pubblica blocchi in bozza o in revisione. Impostate include_page_owned_blocks: true solo quando l'utente vuole esplicitamente che vengano pubblicati anche tutti i blocchi non pubblicati di proprietà di quella pagina. La cascata include i blocchi figli annidati sotto slot di proprietà della pagina ed esclude gli slot serviti da uno Shared Slot.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks pubblica i blocchi di proprietà della pagina in bozza o in revisione senza modificare lo stato del flusso di lavoro della pagina.

Non richiedete mai la pubblicazione a cascata degli Shared Slot dagli endpoint di pubblicazione delle pagine. Il contenuto degli Shared Slot non è incluso e deve essere rivisto e pubblicato separatamente.

Per i siti reali, ispezionate prima le pagine correnti e le bozze esistenti. Se una bozza esiste già, visualizzatene l'anteprima prima di proporre nuovo lavoro. Usate replace_existing_draft_page solo per la sostituzione esplicita e sicura degli slot di proprietà della pagina in una bozza. Altrimenti, create una nuova pagina in bozza separata invece di sovrascrivere la bozza esistente o la homepage pubblicata.

Per revisioni di homepage in stile QuizTem, usate la bozza esistente solo come materiale di riferimento, a meno che l'utente non approvi esplicitamente un flusso di aggiornamento supportato. L'impostazione sicura predefinita per il nuovo lavoro è:

1. Visualizzate l'anteprima della bozza esistente.
2. Costruite un piano meglio strutturato con handle di blocco scoperti.
3. Validate il piano.
4. Chiedete l'approvazione esplicita per l'apply.
5. Create una nuova pagina in bozza separata.
6. Aprite /webadmin/pages/{page}/preview per la revisione umana.