Usar a API de sites / CMS
Autentique, edite e publique conteúdo com API v1 na plataforma ou num CMS independente.
Usar a API de sites / CMS
API v1 conecta integrações externas aos dados do site e do CMS. Consulte o contrato do seu ambiente, crie uma chave com permissões limitadas e salve um rascunho com proteção de versão.
Escolher o serviço e a implantação
Defina QOKIT_API_URL como a origem do serviço API (localmente http://localhost:7777) ou da instalação independente. QOKIT_PROJECT_ID é o ID do projeto; a exportação o guarda em data/seed.json como project.id. Leituras públicas usam o slug do projeto.
| Implantação | Recursos |
|---|---|
| Plataforma | Gerenciamento do CMS, exportações e publicação na plataforma |
cms-managed | Gerenciamento local do CMS e renderização do site |
cms-only | Gerenciamento local e leituras públicas headless; sem renderização do site |
site-only | Páginas HTML e recursos estáticos; sem API de execução |
Consultar o contrato
Cada serviço anuncia apenas operações disponíveis. Operações não suportadas retornam 404. API 1.0 mantém compatibilidade com as rotas existentes sem versão.
| Caminho | Finalidade |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: corpos, respostas, permissões e pré-condições |
GET /v1/capabilities | Versão da API, tipo de implantação e operações disponíveis |
GET /v1/sdk/client.mjs | Cliente JavaScript sem dependências |
GET /v1/sdk/client.d.mts | Declarações TypeScript correspondentes |
Criar uma chave API
Use o accessToken de um login concluído na plataforma como SESSION_TOKEN. A conta precisa de permissão para gerenciar as configurações do site. Conclua toda autenticação necessária antes de emitir a chave.
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}'No CMS independente, inicie sessão com o e-mail e a palavra-passe do proprietário da instalação, guarde o Cookie da sessão e crie a chave:
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}'A criação retorna token uma única vez. Guarde-o na variável de servidor QOKIT_SITE_API_KEY; chamadas usam tokens Bearer iniciados por qk_site_. A validade padrão é 90 dias, configurável de 1 a 365, com até 50 chaves ativas por projeto. Com uma sessão autorizada a gerenciar configurações, liste por GET /v1/projects/{id}/api-keys e revogue por DELETE /v1/projects/{id}/api-keys/{keyId}.
Escolha apenas permissões necessárias. Acesso e permissões atuais do criador são verificados a cada chamada. Expiração, revogação e mudanças de função afetam chamadas seguintes. Chaves API não gerenciam outras chaves.
| Scope | Finalidade |
|---|---|
content:read / content:write | Ler / editar coleções e entradas |
content:publish | Publicação explícita e escritas que publicam entradas |
pages:read / pages:write | Ler runtime / editar conteúdo, estrutura, SEO e formulários |
media:read / media:write | Ler / gerir multimédia e pastas |
settings:read / settings:write | Ler / editar definições do site |
users:read / users:write | Ler / gerir utilizadores do CMS |
leads:read / leads:write / analytics:read | Ler / atualizar leads e consultar o painel CMS |
marketing:read / marketing:write | Ler / gerar conteúdo de marketing |
deployments:read / deployments:write | Tarefas de exportação e publicação da plataforma |
sync:write / updates:read / updates:write | Sincronização e atualizações assinadas de instalações independentes |
Guardar um rascunho com o SDK
O pacote do workspace é @qokit/site-api; ainda não foi publicado no npm. Em projetos externos, transfira ambos os ficheiros do cliente para sdk. As novas exportações já os incluem.
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.mtsO exemplo requer content:read e content:write. Substitua en por um idioma ativado. Cria uma coleção de exemplo; nas execuções seguintes, reutilize um ID de coleção 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 um rascunho preserva a imagem pública anterior de uma entrada publicada. Após revisão, uma chave com content:publish pode publicar explicitamente a versão guardada. As páginas da plataforma continuam como rascunhos até à publicação do site.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Para recuperar, consulte api.entries.revisions(id) e chame api.entries.restore(id, revisionId, { expectedUpdatedAt }). Outras operações documentadas usam api.request(path, options), incluindo idempotencyKey. O cliente nunca repete escritas automaticamente.
Rotas de gerenciamento
Adicione /v1/projects/{id} antes destes caminhos. OpenAPI lista operações, campos e requisitos de cada ambiente. DELETE arquiva coleções, entradas e mídia.
| Caminho | 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 |
A plataforma aceita registo de URL e intenções de carregamento; carregamentos independentes usam fileName, contentType e contentBase64, com limite de 10 MB e validação da assinatura. Alterações de utilizadores da plataforma requerem Idempotency-Key; utilizadores locais precisam de palavra-passe de 12–1024 caracteres. CSV, escritas em lote e ligações de tradução são extensões da plataforma.
Versões, paginação e erros
Atualizações, arquivamentos e restaurações exigem expectedUpdatedAt do último updatedAt lido. Versão ausente retorna 428; versão desatualizada retorna 409.
Para estrutura, SEO e formulários, leia GET /v1/projects/{id}/runtime e envie content.updatedAt e siteVersion.updatedAt como baseContentUpdatedAt e baseSiteVersionUpdatedAt. Verificações de revisão e concessão ativa de edição do Builder continuam na plataforma.
Listas usam page=1&pageSize=24 por padrão, com até 100 itens por página. Listas de gerenciamento retornam items; públicas retornam entries. Revisões e pastas retornam arrays. Leia todas as páginas para exportar conteúdo.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Respostas incluem X-Request-Id e X-Qokit-Api-Version. Erros têm código estável e ID de requisição:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Para 401, verifique a chave; para 403, permissões e acesso do criador. Para 409, releia e compare alterações; para 428, forneça a versão. Para 429, respeite Retry-After. O limite é 300 requisições por minuto por chave/endereço, além dos limites de IP e escrita da plataforma.
Configurar a instalação independente
Integrações de navegador da plataforma usam CORS_ALLOWED_ORIGINS. Chamadas independentes com chave precisam de origens exatas em SITE_API_ALLOWED_ORIGINS; gerenciamento com Cookie mantém a mesma origem. Leituras públicas também podem usar CMS_ALLOWED_ORIGINS. Para URLs de mídia CMS-only, configure CMS_PUBLIC_URL.
Faça uma cópia de segurança de todos os dados e carregamentos, incluindo os ficheiros privados data/api-security.json e data/api-revisions.json. Palavras-passe e chaves ficam localmente como hashes. Cada diretório de dados admite um processo Node de escrita.
Exportações antigas recebem v1 por atualização assinada do runtime. Depois, baixe o contrato e cliente atuais via HTTP; arquivos do pacote são snapshots da exportação.
Para leituras públicas sem credenciais, veja Chamar a API pública de conteúdo.
Última atualização em