Internal Content API

El Internal Content API es un CMS seguro API para herramientas de operador e inteligencia artificial confiables. Permite que esas herramientas inspeccionen contratos de contenido CMS, creen contenido de borrador, reemplacen espacios específicos de páginas en borradores existentes, ejecuten operaciones de publicación explícitas a través de JSON estructurado y soliciten instantáneas de procesamiento de administradores incluidos en la lista permitida para control de calidad visual sin iniciar sesión, raspar o automatizar la interfaz de usuario del administrador del navegador.

Phase 1 se implementa como un API no público, solo para JSON y protegido con token para el descubrimiento de contenido de solo lectura más la creación de borradores de páginas a través de planes de contenido validados. La fase 2A agrega bases seguras para los menús de navegación, Shared Slots y la asignación explícita del espacio de página Shared Slot. La Fase 2B agrega un reemplazo controlado de solo borrador para el contenido de espacios de propiedad de la página en páginas existentes. Los puntos finales de publicación son explícitos y requieren content.publish; La aplicación del contenido permanece como borrador primero y no se publica. El API sigue siendo intencionalmente limitado: no se permite la recuperación remota, no se aplica la eliminación de páginas amplias mediante el contenido, no se reemplazan las ranuras respaldadas por el Shared Slot y no se permite la publicación en cascada del Shared Slot.

La Internal Content API es:

• una API del CMS interna/para operadores
• protegida por token
• no pública
• no una API de entrega de CMS headless
• no un sustituto de los permisos de administración
• no un sustituto de la importación/exportación
• no una integración con un proveedor de IA

El núcleo del CMS debe ser el propietario de esta API porque opera sobre conceptos de contenido del núcleo: sitios, páginas, layouts, slots, bloques, traducciones, navegación y shared slots. Las herramientas de IA o de operador pueden llamar a la API, pero el núcleo del CMS no debe incorporar lógica de integración de OpenAI, LLM, rastreadores ni proveedores concretos.

El prefijo canónico es:

Esto mantiene el API dentro de los límites del administrador del CMS mientras utiliza un segmento API conciso y familiar. Los puntos finales de estilo de recursos deben estar directamente bajo este prefijo, como /webadmin/api/pages y /webadmin/api/blocks.

.

Antes de planificar el contenido, lea el Inventario CMS empaquetado con GET /webadmin/api/inventory. Es el contrato de creación y diseño por bloque y es el primer documento que una IA debe leer. El bloque html es solo para humanos: permanece legible a través del API, pero cada mutación API que lo toca se rechaza con 422 y el código estable block_type_not_api_writable, y ninguna capacidad lo anula. Para un bloque application, primero descubra una definición lista y su esquema de configuración a través de GET /webadmin/api/applications; Las escrituras de API pueden hacer referencia a aplicaciones registradas, pero no pueden introducir código ejecutable ni rutas de archivos.

API el descubrimiento comienza en:

Las personas que llaman autenticadas reciben solo el arranque seguro público JSON. Las personas autenticadas reciben metadatos de la versión segura del producto, además de enlaces a OpenAPI, la guía de IA, contrato de contenido, ejemplos, validación/aplicación de contenido, páginas, bloques, medios, navegación y Shared Slots. Las herramientas externas de operador/IA deben comenzar a partir de esta respuesta de descubrimiento en vivo en lugar de leer el repositorio de CMS o los documentos del paquete local.

Uso de operaciones de contenido basadas en planes:

Opciones de ruta que conviene evitar:

• /webadmin/internal-api, porque es innecesariamente verboso
• /webadmin/api/content-plans/..., porque content-plans es demasiado técnico y limitado para el contrato de la URL
• colocar todos los recursos bajo /webadmin/api/content/..., porque las API de recursos deben mantenerse claras y directas
• /admin, porque el CMS no debe dar por supuesto que la ruta /admin del producto anfitrión le pertenece
• /cms, porque /cms sigue reservado únicamente para los recursos estáticos del CMS

La API utiliza autenticación con token Bearer:

El CMS tiene dos superficies de token. Los editores, administradores del sitio y superadministradores crean tokens API personales a partir de Profile -> Personal API Tokens; esos tokens actúan como su propietario dentro de los límites de función, sitio, flujo de trabajo, red y capacidad en vivo. Los superadministradores crean tokens del sistema API a partir de System -> API Tokens para la automatización a nivel de instalación autorizada explícitamente. El CMS almacena solo un hash SHA-256 más una vista previa segura en la tabla de base de datos cms_api_tokens. El token simple se muestra una vez inmediatamente después de su creación y nunca más se muestra.

El panel de token único proporciona controles de copia tanto para el token completo como para el ejemplo .env local generado. Los comentarios de copia se anuncian de forma accesible y la implementación del navegador incluye un respaldo para entornos sin el Portapapeles moderno API.

Tokens creados con el conjunto de capacidades de creación de páginas predeterminado anterior se tratan como elegibles para la capacidad admin.render de solo lectura en tiempo de ejecución, por lo que las herramientas de operador confiables pueden usar instantáneas visuales de control de calidad del administrador incluidas en la lista permitida después de la actualización sin rotar el token. Los tokens personalizados limitados que no incluyen el conjunto predeterminado anterior siguen restringidos.

Ambas pantallas de tokens incluyen una acción histórica para cada token. Abre un modal WebBlocks UI con los últimos 10 registros de actividad API para ese token. Los registros de actividad son intencionalmente pequeños: tiempo de solicitud, estado, método, ruta sin cadena de consulta, nombre de ruta, capacidad requerida cuando se evaluó una protección de capacidad, IP y un valor breve de agente de usuario. El CMS no almacena cuerpos de solicitud, cadenas de consulta, cuerpos de respuesta, valores de tokens de portador, hashes de tokens ni vistas previas de tokens en las filas de actividad. Las filas de actividad más antiguas se eliminan automáticamente para que cada token conserve solo los 10 registros más recientes.

Users pueden editar, revocar y eliminar sus propios tokens personales; Los superadministradores administran los tokens del sistema. Editar metadatos de políticas de cambios sin revelar el secreto. La revocación deshabilita inmediatamente el acceso a API y conserva la fila de auditoría. Eliminar un token lo elimina permanentemente y su historial de actividad.

La IA local y las herramientas del operador deben almacenar el token generado en un almacén secreto del operador confiable.

Utilice la URL base Internal Content API en la configuración del operador local:

El tiempo de ejecución del CMS no requiere WEBBLOCKS_CMS_INTERNAL_API_TOKEN.

Areglas de autenticación:

• Los tokens faltantes, incorrectos o revocados se devuelven JSON 401
• Los tokens revocados dejan de funcionar inmediatamente
• Los tokens nunca deben imprimirse en ejemplos de registros, diagnósticos, informes de soporte, pruebas o documentación
• La comparación de tokens debe utilizar una comparación de tiempo constante
• Las solicitudes exitosas de API actualizan los last_used_at y last_used_ip
• del token.
• las solicitudes API exitosas también almacenan un agente de usuario truncado para el contexto de auditoría del operador
• respuestas de recursos normales y todos los errores son JSON; Las rutas de control de calidad visual incluidas en la lista permitida pueden devolver HTML directo solo cuando la persona que llama solicita explícitamente un formato HTML

.

Esolicitud de ejemplo:

Los propietarios de tokens eligen las capacidades al crear o editar un token personal; Los superadministradores hacen lo mismo con los tokens del sistema. La edición no expone ni rota el secreto. Un formulario de token personal muestra solo las capacidades que el rol actual del propietario puede delegar, y cada solicitud vuelve a verificar ese rol activo. Discovery expone las capacidades efectivas sin devolver el valor del token, el hash del token o la vista previa del token. Los tokens de creación de páginas estándar utilizan estas capacidades:

• content.read
• content.validate
• content.apply
• navigation.write
• shared-slots.write
• media.read
• site-settings.write

A Las capacidades avanzadas son opciones independientes y no están seleccionadas de forma predeterminada:

• navigation.delete
• shared-slots.delete
• domains.write
• domains.delete
• site-assets.read
• site-assets.write
• engagement.read
• engagement.moderate
• plugins.read
• plugins.install
• plugins.manage
• plugins.setup
• plugins.uninstall
• commerce.read
• commerce.products.write
• commerce.orders.read
• media.write
• media.upload
• media.replace
• media.move
• media.delete
• content.publish
• pages.delete
• content.blocks.delete
• backups.create
• page-assets.write

Los puntos finales de escritura verifican la capacidad relevante del lado del servidor. Las capacidades faltantes devuelven JSON 403 con guía api_discovery_url, openapi_url, documentation_url y example_url. Los tokens normales de creación de páginas no deben incluir capacidades destructivas como eliminación de navegación, eliminación de Shared Slot, publicación de contenido, instalación/administración/configuración/desinstalación de complementos o eliminación de páginas. La lectura de comentarios/calificaciones requiere engagement.read explícito; cambiar el estado del comentario requiere engagement.moderate explícito. La automatización del ciclo de vida de los complementos requiere capacidades de complemento explícitas, y el acceso a productos/pedidos de WebBlocks Commerce API requiere capacidades de comercio explícitas.

Cada ruta /webadmin/api y las rutas heredadas /admin-api comparten dos presupuestos de solicitud. El presupuesto por IP y token por cliente tiene como valor predeterminado 120 solicitudes por minuto (CMS_INTERNAL_API_RATE_LIMIT_PER_MINUTE). Un respaldo de IP independiente tiene como valor predeterminado 300 solicitudes por minuto en todos los tokens proporcionados y las rutas API (CMS_INTERNAL_API_IP_RATE_LIMIT_PER_MINUTE), incluidos los intentos de tokens no válidos. La rotación de tokens no restablece este respaldo. Si se excede cualquiera de los presupuestos, se devuelve 429 con un encabezado Retry-After. Los valores de configuración no positivos vuelven a los valores predeterminados.

Lea los presupuestos en vivo de x-rate-limit en GET /webadmin/api/openapi.json: requests_per_minute es el presupuesto de token e IP, y ip_requests_per_minute es el presupuesto de IP independiente. Los clientes que comparten una IP deben coordinar su volumen de solicitudes combinado.

