Manual de uso del API de Blog (solo lectura)

El API de blog expone endpoints de solo lectura para consultar artículos, autores y categorías. Todas las rutas viven bajo /api/blog/* y devuelven JSON.

Autenticación

Incluye Authorization: Bearer <token> en cada solicitud.
El token debe estar activo y tener permisos sobre el recurso que consultas.
Aunque los endpoints actuales no requieren cuerpo, mantén Content-Type: application/json en caso de enviar parámetros serializados.

Permisos

read: permite ejecutar peticiones GET.

Si el token está vencido, inactivo o carece del permiso read, la respuesta será 401 o 403.

Códigos de respuesta comunes

200 OK: respuesta exitosa.
400 Bad Request: parámetros inválidos.
401 / 403: token ausente, inválido o sin permisos.
404 Not Found: recurso inexistente o no publicado.
405 Method Not Allowed: se intentó un método distinto de GET.
500 Internal Server Error: error no controlado en el servidor.

Artículos — `/api/blog/articles`

GET listado

Devuelve todos los artículos publicados accesibles para el token.

Query params

limit (número, opcional): máximo de resultados (1–100).
categoryId (string, opcional): devuelve solo artículos con esa categoría.
authorId (string, opcional): devuelve solo artículos del autor indicado.
excludeCategoryId (string, opcional): lista separada por comas de categorías a omitir (excludeCategoryId=marketing,eventos).
excludeAuthorId (string, opcional): lista separada por comas de autores a omitir (excludeAuthorId=ana-garcia,pedro-lopez).
sortBy (string, opcional): campo para ordenar resultados. Valores permitidos: publishedAt, title. Por defecto se usa orden descendente por publishedAt si se envía este parámetro sin sortDirection.
sortDirection (string, opcional): dirección de orden. Valores permitidos: asc, desc. Si no se envía, se asume desc.

Puedes combinar categoryId y authorId para filtrar por ambos criterios y, adicionalmente, aplicar exclusiones. Las exclusiones también se respetan cuando consultas un artículo puntual con slug.

Ejemplo listado básico

bash

curl "https://cms.begraffic.com/api/blog/articles?limit=10&categoryId=marketing&authorId=ana-garcia" \
  -H "Authorization: Bearer TU_TOKEN"

Ejemplo con orden

bash

curl "https://cms.begraffic.com/api/blog/articles?sortBy=title&sortDirection=asc&limit=5" \
  -H "Authorization: Bearer TU_TOKEN"

Ejemplos extra

Orden por fecha descendente (default) con exclusión de categorías:

bash

curl "https://cms.begraffic.com/api/blog/articles?sortBy=publishedAt&excludeCategoryId=marketing,eventos" \
  -H "Authorization: Bearer TU_TOKEN"

Orden por fecha ascendente filtrando por autor:

bash

curl "https://cms.begraffic.com/api/blog/articles?authorId=ana-garcia&sortBy=publishedAt&sortDirection=asc" \
  -H "Authorization: Bearer TU_TOKEN"

Orden por título descendente con límite:

bash

curl "https://cms.begraffic.com/api/blog/articles?sortBy=title&sortDirection=desc&limit=20" \
  -H "Authorization: Bearer TU_TOKEN"

Notas de orden:

Si envías sortBy sin sortDirection, se usa desc por defecto.
El orden aplica sobre todos los artículos publicados que cumplan tus filtros (categoryId, authorId, exclusiones); no afecta al endpoint de detalle.
El orden por publishedAt está soportado de forma nativa.

Publicación programada

Los artículos creados con isScheduled = true y un scheduledFor en el futuro permanecen ocultos hasta la fecha.
Los artículos programados se publican automáticamente al llegar su fecha; a partir de ese momento aparecen con status: published.

Respuesta

json

{
  "count": 2,
  "articles": [
    {
      "id": "guia-crm",
      "title": "Guía CRM",
      "slug": "guia-crm",
      "excerpt": "Resumen...",
      "status": "published",
      "tags": ["crm", "ventas"],
      "categoryId": "marketing",
      "categoryName": "Marketing",
      "authorId": "ana-garcia",
      "authorName": "Ana García",
      "isScheduled": false,
      "scheduledFor": null,
      "metadata": null,
      "publishedAt": "2024-05-01T10:00:00.000Z",
      "createdAt": "2024-05-01T10:00:00.000Z",
      "updatedAt": "2024-05-02T12:30:00.000Z",
      "externalId": null
    }
  ]
}

Los artículos programados (isScheduled = true) solo se incluyen cuando scheduledFor es menor o igual a la hora actual.
El campo content se omite en el listado para reducir el tamaño de la respuesta; solo está disponible en el endpoint de detalle.

Ejemplo omitidos

bash

curl "https://cms.begraffic.com/api/blog/articles?excludeCategoryId=marketing&excludeAuthorId=ana-garcia" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "count": 1,
  "articles": [
    {
      "id": "caso-exito",
      "title": "Caso de éxito",
      "slug": "caso-exito",
      "categoryId": "finanzas",
      "authorId": "carlos-mendez",
      "status": "published",
      "isScheduled": false,
      "scheduledFor": null,
      "publishedAt": "2024-06-01T12:00:00.000Z",
      "createdAt": "2024-05-15T08:00:00.000Z",
      "updatedAt": "2024-05-20T09:30:00.000Z"
    }
  ]
}

GET detalle

GET /api/blog/articles?slug=<slug>

Devuelve un artículo publicado que coincida con el slug. Si existe pero no está en estado published, la respuesta será 404. Este endpoint incluye el campo content con la información completa del artículo.

Respuesta

json

{
  "article": {
    "id": "guia-crm",
    "title": "Guía CRM",
    "slug": "guia-crm",
    "excerpt": "Resumen...",
    "categoryId": "marketing",
    "categoryName": "Marketing",
    "authorId": "ana-garcia",
    "authorName": "Ana García",
    "tags": ["crm", "ventas"],
    "status": "published",
    "isScheduled": false,
    "scheduledFor": null,
    "content": {
      "html": "<h1>Hola</h1>",
      "htmlPreview": "<h1>Hola</h1>"
    },
    "metadata": null,
    "publishedAt": "2024-05-01T10:00:00.000Z",
    "createdAt": "2024-05-01T10:00:00.000Z",
    "updatedAt": "2024-05-02T12:30:00.000Z"
  }
}

El endpoint de detalle devuelve el contenido en content, con los campos html y htmlPreview.

Autores — `/api/blog/authors`

GET listado

Lista todos los autores con estado published accesibles para el token. Acepta limit como parámetro opcional.

bash

curl "https://cms.begraffic.com/api/blog/authors" \
  -H "Authorization: Bearer TU_TOKEN"

Respuesta

json

{
  "count": 2,
  "authors": [
    {
      "id": "ana-garcia",
      "name": "Ana García",
      "slug": "ana-garcia",
      "title": "Editora",
      "bio": "Periodista especializada en marketing.",
      "avatar": "https://cdn.example.com/avatars/ana.jpg",
      "featured": true,
      "status": "published",
      "publishedAt": "2024-01-10T15:00:00.000Z",
      "createdAt": "2024-01-10T15:00:00.000Z",
      "updatedAt": "2024-03-05T09:30:00.000Z"
    },
    {
      "id": "carlos-mendez",
      "name": "Carlos Méndez",
      "slug": "carlos-mendez",
      "title": "Analista",
      "featured": false,
      "status": "published",
      "publishedAt": "2024-02-01T09:00:00.000Z",
      "createdAt": "2024-02-01T09:00:00.000Z",
      "updatedAt": "2024-02-15T11:45:00.000Z"
    }
  ]
}

GET detalle

GET /api/blog/authors?slug=<slug> devuelve la información de un autor publicado. Responde 404 si el slug no existe o el autor no está publicado.

Respuesta

json

{
  "author": {
    "id": "ana-garcia",
    "name": "Ana García",
    "slug": "ana-garcia",
    "title": "Editora",
    "email": "ana@example.com",
    "bio": "Periodista especializada en marketing.",
    "avatar": "https://cdn.example.com/avatars/ana.jpg",
    "website": "https://ana.blog",
    "linkedin": "https://linkedin.com/in/anagarcia",
    "twitter": "@anagarcia",
    "featured": true,
    "status": "published",
    "publishedAt": "2024-01-10T15:00:00.000Z",
    "createdAt": "2024-01-10T15:00:00.000Z",
    "updatedAt": "2024-03-05T09:30:00.000Z"
  }
}

Categorías — `/api/blog/categories`

GET listado

Recupera las categorías publicadas. También admite el parámetro opcional limit. Cada documento de categoría incluye articleCount, que refleja cuántos artículos están asignados actualmente a esa categoría.

Respuesta

json

{
  "count": 2,
  "categories": [
    {
      "id": "marketing",
      "name": "Marketing",
      "slug": "marketing",
      "description": "Estrategias y tácticas de marketing.",
      "accent": "#00AEEF",
      "featured": true,
      "articleCount": 12,
      "status": "published",
      "publishedAt": "2024-01-05T08:00:00.000Z",
      "createdAt": "2024-01-05T08:00:00.000Z",
      "updatedAt": "2024-03-20T10:15:00.000Z"
    },
    {
      "id": "finanzas",
      "name": "Finanzas",
      "slug": "finanzas",
      "description": "Noticias y consejos financieros.",
      "featured": false,
      "articleCount": 4,
      "status": "published",
      "publishedAt": "2024-02-12T14:00:00.000Z",
      "createdAt": "2024-02-12T14:00:00.000Z",
      "updatedAt": "2024-02-18T16:45:00.000Z"
    }
  ]
}

GET detalle

GET /api/blog/categories?slug=<slug> devuelve una categoría publicada. Si la categoría existe pero no está publicada, responde 404.

Respuesta

json

{
  "category": {
    "id": "marketing",
    "name": "Marketing",
    "slug": "marketing",
    "description": "Estrategias y tácticas de marketing.",
    "accent": "#00AEEF",
    "featured": true,
    "articleCount": 12,
    "status": "published",
    "publishedAt": "2024-01-05T08:00:00.000Z",
    "createdAt": "2024-01-05T08:00:00.000Z",
    "updatedAt": "2024-03-20T10:15:00.000Z"
  }
}

Buenas prácticas

Normaliza slugs a minúsculas antes de consultarlos.
Envía fechas en formato ISO 8601 al compararlas con scheduledFor o publishedAt.
Maneja específicamente los códigos 404 (recurso no publicado) y 405 (método no permitido) en tus integraciones.
Si llegas a necesitar operaciones de escritura, deberás coordinar con el equipo para habilitar endpoints adicionales.

Manual de uso del API de Blog (solo lectura)

Autenticación

Permisos

Códigos de respuesta comunes

Artículos — /api/blog/articles

GET listado

GET detalle

Autores — /api/blog/authors

GET listado

GET detalle

Categorías — /api/blog/categories

GET listado

GET detalle

Buenas prácticas

Artículos — `/api/blog/articles`

Autores — `/api/blog/authors`

Categorías — `/api/blog/categories`