Przejdź do treści
Sursa Developers

Szybki start

Ten przewodnik w pięć minut prowadzi od zera do działającej integracji: tworzysz klucz API, sprawdzasz go, dodajesz dokument do bazy wiedzy, wyszukujesz go i zadajesz pytanie na jego temat. Każdy krok to jedno żądanie HTTP. Wybierz język w dowolnym przykładzie, a wszystkie przykłady na stronie przełączą się razem z nim.

Przykłady z przełącznikiem języka używają adresu API tego portalu: https://api.sursa.com w chmurze Sursa lub adresu API Twojej własnej instalacji. Tam, gdzie przykład pokazuje https://api.example.com, wstaw w to miejsce swój adres API. Jeśli nie wiesz, którego adresu używasz, zob. Adres API i środowiska.

1. Utwórz klucz API

Administrator organizacji tworzy klucze w Sursie w sekcji Administration → API keys (administracja → klucze API). Nadaj kluczowi nazwę, która mówi, gdzie jest używany (np. „CRM sync”), wybierz jego rolę i, jeśli chcesz go dodatkowo zawęzić, zakresy. Klucz może robić to, co użytkownik z tą rolą, i nic ponad to, na co pozwalają jego zakresy. Na potrzeby tego przewodnika wystarczy rola editor.

Klucz jest pokazywany tylko raz. Przechowuj go w magazynie sekretów swojego systemu i przekazuj do kodu w zmiennej środowiskowej:

export SURSA_API_KEY="kb_…"

Każde żądanie wysyła klucz w nagłówku Authorization jako token typu bearer. Przewodnik Klucze API i zakresy objaśnia role, zakresy, wygasanie i wymianę kluczy.

2. Skonfiguruj klienta

Żadna biblioteka nie jest potrzebna: API to zwykłe HTTPS i JSON. Przykłady w tym przewodniku używają niewielkiej funkcji pomocniczej w każdym języku. Skopiuj tę dla swojego języka; dalsze przewodniki używają tej samej funkcji. Oficjalne biblioteki klienckie są wymienione w sekcji SDK.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. Sprawdź klucz

GET /v1/me opisuje wywołującego: organizację, klucz, jego rolę i zakresy oraz obowiązujący go limit częstotliwości. Działa z każdym prawidłowym kluczem, więc jest najlepszym pierwszym żądaniem każdej integracji.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

401 z kodem auth.not_authenticated oznacza, że klucza brakuje, został unieważniony lub błędnie wpisany; api_keys.expired oznacza, że klucz wygasł.

4. Znajdź kolekcję

Karty znajdują się w kolekcjach. GET /v1/collections zwraca listę kolekcji, które widzi Twój klucz:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

Zanotuj id i name kolekcji, z którą chcesz pracować. Poniższe przykłady używają kolekcji 3 o nazwie support.

5. Dodaj dokument

PUT /v1/cards-by-external-id/{external_id} tworzy kartę z Twoim własnym identyfikatorem albo zastępuje ją, jeśli karta już istnieje. Dwukrotne wykonanie żądania jest bezpieczne: za drugim razem treść się nie zmieniła, więc odpowiedź to skipped z powodem unchanged. Jako external_id użyj identyfikatora rekordu w swoim systemie.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

Żądanie kończy się, gdy kartę można już znaleźć: 201 z "status": "ready" dla nowej karty, 200 dla zastąpionej. HTML i zwykły tekst działają tak samo z "content_type": "html" lub "text". Pliki (PDF, Word, Excel i inne) przechodzą przez tę samą operację jako multipart/form-data; przewodnik Importuj dokumenty omawia pliki, foldery, metadane i import wielu dokumentów.

POST /v1/search znajduje urywki kart pasujące do zapytania, od najlepiej dopasowanego:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection przyjmuje nazwę kolekcji. Bez tego parametru wyszukiwanie obejmuje kolekcję o nazwie default.

7. Zadaj pytanie

POST /v1/ask odpowiada na pytanie zadane w języku naturalnym i zwraca źródła odpowiedzi. Asystent znajduje potrzebną wiedzę i odpowiada wyłącznie na podstawie kart, które klucz może odczytywać.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

Gdy nie znaleziono niczego istotnego, odpowiedź nadal ma status 200, z "empty": "no_hits" i krótkim wyjaśnieniem w answer. W takim przypadku to Twój kod decyduje, co pokazać użytkownikowi.

Dalsze kroki