An Un superadministrador activo puede anular ambos presupuestos en Sistema → Configuración → Seguridad. Los valores del panel respaldados por la base de datos tienen prioridad sobre la configuración de la instalación y se aplican a solicitudes posteriores sin restablecer los contadores existentes. Utilizar los valores predeterminados de instalación elimina las anulaciones de seguridad y restaura los presupuestos configurados. Guardar o restaurar no edita .env ni la configuración del servidor. Los presupuestos solicitados aceptan números enteros positivos hasta 1.000.000. Los límites específicos de los tokens personales siguen siendo límites adicionales; cambiarlos no cambia estos presupuestos API compartidos.

Las capas de alojamiento, proxy o CDN frente al sitio pueden imponer un límite más bajo que el CMS, por lo que un cliente masivo, como un pase de traducción de sitio completo, debe controlar su ritmo y retroceder en 429 en lugar de volver a intentarlo inmediatamente.

Los tokens personales también tienen un límite configurable de 30, 60, 120 o 300 solicitudes por minuto; los tokens personales existentes sin un valor guardado usan 60. También pueden restringir el acceso a direcciones IPv4/IPv6 exactas o redes CIDR. El descubrimiento autenticado informa estas configuraciones en token.network_policy. La IP del cliente resuelta de Laravel tiene autoridad, por lo que los hosts detrás de un proxy inverso o CDN deben confiar solo en sus direcciones de proxy reales y encabezados reenviados antes de confiar en la lista de permitidos.

La API tiene dos modos complementarios.

Los endpoints de recurso reflejan operaciones equivalentes a las de administración, una por una:

• listar y leer páginas
• listar y leer bloques
• listar sitios, idiomas (locales), layouts y tipos de bloque
• más adelante, crear o actualizar directamente recursos de página en borrador
• más adelante, listar o garantizar los slots de página
• más adelante, añadir, actualizar, mover y eliminar bloques mediante endpoints de recurso
• más adelante, añadir bloques hijos mediante endpoints de recurso
• más adelante, gestionar la navegación y los shared slots

Endpoints de recurso de la fase 1:

GET /webadmin/api/locale-options devuelve el catálogo seleccionado de selección de configuración regional de idioma estándar como una lista plana locale_options. Las herramientas API deben elegir un locale_option devuelto al crear una configuración regional de idioma normal en lugar de inventar cadenas code y name.

POST /webadmin/api/locales y PATCH /webadmin/api/locales/{locale} requieren site-settings.write y aceptan campos de configuración regional seguros únicamente: locale_option, code, name, is_default y is_enabled. Al enviar locale_option se copia el código canónico y el nombre en inglés del catálogo estándar; Los modelos code y name directos siguen estando disponibles para variantes de país controladas o casos personalizados/de operador. La configuración de is_default=true fuerza la habilitación regional y degrada cualquier valor predeterminado anterior a través de la invariante local normal de CMS. Las herramientas de migración deben parchear una identificación regional existente al corregir un error de configuración de solo idioma, como cambiar una instalación nueva en alemán de configuración regional única de en a de, de modo que las relaciones de configuración regional de sitios, bloques y páginas existentes conserven sus identificaciones.

Los endpoints de content validate/apply gestionan planes de contenido completos de varios pasos:

validate comprueba un plan de contenido completo y no escribe nada. apply vuelve a validar el plan y después crea de forma transaccional la página en borrador solicitada, los elementos de navegación, los Shared Slots, los árboles de bloques de Shared Slot y las asignaciones de Shared Slot a slots de página. También puede sustituir slots concretos propiedad de la página en una página en borrador existente cuando el plan usa mode: replace_existing_draft_page e incluye una salvaguarda optimista. Esto resulta útil para páginas generadas por IA, plantillas, páginas de inicio rápido, cabeceras/pies compartidos y utilidades de migración, casos en los que el CMS debe evitar contenido creado a medias.

El cuerpo de la petición puede seguir conteniendo un campo plan u otro payload estructurado de plan de contenido. La URL debe seguir siendo /content/validate y /content/apply.

Ambos modos son necesarios:

• la Resource API expone el modelo de contenido y los contratos existentes del CMS a las herramientas internas
• la Content Validate / Apply API evita escrituras parciales durante construcciones de página más grandes

POST /content/apply acepta un indicador create_restore_point: true de nivel superior opcional. Cuando está configurado, el CMS realiza una copia de seguridad completa del sistema (base de datos más cargas) como punto de restauración antes de que aplique el plan, de modo que un operador pueda retroceder desde System -> Backups si una aplicación generada por IA sale mal.

Reglas:

• requiere la capacidad dedicada backups.create, que no forma parte del conjunto de creación de páginas predeterminado; sin ella, la solicitud devuelve JSON 403
• el plan se valida primero, por lo que un plan no válido devuelve 422 sin crear una copia de seguridad desperdiciada
• si no se puede crear la copia de seguridad, la aplicación se cancela y regresa JSON 409; el contenido nunca se aplica sin la red de seguridad solicitada
• en caso de éxito, la respuesta de aplicación incluye un objeto restore_point con la copia de seguridad id, type (content_apply), label, status y created_at
• la copia de seguridad es completa y sincrónica, por lo que agrega una latencia notable; Úselo para aplicaciones grandes o destructivas, no para automatización de alta frecuencia

El API expone intencionalmente solo la creación de puntos de restauración. La restauración, descarga y eliminación de copias de seguridad permanecen en la interfaz de usuario del administrador del operador y no forman parte del token API.

.

Estos puntos finales requieren plugins.read, plugins.install, plugins.manage, plugins.setup o plugins.uninstall respectivamente. Funcionan con autenticación de portador y no requieren una sesión de navegador autenticada. El punto final de instalación manual acepta un artefacto ZIP de complemento validado. Las solicitudes de lista/detalles del catálogo requieren plugins.read; La instalación y actualización del catálogo requieren plugins.install y reutilizar el cliente del catálogo CMS, comprobaciones de compatibilidad, validación de tamaño de artefacto/ZIP y verificación SHA-256. Una actualización del catálogo debe ser más reciente que la versión instalada y restaura el estado habilitado anterior del complemento solo después de que la validación de inicio y la configuración de la base de datos sean exitosas. Ambas rutas de instalación mantienen un complemento recién instalado deshabilitado de forma predeterminada. Desde CMS 1.92.0, la instalación, las actualizaciones y la activación aplican automáticamente los cambios requeridos en la base de datos del complemento. Una configuración fallida deja el complemento deshabilitado con una acción de reintento explícita. Panel/API habilita y configura el rechazo de complementos incompatibles con HTTP 409 y plugin_incompatible antes de cambiar de estado. CMS 1.94.0 agrega una verificación de inicio aislada obligatoria, paquetes retenidos, cuarentena de tiempo de ejecución y /webadmin/plugin-recovery; consulte Plugin System para conocer las condiciones de recuperación. La desinstalación se limita a los complementos cargados manualmente deshabilitados y conserva las tablas propiedad del complemento.

Cuando WebBlocks Commerce está habilitado y listo para configurar, las herramientas confiables pueden crear/enumerar productos y leer pedidos:

Las lecturas de productos de comercio requieren commerce.read, las escrituras de productos requieren commerce.products.write y las lecturas de pedidos requieren commerce.orders.read. Si el complemento está deshabilitado o las migraciones de configuración no se han ejecutado, los puntos finales de Commerce devuelven JSON 409 con orientación de configuración en lugar de un error de base de datos sin formato.

El bloque webblocks-commerce-buy-button propiedad del complemento se puede descubrir desde GET /webadmin/api/block-types y GET /webadmin/api/content-contract solo mientras el complemento está habilitado. Su configuración requiere settings.commerce_product_id de GET /webadmin/api/commerce/products; validar/aplicar rechaza los identificadores de productos faltantes, desconocidos o inactivos. El pago permanece en el flujo público de Commerce/PayPal. El CMS API crea productos y bloques de páginas, pero no recopila datos de tarjetas ni inicia un flujo de entrada de tarjetas.

Uuse la validación/aplicación de contenido para crear una página completa en una sola transacción. Para ediciones de borrador incrementales, utilice la topología de bloques de páginas API para agregar, reordenar o eliminar bloques individuales de propiedad de páginas. Utilice el punto final de actualización del bloque existente solo cuando el bloque ya exista y el cambio se asigne a un campo nativo seguro:

El punto final requiere content.apply. Si el bloque forma parte de un árbol de origen Shared Slot, el token también debe tener shared-slots.write.

.

Los campos admitidos son intencionalmente estrechos:

• media_idoasset_idparanavbar-brandysidebar-brandlogotipo de medios de comunicación
• media_idoasset_idparahero,section,card,cta, ycontent_headermedios de comunicación de fondo
• settings.url
• settings.target
• settings.aria_label
• settings.background_position
• settings.background_overlay
• settings.show_searchparaheader-actions
• settings.show_mode_toggleparaheader-actions
• settings.show_accent_toggleparaheader-actions
• settings.show_language_switcherparaheader-actions
• traducciones de textos comotitleysubtitle
• traducciones de bloques de imágenes a través detranslations.image.alt_text,translations.image.caption, o la taquigrafíatranslations.alt_textytranslations.caption
• Agrupación del visor de galería de imágenes mediantesettings.viewer_enabledy una minúsculasettings.viewer_group; bloques de imágenes habilitados y no vinculados que comparten un renderizado grupal en un visor de galería CMS existente mientras permanecen en una posición independiente
• traducciones de formularios de contacto a través detranslations.contact_form.submit_labelytranslations.contact_form.success_message, o los mismos nombres que taquigrafía, junto contitleycontent
• url
• variant

Los campos traducidos se escriben en la familia de traducción a la que pertenece el tipo de bloque, para la configuración regional en la solicitud (la configuración regional predeterminada del sitio cuando se omite locale):

A que la familia no posee se rechaza con 422 y el código unsupported_block_translation_fields, y un tipo de bloque sin familia de traducción rechaza directamente translations con unsupported_block_translations; ninguno de los dos se escribe en la tabla de texto, donde nada lo leería. Una configuración regional que el sitio del bloque no ha habilitado se rechaza con invalid_block_translation_locale. Las filas almacenadas se devuelven en block.translations, codificadas por familia.

Para bloques de imagen, una cadena explícitamente vacía o null borra el caption o alt_text de la configuración regional seleccionada; los alias title y subtitle tienen el mismo comportamiento. Los campos omitidos mantienen sus valores almacenados. Al borrar el texto de la imagen editorial se conservan otros idiomas, referencias de medios y enlaces dinámicos. Un título editorial vacío no produce ningún título a menos que un enlace dinámico proporcione uno; la alternativa existente de medios/fuente dinámica para texto alternativo permanece vigente.

A Los formularios de contacto submit_label y success_message son traducciones, no configuraciones: son la única forma de localizar el botón del formulario y el texto de confirmación, y no se pueden configurar a través de settings.

El punto final rechaza campos de implementación de base de datos y topología como parent_id, slot_type_id, block_type_id, type, sort_order y children. También rechaza HTML sin formato, URL de medios remotos y URL de origen. Los medios existentes se pueden seleccionar desde la biblioteca de medios de CMS, pero este API no importa ni descarga nuevos medios remotos.

Ejemplo:

Para un bloque de imagen existente, actualice la fila de traducción de imágenes de propiedad local con:

Para la edición incremental de borradores de páginas, la topología de bloques de propiedad de la página se puede cambiar una operación a la vez sin enviar un plan de contenido completo:

{slot} es un slug de ranura propiedad de la página. Estos puntos finales son intencionalmente estrechos y seguros contra corrientes de aire:

• funcionan sólo en páginas borrador; una página que no es borrador devuelve JSON 409 con el código page_not_draft. Utilice contenido para aplicar actualizaciones por etapas para las páginas publicadas.
• operan solo en espacios de propiedad de la página; una ranura respaldada por Shared Slot devuelve JSON 422. Utilice los puntos finales Shared Slot para el contenido Shared Slot.
• an espacio de página desconocido devuelve JSON 404.

POST .../blocks agrega un bloque utilizando la misma carga útil de bloque normalizado que se aplica al contenido (type, settings, translations y children anidado). Los nuevos bloques se crean con el estado draft y se agregan al final de la ranura. Pase parent_id para agregarlo debajo de un bloque contenedor existente en la misma ranura; el padre debe aceptar a los niños. La creación y el reordenamiento requieren content.apply.

PATCH .../blocks/reorder vuelve a numerar un grupo de hermanos. La matriz blocks debe contener cada ID de hermano para un único grupo principal exactamente una vez, en el orden deseado; el padre se deriva de los bloques enviados. Al enviar un grupo parcial se devuelve JSON 422.

DELETE .../blocks/{block} elimina el bloque y todo su subárbol y devuelve deleted_blocks_count. La eliminación requiere la capacidad content.blocks.delete dedicada, que no forma parte del conjunto de capacidades de creación de páginas predeterminado. Los bloques de origen Shared Slot no se pueden eliminar a través de este punto final.

Cada escritura captura una revisión de página, por lo que las ediciones en borrador siguen siendo reversibles.

hero y cta son contenedores normales cuyos botones de acción son hijos simples de button_link; declarelos en children como cualquier otro bloque anidado. Quedan dos campos de bloqueo opcionales como abreviatura del caso común de uno o dos botones:

Ambos campos aceptan un objeto con un label requerido y un url requerido, o null para dejar la acción sin configurar. Las URL deben ser una ruta interna segura o una URL http(s). La taquigrafía escribe los dos primeros elementos secundarios button_link, por lo que el resultado es indistinguible de los botones que un editor agrega a mano. Declarar a los hijos explícitamente es la forma canónica y la única forma de crear más de dos botones. Se rechaza el envío de primary_cta o secondary_cta en cualquier otro tipo de bloque.

Los campos funcionan en todos los lugares donde se acepta una carga útil de bloque: validar/aplicar planes de contenido, POST /pages/{page}/slots/{slot}/blocks y POST /shared-slots/{sharedSlot}/blocks.

La recuperación de páginas utiliza un flujo de trabajo de inspección, vista previa y aplicación. No existe un punto final de restauración directa.

• GET /webadmin/api/pages/{page}/versions enumera las versiones guardadas con el estado de su página, los campos de auditoría y un resumen de los cambios de la versión anterior. GET .../versions/{version} devuelve la comparación completa y el resultado del estado de referencia. Ambos requieren content.read.
• POST .../versions/{version}/candidate requieren content.apply. Crea un borrador privado de candidato a partir de la instantánea y devuelve la URL de vista previa del navegador. La página de origen no se modifica.
• POST .../version-candidates/{candidate}/apply requiere tanto content.apply como content.publish. La solicitud se rechaza con JSON 409 y el código restore_candidate_stale si la página de origen cambió después de que se preparó el candidato. Una aplicación exitosa crea las versiones de seguridad normales previas y posteriores a la restauración y elimina el borrador técnico.
• DELETE .../version-candidates/{candidate} requiere content.apply; elimina el candidato sin cambiar la página de origen.

Los candidatos están deliberadamente ausentes del descubrimiento de páginas normal y de la exportación de sitios. Las herramientas siempre deben inspeccionar la versión, preparar un candidato, renderizar o abrir su preview_url, y solo entonces llamar a apply_url después de la aprobación explícita del operador.

GET /webadmin/api/pages/{page}/render requiere content.read y devuelve la página representada exactamente como la muestra la vista previa del administrador del navegador: bloques de borrador incluidos, X-Robots-Tag: noindex, nofollow, y nunca a través de la ruta pública, por lo que nada publica nada.

Agregue ?format=html para el marcado en sí en lugar del sobre JSON y ?locale=de para representar una traducción específica; el valor predeterminado es la configuración regional predeterminada del sitio. Una configuración regional para la que la página no tiene traducción devuelve 422 con page_translation_missing y las configuraciones regionales que sí tiene. Las páginas de origen Shared Slot están editando andamios y devuelven 422 con page_not_renderable, coincidiendo con el 404 del administrador del navegador.

Rendering ya era accesible antes de que existiera este punto final: GET /webadmin/pages/{page}/preview acepta un token de portador con content.read, así como una sesión de administrador, y todavía lo hace. El API agrega un sobre JSON y enlaces de descubrimiento/OpenAPI. La vista previa del navegador también acepta un código locale: el idioma debe estar habilitado para el sitio y tener una traducción de la página. Omitirlo mantiene el idioma predeterminado. Ambas vistas previas pasan el idioma elegido para bloquear la representación; ni guarda ni publica contenido.

Ede cualquier manera, renderice antes de informar que una página ha finalizado. La aplicación de contenido dice lo que se almacenó, que no es lo mismo que lo que se representa: un bloque contenedor sin elementos secundarios, una ranura asignada al Shared Slot incorrecto o un diseño sin las ranuras que el plan asumió, todos se aplican limpiamente y aun así producen una página que nadie quiere.

Las traducciones de páginas poseen la identidad de la página localizada y las anulaciones de SEO y Open Graph a nivel de página. La aplicación de contenido escribe una fila de traducción para una configuración regional cuando crea una página; estos puntos finales son cómo se lee esa fila y se cambia después.

GET /webadmin/api/pages/{page}/translations enumera todas las traducciones en una página con name, slug, path, seo_title, seo_description, seo_keywords, list_excerpt, og_title, og_description y og_image_media_id. list_excerpt es la oración por configuración regional que un bloque de Lista de páginas muestra bajo el título de esta página en una tarjeta de listado; tiene un límite de 300 caracteres y vuelve a la descripción SEO cuando está vacío. Los mismos campos ahora aparecen en cada traducción en GET /webadmin/api/pages/{page}.

POST /webadmin/api/pages/{page}/translations/{locale} requiere content.apply y agrega una traducción para una configuración regional que ya está habilitada para el sitio de la página. El segmento {locale} acepta un código local o una identificación numérica. Solo se requiere name: omita slug y path y ambos se derivan del nombre, exactamente como los deriva el administrador del navegador. Al crear una traducción para una configuración regional que la página ya tiene, se devuelve 422 con el código page_translation_exists.

.

PATCH /webadmin/api/pages/{page}/translations/{translation} requiere content.apply y escribe solo los campos que contiene la solicitud, por lo que una herramienta puede configurar seo_description sin reenviar la identidad de la página. Envíe null para borrar un campo opcional.

Slug y path siempre se mueven juntos. Al enviar path se vuelve a derivar el slug de su último segmento; enviar slug solo mueve la página a /{slug}. Las rutas se canonicalizan, se comparan con el CMS reservado y las rutas del host, y deben seguir siendo únicas para el sitio y la configuración regional. Debido a que el título y el slug Page leen la traducción predeterminada, cambiar el nombre de esa traducción cambia el nombre de la página misma.

Los campos fuera de identidad localizada y SEO se rechazan con 422 y el código unsupported_page_translation_fields, que los nombra en blocked_fields. El estado de la página, el diseño y el contenido del bloque tienen sus propios puntos finales.

Las páginas pueden cargar sus propios archivos /site/... CSS y JS además de los activos de todo el sitio:

{type} es css o js. El listado está disponible para cualquier token válido; los puntos finales de escritura requieren la capacidad de suscripción exclusiva page-assets.write, que no forma parte del conjunto de creación de páginas predeterminado.

El contrato path es deliberadamente estrecho y es el límite de seguridad para este API:

