Guide de création de pages par IA

Ce guide définit le flux de travail sécurisé des outils IA/opérateur de confiance qui construisent des pages WebBlocks CMS via l'Internal Content API. Il s'agit d'indications génériques sur le produit CMS. N'ajoutez pas au cœur du CMS de comportements d'import, de synchronisation ou de scraping spécifiques à un site.

Les outils IA/opérateur externes n'ont pas besoin d'un accès au système de fichiers local du dépôt du CMS ni à la documentation du paquet installé. Commencez par l'endpoint de découverte de l'API en direct :

GET /webadmin/api

Dans les sites natifs à paquet installé, ce guide est également livré à l'intérieur du paquet Composer, à l'emplacement :

vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md

Objectif

Les outils IA/opérateur de confiance peuvent inspecter une installation du CMS, construire un plan de contenu structuré en brouillon, le valider, créer une page en brouillon distincte, remplacer des slots précis appartenant à la page sur une page en brouillon existante après approbation explicite de l'utilisateur, ou appeler des endpoints de publication explicites lorsque le jeton dispose de content.publish. Le flux normal de création de pages est brouillon d'abord et API d'abord. L'application de contenu ne publie pas de contenu, n'écrase pas les pages publiées, ne vide pas les slots servis par un Shared Slot, ne récupère pas de sites web distants et n'importe pas de médias.

Configuration du jeton

Créez les jetons d'API depuis le panneau d'administration du CMS :

System -> API Tokens

Le jeton en clair n'est affiché qu'une seule fois, juste après sa création. Conservez-le dans un coffre à secrets d'opérateur de confiance et ne collez jamais un jeton réel dans des prompts, de la documentation, des journaux, des captures d'écran, des tickets ou des rapports de version.

Utilisez l'URL de base de découverte de l'API dans la configuration locale de l'outil :

WEBBLOCKS_CMS_API_URL=https://example.com/webadmin/api
WEBBLOCKS_CMS_API_TOKEN=...

Pour les outils ordinaires de création de pages, conservez les capacités de création de pages sélectionnées par défaut. N'accordez les capacités avancées de publication ou de suppression de pages qu'aux outils d'opérateur de confiance qui en ont explicitement besoin.

Les requêtes API utilisent :

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Premiers appels de découverte

Commencez par la découverte de l'API. Le premier appel est :

GET /webadmin/api

Sans jeton valide, cet endpoint ne renvoie qu'un JSON d'amorçage minimal et sûr pour le public. Avec un jeton Bearer valide, il renvoie les liens vers le schéma OpenAPI, le guide IA, le contrat de contenu, les exemples, les endpoints de validation/application, les pages, la navigation et les Shared Slots.

Suivez ensuite les liens renvoyés. Les endpoints protégés par jeton les plus courants se trouvent sous /webadmin/api :

GET /webadmin/api/openapi.json
GET /webadmin/api/ai-guide
GET /webadmin/api/examples/contact-page
GET /webadmin/api/sites
GET /webadmin/api/locales
GET /webadmin/api/page-layouts
GET /webadmin/api/block-types
GET /webadmin/api/content-contract
GET /webadmin/api/navigation-menus
GET /webadmin/api/shared-slots
GET /webadmin/api/pages

Utilisez GET /webadmin/api/pages lorsque vous devez vérifier les slugs existants, les pages d'attente en ligne ou les brouillons antérieurs avant de proposer une nouvelle page.

Ne devinez jamais les handles de bloc

Les outils IA ne doivent ni inventer ni deviner les handles de bloc. Les handles exacts doivent être obtenus depuis GET /webadmin/api/block-types ou GET /webadmin/api/content-contract pour l'installation courante avant de construire un plan.

Exemples de handles qui existent souvent mais qui doivent tout de même être vérifiés à l'exécution :

section
container
grid
card
card_body
hero
cta
plain_text
rich-text
button_link
sticky-navbar

Ne substituez pas des orthographes voisines telles que plain-text, rich_text, button, navbar ou navigation_auto, sauf si la découverte confirme ces handles exacts.

Flux de travail sécurisé

Exécutez la découverte en lecture seule.
Lisez OpenAPI, le contrat de contenu et les exemples depuis les liens de l'API en direct.
Construisez un plan de contenu en n'utilisant que des handles découverts et le site/layout/langue (locale) courant.
Validez avec POST /webadmin/api/content/validate.
Lisez les erreurs de validation et ajustez le plan.
Demandez à l'utilisateur son approbation explicite pour appliquer exactement le plan final.
Seulement après approbation, appelez POST /webadmin/api/content/apply.
Lisez l'id de la page en brouillon créée dans la réponse d'apply.
Produisez l'URL d'aperçu de l'administration avec /webadmin/pages/{page}/preview.
Laissez la publication à un flux humain, sauf si l'utilisateur a explicitement approuvé une opération de publication par API et que le jeton dispose de content.publish.

