API de Gestión de Plantillas
Qué es esto
Endpoints REST para gestionar plantillas de páginas (plantillas de documentos) y plantillas de proyectos a nivel global, así como para asignar plantillas a proyectos específicos.
Prefijos de ruta:
/api/templates/doc/…— CRUD global de plantillas de documentos (solo admin)/api/templates/project/…— CRUD global de plantillas de proyectos (solo admin)/api/projects/:projectId/templates— asignación de plantillas por proyecto (manager)
Cómo funciona
Las plantillas de documentos definen el diseño estructurado de un tipo de contenido: qué campos requiere, qué esquema JSON-LD emite y cómo la IA debe extraer el contenido en él. Las plantillas de proyectos definen un tipo de proyecto: qué plantillas de documentos están disponibles y qué límites de plan se aplican según el nivel.
Las operaciones de escritura globales requieren acceso de administrador de la plataforma. La asignación por proyecto requiere el rol de manager o admin en el proyecto.
Las mismas operaciones están disponibles como herramientas MCP — create-doc-template, update-doc-template, assign-project-template, entre otras — para usuarios administradores que trabajan dentro de Claude o Cursor.
Cuándo usarlo
- Crear un nuevo tipo de contenido para su proyecto (ej. un listado de propiedades o una plantilla de miembro del equipo)
- Asignar o eliminar plantillas de un proyecto específico
- Listar plantillas para entender qué hay disponible antes de crear páginas
- Deshabilitar suavemente una plantilla que ya no debería usarse (la eliminación suave preserva las páginas existentes)
Parámetros / campos / entradas
Plantilla de documento — campos clave:
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | Sí | Nombre de la plantilla legible por humanos. |
card_template_id | string | Sí | Referencia de la plantilla de renderizado de tarjeta. |
fields | array | Sí | Definiciones de campo. Cada uno tiene name, type (string/number/boolean/date/array), required opcional, schema_org, instructions. |
description | string | No | Descripción del propósito de la plantilla. |
slug_instructions | string | No | Guía para la generación del slug de la URL. |
schema_org_type | string | No | Tipo de Schema.org para JSON-LD (ej. TechArticle, RealEstateListing). |
default_sitemap_priority | number | No | sitemap_priority predeterminado para páginas que usan esta plantilla (0.0–1.0). |
default_sitemap_changefreq | string | No | Frecuencia de cambio predeterminada. Uno de: always, hourly, daily, weekly, monthly, yearly, never. |
Catálogo de endpoints:
| Método | Ruta | Auth | Propósito |
|---|---|---|---|
| GET | /api/templates/doc | Admin | Listar todas las plantillas de documentos |
| GET | /api/templates/doc/:id | Admin | Obtener una plantilla de documento |
| POST | /api/templates/doc | Admin | Crear plantilla de documento |
| PATCH | /api/templates/doc/:id | Admin | Actualización parcial |
| DELETE | /api/templates/doc/:id | Admin | Eliminación suave (status=disabled) |
| GET | /api/projects/:projectId/templates | Manager | Listar plantillas asignadas (resueltas) |
| POST | /api/projects/:projectId/templates/:templateId | Manager | Añadir plantilla al proyecto |
| DELETE | /api/projects/:projectId/templates/:templateId | Manager | Eliminar plantilla del proyecto |
Ejemplo
Listar todas las plantillas de documentos activas:
curl https://api.comstack.ai/api/templates/doc \ -H "Authorization: Bearer <firebase-id-token>"Asignar una plantilla a un proyecto:
curl -X POST https://api.comstack.ai/api/projects/your-project-id/templates/property-listing-v1 \ -H "Authorization: Bearer <firebase-id-token>"Errores comunes
401 Unauthorized — falta el token de ID de Firebase o ha caducado.
403 Forbidden — no es administrador de la plataforma (CRUD global) o no es manager (asignación de proyecto).
404 Not found — el ID de la plantilla o del proyecto no existe.
409 Conflict (creación) — ya existe una plantilla con ese ID.
409 Conflict (eliminación suave) — la plantilla está asignada a uno o más proyectos. Elimine las asignaciones primero.
409 Conflict (asignación de proyecto) — la plantilla ya está asignada a este proyecto.
400 (integridad referencial) — available_doc_templates hace referencia a una plantilla que no existe o está deshabilitada.
Relacionado
- Servidor MCP —
create-doc-template,assign-project-templatey herramientas MCP relacionadas - Descripción general de la API — índice completo de endpoints
- Autenticación — requisitos de roles