Přejít na obsah
Sursa Developers

Rychlý start

Tento návod vás za pět minut dovede od nuly k fungující integraci: vytvoříte klíč API, ověříte ho, přidáte dokument do znalostní báze, najdete ho a položíte k němu otázku. Každý krok je jeden požadavek HTTP. Jazyk zvolte jednou v kterékoli ukázce; spolu s ní se přepnou všechny ukázky na stránce.

Ukázky s přepínačem jazyka používají adresu API tohoto portálu: https://api.sursa.com v cloudu Sursa nebo adresu API vaší vlastní instalace. Kde ukázka uvádí https://api.example.com, dosaďte místo ní svou adresu API. Pokud nevíte jistě, kterou máte, podívejte se do návodu Adresa API a prostředí.

1. Vytvořte klíč API

Administrátor organizace vytváří klíče v Surse v Administration → API keys (administrace → klíče API). Dejte klíči název, který říká, kde se používá (například „CRM sync“), zvolte jeho roli a případně i rozsahy, pokud ho chcete dál omezit. Klíč smí to, co uživatel s touto rolí, a nic nad rámec svých rozsahů. Pro tento návod stačí role editor.

Klíč se zobrazí jen jednou. Uložte ho do úložiště tajných klíčů svého systému a předávejte ho svému kódu v proměnné prostředí:

export SURSA_API_KEY="kb_…"

Každý požadavek posílá klíč v hlavičce Authorization jako token typu bearer. Role, rozsahy, vypršení platnosti a obměnu vysvětluje návod Klíče API a rozsahy.

2. Nastavte klienta

Žádná knihovna není potřeba: API je obyčejné HTTPS a JSON. Ukázky v tomto návodu používají v každém jazyce malou pomocnou funkci. Zkopírujte tu pro svůj jazyk; další návody používají tutéž. Oficiální klientské knihovny najdete v sekci SDK.

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

3. Ověřte klíč

GET /v1/me popisuje volajícího: organizaci, klíč, jeho roli a rozsahy a limit četnosti, který se na něj vztahuje. Funguje s jakýmkoli platným klíčem, a proto je nejlepším prvním požadavkem každé integrace.

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 s kódem auth.not_authenticated znamená, že klíč chybí, je odvolaný nebo chybně zadaný; api_keys.expired znamená, že mu vypršela platnost.

4. Najděte kolekci

Karty jsou uložené v kolekcích. GET /v1/collections vypíše kolekce, které váš klíč vidí:

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

Poznamenejte si id a name kolekce, se kterou chcete pracovat. Následující ukázky používají kolekci 3 s názvem support.

5. Přidejte dokument

PUT /v1/cards-by-external-id/{external_id} vytvoří kartu pod vaším vlastním identifikátorem, nebo ji nahradí, pokud karta už existuje. Spustit požadavek dvakrát je bezpečné: podruhé se obsah nezměnil a odpověď je skipped s důvodem unchanged. Jako external_id použijte identifikátor záznamu ve svém systému.

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

Požadavek se vrátí, jakmile je karta připravená k nalezení: 201 s "status": "ready" pro novou kartu, 200 pro nahrazenou. HTML a prostý text fungují stejně s "content_type": "html" nebo "text". Soubory (PDF, Word, Excel a další) procházejí stejnou operací jako multipart/form-data; soubory, složky, metadata a importy mnoha dokumentů popisuje návod Import dokumentů.

POST /v1/search najde pasáže karet, které odpovídají dotazu, nejlepší shoda první:

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 přijímá název kolekce. Bez něj se vyhledává v kolekci s názvem default.

7. Položte otázku

POST /v1/ask odpoví na otázku v přirozeném jazyce a vrátí zdroje odpovědi. Asistent najde potřebné znalosti a odpovídá jen z karet, které klíč smí číst.

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

Když se nic relevantního nenajde, odpověď je stále 200, s "empty": "no_hits" a krátkým vysvětlením v answer. Co v takovém případě uživateli ukázat, rozhoduje váš kód.

Další kroky