Guía de creación de páginas con IA

Esta guía define el flujo de trabajo seguro para las herramientas de IA/operador de confianza que construyen páginas de WebBlocks CMS a través de la Internal Content API. Es orientación genérica sobre el producto CMS. No añada al núcleo del CMS comportamientos de importación, sincronización o scraping específicos de un sitio.

Las herramientas externas de IA/operador no necesitan acceso al sistema de archivos local del repositorio del CMS ni a la documentación del paquete instalado. Empiece por el endpoint de descubrimiento de la API en vivo:

GET /webadmin/api

En los sitios nativos de paquete instalado, esta guía también se distribuye dentro del paquete de Composer en:

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

Propósito

Las herramientas de IA/operador de confianza pueden inspeccionar una instalación del CMS, elaborar un plan de contenido estructurado en borrador, validarlo, crear una página en borrador aparte, sustituir slots concretos propiedad de la página en una página en borrador existente tras la aprobación explícita del usuario, o llamar a endpoints de publicación explícitos cuando el token dispone de content.publish. El flujo normal de creación de páginas es primero el borrador y primero la API. La aplicación de contenido no publica contenido, no sobrescribe páginas publicadas, no vacía slots respaldados por un Shared Slot, no descarga sitios web remotos ni importa medios.

Configuración del token

Cree tokens de API desde el panel de administración del CMS:

System -> API Tokens

El token en texto plano se muestra una sola vez, justo después de crearlo. Guárdelo en un almacén de secretos de operador de confianza y no pegue nunca un token real en prompts, documentación, registros, capturas de pantalla, tickets o informes de versión.

Use la URL base de descubrimiento de la API en la configuración local de la herramienta:

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

Para las herramientas normales de creación de páginas, mantenga seleccionadas las capacidades de creación de páginas por defecto. Conceda capacidades avanzadas de publicación o de borrado de páginas solo a herramientas de operador de confianza que las necesiten explícitamente.

Las peticiones a la API usan:

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

Primeras llamadas de descubrimiento

Empiece por el descubrimiento de la API. La primera llamada es:

GET /webadmin/api

Sin un token válido, este endpoint devuelve únicamente un JSON de arranque mínimo y seguro para el público. Con un token Bearer válido, devuelve enlaces al esquema OpenAPI, la guía de IA, el contrato de contenido, los ejemplos, los endpoints de validación/aplicación, las páginas, la navegación y los Shared Slots.

Después siga los enlaces devueltos. Los endpoints protegidos por token más habituales están bajo /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

Use GET /webadmin/api/pages cuando necesite comprobar slugs existentes, páginas marcador de posición en producción o borradores anteriores antes de proponer una página nueva.

Nunca adivine los handles de bloque

Las herramientas de IA no deben inventar ni adivinar handles de bloque. Los handles exactos deben obtenerse de GET /webadmin/api/block-types o de GET /webadmin/api/content-contract para la instalación actual antes de elaborar un plan.

Ejemplos de handles que suelen existir pero que aun así deben verificarse en tiempo de ejecución:

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

No sustituya por grafías parecidas como plain-text, rich_text, button, navbar o navigation_auto salvo que el descubrimiento confirme esos handles exactos.

Flujo de trabajo seguro

Ejecute el descubrimiento de solo lectura.
Lea OpenAPI, el contrato de contenido y los ejemplos desde los enlaces de la API en vivo.
Elabore un plan de contenido usando solo handles descubiertos y el sitio/layout/idioma (locale) actual.
Valide con POST /webadmin/api/content/validate.
Lea los errores de validación y ajuste el plan.
Pida al usuario la aprobación explícita para aplicar el plan final exacto.
Solo después de la aprobación, llame a POST /webadmin/api/content/apply.
Lea el id de la página en borrador creada en la respuesta de apply.
Genere la URL de vista previa del panel de administración con /webadmin/pages/{page}/preview.
Deje la publicación a un flujo humano salvo que el usuario haya aprobado explícitamente una operación de publicación por API y el token disponga de content.publish.

Reglas de seguridad

Primero el borrador.
Aplique solo tras la aprobación explícita del usuario.
No publique a través de content apply.
No dé por hecho que publicar la página hace públicos todos los bloques; use include_page_owned_blocks: true solo tras una aprobación explícita.
No borre páginas a través de content apply.
No sobrescriba páginas o bloques existentes salvo con el modo explícito replace_existing_draft_page.
No llame a apply si la ruta de destino ya existe, salvo que el usuario apruebe explícitamente un plan de gestión de conflictos compatible con la API.
Para sustituir un borrador existente, incluya expected_path o expected_updated_at y sustituya únicamente slots propiedad de la página.
Trate page.path como la URL pública canónica. Use /contact o /docs/internal-content-api, no /p/contact; /p/... es solo una redirección pública heredada.
No intente sustituir slots respaldados por un Shared Slot; deje intactas las asignaciones compartidas de cabecera y pie.
No descargue páginas remotas.
No use automatización de navegador ni clics en la interfaz de administración cuando el descubrimiento por API esté disponible.
No descargue ni importe medios.
No cree tokens de API desde la automatización salvo que el usuario pida explícitamente la administración de tokens.
No imprima, registre ni comunique valores de tokens.
Informe solo de códigos de estado y de datos de respuesta resumidos y seguros.
Trate las respuestas JSON 401, 403 y 422 como retroalimentación de la API y siga sus enlaces de descubrimiento/documentación.