Règles de sécurité

Le brouillon d'abord.
N'appliquez qu'après approbation explicite de l'utilisateur.
Ne publiez pas via content apply.
Ne supposez pas que publier la page rend tous les blocs publics ; n'utilisez include_page_owned_blocks: true qu'après une approbation explicite.
Ne supprimez pas de pages via content apply.
N'écrasez pas de pages ou de blocs existants, sauf avec le mode explicite replace_existing_draft_page.
N'appelez pas apply si le chemin cible existe déjà, sauf si l'utilisateur approuve explicitement un plan de gestion des conflits pris en charge par l'API.
Pour le remplacement d'un brouillon existant, incluez expected_path ou expected_updated_at et ne remplacez que les slots appartenant à la page.
Traitez page.path comme l'URL publique canonique. Utilisez /contact ou /docs/internal-content-api, et non /p/contact ; /p/... n'est qu'une ancienne redirection publique.
N'essayez pas de remplacer des slots servis par un Shared Slot ; laissez intactes les affectations partagées d'en-tête et de pied de page.
Ne récupérez pas de pages distantes.
N'utilisez pas l'automatisation du navigateur ni les clics dans l'interface d'administration lorsque la découverte par API est disponible.
Ne téléchargez ni n'importez de médias.
Ne créez pas de jetons d'API depuis l'automatisation, sauf si l'utilisateur demande explicitement l'administration des jetons.
N'affichez, ne journalisez et ne rapportez jamais les valeurs de jeton.
Ne rapportez que des codes de statut et des données de réponse résumées et sûres.
Traitez les réponses JSON 401, 403 et 422 comme des retours de l'API et suivez leurs liens de découverte/documentation.

Bonnes structures

Préférez des blocs structurés à un unique gros bloc de contenu.

Page d'accueil marketing :

section -> container -> hero
section -> container -> grid -> card -> card_body
section -> container -> cta

En-tête/navbar :

shared_slot header
sticky-navbar -> container(flow:none) -> cluster -> navbar-brand + cluster -> navbar-navigation + header-actions

Pour la plupart des pages publiques, placez les blocs promotionnels larges comme hero et cta à l'intérieur de section -> container. Les blocs hero ou cta pleine largeur directement sous main doivent relever d'un choix de design bord à bord assumé, non du comportement par défaut.

Page de contact :

section -> hero + contact_form

Utilisez le bloc natif contact_form pour les pages de contact une fois que la découverte a confirmé la disponibilité du handle. Son texte visible se traduit via title, content, submit_label et success_message ; les réglages partagés sont recipient_email, send_email_notification et store_submissions. Le moteur de rendu produit le formulaire public natif protégé par CSRF, le champ caché de contrôle anti-spam généré et géré par le CMS, ainsi que l'endpoint d'envoi /contact-messages. Les outils IA/opérateur ne doivent pas créer le champ de contrôle manuellement ni utiliser Trusted HTML, des formulaires bruts ou mailto: comme substituts.

Mauvaises structures

Ne mettez pas une page entière dans un seul bloc rich-text.
Ne mettez pas une page entière dans un seul bloc html de confiance lorsque des blocs structurés peuvent la représenter.
Ne construisez pas de formulaires de contact avec Trusted HTML, du balisage de formulaire brut ou des liens mailto: lorsque contact_form est disponible.
Ne devinez pas les handles.
N'écrasez pas de contenu publié.
Ne modifiez pas une page en ligne existante lorsqu'une nouvelle page en brouillon distincte est plus sûre.
Ne collez pas de jetons dans les prompts ou les rapports.

Exemple de plan de brouillon minimal

Cet exemple suppose que la découverte a confirmé section, container, hero, grid, card, card_body, plain_text, button_link et cta.

{
  "plan": {
    "site": "default",
    "locale": "en",
    "layout": "default",
    "page": {
      "title": "Example Homepage Draft",
      "path": "/example-homepage-draft",
      "status": "draft"
    },
    "slots": {
      "main": [
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "hero",
                  "translations": {
                    "title": "Build useful pages faster",
                    "subtitle": "A structured CMS workflow for practical content teams.",
                    "content": "Create focused draft pages from reusable blocks, then review them safely before publishing."
                  },
                  "children": [
                    {
                      "type": "button_link",
                      "translations": {
                        "title": "Start building"
                      },
                      "settings": {
                        "url": "/get-started",
                        "variant": "primary"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "grid",
                  "children": [
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Create drafts from structured content plans."
                              }
                            }
                          ]
                        }
                      ]
                    },
                    {
                      "type": "card",
                      "children": [
                        {
                          "type": "card_body",
                          "children": [
                            {
                              "type": "plain_text",
                              "translations": {
                                "content": "Review safely through authenticated admin preview."
                              }
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "section",
          "settings": {
            "spacing": "lg"
          },
          "children": [
            {
              "type": "container",
              "children": [
                {
                  "type": "cta",
                  "translations": {
                    "title": "Ready for review?",
                    "content": "Validate the plan, apply only after approval, then open the admin preview."
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Validez d'abord :

POST /webadmin/api/content/validate

N'appliquez qu'après approbation explicite :

POST /webadmin/api/content/apply

Puis prévisualisez :

/webadmin/pages/{page}/preview

L'URL d'aperçu est une route navigateur/administration. Elle exige une session de navigateur d'administration authentifiée et n'est pas accessible avec un jeton Bearer de l'API du CMS. Si un test de fumée dans le navigateur aboutit à une page de connexion, signalez que la session de navigateur d'administration est absente ; n'y voyez pas un échec de jeton de l'API JSON.

Remplacement de slots dans un brouillon existant

N'utilisez ce mode que lorsque l'utilisateur souhaite explicitement mettre à jour une page en brouillon existante plutôt que d'en créer une nouvelle. Validez d'abord, puis n'appliquez qu'après approbation :

{
  "plan": {
    "mode": "replace_existing_draft_page",
    "site": "default",
    "locale": "en",
    "page": {
      "id": 9,
      "expected_path": "/contact",
      "status": "draft"
    },
    "replace_slots": {
      "main": [
        {
          "type": "plain_text",
          "translations": {
            "content": "Updated draft page copy."
          }
        }
      ]
    }
  }
}

Valider :

POST /webadmin/api/content/validate

Appliquer :

POST /webadmin/api/content/apply

Le CMS ne retire les anciens blocs appartenant à la page que des slots nommés et écrit le nouvel arbre de blocs en une seule transaction. Les slots servis par un Shared Slot sont rejetés par ce mode, de sorte que les affectations d'en-tête et de pied de page restent intactes, sauf si une autre opération d'API prise en charge les modifie.

Publication explicite

La publication ne fait pas partie de validate/apply. Les outils d'opérateur de confiance disposant de content.publish peuvent appeler :

POST /webadmin/api/pages/{page}/publish
POST /webadmin/api/pages/{page}/publish-page-owned-blocks

POST /webadmin/api/pages/{page}/publish a pour valeur par défaut :

{
  "include_page_owned_blocks": false
}

Avec la valeur par défaut, l'endpoint ne publie que l'enregistrement de la page. Il ne publie pas les blocs en brouillon ou en relecture. Ne définissez include_page_owned_blocks: true que lorsque l'utilisateur souhaite explicitement que tous les blocs non publiés appartenant à cette page soient publiés également. La cascade inclut les blocs enfants imbriqués sous les slots appartenant à la page et exclut les slots servis par un Shared Slot.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks publie les blocs appartenant à la page qui sont en brouillon ou en relecture, sans changer le statut de workflow de la page.

Ne demandez jamais la publication en cascade des Shared Slots depuis les endpoints de publication de page. Le contenu des Shared Slots n'est pas inclus et doit être relu et publié séparément.

Révisions de sites réels

Pour les sites réels, inspectez d'abord les pages actuelles et les brouillons existants. Si un brouillon existe déjà, prévisualisez-le avant de proposer un nouveau travail. N'utilisez replace_existing_draft_page que pour le remplacement explicite et sûr de slots appartenant à la page dans un brouillon. Sinon, créez une nouvelle page en brouillon distincte plutôt que d'écraser le brouillon existant ou la page d'accueil publiée.

Pour les révisions de page d'accueil de type QuizTem, n'utilisez le brouillon existant que comme matériau de référence, sauf si l'utilisateur approuve explicitement un flux de mise à jour pris en charge. Le comportement sûr par défaut pour un nouveau travail est :

Prévisualisez le brouillon existant.
Construisez un plan mieux structuré avec des handles de bloc découverts.
Validez le plan.
Demandez l'approbation explicite pour appliquer.
Créez une nouvelle page en brouillon distincte.
Ouvrez /webadmin/pages/{page}/preview pour la relecture humaine.