Skip to Content
Documentación para desarrolladores

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.

DespliegueFunciones
PlataformaGestión del CMS, exportación y publicación en la plataforma
cms-managedGestión local del CMS y renderizado del sitio
cms-onlyGestión local del CMS y lecturas públicas headless; sin renderizado del sitio
site-onlyPá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.

RutaUso
GET /v1/openapi.jsonOpenAPI 3.1: cuerpos, respuestas, permisos y condiciones previas
GET /v1/capabilitiesVersión de API, tipo de despliegue y operaciones disponibles
GET /v1/sdk/client.mjsCliente JavaScript sin dependencias
GET /v1/sdk/client.d.mtsDeclaraciones 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.

ScopeUso
content:read / content:writeLeer / editar colecciones y entradas
content:publishPublicación explícita y escrituras que publican entradas
pages:read / pages:writeLeer runtime / editar contenido, estructura, SEO y formularios
media:read / media:writeLeer / gestionar medios y carpetas
settings:read / settings:writeLeer / editar configuración del sitio
users:read / users:writeLeer / gestionar usuarios del CMS
leads:read / leads:write / analytics:readLeer / actualizar contactos y consultar el panel del CMS
marketing:read / marketing:writeLeer / generar contenido de marketing
deployments:read / deployments:writeTrabajos de exportación y publicación en la plataforma
sync:write / updates:read / updates:writeSincronizació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.mts

El 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.

RutaMétodo
/cms/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, 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/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, 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.

¿Te ha resultado útil esta guía?

Última actualización

En esta página