Usar la API de sitios / CMS
Autentica, edita y publica contenido mediante API v1 en la plataforma o un CMS independiente.
Usar la API de sitios / CMS
API v1 conecta integraciones externas con los datos del sitio y del CMS. Consulta el contrato de tu despliegue, crea una clave con permisos limitados y guarda un borrador con protección de versiones.
Elegir servicio y despliegue
Configura QOKIT_API_URL con el origen del servicio API (en local, http://localhost:7777) o de la instalación independiente. QOKIT_PROJECT_ID es el ID del proyecto; la exportación lo guarda en data/seed.json, como project.id. Las lecturas públicas usan el slug del proyecto.
| Despliegue | Funciones |
|---|---|
| Plataforma | Gestión del CMS, exportación y publicación en la plataforma |
cms-managed | Gestión local del CMS y renderizado del sitio |
cms-only | Gestión local del CMS y lecturas públicas headless; sin renderizado del sitio |
site-only | Páginas HTML y recursos estáticos; sin API en tiempo de ejecución |
Consultar el contrato
Cada servicio anuncia solo las operaciones que admite. Las no disponibles devuelven 404. API 1.0 mantiene la compatibilidad de las rutas existentes sin versión.
| Ruta | Uso |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: cuerpos, respuestas, permisos y condiciones previas |
GET /v1/capabilities | Versión de API, tipo de despliegue y operaciones disponibles |
GET /v1/sdk/client.mjs | Cliente JavaScript sin dependencias |
GET /v1/sdk/client.d.mts | Declaraciones TypeScript correspondientes |
Crear una clave API
Usa el accessToken de un inicio de sesión completo como SESSION_TOKEN. La cuenta necesita permiso para gestionar la configuración del sitio. Completa toda la autenticación requerida antes de emitir la clave.
curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'En un CMS independiente, inicia sesión con el correo y la contraseña del propietario del despliegue, guarda la Cookie de sesión y crea la clave:
curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'La creación devuelve token una sola vez. Guárdalo en la variable de servidor QOKIT_SITE_API_KEY; las llamadas usan tokens Bearer que empiezan por qk_site_. La duración predeterminada es de 90 días, configurable entre 1 y 365, con hasta 50 claves activas por proyecto. Usa una sesión con permiso de configuración para listar con GET /v1/projects/{id}/api-keys y revocar con DELETE /v1/projects/{id}/api-keys/{keyId}.
Selecciona solo los permisos necesarios. Cada llamada comprueba el acceso y los permisos actuales del creador. La caducidad, revocación y cambios de rol afectan a las siguientes llamadas. Las claves API no pueden gestionar otras claves.
| Scope | Uso |
|---|---|
content:read / content:write | Leer / editar colecciones y entradas |
content:publish | Publicación explícita y escrituras que publican entradas |
pages:read / pages:write | Leer runtime / editar contenido, estructura, SEO y formularios |
media:read / media:write | Leer / gestionar medios y carpetas |
settings:read / settings:write | Leer / editar configuración del sitio |
users:read / users:write | Leer / gestionar usuarios del CMS |
leads:read / leads:write / analytics:read | Leer / actualizar contactos y consultar el panel del CMS |
marketing:read / marketing:write | Leer / generar contenido de marketing |
deployments:read / deployments:write | Trabajos de exportación y publicación en la plataforma |
sync:write / updates:read / updates:write | Sincronización y actualizaciones firmadas de instalaciones independientes |
Guardar un borrador con el SDK
El paquete del workspace es @qokit/site-api; todavía no está publicado en npm. Para un proyecto externo, descarga ambos archivos del cliente en sdk. Las nuevas exportaciones ya los incluyen.
mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mtsEl ejemplo necesita content:read y content:write. Sustituye en por un idioma habilitado. Crea una colección de ejemplo nueva; al repetirlo, reutiliza el ID de una colección existente.
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({
baseUrl: process.env.QOKIT_API_URL,
projectId: process.env.QOKIT_PROJECT_ID,
token: process.env.QOKIT_SITE_API_KEY
});
const collection = await api.collections.create({
key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);Guardar un borrador conserva la instantánea pública anterior de una entrada publicada. Tras revisarlo, una clave con content:publish puede publicar explícitamente la versión guardada. Las ediciones de páginas de la plataforma siguen siendo borradores hasta completar la publicación del sitio.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Para recuperar contenido, consulta api.entries.revisions(id) y llama a api.entries.restore(id, revisionId, { expectedUpdatedAt }). Para otras operaciones documentadas usa api.request(path, options), con soporte para idempotencyKey. El cliente no reintenta escrituras automáticamente.
Rutas de gestión
Añade el prefijo /v1/projects/{id} a estas rutas. OpenAPI enumera las operaciones, campos y requisitos de cada despliegue. DELETE archiva colecciones, entradas y medios.
| Ruta | Método |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, POST |
/cms/media/{assetId}, /cms/media/folders/{folderId} | PUT, DELETE |
/runtime, /content/{locale} | GET; PUT /content/{locale} |
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
Los medios de la plataforma admiten registro de URL e intenciones de carga; las cargas independientes usan fileName, contentType y contentBase64, con un límite de 10 MB y validación de firma. Los cambios de usuarios de la plataforma requieren Idempotency-Key; los usuarios locales necesitan una contraseña de 12–1024 caracteres. CSV, escrituras en lote y enlaces de traducción son extensiones de la plataforma.
Versiones, paginación y errores
Las actualizaciones, archivados y restauraciones requieren expectedUpdatedAt del último updatedAt leído. La ausencia de versión devuelve 428; una versión obsoleta devuelve 409.
Para estructura, SEO y formularios, consulta GET /v1/projects/{id}/runtime y envía content.updatedAt y siteVersion.updatedAt como baseContentUpdatedAt y baseSiteVersionUpdatedAt. Se mantienen las comprobaciones de revisiones y bloqueos de edición activos de Builder.
Las listas paginadas usan page=1&pageSize=24 por defecto y hasta 100 elementos por página. Las listas de gestión devuelven items; las públicas, entries. Las revisiones y carpetas devuelven arrays. Para exportar contenido, lee todas las páginas.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Las respuestas incluyen X-Request-Id y X-Qokit-Api-Version. Los errores tienen un código estable y un ID de petición:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Para 401, comprueba la validez de la clave; para 403, los permisos y el acceso del creador. Para 409, vuelve a leer y compara los cambios; para 428, aporta la versión. Ante 429, respeta Retry-After. El límite es de 300 peticiones por minuto por clave/origen, más los límites de IP y escritura de la plataforma.
Configurar la instalación independiente
La plataforma usa CORS_ALLOWED_ORIGINS para integraciones de navegador. Las llamadas independientes con clave necesitan orígenes exactos en SITE_API_ALLOWED_ORIGINS; la administración con Cookie sigue en el mismo origen. Las lecturas públicas también pueden usar CMS_ALLOWED_ORIGINS. Para URL de medios de CMS-only, configura CMS_PUBLIC_URL.
Copia todo el directorio de datos y las cargas, incluidos los archivos privados data/api-security.json y data/api-revisions.json. Las contraseñas y claves se guardan como hashes locales. Cada directorio admite un único proceso Node escritor.
Las exportaciones antiguas reciben v1 mediante una actualización firmada del runtime. Después, descarga por HTTP el contrato y cliente actuales; los archivos del paquete son instantáneas de la exportación.
Para lecturas públicas sin credenciales, consulta Llamar a la API pública de contenido.
Última actualización