Buenas estructuras

Prefiera bloques estructurados antes que un único bloque de contenido de gran tamaño.

Página de inicio de marketing:

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

Cabecera/navbar:

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

Para la mayoría de las páginas públicas, coloque los bloques promocionales anchos como hero y cta dentro de section -> container. Los bloques hero o cta a todo el ancho directamente bajo main deberían ser decisiones de diseño de borde a borde intencionadas, no la opción por defecto.

Página de contacto:

section -> hero + contact_form

Use el bloque nativo contact_form para las páginas de contacto una vez que el descubrimiento confirme que el handle está disponible. Su texto visible se traduce con title, content, submit_label y success_message; los ajustes compartidos son recipient_email, send_email_notification y store_submissions. El renderizador genera el formulario público nativo protegido por CSRF, el campo oculto de comprobación antispam generado y gestionado por el CMS, y el endpoint de envío /contact-messages. Las herramientas de IA/operador no deben crear el campo de comprobación manualmente ni usar Trusted HTML, formularios en bruto o mailto: como sustitutos.

Malas estructuras

No meta una página completa en un solo bloque rich-text.
No meta una página completa en un solo bloque html de confianza cuando los bloques estructurados pueden representarla.
No construya formularios de contacto con Trusted HTML, marcado de formulario en bruto o enlaces mailto: cuando contact_form esté disponible.
No adivine handles.
No sobrescriba contenido publicado.
No modifique una página en producción existente cuando sea más seguro crear una página en borrador nueva y aparte.
No pegue tokens en prompts ni en informes.

Ejemplo de plan mínimo de borrador

Este ejemplo presupone que el descubrimiento confirmó section, container, hero, grid, card, card_body, plain_text, button_link y 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."
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Valide primero:

POST /webadmin/api/content/validate

Aplique solo tras la aprobación explícita:

POST /webadmin/api/content/apply

Después, previsualice:

/webadmin/pages/{page}/preview

La URL de vista previa es una ruta de navegador/administración. Requiere una sesión de navegador de administración autenticada y no es accesible con un token Bearer de la API del CMS. Si una prueba de humo en el navegador acaba en una página de inicio de sesión, informe de que falta la sesión de navegador de administración; no lo trate como un fallo de token de la API JSON.

Sustitución de slots en un borrador existente

Use este modo solo cuando el usuario quiera explícitamente actualizar una página en borrador existente en lugar de crear un borrador nuevo. Valide primero y aplique después, solo tras la aprobación:

{
  "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."
          }
        }
      ]
    }
  }
}

Validar:

POST /webadmin/api/content/validate

Aplicar:

POST /webadmin/api/content/apply

El CMS elimina los bloques antiguos propiedad de la página únicamente de los slots indicados y escribe el nuevo árbol de bloques en una sola transacción. Los slots respaldados por un Shared Slot son rechazados por este modo, de modo que las asignaciones de cabecera y pie permanecen intactas salvo que las cambie otra operación de la API compatible.

Publicación explícita

La publicación no forma parte de validate/apply. Las herramientas de operador de confianza con content.publish pueden llamar a:

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

POST /webadmin/api/pages/{page}/publish tiene por defecto:

{
  "include_page_owned_blocks": false
}

Con el valor por defecto, el endpoint publica únicamente el registro de la página. No publica bloques en borrador ni en revisión. Ponga include_page_owned_blocks: true solo cuando el usuario quiera explícitamente que también se publiquen todos los bloques sin publicar propiedad de esa página. La cascada incluye los bloques hijos anidados bajo slots propiedad de la página y excluye los slots respaldados por un Shared Slot.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks publica los bloques propiedad de la página que están en borrador o en revisión sin cambiar el estado de flujo de trabajo de la página.

No solicite nunca la publicación en cascada de Shared Slots desde los endpoints de publicación de páginas. El contenido de los Shared Slots no se incluye y debe revisarse y publicarse por separado.

Revisiones de sitios reales

En sitios reales, inspeccione primero las páginas actuales y los borradores existentes. Si ya existe un borrador, previsualícelo antes de proponer trabajo nuevo. Use replace_existing_draft_page únicamente para la sustitución explícita y segura de slots propiedad de la página en un borrador. En caso contrario, cree una página en borrador nueva y aparte en lugar de sobrescribir el borrador existente o la página de inicio publicada.

Para revisiones de páginas de inicio al estilo de QuizTem, use el borrador existente solo como material de referencia, salvo que el usuario apruebe explícitamente un flujo de actualización compatible. El valor seguro por defecto para el trabajo nuevo es:

Previsualice el borrador existente.
Elabore un plan mejor estructurado con handles de bloque descubiertos.
Valide el plan.
Pida la aprobación explícita para aplicar.
Cree una página en borrador nueva y aparte.
Abra /webadmin/pages/{page}/preview para la revisión humana.