Contenido editorial

API de blog: artículos, autores y categorías

Orquesta tu blog desde Be CMS con endpoints seguros y consistentes. Gestiona artículos, relaciona autores y controla la taxonomía desde integraciones headless o automatizaciones internas. Administra contenidos directamente desde cms.begraffic.com con las credenciales de tu workspace.

Firestore + StoragePermisos granularesWebhooks opcionales

Abrir la plataforma

Arquitectura

Panorama general

Los endpoints de blog validan tokens con scopes específicos, actualizan métricas agregadas y sincronizan contenido entre Firestore y Storage. Cada llamada registra uso y requiere los encabezados `Authorization` y `X-Workspace-Id`.

Ciclo de autenticación

El token se valida con firma JWT y estado activo.
Se verifica el permiso asociado (read, create, update, delete).
Se incrementa el contador de uso (`incrementTokenCallCount`).
Se ejecuta la operación contra Firestore/Storage según el método.

Estados editoriales

draft: Visible solo para integraciones internas; ideal para revisión previa.
published: Disponible para todas las consultas públicas y listados.
hidden: Excluir del canal público sin perder contenido ni historiales.
archived: Conserva el historial pero se omite por defecto en listados.

Arquitectura

Colecciones y relaciones

Cada página del blog se almacena en tables/{pageId} y sus subcolecciones (autores, categorías, artículos) se anidan directamente bajo ese documento. Se guardan timestamps (createdAt, updatedAt, publishedAt) y slugs que actúan como claves de relación entre datasets.

Colección	Descripción	Campos clave
blogArticles	Metadatos del artículo y referencias al contenido en Storage.	status authorSlug categorySlug tags publishedAt
blogAuthors	Ficha de autor con biografía, redes y métricas de visibilidad.	name bio featured status
blogCategories	Taxonomía del blog con descripciones y banderas de featured.	name slug status parentSlug

Artículos

Operaciones sobre artículos

Estas rutas controlan el ciclo de vida completo de un artículo, incluyendo persistencia de contenido pesado y control de permisos. Usa el campo `slug` como identificador único en actualizaciones y eliminaciones.

GET/api/blog/articles

Listar artículos publicados

Devuelve artículos filtrados por estado "published" con soporte para `limit` y búsqueda por `slug` individual.

fetch('https://cms.begraffic.com/v1/blog/articles?limit=10', {
  headers: {
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data.articles))
  .catch((error) => console.error(error))

Usa `slug` para obtener un artículo específico y asegúrate de que esté publicado.
El resultado devuelve metadatos (estado, timestamps) y vistas previas del contenido si existen.

POST/api/blog/articles

Crear un artículo

Crea un documento con contenido opcional. El HTML/diseño pesado se persiste en Cloud Storage y se vincula automáticamente.

await fetch('https://cms.begraffic.com/v1/blog/articles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
  body: JSON.stringify({
    slug: 'guia-personalizacion',
    title: 'Guía definitiva de personalización',
    status: 'draft',
    excerpt: 'Explora cómo personalizar campañas en minutos.',
    content: { html: renderedHtml, design: studioProject },
  }),
})

El campo `content` acepta `html` y `design`; si se omiten, se limpia cualquier versión previa.
Se requiere permiso `create` en el token y se registrará un contador de uso por llamada.

PUT/api/blog/articles

Actualizar metadatos o contenido

Actualiza cualquier campo mutable: título, estado, fechas, tags o el contenido almacenado en Storage.

await fetch('https://cms.begraffic.com/v1/blog/articles?slug=guia-personalizacion', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
  body: JSON.stringify({
    title: 'Personalización avanzada 2025',
    status: 'published',
    publishedAt: new Date().toISOString(),
  }),
})

Incluye `slug` como query string obligatorio. Si cambias el contenido, se sobrescribe el archivo JSON en Storage.
Las validaciones garantizan que `publishedAt` sea una fecha ISO 8601 válida.

DELETE/api/blog/articles

Eliminar un artículo

Elimina el documento de Firestore y borra el contenido asociado en Storage. Ajusta el contador de artículos automáticamente.

await fetch('https://cms.begraffic.com/v1/blog/articles?slug=guia-personalizacion', {
  method: 'DELETE',
  headers: {
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
})

Exige permiso `delete`; responde con 204 sin cuerpo cuando la operación es correcta.
Si el artículo no existe, devuelve 404 con un mensaje guiado para listar slugs disponibles.

Autores y categorías

Gestión de fichas complementarias

Completa el ecosistema editorial con autores y categorías sincronizados. Ambos endpoints replican el ciclo CRUD con validaciones similares a los artículos para mantener consistencia en el contenido público.

GET/api/blog/authors

Catálogo de autores

Lista autores publicados o recupera uno específico mediante `slug`. Filtra automáticamente por estado publicado.

const response = await fetch('https://cms.begraffic.com/v1/blog/authors?featured=true', {
  headers: {
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
})
const { authors } = await response.json()

El cuerpo serializa `createdAt`, `updatedAt` y `publishedAt` a ISO 8601.
Permite `limit` para paginación ligera y campos opcionales como `bio`, `avatarUrl`, `featured`.

POST/api/blog/authors

Crear o actualizar autores

Gestiona autores con validaciones de slug único y control de estado. Usa `PUT` con `slug` para actualizaciones puntuales.

await fetch('https://cms.begraffic.com/v1/blog/authors', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
  body: JSON.stringify({
    slug: 'maria-gonzalez',
    name: 'María González',
    status: 'draft',
    bio: 'Especialista en marketing relacional.',
    featured: true,
  }),
})

Para actualizar usa `PUT` con query `?slug=`; `DELETE` elimina la ficha y ajusta los contadores automáticamente.

GET/api/blog/categories

Gestión de categorías

Provee categorías publicadas o una categoría específica según slug. Soporta `limit` y estados exactos.

const response = await fetch('https://cms.begraffic.com/v1/blog/categories', {
  headers: {
    'X-Workspace-Id': process.env.BE_WORKSPACE_ID ?? '',
    Authorization: `Bearer ${process.env.BE_API_TOKEN}`,
  },
})
const { categories } = await response.json()

Las categorías utilizan el mismo ciclo de vida que artículos y autores (draft, published, archived, hidden).
Usa `POST`/`PUT` para mantener árboles de navegación, con validación automática de slug duplicado.

Buenas prácticas

Operación y monitoreo

Complementa tu implementación conectando observabilidad, automatización y analíticas. Usa estos consejos como checklist inicial para mantener la salud del canal editorial.

Dispara sincronizaciones con webhooks

Suscríbete a webhooks de actualización para refrescar sitios estáticos o invalidar cachés cuando se publique un artículo o cambie su estado.

Supervisa errores y cuotas

Revisa el contador de llamadas por token y utiliza códigos de estado para alertar a tus equipos (400 validación, 403 permisos, 404 recursos, 429 límites).

Conecta métricas editoriales

Los ajustes de `adjustBlog*Count` mantienen estadísticas agregadas; consúmelas desde `tableMetrics` para dashboards personalizados.