Skip to Content
Documentação para desenvolvedores

Usar a API de sites / CMS

Autentique, edite e publique conteúdo com API v1 na plataforma ou em um 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çãoRecursos
PlataformaGerenciamento do CMS, exportações e publicação na plataforma
cms-managedGerenciamento local do CMS e renderização do site
cms-onlyGerenciamento local e leituras públicas headless; sem renderização do site
site-onlyPá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.

CaminhoFinalidade
GET /v1/openapi.jsonOpenAPI 3.1: corpos, respostas, permissões e pré-condições
GET /v1/capabilitiesVersão da API, tipo de implantação e operações disponíveis
GET /v1/sdk/client.mjsCliente JavaScript sem dependências
GET /v1/sdk/client.d.mtsDeclaraçõ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, entre com o e-mail e a senha do proprietário da implantação, salve 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.

ScopeFinalidade
content:read / content:writeLer / editar coleções e entradas
content:publishPublicação explícita e escritas que publicam entradas
pages:read / pages:writeLer runtime / editar conteúdo, estrutura, SEO e formulários
media:read / media:writeLer / gerenciar mídia e pastas
settings:read / settings:writeLer / editar configurações do site
users:read / users:writeLer / gerenciar usuários do CMS
leads:read / leads:write / analytics:readLer / atualizar leads e consultar o painel CMS
marketing:read / marketing:writeLer / gerar conteúdo de marketing
deployments:read / deployments:writeTarefas de exportação e publicação da plataforma
sync:write / updates:read / updates:writeSincronização e atualizações assinadas de instalações independentes

Salvar um rascunho com o SDK

O pacote do workspace é @qokit/site-api; ainda não foi publicado no npm. Em projetos externos, baixe ambos os arquivos do cliente em sdk. 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.mts

O exemplo requer content:read e content:write. Troque en por um idioma habilitado. Ele cria uma coleção de exemplo; nas próximas execuções, 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);

Salvar um rascunho preserva o snapshot público anterior de uma entrada publicada. Após revisão, uma chave com content:publish pode publicar explicitamente a versão salva. Edições de páginas da plataforma continuam como rascunhos até a 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.

CaminhoMé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

A plataforma aceita registro de URL e intenções de upload; uploads independentes usam fileName, contentType e contentBase64, com limite de 10 MB e validação da assinatura. Alterações de usuários da plataforma requerem Idempotency-Key; usuários locais precisam de senha de 12–1024 caracteres. CSV, escritas em lote e vínculos 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 backup de todos os dados e uploads, incluindo os arquivos privados data/api-security.json e data/api-revisions.json. Senhas e chaves ficam localmente como hashes. Cada diretório de dados admite um processo Node escritor.

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.

Este guia foi útil?

Última atualização

Nesta página