Skip to Content
Documentazione per sviluppatori

Usare l’API di siti / CMS

Autentica, modifica e pubblica contenuti con API v1 sulla piattaforma o in un CMS indipendente.

Usare l’API di siti / CMS

API v1 collega integrazioni esterne ai dati di siti e CMS. Consulta il contratto della distribuzione, crea una chiave con permessi limitati e salva una bozza con protezione della versione.

Scegliere servizio e distribuzione

Imposta QOKIT_API_URL sull’origine del servizio API (in locale http://localhost:7777) o dell’installazione indipendente. QOKIT_PROJECT_ID è l’ID del progetto; l’esportazione lo salva in data/seed.json come project.id. Le letture pubbliche usano lo slug del progetto.

DistribuzioneFunzioni
PiattaformaGestione CMS, esportazioni e pubblicazione sulla piattaforma
cms-managedGestione CMS locale e rendering del sito
cms-onlyGestione CMS locale e letture pubbliche headless; nessun rendering del sito
site-onlyPagine HTML e risorse statiche; nessuna API runtime

Consultare il contratto

Ogni servizio espone solo operazioni supportate. Le altre restituiscono 404. API 1.0 mantiene compatibilità con le rotte esistenti senza versione.

PercorsoScopo
GET /v1/openapi.jsonOpenAPI 3.1: corpi, risposte, permessi e precondizioni
GET /v1/capabilitiesVersione API, tipo di distribuzione e operazioni disponibili
GET /v1/sdk/client.mjsClient JavaScript senza dipendenze
GET /v1/sdk/client.d.mtsDichiarazioni TypeScript corrispondenti

Creare una chiave API

Usa l’accessToken di un accesso completato alla piattaforma come SESSION_TOKEN. L’account deve poter gestire le impostazioni del sito. Completa l’autenticazione richiesta prima di emettere la chiave.

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}'

Nel CMS indipendente, accedi con e-mail e password del proprietario della distribuzione, salva il Cookie di sessione e crea la chiave:

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 creazione restituisce token una sola volta. Salvalo nella variabile server QOKIT_SITE_API_KEY; le richieste usano token Bearer con prefisso qk_site_. Durata predefinita: 90 giorni, configurabile da 1 a 365, fino a 50 chiavi attive per progetto. Con una sessione autorizzata alle impostazioni, elenca tramite GET /v1/projects/{id}/api-keys e revoca tramite DELETE /v1/projects/{id}/api-keys/{keyId}.

Scegli solo i permessi necessari. Accesso e permessi del creatore vengono verificati a ogni richiesta. Scadenza, revoca e modifiche di ruolo valgono dalle richieste successive. Le chiavi API non gestiscono altre chiavi.

ScopeScopo
content:read / content:writeLeggere / modificare raccolte e voci
content:publishPubblicazione esplicita e scritture che pubblicano voci
pages:read / pages:writeLeggere runtime / modificare contenuti, struttura, SEO e moduli
media:read / media:writeLeggere / gestire media e cartelle
settings:read / settings:writeLeggere / modificare impostazioni del sito
users:read / users:writeLeggere / gestire utenti CMS
leads:read / leads:write / analytics:readLeggere / aggiornare contatti e leggere la dashboard CMS
marketing:read / marketing:writeLeggere / generare contenuti marketing
deployments:read / deployments:writeProcessi di esportazione e pubblicazione della piattaforma
sync:write / updates:read / updates:writeSincronizzazione e aggiornamenti firmati delle installazioni indipendenti

Salvare una bozza con l’SDK

Il pacchetto workspace è @qokit/site-api; non è ancora pubblicato su npm. Per progetti esterni, scarica entrambi i file client in sdk. Le nuove esportazioni li includono già.

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

L’esempio richiede content:read e content:write. Sostituisci en con una lingua abilitata. Crea una nuova raccolta di esempio; nelle esecuzioni successive riutilizza un ID di raccolta esistente.

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);

Il salvataggio di una bozza conserva l’istantanea pubblica precedente della voce pubblicata. Dopo la revisione, una chiave con content:publish può pubblicare esplicitamente la versione salvata. Le pagine della piattaforma restano bozze fino alla pubblicazione del sito.

await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });

Per recuperare contenuti, leggi api.entries.revisions(id) e chiama api.entries.restore(id, revisionId, { expectedUpdatedAt }). Le altre operazioni documentate usano api.request(path, options), con idempotencyKey. Il client non ritenta automaticamente le scritture.

Rotte di gestione

Aggiungi il prefisso /v1/projects/{id} a questi percorsi. OpenAPI elenca operazioni, campi e requisiti specifici. DELETE archivia raccolte, voci e media.

PercorsoMetodo
/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

La piattaforma supporta registrazione URL e intenzioni di caricamento; i caricamenti indipendenti usano fileName, contentType e contentBase64, con limite di 10 MB e controllo della firma. Le modifiche degli utenti piattaforma richiedono Idempotency-Key; gli utenti locali una password di 12–1024 caratteri. CSV, scritture in blocco e collegamenti di traduzione sono estensioni della piattaforma.

Versioni, paginazione ed errori

Aggiornamenti, archiviazioni e ripristini richiedono expectedUpdatedAt dall’ultimo updatedAt letto. La versione mancante restituisce 428; quella obsoleta 409.

Per struttura, SEO e moduli, leggi GET /v1/projects/{id}/runtime e invia content.updatedAt e siteVersion.updatedAt come baseContentUpdatedAt e baseSiteVersionUpdatedAt. Restano validi i controlli di revisione e del lease di modifica attivo di Builder.

Le liste usano page=1&pageSize=24 per impostazione predefinita, fino a 100 elementi per pagina. La gestione restituisce items; le liste pubbliche entries. Revisioni e cartelle restituiscono array. Leggi tutte le pagine per esportare i contenuti.

{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}

Le risposte includono X-Request-Id e X-Qokit-Api-Version. Gli errori hanno un codice stabile e un ID di richiesta:

{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}

Per 401, verifica la chiave; per 403, permessi e accesso del creatore. Per 409, rileggi e confronta le modifiche; per 428, fornisci la versione. Per 429, rispetta Retry-After. Il limite è 300 richieste al minuto per chiave/indirizzo, oltre ai limiti IP e scrittura della piattaforma.

Configurare l’installazione indipendente

La piattaforma usa CORS_ALLOWED_ORIGINS per il browser. Le chiamate indipendenti con chiave richiedono origini esatte in SITE_API_ALLOWED_ORIGINS; la gestione con Cookie resta sulla stessa origine. Le letture pubbliche CMS possono usare CMS_ALLOWED_ORIGINS. Per URL dei media CMS-only configura CMS_PUBLIC_URL.

Esegui il backup di tutti i dati e caricamenti, inclusi i file privati data/api-security.json e data/api-revisions.json. Password e chiavi restano locali come hash. Ogni directory dati ha un solo processo Node scrittore.

Le vecchie esportazioni ottengono v1 con un aggiornamento firmato del runtime. Dopo l’aggiornamento, scarica contratto e client attuali via HTTP; i file del pacchetto restano istantanee dell’esportazione.

Per letture pubbliche senza credenziali, consulta Chiamare l’API pubblica dei contenuti.

Questa guida è stata utile?

Ultimo aggiornamento il

In questa pagina