Skip to Content
Dokumentacja dla deweloperów

Korzystanie z API witryny / CMS

Uwierzytelniaj, edytuj i publikuj treści przez API v1 na platformie lub w niezależnym CMS.

Korzystanie z API witryny / CMS

API v1 łączy integracje zewnętrzne z danymi witryny i CMS. Sprawdź kontrakt wdrożenia, utwórz klucz z ograniczonymi prawami i zapisz szkic z ochroną wersji.

Wybór usługi i wdrożenia

Ustaw QOKIT_API_URL na origin usługi API (lokalnie http://localhost:7777) lub niezależnej instalacji. QOKIT_PROJECT_ID to ID projektu; eksport zapisuje je w data/seed.json jako project.id. Publiczne odczyty używają projektu slug.

WdrożenieMożliwości
PlatformaZarządzanie CMS, eksporty i publikacja na platformie
cms-managedLokalne zarządzanie CMS i renderowanie witryny
cms-onlyLokalne zarządzanie CMS i publiczne odczyty headless; bez renderowania witryny
site-onlyStatyczne strony HTML i zasoby; bez API środowiska uruchomieniowego

Odczyt kontraktu

Każda usługa opisuje tylko obsługiwane operacje. Pozostałe zwracają 404. API 1.0 zachowuje zgodność istniejących tras bez wersji.

ŚcieżkaCel
GET /v1/openapi.jsonOpenAPI 3.1: treść żądania, odpowiedzi, uprawnienia i warunki wstępne
GET /v1/capabilitiesWersja API, typ wdrożenia i dostępne operacje
GET /v1/sdk/client.mjsKlient JavaScript bez zależności
GET /v1/sdk/client.d.mtsOdpowiadające deklaracje TypeScript

Tworzenie klucza API

Użyj accessToken z zakończonego logowania na platformie jako SESSION_TOKEN. Konto wymaga praw zarządzania ustawieniami witryny. Przed wydaniem klucza zakończ wymagane uwierzytelnianie.

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

W niezależnym CMS zaloguj się adresem e-mail i hasłem właściciela wdrożenia, zachowaj Cookie sesji i utwórz klucz:

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

Podczas tworzenia token jest zwracany tylko raz. Zapisz go w zmiennej serwera QOKIT_SITE_API_KEY; żądania używają tokenów Bearer z prefiksem qk_site_. Domyślna ważność wynosi 90 dni, można ustawić 1–365 dni, maksymalnie 50 aktywnych kluczy na projekt. Sesją administratora ustawień wyświetlaj przez GET /v1/projects/{id}/api-keys i unieważniaj przez DELETE /v1/projects/{id}/api-keys/{keyId}.

Wybierz tylko potrzebne prawa. Każde żądanie sprawdza aktualny dostęp i uprawnienia twórcy. Wygaśnięcie, unieważnienie i zmiany roli działają na kolejne żądania. Klucze API nie zarządzają innymi kluczami.

ScopeCel
content:read / content:writeOdczyt / edycja kolekcji i wpisów
content:publishJawna publikacja i zapisy publikujące wpisy
pages:read / pages:writeOdczyt runtime / edycja treści, struktury, SEO i formularzy
media:read / media:writeOdczyt / zarządzanie mediami i folderami
settings:read / settings:writeOdczyt / edycja ustawień witryny
users:read / users:writeOdczyt / zarządzanie użytkownikami CMS
leads:read / leads:write / analytics:readOdczyt / aktualizacja leadów i odczyt panelu CMS
marketing:read / marketing:writeOdczyt / generowanie treści marketingowych
deployments:read / deployments:writeZadania eksportu i publikacji platformy
sync:write / updates:read / updates:writeSynchronizacja i podpisane aktualizacje niezależnych instalacji

Zapis szkicu przez SDK

Pakiet workspace to @qokit/site-api; nie został jeszcze opublikowany w npm. W projekcie zewnętrznym pobierz oba pliki klienta do sdk. Nowe eksporty już je zawierają.

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

Przykład wymaga content:read i content:write. Zastąp en włączonym językiem projektu. Tworzy nową kolekcję przykładową; przy kolejnych uruchomieniach użyj istniejącego ID kolekcji.

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

Zapis szkicu zachowuje poprzedni publiczny snapshot opublikowanego wpisu. Po sprawdzeniu klucz z content:publish może jawnie opublikować zapisaną wersję. Strony platformy pozostają szkicami do ukończenia publikacji witryny.

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

Aby odzyskać treści, odczytaj api.entries.revisions(id) i wywołaj api.entries.restore(id, revisionId, { expectedUpdatedAt }). Inne opisane operacje używają api.request(path, options), z obsługą idempotencyKey. Klient nie ponawia zapisów automatycznie.

Trasy zarządzania

Dodaj prefiks /v1/projects/{id} do tych ścieżek. OpenAPI opisuje wszystkie operacje, pola i wymagania danego wdrożenia. DELETE archiwizuje kolekcje, wpisy i media.

ŚcieżkaMetoda
/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

Platforma obsługuje rejestrację URL i przygotowanie przesyłania; niezależne przesyłanie używa fileName, contentType i contentBase64, z limitem 10 MB i weryfikacją sygnatury. Zmiany użytkowników platformy wymagają Idempotency-Key; lokalni użytkownicy hasła o długości 12–1024 znaków. CSV, zapisy zbiorcze i powiązania tłumaczeń są rozszerzeniami platformy.

Wersje, paginacja i błędy

Aktualizacje, archiwizacja i przywracanie rewizji wymagają expectedUpdatedAt z ostatnio odczytanego updatedAt. Brak wersji zwraca 428, nieaktualna wersja 409.

Dla struktury, SEO i formularzy odczytaj GET /v1/projects/{id}/runtime i prześlij content.updatedAt oraz siteVersion.updatedAt jako baseContentUpdatedAt oraz baseSiteVersionUpdatedAt. Na platformie nadal obowiązują kontrole rewizji Builder i aktywnej dzierżawy edycji.

Listy domyślnie używają page=1&pageSize=24, maksymalnie 100 elementów na stronę. Zarządzanie zwraca items, listy publiczne entries. Rewizje i foldery zwracają tablice. Przy eksporcie odczytaj wszystkie strony.

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

Odpowiedzi zawierają X-Request-Id i X-Qokit-Api-Version. Błędy mają stały kod oraz ID żądania:

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

Dla 401 sprawdź klucz, dla 403 uprawnienia i dostęp twórcy. Przy 409 odczytaj ponownie i porównaj zmiany; dla 428 podaj wersję. Przy 429 stosuj Retry-After. Limit wynosi 300 żądań na minutę na klucz/adres, z dodatkowymi limitami IP i zapisu platformy.

Konfiguracja niezależnej instalacji

Platforma używa CORS_ALLOWED_ORIGINS dla integracji przeglądarkowych. Niezależne wywołania z kluczem wymagają dokładnych originów w SITE_API_ALLOWED_ORIGINS; zarządzanie przez Cookie pozostaje w tym samym originie. Publiczne odczyty CMS mogą używać CMS_ALLOWED_ORIGINS. Dla adresów mediów CMS-only skonfiguruj CMS_PUBLIC_URL.

Wykonuj kopie wszystkich danych i przesłanych plików, w tym prywatnych data/api-security.json i data/api-revisions.json. Hasła i klucze pozostają lokalnie jako hashe. Jeden proces Node zapisuje w każdym katalogu danych.

Starsze eksporty uzyskują v1 przez podpisaną aktualizację runtime. Następnie pobierz aktualny kontrakt i klienta przez HTTP; pliki pakietu pozostają snapshotami eksportu.

Publiczne odczyty bez poświadczeń opisuje Wywołanie publicznego API treści.

Czy ten przewodnik był pomocny?

Ostatnia aktualizacja

Na tej stronie