Ir al contenido
ComStack

API de modo de edición

Qué es esto

Cuatro endpoints HTTP para gestionar borradores de documentos a través de un editor web: abrir un borrador, leer un borrador específico, guardar cambios y descartar. Todos requieren un Firebase ID Token con rol de manager o admin.

Prefijo de ruta: POST /api/projects/:projectId/docs/edit

Cómo funciona

El modo de edición es la superficie de edición en el navegador del portal web. Los borradores se crean a partir de páginas activas (clonación) o desde cero. Solo los documentos con visibility: "draft" pueden editarse o descartarse; los documentos activos se clonan al usar open.

El flujo de trabajo:

  1. open — busca o crea un borrador para un slug + idioma dado. Devuelve el ID del borrador y el documento completo, además de la plantilla resuelta (para renderizar campos de formulario de metadatos).
  2. save — persiste los cambios. Se llama al guardar explícitamente o mediante autoguardado. Fusiona metadatos (los campos no enviados se conservan). Nuevo borrador: pase draftId: "new".
  3. discard — elimina permanentemente el borrador y su subcolección de versiones.

Cuándo usarlo

  • Construir una interfaz de edición web para documentos de ComStack
  • Reanudar una sesión de edición en curso para un ID de borrador conocido
  • Autoguardar cambios del editor mediante un temporizador
  • Descartar un borrador que no debe publicarse

Parámetros / campos / entradas

POST /edit/open

CampoTipoRequeridoDescripción
slugstringSíSlug de URL de la página a abrir.
languagestringSíCódigo de idioma BCP-47.

Respuesta:

CampoDescripción
draftIdID del documento de Firestore del borrador.
docDocumento — metadata, content, doc_template_id, language.
templateDocumento de plantilla completo — usado para renderizar campos de formulario de metadatos.
action"existing_draft" o "cloned_from_live".

POST /edit/save

CampoTipoRequeridoDescripción
draftIdstringSíID del borrador. Use "new" para crear un borrador desde cero.
metadataobjectSíFusionado con el existente — los campos no enviados se conservan.
contentstringSíCuerpo completo en markdown.
languagestringSíCódigo de idioma BCP-47.
doc_template_idstringSolo para "new"ID de plantilla. No se puede cambiar tras la creación.

Respuesta: { "success": true, "draftId": "abc123" }

POST /edit/discard

CampoTipoRequeridoDescripción
draftIdstringSíID del borrador a eliminar permanentemente.

Respuesta: { "success": true, "draftId": "abc123" }

GET /edit/:draftId

Devuelve un borrador existente por ID. Misma estructura de respuesta que open.

Ejemplo

Abrir una página para editar:

Terminal window
curl -X POST https://api.comstack.ai/api/projects/your-project-id/docs/edit/open \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{"slug": "guides/intro", "language": "en"}'

Guardar un cambio:

Terminal window
curl -X POST https://api.comstack.ai/api/projects/your-project-id/docs/edit/save \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "draftId": "abc123",
    "metadata": {"title": "Updated Title"},
    "content": "## Section\n\nBody text.",
    "language": "en"
  }'

Errores comunes

400 — non-draft document — intento de guardar o descartar un documento activo. Use open primero para clonarlo como borrador.

400 — missing required fields — slug y language requeridos para open; draftId, metadata, content, language requeridos para save.

401 Unauthorized — falta el Firebase ID Token o ha expirado.

403 Forbidden — el llamador no tiene rol de manager o admin en el proyecto.

404 Not found — no existe documento activo o borrador para el slug/idioma dado (para open), o el ID del borrador no existe.

Relacionado

Última actualización: