Использование 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.json | OpenAPI 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/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 |
Платформа поддерживает регистрацию 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 контента.
Последнее обновление: