API Editorial (Blog CMS)

1) Base URL y Endpoints

Las escrituras editoriales se hacen por Supabase Edge Functions.

https://<project-ref>.functions.supabase.co

POST https://<project-ref>.supabase.co/auth/v1/token?grant_type=password

2) Autenticacion y Headers

Todos los endpoints de escritura requieren JWT de usuario autenticado en Supabase Auth + perfil activo en profiles con rol editorial.

curl -X POST "https://<project-ref>.supabase.co/auth/v1/token?grant_type=password"   -H "apikey: &lt;PUBLIC_SUPABASE_ANON_KEY&gt;"   -H "Content-Type: application/json"   -d '{"email":"usuario@dominio.com","password":"tu-password"}'

3) Envelope de Respuesta

Las respuestas exitosas y de error tienen forma estable.

{
  "data": { ... },
  "meta": {
    "requestId": "uuid",
    "endpoint": "cms-blog-create"
  }
}

{
  "error": {
    "code": "INVALID_SLUG",
    "message": "Field 'slug' must use slug format a-z0-9-",
    "details": null
  }
}

4) Endpoints de lectura (catalogos y posts)

Estos endpoints permiten resolver IDs reales antes de crear/editar contenido y evitar errores como STATUS_UNCHANGED consultando el estado actual del post.

GET /cms-catalogs?catalog=all&includeInactive=false

GET /cms-blog-post?postId=<uuid>
GET /cms-blog-post?categorySlug=automatizacion&slug=mi-post

GET /cms-blog-posts?status=draft&search=ia&limit=20&offset=0&sort=updated_desc

5) Endpoint: POST /cms-blog-create

Crea un post en estado draft. Permite incluir tags y FAQs desde el primer write.

• Rol permitido: admin, editor.
• Rate limit: 30 req/min por usuario.
• Status HTTP: 201 en exito.

{
  "slug": "mi-slug-seo",
  "categoryId": "uuid",
  "h1": "Titulo H1",
  "metaDescription": "Meta description",
  "canonicalUrl": "https://creamvp.com/blog/categoria/mi-slug-seo",
  "shortDescription": "Texto corto para listados",
  "featuredImage": {
    "url": "https://cdn.com/imagen.jpg",
    "alt": "Texto ALT",
    "metadata": { "width": 1200, "height": 630 }
  },
  "authorId": "uuid",
  "contentMarkdown": "# Contenido",
  "schemaOverride": { "@type": "BlogPosting" },
  "seo": { "title": "SEO title" },
  "tags": ["uuid", "uuid"],
  "faqs": [
    { "question": "Pregunta", "answer": "Respuesta", "position": 0 }
  ]
}

Campos clave:

6) Endpoint: PATCH /cms-blog-update

Aplica cambios de contenido/SEO sobre posts en draft o scheduled.

• Rol permitido: admin, editor.
• Rate limit: 60 req/min por usuario.
• Status HTTP: 200 en exito.
• No permite cambiar status (usar cms-blog-status).

{
  "postId": "uuid",
  "patch": {
    "h1": "H1 actualizado",
    "metaDescription": "Meta actualizada",
    "slug": "nuevo-slug",
    "categoryId": "uuid",
    "canonicalUrl": "https://creamvp.com/blog/categoria/nuevo-slug",
    "shortDescription": "Resumen corto",
    "featuredImage": { "url": "https://...", "alt": "ALT" },
    "authorId": "uuid",
    "contentMarkdown": "## Markdown",
    "schemaOverride": { "@type": "BlogPosting" },
    "seo": { "title": "SEO title" }
  },
  "tags": ["uuid"],
  "faqs": [{ "question": "Q", "answer": "A", "position": 0 }]
}

Reglas criticas:

• patch debe tener al menos 1 campo editable.
• Si envias tags, reemplaza el set completo de tags actuales.
• Si envias faqs, reemplaza el set completo de FAQs actuales.
• Si el post esta published, responde 409 UPDATE_REQUIRES_DRAFT_OR_SCHEDULED.

7) Endpoint: PATCH /cms-blog-status

Gestiona transiciones editoriales de estado.

• Rate limit: 30 req/min por usuario.
• Status HTTP: 200 en exito.

{
  "postId": "uuid",
  "status": "draft | scheduled | published",
  "scheduledPublishAt": "2026-03-10T22:00:00.000Z",
  "publishDate": "2026-02-10T10:00:00.000Z",
  "changeReason": "Motivo de cambio"
}

Reglas de validacion:

• Si status = scheduled, scheduledPublishAt es obligatorio (ISO valido).
• publishDate solo se permite cuando status = published.
• No permite pedir el mismo estado actual (409 STATUS_UNCHANGED).

8) Endpoint: DELETE /cms-blog-delete

Elimina un post por ID.

• Rol permitido: admin.
• Rate limit: 10 req/min por usuario.
• Status HTTP: 200 en exito.

{
  "postId": "uuid",
  "changeReason": "Motivo opcional"
}

9) Endpoint interno: POST /api/cms/preview-token

Endpoint Astro (no edge function) para generar URL de preview de posts no publicados.

• Requiere JWT valido y perfil editorial activo.
• Solo aplica para estados draft y scheduled.
• TTL actual del token: 30 minutos.

{
  "postId": "uuid"
}

{
  "data": {
    "postId": "uuid",
    "status": "draft",
    "previewUrl": "https://creamvp.com/blog/preview/uuid?pt=token",
    "token": "token",
    "expiresAt": "2026-03-10T23:00:00.000Z"
  },
  "meta": {
    "generatedBy": "user-id",
    "generatedRole": "admin"
  }
}

10) Errores comunes y diagnostico