Skip to Content
Документация для разработчиков

Использование API сайта / CMS

Аутентификация, редактирование и публикация контента через API v1 на платформе или в независимой CMS.

Использование API сайта / CMS

API v1 связывает внешние интеграции с данными сайта и CMS. Прочитайте контракт своего развёртывания, создайте ключ с ограниченными правами и сохраните черновик с защитой версии.

Выбор сервиса и развёртывания

Укажите в QOKIT_API_URL источник сервиса API (локально http://localhost:7777) или независимой установки. QOKIT_PROJECT_ID — ID проекта; экспорт сохраняет его в data/seed.json как project.id. Публичное чтение использует slug проекта.

РазвёртываниеВозможности
ПлатформаУправление CMS, экспорт и публикация на платформе
cms-managedЛокальное управление CMS и отображение сайта
cms-onlyЛокальное управление CMS и публичное headless-чтение; без отображения сайта
site-onlyСтатические HTML-страницы и ресурсы; без API времени выполнения

Получение контракта

Каждый сервис описывает только поддерживаемые операции. Остальные возвращают 404. API 1.0 сохраняет совместимость существующих маршрутов без версии.

ПутьНазначение
GET /v1/openapi.jsonOpenAPI 3.1: тела запросов, ответы, права и предусловия
GET /v1/capabilitiesВерсия API, тип развёртывания и доступные операции
GET /v1/sdk/client.mjsКлиент JavaScript без зависимостей
GET /v1/sdk/client.d.mtsСоответствующие объявления TypeScript

Создание ключа API

Используйте accessToken, полученный после завершённого входа на платформу, как SESSION_TOKEN. Учётная запись должна управлять настройками сайта. Пройдите необходимую аутентификацию до выпуска ключа.

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

В независимой CMS войдите с почтой и паролем владельца развёртывания, сохраните Cookie сеанса и создайте ключ:

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

Создание возвращает token только один раз. Сохраните его в серверной переменной QOKIT_SITE_API_KEY; запросы используют Bearer-токены с префиксом qk_site_. Срок по умолчанию — 90 дней, доступно 1–365 дней, не более 50 активных ключей на проект. С сеансом администратора настроек просматривайте ключи через GET /v1/projects/{id}/api-keys и отзывайте через DELETE /v1/projects/{id}/api-keys/{keyId}.

Выбирайте только необходимые права. Доступ и текущие разрешения создателя проверяются при каждом запросе. Истечение срока, отзыв и смена роли действуют на последующие запросы. Ключи API не управляют другими ключами.

ScopeНазначение
content:read / content:writeЧтение / редактирование коллекций и записей
content:publishЯвная публикация и операции записи с публикацией
pages:read / pages:writeЧтение runtime / редактирование содержимого, структуры, SEO и форм
media:read / media:writeЧтение / управление медиа и папками
settings:read / settings:writeЧтение / изменение настроек сайта
users:read / users:writeЧтение / управление пользователями CMS
leads:read / leads:write / analytics:readЧтение / обновление лидов и чтение панели CMS
marketing:read / marketing:writeЧтение / генерация маркетингового контента
deployments:read / deployments:writeЗадания экспорта и публикации платформы
sync:write / updates:read / updates:writeСинхронизация и подписанные обновления независимых установок

Сохранение черновика с SDK

Пакет workspace — @qokit/site-api; он пока не опубликован в npm. Для внешнего проекта скачайте оба файла клиента в sdk. Новые экспорты уже содержат их.

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

Пример требует content:read и content:write. Замените en включённым языком проекта. Пример создаёт коллекцию; при повторном запуске используйте ID существующей коллекции.

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

Сохранение черновика оставляет прежний публичный снимок опубликованной записи. После проверки ключ с content:publish может явно опубликовать сохранённую версию. Страницы платформы остаются черновиками до завершения публикации сайта.

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

Для восстановления прочитайте api.entries.revisions(id) и вызовите api.entries.restore(id, revisionId, { expectedUpdatedAt }). Другие операции доступны через api.request(path, options), включая idempotencyKey. Клиент не повторяет операции записи автоматически.

Маршруты управления

Добавьте к путям префикс /v1/projects/{id}. OpenAPI описывает все операции, поля и требования конкретного сервиса. DELETE архивирует коллекции, записи и медиа.

ПутьМетод
/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

Платформа поддерживает регистрацию URL и подготовку загрузки; независимые загрузки используют fileName, contentType и contentBase64, с лимитом 10 MB и проверкой сигнатуры. Изменения пользователей платформы требуют Idempotency-Key; локальным пользователям нужен пароль длиной 12–1024 символа. CSV, пакетные записи и связи переводов — расширения платформы.

Версии, страницы и ошибки

Обновление, архивирование и восстановление ревизий требуют expectedUpdatedAt из последнего прочитанного updatedAt. Отсутствующая версия возвращает 428, устаревшая — 409.

Для структуры, SEO и форм прочитайте GET /v1/projects/{id}/runtime и передайте content.updatedAt и siteVersion.updatedAt как baseContentUpdatedAt и baseSiteVersionUpdatedAt. На платформе сохраняются проверки ревизий Builder и активной аренды редактирования.

Списки по умолчанию используют page=1&pageSize=24, максимум 100 элементов на страницу. Управление возвращает items, публичные списки — entries. Ревизии и папки возвращают массивы. Для экспорта прочитайте все страницы.

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

Ответы содержат X-Request-Id и X-Qokit-Api-Version. Ошибки содержат стабильный код и ID запроса:

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

При 401 проверьте ключ, при 403 — права и доступ создателя. При 409 перечитайте и сравните изменения; при 428 передайте версию. При 429 соблюдайте Retry-After. Лимит — 300 запросов в минуту на ключ/адрес, плюс ограничения IP и записи платформы.

Настройка независимой установки

Браузерные интеграции платформы используют CORS_ALLOWED_ORIGINS. Независимым вызовам с ключами нужны точные источники в SITE_API_ALLOWED_ORIGINS; управление с Cookie остаётся в том же источнике. Публичное чтение CMS также допускает CMS_ALLOWED_ORIGINS. Для медиа CMS-only настройте CMS_PUBLIC_URL.

Сохраняйте резервную копию всего каталога данных и загрузок, включая закрытые data/api-security.json и data/api-revisions.json. Пароли и ключи хранятся локально в виде хешей. В каждый каталог данных записывает один процесс Node.

Старые экспорты получают v1 через подписанное обновление runtime. После обновления скачайте текущий контракт и клиент по HTTP; файлы пакета остаются снимками момента экспорта.

Для публичного чтения без учётных данных см. Вызов публичного API контента.

Было ли это руководство полезным?

Последнее обновление:

На этой странице