• debe ser una ruta local que comience con /site/ y termine en .css o .js que coincida con el tipo de activo
• URL externas (http://, https://), relativa al protocolo (//), javascript: y data: se rechazan
• Se rechaza el recorrido de directorio, las barras invertidas, las cadenas de consulta y los fragmentos

Este punto final solo adjunta un archivo existente a una página; nunca escribe el contenido del archivo. Escriba el archivo con los recursos del sitio API (PUT /webadmin/api/sites/{site}/assets/{type}, que requiere site-assets.write) o desde la interfaz de usuario del administrador.

Los campos admitidos son path (obligatorio al crear), sort_order, is_enabled y, solo para activos JS, is_defer, is_async y is_module. load_position se deriva del tipo (head para CSS, body_end para JS), que coincide con el editor de administración. El tipo css/js es inmutable en la actualización; eliminar y volver a agregar para cambiarlo.

UA diferencia de los puntos finales de topología de bloque de página, los recursos de página no son solo borradores: se pueden cambiar en cualquier página, coincidiendo con la pestaña Recursos de página de administración. Cada escritura captura una revisión de página.

Shared Slot los árboles de bloques tienen sus propios puntos finales de topología porque se comparten en cada página a la que está asignada la ranura:

Aagregar bloques permanece en POST /shared-slots/{sharedSlot}/blocks y editar los campos de contenido seguro de un solo bloque permanece en PATCH /blocks/{block} (que ya acepta bloques de origen Shared Slot con shared-slots.write). Los nuevos puntos finales agregan las operaciones de topología que faltan:

• PATCH .../blocks/reorder vuelve a numerar un grupo de hermanos; la matriz blocks debe contener cada ID de hermano para un único grupo principal exactamente una vez, en el orden deseado. Requiere shared-slots.write.
• DELETE .../blocks/{block} elimina un bloque y su subárbol y devuelve deleted_blocks_count.
• DELETE .../blocks limpia cada bloque en la ranura para que una herramienta pueda borrar y reemplazar un Shared Slot; devuelve deleted_blocks_count.
• Ambas eliminaciones requieren shared-slots.write más la capacidad dedicada content.blocks.delete.

A diferencia de las ediciones de bloques de páginas, estas no son solo borradores: Shared Slots no tiene el concepto de página borrador. Por lo tanto, reordenar o eliminar un bloque Shared Slot ya publicado afecta inmediatamente a todas las páginas asignadas, razón por la cual la eliminación está bloqueada detrás de la capacidad destructiva content.blocks.delete. Cada escritura reconstruye las asignaciones de página de la ranura y captura una revisión Shared Slot para que los cambios sigan siendo reversibles.

Ajunto a branding, head, timezone y public-theme, se pueden escribir tres campos de sitio más. Los tres requieren site-settings.write.

PATCH /webadmin/api/sites/{site}/seo escribe seo_title, seo_description y seo_keywords: los metadatos alternativos de todo el sitio que hereda una página pública cuando la traducción de su propia página no tiene anulación. Parcial y null borra un campo. Las anulaciones a nivel de página pertenecen a la traducción de la página; consulte la traducción de la página API arriba.

PATCH /webadmin/api/sites/{site}/contact-recipient escribe contact_recipient_email, la dirección a la que se envían los envíos del formulario de contacto. Envíe un valor vacío para recurrir al destinatario del sistema. Un formulario de contacto creado a través del API no hace nada útil hasta que se configura.

PUT /webadmin/api/sites/{site}/locales reemplaza la configuración regional del sitio establecida de locale_ids. La configuración regional predeterminada siempre se mantiene, exactamente como la mantiene el formulario de administrador, y las configuraciones regionales deben habilitarse globalmente primero a través de POST/PATCH /webadmin/api/locales. No se puede guardar la traducción de una página para una configuración regional que el sitio no ha habilitado, por lo que este es el punto final que hace que una nueva configuración regional sea utilizable en un sitio.

Este punto final es más estricto que el formulario de administración en un aspecto: se niega a separar una configuración regional que todavía tiene traducciones de páginas en el sitio, y 422 nombra la configuración regional y el recuento. El formulario permite al operador hacerlo a sabiendas; una herramienta desatendida dejaría huérfano silenciosamente el contenido.

Los registros de dominio deciden qué nombre de host se resuelve en qué sitio, por lo que el administrador del navegador los mantiene con acceso a nivel de sistema. Los puntos finales API son:

• PATCH /webadmin/api/sites/{site}/seo
• PATCH /webadmin/api/sites/{site}/contact-recipient
• PUT /webadmin/api/sites/{site}/locales
• GET /webadmin/api/sites/{site}/domains requiere content.read
• POST /webadmin/api/sites/{site}/domains requiere domains.write
• PUT /webadmin/api/sites/{site}/domains/{domain} requiere domains.write
• POST /webadmin/api/sites/{site}/domains/{domain}/primary requiere domains.write
• DELETE /webadmin/api/sites/{site}/domains/{domain} requiere el destructivo domains.delete
• GET /webadmin/api/domains/{domain}/status requiere content.read

Estos puntos finales anteriormente vivían solo bajo un prefijo /admin-api y no verificaban nada más allá de la validez del token, por lo que cualquier token podía agregar o eliminar un dominio. Ahora se encuentran debajo del /webadmin/api con el resto del API y cada ruta tiene una capacidad. El prefijo /admin-api sigue funcionando para las herramientas de aprovisionamiento existentes, con los mismos requisitos de capacidad y una ruta adicional, GET /admin-api/sites; las nuevas integraciones deben usar /webadmin/api, cuyas rutas también están cubiertas por la exención CSRF que el prefijo heredado nunca tuvo.

PATCH /webadmin/api/shared-slots/{sharedSlot} requiere shared-slots.write y cambia el propio Shared Slot en lugar de sus bloques: label, handle, slot, layout y is_active. Sólo se escriben los campos presentes. Los identificadores siguen siendo únicos por sitio, el nombre del espacio debe resolverse en un tipo de espacio publicado y la página de origen Shared Slot y sus asignaciones se reconstruyen posteriormente exactamente como las reconstruye el administrador del navegador. Un cambio de estado o metadatos captura una revisión Shared Slot.

Mover un Shared Slot a otro sitio no se admite aquí y se rechaza con 422 y el código unsupported_shared_slot_fields, que también cubre cualquier otro campo fuera de ese conjunto. Los movimientos entre sitios permanecen en el administrador del navegador junto con las operaciones de transferencia de otros sitios.

DELETE /webadmin/api/shared-slots/{sharedSlot} requiere la capacidad destructiva shared-slots.delete y aplica la misma protección que el administrador del navegador: un Shared Slot al que todavía se hace referencia en cualquier espacio de página nunca se elimina. La respuesta 422 lleva el código shared_slot_in_use y una matriz usage que nombra las ranuras de la página de referencia, por lo que una herramienta puede separarlas primero con PUT /webadmin/api/pages/{page}/slots/{slot}/source. Si las columnas de referencia Shared Slot aún no se han migrado, el punto final devuelve 409 con shared_slots_not_ready en lugar de adivinar.

La biblioteca multimedia API está separada intencionalmente de amplios permisos de contenido para que las herramientas de operador/IA puedan recibir descubrimiento de medios o limpieza de metadatos sin recibir poderes de escritura no relacionados.

Capacidad:

• media.read: enumera e inspecciona los registros existentes de la biblioteca multimedia de CMS.
• media.upload: carga archivos en la biblioteca multimedia.
• media.write: actualiza metadatos seguros en registros multimedia existentes.
• media.replace: reemplaza un archivo multimedia existente conservando su ID de medio.
• media.move: mueve medios entre carpetas o borra su carpeta.
• media.delete: elimina los medios no utilizados con la misma protección de uso que el panel de administración.

Alcance de la fase 1:

GET /webadmin/api/media devuelve registros multimedia existentes con campos seguros como ID, tipo, título, nombre de archivo, nombre original, tipo MIME, visibilidad, URL pública cuando esté disponible, texto alternativo, dimensiones, capacidad de vista previa y etiqueta de metadatos compactos. Requiere media.read. Durante la transición de tokens API más antiguos, es posible que también se acepte content.read para el descubrimiento de medios de solo lectura, de modo que las integraciones de creación de páginas existentes sigan funcionando.

GET /webadmin/api/media/folders enumera las carpetas de la biblioteca multimedia con sus recuentos de medios, y POST /webadmin/api/media/folders requiere media.write y crea una a partir de name, con slug y parent_id opcionales. Un nombre que ya existe bajo el mismo padre se rechaza con 422 y el código media_folder_exists, y la respuesta lleva la carpeta existente, por lo que una herramienta de reintento la reutiliza en lugar de crear duplicados. Carga de archivos en una carpeta con folder_id; mover medios existentes con POST /webadmin/api/media/{media}/move.

POST /webadmin/api/media requiere media.upload y acepta cargas de multipart/form-data en la biblioteca multimedia CMS normal. El archivo cargado se convierte en una fila media normal y es visible en la pantalla de medios del administrador del navegador y en los selectores de medios. La validación de carga refleja los tipos de archivos permitidos por la biblioteca multimedia del administrador del navegador: imágenes comunes, videos, PDF, documentos de Office, texto/CSV/RTF y archivos ZIP.

Los campos de metadatos admitidos son folder_id, title, alt_text, caption y description. El punto final devuelve el objeto multimedia creado con su ID y URL pública cuando esté disponible.

PATCH /webadmin/api/media/{media} requiere media.write y actualiza solo metadatos descriptivos seguros:

• title
• alt_text
• caption
• description

POST /webadmin/api/media/{media}/replace requiere media.replace y reemplaza el archivo binario almacenado conservando la identificación del medio y las referencias existentes. El archivo de reemplazo debe resolverse en el mismo tipo de medio que el registro existente, como imagen a imagen o documento a documento. La respuesta incluye detalles de uso actual para que las herramientas puedan ver si el reemplazo afecta los bloques, la marca del sitio o el SEO de la página.

POST /webadmin/api/media/{media}/move requiere media.move y acepta folder_id, incluido null para borrar la asignación de carpeta.

DELETE /webadmin/api/media/{media} requiere media.delete y utiliza la misma protección de uso que el administrador del navegador. Los medios a los que se hace referencia en bloques, galerías, archivos adjuntos, marcas del sitio o SEO de la página no se eliminan; el API devuelve 422 con detalles de uso en su lugar.

Este API no admite explícitamente:

• cambiar disco, ruta, nombre de archivo, tipo MIME, tipo, visibilidad, tamaño, dimensiones, cargador o relaciones de uso directamente
• obtener o importar URL de medios remotos

Este límite permite que las herramientas de operador/IA reciban solo los poderes de medios que necesitan. Por ejemplo, un token de creación de páginas puede leer y cargar medios sin poder eliminar o reemplazar archivos existentes, mientras que a un token de mantenimiento confiable se le puede otorgar media.replace o media.delete explícitamente.

La sustitución en páginas en borrador existentes se mantiene dentro del contrato de validate/apply:

Utilice mode: replace_existing_draft_page para reemplazar uno o más espacios de propiedad de la página en una página borrador existente. La operación requiere content.validate para validar y content.apply para aplicar. No requiere pages.delete, porque no es una operación de eliminación de página general.

Traducción de página path es la URL pública canónica. Los nuevos planes deben utilizar rutas como /contact, /features, /games/fruit-train o /docs/internal-content-api; /p/... es solo compatible con versiones anteriores. Las rutas con barras diagonales se normalizan segmento por segmento, por lo que /docs/internal-content-api/ se convierte en /docs/internal-content-api y no se contrae en docsinternal-content-api. CMS deriva el slug de página corta del segmento de ruta final, por lo que /games/fruit-train almacena el slug fruit-train y la ruta /games/fruit-train. Las áreas de rutas reservadas como /webadmin, /webadmin/api, /cms, /search, /search.json, /contact-messages, /install y las rutas de autenticación de host no se pueden crear como rutas de páginas públicas.

Ejemplo:

Reglas:

• la página de destino debe estar en estado draft
• se requiere expected_path o expected_updated_at
• expected_path usa la ruta pública canónica de Page Translation, no un alias heredado /p/...
• la página de destino debe pertenecer al sitio solicitado y el idioma (locale) debe estar habilitado para ese sitio
• cada slot debe existir en la página y usar bloques propiedad de la página
• los slots respaldados por Shared Slots se rechazan en lugar de vaciarse
• solo se eliminan los bloques de los replace_slots indicados
• los bloques antiguos se eliminan y los nuevos se escriben en una sola transacción
• se capturan revisiones de la página antes y después de aplicar
• no se produce publicación, descarga/importación de medios, eliminación amplia ni vaciado de asignaciones de Shared Slot

Las páginas publicadas no se pueden reemplazar directamente. Para páginas de documentos con vínculos de origen u otras páginas activas que deben permanecer públicas mientras se preparan los cambios de contenido, utilice los modos de actualización por etapas:

create_staged_update_for_published_page crea un borrador de página provisional a partir de la página de origen publicada solo cuando esa página de origen aún no tiene un borrador de actualización provisional activa. Al repetir la llamada de creación para la misma página de origen, se devuelve el borrador preparado activo existente con data.reused_staged_update=true en lugar de crear otra página técnica. La página de origen permanece publicada en su ruta pública existente. La página preparada almacena metadatos settings.staged_update con la identificación de la página de origen, la ruta de origen, la marca de tiempo actualizada del origen, el estado del ciclo de vida y las ranuras administradas. Utiliza una ruta de borrador interna como /staged-updates/page-123/update-456, por lo que no choca con la ruta canónica de origen y no se enruta públicamente. La URL de vista previa de administrador normal /webadmin/pages/{page}/preview puede representar la página preparada para sesiones de administrador autenticadas o tokens de portador CMS API con content.read.

replace_staged_page_update reutiliza las reglas de reemplazo de borradores en la página de borrador preparado. Úselo para cada revisión posterior después de que exista un borrador preparado. Reemplaza únicamente los espacios propiedad de la página y rechaza los espacios respaldados por Shared Slot.

promote_staged_page_update aplica el contenido del espacio de propiedad de la página preparada nuevamente en la página de origen publicada en una transacción. Conserva la ruta de la página de origen, el estado, el diseño, las asignaciones de Shared Slot y la configuración de la página a menos que se proporcione una actualización de source_sync incluida en la lista de permitidos. Los bloques propiedad de páginas promocionadas se escriben como published, por lo que la página pública refleja el contenido promocionado de inmediato. El contenido Shared Slot nunca se pone en cascada. Después de capturar las versiones de seguridad anteriores y posteriores a la promoción de la página de origen, la página técnica preparada se elimina en la misma transacción; por lo tanto, una promoción fallida deja el borrador disponible para su corrección. La promoción requiere la capacidad de ruta normal content.apply y la capacidad avanzada content.publish.

Abandando un borrador por etapas activo se utiliza DELETE /webadmin/api/pages/{staged_page}/staged-update. Este punto final de descarte restringido requiere content.apply, acepta solo una página borrador con metadatos de actualización por etapas activa y nunca cambia la página de origen publicada ni sus versiones guardadas. Evita conceder a una herramienta de creación de páginas la amplia capacidad pages.delete simplemente para limpiar su propio borrador técnico.

Si un plan de aplicación normalizado pasa la validación pero falla durante las escrituras transaccionales, API devuelve la validación normal JSON con ok=false y un error en plan.apply. La excepción detallada se registra en los registros de la aplicación; Las respuestas de API son seguras para el público y no incluyen seguimientos de pila, componentes internos de bases de datos, tokens ni rutas locales.

Emplo de flujo de trabajo por etapas:

Luego reemplace el contenido preparado:

Promoción después de vista previa y aprobación explícita:

No se requiere una nueva tabla de esquema para este flujo de trabajo; Los metadatos del ciclo de vida por etapas activos utilizan la columna de página settings JSON existente. Las páginas técnicas promocionadas no se conservan porque las versiones de la página de origen proporcionan el rastro de recuperación.

Las instalaciones que se actualizan desde una versión que archivó páginas preparadas promocionadas pueden obtener una vista previa y eliminar esos registros heredados una vez:

El comando selecciona solo páginas archivadas cuyos metadatos preparados digan explícitamente type=published_page_update y state=promoted. Los borradores activos y las páginas archivadas ordinarias nunca son candidatos.

Los planes de contenido pueden guardar un objeto source_sync limitado y libre de secretos para los flujos de sincronización de documentación de IA/operador. Los ajustes de página arbitrarios se rechazan. La forma aceptada es:

Apply guarda estos metadatos en los ajustes de la página, y las respuestas de la API de listado/detalle de páginas exponen los mismos campos permitidos de source_sync para futuras coincidencias. No incluya tokens, valores de entorno, rutas absolutas locales o del servidor ni otros secretos.

La publicación está separada de content apply y requiere un token con content.publish.

POST /webadmin/api/pages/{page}/publish publica el registro de la página. Su payload por defecto afecta solo a la página:

Reglas:

• omitidoinclude_page_owned_blocksse comporta comofalse
• include_page_owned_blocks: falsepublica solo el registro de la página y deja sin cambios los borradores o los bloques en revisión
• include_page_owned_blocks: truepublica bloques borradores y en revisión propiedad de los espacios de página no compartidos de la página, incluidos los bloques secundarios anidados
• Los bloques ya publicados permanecen sin cambios.
• Las ranuras respaldadas por Shared Slot están excluidas y se informan en la respuesta
• campos en cascada Shared Slot no compatibles, comopublish_shared_slots,include_shared_slot_blocks, oshared_slot_cascadedevolver JSON422
• la respuesta incluye metadatos de identificación/estado/ruta de la página, si se incluyeron bloques de propiedad de la página, el recuento publicado, los resúmenes Shared Slot excluidos y la identificación de la revisión de la página.

POST /webadmin/api/pages/{page}/publish-page-owned-blocks publica solo bloques propiedad de la página no publicados y no cambia el estado del flujo de trabajo de la página. Utiliza la misma capacidad content.publish y la misma regla de exclusión Shared Slot.

POST /webadmin/api/pages/{page}/archive saca la página del sitio público: las páginas archivadas devuelven 404 a los visitantes y los elementos del menú vinculados a la página dejan de mostrarse en los menús públicos. Utiliza la misma capacidad content.publish y refleja las reglas del flujo de trabajo de administración: permitido desde in_review y published, una página borrador devuelve JSON 422, volver a archivar una página archivada no es un éxito operativo y las páginas de actualización por etapas se rechazan (promocionarlas o eliminarlas). La respuesta incluye metadatos de la página, from_status, y el ID de revisión de la página capturada. Al publicar la página nuevamente se invierte el archivo.

I/las herramientas del operador no deben asumir que la publicación de la página hace público todo el contenido del bloque. Utilice include_page_owned_blocks: true solo cuando el usuario haya aprobado explícitamente la publicación de todos los bloques de propiedad de la página no publicados para esa página. El contenido de Shared Slot debe revisarse y publicarse por separado.

GET /webadmin/api/content-contract es un punto final de descubrimiento de solo lectura para herramientas de operador/IA confiables. Devuelve el prefijo API, validar/aplicar URL, plantilla de URL de vista previa del administrador, indicadores de seguridad, URL de descubrimiento, patrones de creación de páginas recomendados, un contrato de dirección de diseño legible por máquina y metadatos de contrato de bloque desinfectados.

Antes de elegir un árbol de bloques, las herramientas deben leer design_direction, seleccionar un valor para cada uno de character, density, typography, geometry, imagery, corners, contrast y framing, y explique cómo el mapa de composición implementa esas opciones. Se trata de un contrato de planificación en lugar de un almacén de contenido oculto: el resultado se expresa a través de configuraciones de bloques nativos, tokens de temas públicos y el sitio estable CSS. Su política de composición hace que las columnas sean claras de forma predeterminada para los nuevos planes API, mantiene la opción de participación de las tarjetas y requiere una justificación de acción/límite de contenido para cada colección de tarjetas. Una fuente que contenga tres artículos breves no constituye tal justificación.

framing es una dimensión de planificación, no datos de página persistentes. Elija open, restrained, framed o dense-ui según el contenido y el contexto. No utilice una Tarjeta o un panel con bordes simplemente para organizar una sección. El encuadre debe comunicar independencia semántica, interacción o límites de entidad. Los contenedores externos de héroe, los grupos de características/principios, los envoltorios de sección, las columnas de navegación/pie de página, las bandas de CTA, las estadísticas decorativas y las divisiones editoriales no están enmarcados de forma predeterminada. Prefiere espacios en blanco, jerarquía tipográfica, diseño asimétrico, divisores, cambios de tono, secciones anchas, alineación, desplazamiento/superposición y reglas restringidas. La auditoría de superficie enmarcada requerida debe justificar cada superficie enmarcada que no sea una entidad; “separar visualmente la sección” no es suficiente.

La sección adyacente design_fixtures publica árboles de bloques nativos canónicos, direcciones de diseño compatibles, ganchos públicos esperados, antipatrones y tamaños de captura deterministas de escritorio/móvil. Su estado distingue un contrato de renderizado respaldado en fuente de capturas de pantalla aprobadas por humanos. Las herramientas pueden utilizar un árbol de elementos fijos como referencia de composición, pero no deben reclamar aprobación visual mientras el registro informa render_contract_ready_capture_pending. Consulte los contratos de composición disponibles en design_fixtures dentro de la respuesta de descubrimiento.

El punto final es el comportamiento genérico del producto CMS. No debe devolver secretos específicos de la instalación, valores de token, contenidos sin procesar de Blade, rutas absolutas del sistema de archivos, rutas de servidores privados ni instrucciones específicas del sitio. Las filas de contrato de bloque pueden incluir identificador/slug, etiqueta, categoría, estado, contenedor y manutención infantil, campos traducibles, campos de configuración compartida y comportamiento de raíz del procesador público.

Las herramientas

I deben llamar a este punto final o GET /webadmin/api/block-types antes de crear un plan y deben usar solo identificadores que estén presentes en la instalación actual.

Los contratos en bloque pueden exponer campos de insignias e íconos públicos opcionales, incluidos settings.icon_slug, settings.icon_tone, settings.icon_size, settings.badge_tone y la copia traducida de eyebrow/badge_label. Las herramientas deben tratar los iconos como selecciones respaldadas por catálogos en lugar de texto libre; La representación pública omite los íconos desconocidos o inactivos y solo emite clases wb-icon wb-icon-{slug} seguras para las filas activas del catálogo WebBlocks UI. settings.icon_tone es una configuración de tono visual pública compartida, no una copia de propiedad local, y acepta solo default, soft, brand, accent, highlight, bold y quiet; settings.icon_size acepta default, sm, lg o xl y se asigna a la clase de tamaño WebBlocks UI correspondiente. info, success, warning y danger siguen siendo tonos de estado semánticos para insignias, alertas, validación y comentarios. Los tonos o tamaños de íconos desconocidos se rechazan durante la validación del plan de contenido o se ignoran en la representación pública como alternativa segura. El tono de la insignia se expone solo cuando el bloque también posee la copia traducida de la etiqueta de la insignia.

GET /webadmin/api/icon-catalog?context=content devuelve los iconos de seguridad activos que los clientes de API pueden asignar a bloques de contenido público. Utilice context=navigation para clasificar primero las sugerencias etiquetadas de navegación para las opciones de íconos de elementos de navegación; Ambos contextos aún devuelven todos los íconos activos porque el contexto es una pista en lugar de una lista de permitidos. Las herramientas API deben leer este punto final antes de enviar valores settings.icon_slug o icon de navegación y no deben adivinar los nombres de los iconos del manifiesto WebBlocks UI.

El contrato contact_form incluye metadatos de formulario seguros adicionales: esquema de configuración, campos traducidos, punto final de envío público POST /contact-messages, comportamiento requerido del navegador CSRF, reglas de validación del servidor, campo de verificación antispam generado oculto propiedad del CMS, comportamiento exitoso del campo de verificación genérico, clasificación de spam/notas de cuarentena, comportamiento de almacenamiento antes de la notificación, orden de reserva del destinatario, falla de notificación segura grabación y comportamiento de revisión /webadmin/contact-messages. El campo de verificación lo genera el renderizador, no forma parte de la entrada normal de los visitantes y no debe crearse manualmente mediante API o herramientas de operador/IA. Las herramientas de la página de contacto deben usar ese bloque nativo en lugar de Trusted HTML, marcado de formulario sin formato o formularios mailto:. El antiguo campo website ya no es el contrato del formulario de contacto público.

La guía de creación de páginas de IA legible por humanos se envía en instalaciones nativas del paquete en vendor/fklavyenet/webblocks-cms/docs/ai-page-building-guide.md.

• GET /webadmin/api
• GET /webadmin/api/openapi.json
• GET /webadmin/api/ai-guide
• GET /webadmin/api/examples
• GET /webadmin/api/examples/contact-page
• GET /webadmin/api/examples/landing-page
• GET /webadmin/api/sites
• GET /webadmin/api/locales
• GET /webadmin/api/locale-options
• POST /webadmin/api/locales
• PATCH /webadmin/api/locales/{locale}
• GET /webadmin/api/page-layouts
• GET /webadmin/api/block-types
• GET /webadmin/api/icon-catalog
• GET /webadmin/api/content-contract

• GET /webadmin/api/pages
• GET /webadmin/api/pages/{page}
• GET /webadmin/api/pages/{page}/render
• GET /webadmin/api/pages/{page}/translations
• POST /webadmin/api/pages/{page}/translations/{locale}
• PATCH /webadmin/api/pages/{page}/translations/{translation}
• POST /webadmin/api/pages/{page}/sync-layout-slots
• PATCH /webadmin/api/pages/{page}/layout
• POST /webadmin/api/pages/{page}/slots/{slot}/shared-slot
• PUT /webadmin/api/pages/{page}/slots/{slot}/source

• GET /webadmin/api/blocks
• GET /webadmin/api/blocks/{block}

• GET /webadmin/api/navigation-menus
• GET /webadmin/api/navigation-menus/{navigationMenu}
• POST /webadmin/api/navigation-menus
• POST /webadmin/api/navigation-menus/{navigationMenu}/items
• PATCH /webadmin/api/navigation-menus/{navigationMenu}/items/{item}
• PATCH /webadmin/api/navigation-menus/{navigationMenu}/items/reorder
• DELETE /webadmin/api/navigation-menus/{navigationMenu}/items/{item}

Los menús de navegación utilizan el modelo CMS navigation_items.menu_key existente. La Fase 2A admite los identificadores de menú del CMS enviados, como primary, footer, mobile, legal y docs; no agrega una tabla de menú separada. La creación de un menú de navegación se considera como la creación de un grupo de menús seguro para el sitio con elementos iniciales opcionales. Se niega a sobrescribir un sitio/menú que ya tiene elementos.

La creación, actualización, cambios de visibilidad y reordenamiento de elementos de navegación requieren navigation.write. Eliminar requiere la capacidad explícitamente destructiva navigation.delete. Las actualizaciones de artículos son compatibles con label/title, url, link_type, page_id, target, visibility, sort_order/position, parent_id y icon donde esos campos son válidos para el tipo de enlace seleccionado. Las actualizaciones son parciales: los campos ausentes de la carga útil mantienen sus valores almacenados sin revalidación, por lo que las filas heredadas (un orden de clasificación previo al editor de árbol de 0, un hijo anidado bajo un padre de tipo de página) siguen siendo actualizables; las reglas se aplican a los valores que realmente envía una solicitud.

Las actualizaciones de artículos también aceptan una clave locale opcional (un código local habilitado para el sitio del artículo), lo que refleja las escrituras de traducción de bloques. Sin locale, o con la configuración regional predeterminada del sitio, label/title escribe el título canónico de la configuración regional predeterminada. Con un locale no predeterminado, el valor label/title se almacena como una fila de traducción con clave regional para ese elemento y el título canónico permanece intacto; Otros campos en la misma solicitud (visibilidad, posición, etc.) permanecen compartidos y se aplican al artículo en sí. La representación pública elige el título de navegación para la configuración regional solicitada y recurre al título canónico de configuración regional predeterminada cuando no existe una fila de traducción. Las cargas útiles de lectura de elementos exponen los títulos almacenados por configuración regional como un mapa title_translations codificado por código de configuración regional. Las cargas útiles de reorden deben incluir todos los elementos del sitio/menú seleccionado exactamente una vez. Eliminar rechaza los elementos principales que todavía tienen elementos secundarios, por lo que las herramientas deben mover o eliminar los elementos secundarios primero en lugar de depender de las cascadas.

Las URL de elementos de navegación pueden ser rutas internas como /, /about, /contact y /#platform, o URL seguras http/https. Utilice una ruta más un fragmento para anclajes de la misma página; Los valores de solo fragmentos sin procesar, como #platform, no son URL de navegación. El API rechaza javascript:, data:, URL relativas al protocolo, recorrido, URL con formato incorrecto, destinos no admitidos y etiquetas vacías. Los puntos finales de navegación no crean páginas, publican páginas, rastrean sitios, recuperan URL remotas ni eliminan elementos secundarios en cascada.

• GET /webadmin/api/shared-slots
• GET /webadmin/api/shared-slots/{sharedSlot}
• PATCH /webadmin/api/shared-slots/{sharedSlot}
• DELETE /webadmin/api/shared-slots/{sharedSlot}
• POST /webadmin/api/shared-slots
• POST /webadmin/api/shared-slots/{sharedSlot}/blocks
• POST /webadmin/api/shared-slots/{sharedSlot}/publish-blocks

Shared Slot La creación tiene un ámbito de sitio y rechaza identificadores duplicados para el mismo sitio. Los bloques Shared Slot reutilizan el mismo escritor de carga útil de bloque utilizado por los bloques propiedad de la página, por lo que la copia de propiedad local permanece en las filas de traducción y las configuraciones compartidas permanecen en la ruta de configuración/registro del bloque. Las solicitudes de adición de bloque Shared Slot pueden incluir parent_id o parent_block_id para agregar un bloque debajo de un bloque existente en el mismo árbol de origen Shared Slot cuando ese padre acepta el tipo de hijo solicitado. Los bloques Shared Slot se crean como contenido borrador y requieren POST /webadmin/api/shared-slots/{sharedSlot}/publish-blocks explícito con shared-slots.write más content.publish antes de renderizarse públicamente. La importación y asignación de medios quedan fuera de esta fase.

El punto final shared-slot asigna un Shared Slot activo compatible existente en el mismo sitio a un espacio de página existente. No publica la página. Rechaza Shared Slots entre sitios, inactivo e incompatible. También se niega a cambiar una ranura que todavía tiene bloques de propiedad de la página, porque la Fase 2A no elimina ni reemplaza esos bloques automáticamente.

PUT .../source escribe la fuente de contenido de la ranura y es el camino de regreso: source_type acepta page, shared_slot o disabled. Requiere content.apply y shared_slot requiere además shared-slots.write y las mismas reglas de compatibilidad que el punto final de asignación, en el que delega. La separación borra shared_slot_id y deja intactos los bloques de propiedad de la página, por lo que page los renderiza nuevamente y disabled mantiene el contenedor de ranura sin nada dentro. Antes de que existiera este punto final, el API podía crear una referencia Shared Slot que no tenía forma de eliminar; la única salida era la pantalla de administración autenticada por sesión.

Si el diseño de página contiene un espacio como header pero el registro de página se creó antes de que existiera ese espacio de página, llame primero a POST /webadmin/api/pages/{page}/sync-layout-slots. La sincronización de ranuras es idempotente y solo crea ranuras de página faltantes en el diseño de página seleccionado; nunca elimina ranuras, bloques, estados deshabilitados, asignaciones, traducciones o revisiones de Shared Slot existentes. Para un nuevo encabezado Shared Slot, publique los bloques Shared Slot explícitamente antes de esperar una salida pública.

Escribe el diseño de página de una página existente (public_shell). El formulario de edición del administrador siempre podría cambiar esto; Anteriormente, el API solo podía configurarlo al crear una página. content.apply lo cubre. layout (o handle) debe ser uno de los identificadores activos de GET /webadmin/api/page-layouts; el alias heredado dashboard aún se normaliza como docs. Coincide con el propio contrato de PageController::update(): no muta los espacios de página en un cambio de diseño simple, por lo que este punto final tampoco lo hace. Llame a sync-layout-slots por separado si el nuevo diseño define espacios que la página aún no tiene.

Este punto final actualiza solo el tema público del sitio seguro preestablecido utilizado por la representación pública. Envíe public_theme_preset o theme con uno de los valores Site::PUBLIC_THEME_PRESETS admitidos, como canvas, atlas, pulse, prism, graphite o horizon. Utilice esto cuando el descubrimiento de API muestre una representación del sitio con el ajuste preestablecido de data-wb-public-theme incorrecto; no intente anular el ajuste preestablecido con bloques de contenido.

PATCH /webadmin/api/sites/{site}/branding requiere site-settings.write y actualiza los campos de marca de sitio público seguros que también son visibles en Sites -> Edit Site -> Branding:

• display_name
• tagline
• favicon_media_id
• social_image_media_id
• El reemplazo de medios conserva la identificación del medio y las referencias editoriales, borra las transformaciones de imágenes obsoletas y deriva variantes futuras del binario de reemplazo.

Los campos de favicon e imagen social deben hacer referencia a registros de imágenes de la biblioteca multimedia de CMS y null borra los medios seleccionados. Los cambios en el favicon del sitio público deben utilizar este punto final para que el resultado siga siendo editable por el administrador. No sobrescriba /cms/brand/*; esos archivos son activos de shell de administrador/producto CMS, no marcas públicas a nivel de sitio.

PATCH /webadmin/api/sites/{site}/timezone requiere site-settings.write y establece la propia zona horaria de un sitio: un identificador estándar de IANA como Europe/Berlin. Cualquier cosa que resuelva la hora del reloj local para ese sitio, como las ventanas de disponibilidad de reservas de un complemento, se interpreta en función de este valor. Envíe un timezone vacío para borrarlo de nuevo a la zona horaria de todo el sistema de instalación desde Admin -> System Settings.

GET /webadmin/api/sites/{site}/assets/{css|js} requiere site-assets.read y lee el archivo de anulación físico canónico a nivel de sitio. Devuelve relative_path, public_path, exists, contents, checksum, size, updated_at, readiness, guidance y CSS. analysis sin exponer la ruta absoluta del servidor. El objeto readiness informa si el directorio del sitio, el directorio de activos y el archivo se pueden escribir lo suficiente para que CMS cree o actualice el activo. El objeto guidance indica a las herramientas de operador/IA que mantengan el token CSS primero, el modo consciente y el bloque nativo primero. Para CSS, asset.analysis.mode_awareness informa status, mensajes de advertencia, claves antipatrón detectadas, señales como recuento de colores literales y tokens --wb-public-* recomendados. PUT /webadmin/api/sites/{site}/assets/{css|js} requiere site-assets.write y acepta:

• contents
• expected_checksum

El punto final de escritura utiliza el mismo almacén de archivos físicos que Sites -> Edit Site -> Assets. Escribe solo public/site/{site_handle}/css/site.css o public/site/{site_handle}/js/site.js, crea directorios faltantes en el primer guardado, rechaza valores obsoletos de expected_checksum y almacena una instantánea de revisión previa a la sobrescritura antes de reemplazar un archivo modificado existente. No existe una ruta alternativa de base de datos ni un escritor de ruta /site/... arbitrario. Si los permisos de alojamiento impiden la creación de directorios o la escritura de archivos, el punto final devuelve JSON 422 con errors.0.path = asset.write y los metadatos de preparación actuales en lugar de un error de servidor HTML.

Para escrituras de CSS, utilice la estructura/configuración de bloques nativos, los campos de fondo de la biblioteca multimedia, los tokens de temas públicos y los estilos de componentes WebBlocks UI heredados antes de agregar selectores personalizados. Si los colores personalizados son inevitables, defina propiedades semánticas personalizadas con valores claros y oscuros vinculados a selectores de modo activo o tokens de temas públicos para que las páginas públicas permanezcan coherentes en el modo Claro/Oscuro/Automático. Evite fondos claros codificados en toda la página, texto oscuro, tarjetas blancas o paletas únicas en modo oscuro cuando los tokens de temas públicos puedan expresar el diseño. PUT no rechaza las advertencias de reconocimiento de modo porque algunos sistemas de marca necesitan colores personalizados intencionales, pero las herramientas deben tratar a asset.analysis.mode_awareness.status = warning como un trabajo para revisar, informar o corregir antes de considerar completada una migración o la configuración de un nuevo sitio.

Los comentarios se eliminan antes del análisis: una hoja de estilo que se documenta citando la regla que repara no informa el color citado como uno propio, y un ámbito de modo oscuro nombrado solo en un comentario no cuenta como presente.

Las comprobaciones de anti_patterns se refieren a pintura en toda la página, por lo que cada una requiere que su token sea el último compuesto del selector y termine donde termina el nombre: se informa body { background: #fff }, no se lee body .promo { background: #fff } y .wb-public-body { ... }, y no se lee .wb-card-title. .wb-card. Una regla que pinta un elemento se deja según las señales de color literal en lugar de informarse como un antipatrón para toda la página.

asset.analysis.mode_awareness es intencionalmente un contrato heurístico, no un linter CSS. Informa pass o warning, warnings, anti_patterns detectado, signals simple como declaraciones de color literales, uses_public_theme_tokens y has_dark_mode_scope, además de los roles de token --wb-public-* recomendados. Las herramientas deben usar esta señal para detectar posibles regresiones de modo mixto de manera temprana y seguir dependiendo del control de calidad visual para la paridad del diseño final.

Acódigo de aplicación no debe fusionarse en el site.css o site.js global de un sitio. Un Embedded Application registrado puede poseer un CSS físico, un JavaScript y una entrada index.html administrada en su directorio público de ámbito de sitio:

.

CSS y JavaScript utilizan la ruta pública determinista /site/{site_handle}/applications/{application_handle}/{type}/{filename}. El tipo HTML acepta solo index.html, lo almacena en la raíz de la aplicación y devuelve la ruta pública estable seleccionada por el host /webblocks-applications/{application_handle}/index.html. Al escribir esta entrada administrada, la definición cambia al modo iframe y activa esa URL. GET, PUT y DELETE requieren applications.read, applications.write y applications.delete respectivamente. Los nombres de archivo son solo nombres base y deben terminar en la extensión .css, .js o .html seleccionada. HTML no acepta ningún nombre de archivo que no sea index.html; Se rechazan el recorrido, las rutas anidadas, otros tipos de archivos y las URL remotas.

PUT acepta contents y expected_checksum. Envíe null solo cuando cree un archivo faltante; lea primero un archivo existente y envíe su suma de verificación al reemplazarlo. Los reemplazos y eliminaciones conservan copias de revisión. Se rechaza la eliminación mientras la definición Embedded Application todavía haga referencia a la ruta pública del activo. Después de escribir un activo, utilice su public_path devuelto en css_assets o js_assets; el bloque de aplicaciones luego lo carga solo donde se coloca la aplicación.

Las aplicaciones completas deben usar el punto final del paquete en lugar de escribir archivos uno por uno. Requiere applications.write y multipart/form-data con un campo ZIP package (tamaño máximo de carga 50 MB). Primero incremente el version de la aplicación registrada con PATCH /webadmin/api/applications/{application}; luego cargue un ZIP que contenga index.html en su raíz y use las URL de activos relativas dentro de él. Una respuesta exitosa devuelve la versión del paquete, el inmutable entry_url activado, el recuento de archivos y el tamaño de bytes ampliado, además de la definición de aplicación actualizada. Las versiones instaladas no se pueden sobrescribir. Las fallas de seguridad de validación y archivado devuelven errores estructurados JSON 422 en errors[0].path = application_package (o application_package.package para el campo multiparte).

• POST /webadmin/api/content/validate
• POST /webadmin/api/content/apply

Los planes de contenido pueden asignar registros de la biblioteca multimedia CMS ya cargados a bloques respaldados por medios nativos. Utilice media_id o asset_id en bloques image, navbar-brand, sidebar-brand, file, download y video con medios del tipo correspondiente. Utilice media_id o asset_id en hero, section, card, cta y content_header cuando el medio sea la imagen de fondo del bloque, con settings.background_position y settings.background_overlay opcionales. Utilice gallery_items o gallery_media_ids en bloques gallery con registros de medios de imagen; el API conserva el orden de los elementos de la Galería enviados al escribir block_media.position. Para imágenes de contenido de tarjeta, cree la estructura anidada normal, como card -> card_body -> image, y coloque media_id en el bloque secundario image. Los planes de contenido aún rechazan remote_url y source_url; cargue archivos a través de POST /webadmin/api/media o importe una URL de archivo público aprobado a través de POST /webadmin/api/media/fetch primero, luego asigne el media.id.

devuelto

Los planes usan modos explícitos de borrador o actualización preparada. Valide antes de aplicar y mantenga la publicación como operación autorizada aparte. Las páginas públicas requieren una actualización preparada propia, no sustitución directa.

Un plan puede referenciar registros aprobados de la biblioteca. Descargas remotas, subidas y otras operaciones usan endpoints y capacidades propios; el plan no concede esos permisos. Descubra los endpoints actuales antes de cambiar.

Las escrituras JSON con Bearer-token usan autorización del token. El descubrimiento mínimo sin autenticar no concede acceso al contenido. Consulte Authentication y Capabilities para el ámbito requerido.

Los errores de la API son exclusivamente JSON. No deben redirigir al inicio de sesión, mostrar páginas de CSRF ni exponer trazas de pila. Campos habituales:

Estados esperados:

• 401 invalid_internal_api_token para tokens faltantes, no válidos, revocados, vencidos o que ya no están respaldados por el usuario
• 403 missing_internal_api_capability para capacidades faltantes
• 403 delegated_site_access_denied cuando un token personal apunta a un sitio fuera de su alcance activo
• 403 delegated_workflow_access_denied cuando el propietario no puede editar la página en su estado de flujo de trabajo actual
• 403 delegated_operation_denied para operaciones a nivel de instalación que rechazan personal tokens
• 403 delegated_network_access_denied cuando la IP resuelta está fuera de la lista de tokens personales permitidos
• 429 personal_api_token_rate_limit_exceeded cuando se alcanza el límite personal; los clientes deben respetar Retry-After
• 422 por errores de validación

Requiere admin.render y un token creado por un usuario que pueda acceder a System. La respuesta JSON incluye el administrador renderizado HTML para la pantalla System Updates incluida en la lista permitida; ?format=html devuelve text/html directo para que las herramientas del operador puedan cargar la instantánea en un navegador local y capturar capturas de pantalla para compararlas visualmente. El punto final es de solo lectura y no debe hacer clic, instalar, publicar ni cambiar el estado de actualización.

Requiere engagement.read. Los filtros admitidos son status, site_id, page_id, block_id, search y per_page. Las respuestas incluyen el cuerpo del comentario, el estado, la puntuación o los motivos del spam, las referencias a la página de origen o al bloque y las marcas de tiempo, pero no exponen los hashes de los visitantes, los hashes de IP ni los valores de los agentes de usuario.

Requiere engagement.moderate. Los estados admitidos son pending, approved, rejected, spam y hidden.

.

Requiere engagement.read. Los filtros admitidos son status, site_id, page_id, block_id y per_page. Las respuestas incluyen filas de calificación más resúmenes totales, promedio y de recuento de valores, pero no exponen hashes de visitantes, hashes de IP ni valores de agente de usuario.

El mismo payload puede enviarse a cualquiera de los dos endpoints:

Ejemplo de borrador de página de inicio de marketing en inglés:

• Los campos del plan que API no comprende se rechazan con 422 y el código estable unsupported_plan_fields, y los nombres de ruta de error de cada uno; el conjunto de claves aceptado tiene como alcance el plan mode, por lo que una clave que sea significativa en un modo aún se rechaza en otro
• el identificador o ID del sitio debe resolverse
• la configuración local debe existir y estar habilitada para el sitio de destino
• layout debe existir
• Creación de página de bloques de conflicto de ruta
• El tipo de bloque debe ser publicado y utilizable
• El soporte infantil debe seguir los contratos de bloque cuando estén disponibles
• Los árboles de bloques del plan de contenido deben usar anidados children; Los campos de relación planos id, parent_id, block_id, slot_type_id y block_type_id se rechazan porque API posee los ID de la base de datos y la asignación principal.
• el bloque translations debe contener claves de campo directas. para la configuración regional del plan seleccionada, como title, subtitle y content; Las formas con clave local, como translations.en.title, se rechazan en lugar de ignorarse silenciosamente.
• Los bloques envolventes, como section, container, stack, split, cluster, grid, card, card_body, card_footer, sticky-navbar y sidebar-navigation deben incluir bloques secundarios para que no puedan validarse como Chrome público vacío; split requiere exactamente dos hijos directos, y cada lado puede ser un stack
• el texto orientado al usuario pertenece a las filas de traducción
• las configuraciones compartidas permanecen compartidas
• Las configuraciones principales nuevas o modificadas deben coincidir con el esquema de creación por bloque descubierto; los campos desconocidos y los valores no válidos se rechazan con las rutas de campo
• . Las configuraciones históricas desconocidas permanecen legibles y sobreviven a actualizaciones no relacionadas; un valor exacto sin cambios puede acompañar a PATCH pero no autoriza cambiar un campo no declarado
• apply valida nuevamente antes de escribir
• apply es transaccional
• La aplicación de contenido aún rechaza la publicación, la creación de sitios y los medios operaciones de importación, recuperación remota, sobrescritura no admitida, reemplazo no admitido y eliminación
• Shared Slot la creación sigue siendo de solo creación a menos que una fase posterior agregue contratos de mutación explícitos seguros para borradores
• los puntos finales de recursos de elementos de navegación admiten operaciones explícitas de actualización, visibilidad, reordenamiento y eliminación fuera del contenido que se aplican con capacidad protectores

Las respuestas deben ser JSON predecible:

Los errores de validación deben incluir una ruta y un mensaje:

Incluya edit_url cuando sea útil para recursos CMS creados o actualizados.

renderability es un resumen de estado del plan para herramientas de operador/IA. Un plan de páginas estructurado exitoso normalmente debería tener wrapper_blocks_without_children, text_blocks_without_visible_content y button_blocks_without_label_or_url en 0. html_blocks arriba de 0 significa que el plan utilizó la trampilla de escape Trusted HTML; Las herramientas deben hacerlo solo con la aprobación explícita del operador y solo cuando los tipos de bloques de primera clase no puedan representar el contenido.

Los planes de contenido pueden incluir navigation_menus, shared_slots y page_slot_shared_slots junto al plan de páginas/slots ya existente. validate no escribe nada. apply escribe todas las secciones válidas en una sola transacción y revierte el plan completo cuando falla cualquier sección posterior.

Los elementos de navegación llevan link_type: custom_url (el valor predeterminado, requiere una ruta interna segura o una URL http(s)), page (requiere page_id para una página en el mismo sitio; la etiqueta vuelve al nombre de la página), o group (una etiqueta que abre sus hijos y no lleva URL). Solo un group acepta children, que se crean con su parent_id ya vinculado, por lo que un menú desplegable es un plan en lugar de un POST más un PATCH por artículo. Los planes de contenido se anidan en un nivel; los árboles más profundos utilizan POST /navigation-menus/{menu}/items. Un link_type no compatible se rechaza por su nombre en lugar de ser forzado a custom_url.

page_slot_shared_slots[].page puede hacer referencia a la página creada por el mismo plan utilizando created, o a una ID de página existente. shared_slot puede hacer referencia a un Shared Slot creado anteriormente en el mismo plan o a un identificador Shared Slot existente en el mismo sitio.

Los planes de contenido guardan una versión de página completa después de todas las escrituras de bloques y asignaciones de Shared Slot, y una versión completa por cada Shared Slot recién creado. Los planes de asignación de páginas existentes guardan una versión de seguridad previa al cambio por página afectada. El reemplazo de espacios y la promoción por etapas conservan sus puntos de control de seguridad explícitos. Una captura consecutiva sin cambios reutiliza la última instantánea completa y registra un evento de captura separado; Las solicitudes HTTP independientes siguen siendo operaciones separadas. Las lecturas detalladas de la versión incluyen inspection.capture_history delimitado que contiene eventos de captura recientes y una marca has_more. Ver Revisiones.

• descubra primero los sitios, los idiomas (locales), los layouts y los tipos de bloque
• valide antes de aplicar
• cree contenido en borrador
• prefiera los bloques estructurados de docs/public-block-render-markup.md
• evite Safe HTML salvo como alternativa revisada
• mantenga el texto público generado en el idioma de destino, por ejemplo inglés para una página de inicio en inglés

• sin integración de OpenAI ni de LLM en el núcleo del CMS
• sin rastreo ni descarga de contenidos
• sin sustitución arbitraria de la importación/exportación
• sin publicación automática
• sin eliminación destructiva en la fase 1
• sin suponer la ruta /admin del host
• sin uso del prefijo de ruta /cms
• sin código de ejecución específico de QuizTem; la generación de la página de inicio de QuizTem es un caso de uso posterior de esta API genérica del CMS

Consulte Contratos de tipos de bloque para conocer el catálogo completo, la responsabilidad del almacenamiento y los contratos de renderizado. Los esquemas complementan el Inventario del CMS; no conceden acceso ni permiten escribir por API en un bloque reservado a la edición humana.

Desde CMS 1.105.9, el descubrimiento de tipos de bloque y los contratos de contenido incluyen un objeto adicional authoring_settings_schema. Los formatos anteriores de settings_schema se mantienen. La revisión 1 abarca todos los bloques principales publicados y expone mode, unknown_fields y fields. Cada campo describe su tipo, opciones y límites de rango y longitud, cómo se vacía con null o valores vacíos, la conservación de campos omitidos en las actualizaciones y las decisiones independientes de writes.admin, writes.create y writes.patch, con el motivo closed_reason cuando corresponda.

Lea esos indicadores de operación antes de escribir. Un campo aceptado al crear un bloque no se puede escribir automáticamente a través de PATCH. Los campos de entrega/privacidad de contacto conservan sus exclusiones PATCH existentes deliberadas, HTML sigue siendo solo para humanos y las referencias de los medios utilizan sus campos de relación dedicados. Los esquemas de campo no otorgan permisos y no consultan proveedores de contenido externos.

Los planes de contenido y el bloque de ranuras POST rechazan claves desconocidas y valores proporcionados no válidos antes de escribir. PATCH valida solo los cambios y los combina con la configuración actual. Se rechaza un aligment mal escrito en lugar de aceptar un valor que no tiene ningún efecto visible; se rechaza un valor alignment no válido en lugar de borrar silenciosamente la opción existente. Los valores faltantes no insertan valores predeterminados durante las actualizaciones. Los alias de compatibilidad declarados siguen siendo compatibles: el control deslizante fade se normaliza a slide, la galería masonary a masonry, y el escritor de traducción local consume las claves de copia del formulario de contacto existentes en la configuración de creación. PATCH usa translations para esa copia. Los valores enteros no se limitan de forma silenciosa y el texto demasiado largo no se trunca de forma silenciosa. Los valores predeterminados de creación existentes, como las columnas plain y Split stack, permanecen.

HLos valores históricos desconocidos o con formato incorrecto siguen siendo legibles, se representan con las reservas existentes y sobreviven a actualizaciones no relacionadas. Un cliente puede llevar un campo histórico idéntico sólo cuando el servidor puede compararlo con ese bloque existente exacto; esto no autoriza a agregar o cambiar configuraciones desconocidas. Los bloques nuevos y las cargas útiles de reemplazo completo son de nueva creación, por lo que no pueden reclamar una excepción de valor histórico. La clonación, la puesta en escena y la restauración de revisiones confiables conservan sus rutas de almacenamiento sin pérdidas.

Los complementos sin esquemas mantienen su propio comportamiento de configuración existente. Los complementos pueden optar por la definición de bloque o manifestarse con reglas escalares; una declaración no válida bloquea las escrituras para ese esquema sin bloquear bloques centrales no relacionados. La configuración de la aplicación, los íconos activos y los enlaces Dynamic Content continúan usando sus validadores especializados después de la verificación del campo común.

Los operadores del servidor pueden ejecutar php artisan webblocks:blocks:audit-settings para obtener un informe de compatibilidad de solo lectura antes de crear contenido existente. Imprime identidades, rutas de campo y códigos en lugar de valores de configuración, escanea sin reparaciones ni consultas al proveedor y sale de 1 si existen configuraciones incompatibles. --limit=100 limita los bloques informados (máximo 1000); el resumen todavía cuenta el escaneo completo. Esto verifica la compatibilidad del esquema escalar, no el proveedor externo o el estado de la aplicación. Los complementos sin esquema se cuentan por separado. Las nuevas configuraciones declaradas modificadas están limitadas a 128 campos, 256 KiB, 32 niveles anidados y 4096 nodos sin aplicar esos límites retrospectivamente a datos históricos sin cambios.