Contrato de entrega de artículos
Referencia para desarrolladores que reciben artículos publicados completos.
Usa una clave distinta por receptor. Las claves se almacenan cifradas y nunca se devuelven en los resúmenes de conexión. Autentica mediante la firma antes de confiar en el identificador del sitio. Lee la clave del entorno del receptor al procesar cada solicitud; nunca la guardes en una base de datos ni la expongas a través de nada que el navegador pueda llamar.
Solicitud y verificación
Structura envía HTTPS POST con Content-Type: application/json, X-Structura-Event-Id, X-Structura-Timestamp (segundos Unix) y X-Structura-Signature (sha256= seguido de un digest hexadecimal en minúsculas). Calcula HMAC-SHA256 de timestamp + "." + rawBody con la clave en UTF-8. Compara bytes de igual longitud en tiempo constante, rechaza diferencias de más de cinco minutos y después analiza el JSON. El ID del encabezado debe coincidir con el cuerpo. No vuelvas a serializar JSON para verificar la firma.
Formato del mensaje
{
"schema_version": 1,
"event": "post.published",
"event_id": "article_<sha256>",
"delivered_at": "2026-09-28T10:00:00.000Z",
"site": {
"id": "site_123"
},
"post": {
"id": "post_123",
"slug": "first-article",
"title": "First article",
"html": "<p>Article body</p>",
"markdown": "Article body",
"excerpt": null,
"metaTitle": null,
"metaDescription": null,
"focusKeyword": null,
"locale": "en",
"publishedAt": "2026-09-28T10:00:00.000Z",
"updatedAt": "2026-09-28T10:00:00.000Z",
"canonicalUrl": "https://example.com/blog/first-article",
"featuredImage": {
"url": "https://example.com/images/first-article.jpg",
"alt": "A short description of the image"
},
"author": null,
"jsonLd": []
}
}id es texto para artículos headless o un número para WordPress. Los metadatos ausentes son null; jsonLd es una matriz. El HTML está saneado y Markdown se genera desde ese HTML. El idioma del contenido no depende de las notificaciones. Las imágenes permanecen alojadas en sus URL. Solo se incluye la identidad pública del autor cuando la fuente la proporciona.
featuredImage es null o un objeto con url y alt; usa url para la imagen del artículo y para og:image.
Antes de insertar jsonLd en un elemento <script type="application/ld+json">, serialízalo y sustituye cada < por \u003c. Un JSON válido puede contener </script>; sanear el HTML no hace seguro insertar ese JSON directamente.
La solicitud completa admite un máximo de 1.000.000 bytes UTF-8, incluidos HTML, Markdown, metadatos y escapes JSON. La normalización permite 995.904 bytes para el artículo y reserva 4.096 bytes para el evento. Los artículos mayores se omiten con article_too_large; usa la Content API para contenido más grande.
Autor
post.author es el autor real al que el sitio atribuye el artículo, o null si la fuente no acredita a nadie. Nunca contiene el nombre de una persona (la voz de escritura).
{
"name": "Jane Doe",
"bio": "Pastry chef and owner of a bakery in Leeds.",
"url": "https://example.com/about/jane-doe",
"avatarUrl": "https://example.com/images/jane-doe.jpg",
"sameAs": ["https://www.linkedin.com/in/jane-doe"]
}name siempre está presente. bio, url (la página del autor) y avatarUrl son null si faltan. sameAs contiene hasta 10 URL de otros perfiles del autor y puede estar vacío. avatarUrl y sameAs son campos añadidos, así que schema_version sigue siendo 1; ignora las claves que no conozcas. A partir del plugin 2.32.0, las fuentes WordPress rellenan avatarUrl con la imagen de perfil y sameAs con la web del perfil de WordPress del usuario. Con plugins anteriores recibes avatarUrl: null y sameAs: [].
En las fuentes headless, jsonLd[0] es un nodo BlogPosting del artículo con el autor como Person, el mismo nodo que sirve la Content API. Le siguen los elementos HowTo y FAQPage. Las fuentes WordPress solo envían los elementos HowTo y FAQPage. Emite cada elemento tal como llega, incluido el BlogPosting; ya nombra al autor como Person. Omite el nuestro solo cuando tu sitio genere su propio BlogPosting para cada artículo, para que una página nunca lleve dos, y en ese caso toma la firma de post.author.
Almacenamiento y entrega
Impón una restricción única duradera sobre event_id. En la misma transacción, actualiza por site.id, post.id y post.locale, y marca el evento como procesado. Confirma tras el commit. Un duplicado válido devuelve 2xx sin volver a aplicarse. Compara updatedAt para no sobrescribir una revisión nueva con una antigua. Los ID incluyen identidad del espacio, sitio y contenido; una revisión republicada tiene otro ID.
Cualquier 2xx indica éxito. Los errores de red y HTTP 408, 429 y 5xx tienen un reintento tras 150 ms. Los demás fallan inmediatamente. Cada intento dura como máximo 8 segundos; el cuerpo de respuesta se ignora, salvo en un envío de prueba, que te muestra los primeros 200 caracteres. No hay repetición automática posterior. Se rechazan redirecciones, direcciones privadas y receptores sin HTTPS. Guarda primero y procesa el trabajo pesado en tu propia cola.
Solo la publicación genera un envío. Las ediciones y eliminaciones no generan eventos. Usa la Content API pública para reconciliar publicaciones perdidas o cambios. La entrega de artículos se configura para sitios headless en el portal de clientes.
Artículos de prueba
Al configurar o editar una conexión, el portal puede enviar un artículo de prueba. Es un evento post.published normal, firmado como cualquier otro, así que un receptor correcto lo guarda. post.id y post.slug son siempre structura-test-article y post.locale es en, por lo que las pruebas repetidas actualizan un único artículo guardado. Cada prueba tiene un event_id nuevo y un updatedAt posterior. Puedes borrar el artículo de prueba cuando quieras. Un envío de prueba hace un solo intento con el mismo límite de 8 segundos, y cada URL de receptor admite cinco pruebas cada diez minutos.
Páginas relacionadas
Última verificación: