Preskočiť na obsah
Sursa Developers

Rýchly štart

Tento návod vás za päť minút dovedie od nuly k fungujúcej integrácii: vytvoríte kľúč API, overíte ho, pridáte dokument do bázy znalostí, nájdete ho a položíte k nemu otázku. Každý krok je jedna požiadavka HTTP. Jazyk vyberte raz v ktorejkoľvek ukážke; prepnú sa s ním všetky ukážky na stránke.

Ukážky s prepínačom jazyka používajú adresu API tohto portálu: https://api.sursa.com v cloude Sursa alebo adresu API vašej vlastnej inštalácie. Kde ukážka uvádza https://api.example.com, nahraďte ju svojou adresou API. Ak si nie ste istí, akú adresu máte, pozrite si návod Adresa API a prostredia.

1. Vytvorte kľúč API

Administrátor organizácie vytvára kľúče v Surse v časti Administration → API keys (administrácia → kľúče API). Dajte kľúču názov, ktorý hovorí, kde sa používa (napríklad „CRM sync“), zvoľte jeho rolu a, ak ho chcete ešte obmedziť, aj rozsahy. Kľúč smie robiť to, čo používateľ s touto rolou, a nie viac, než mu dovoľujú jeho rozsahy. Pre tento návod stačí rola editor.

Kľúč sa zobrazí raz. Uložte ho do úložiska tajných kľúčov svojho systému a do kódu ho odovzdávajte v premennej prostredia:

export SURSA_API_KEY="kb_…"

Každá požiadavka posiela kľúč v hlavičke Authorization ako token typu bearer. Roly, rozsahy, vypršanie platnosti a výmenu kľúčov vysvetľuje návod Kľúče API a rozsahy.

2. Nastavte klienta

Žiadna knižnica nie je potrebná: API je obyčajné HTTPS a JSON. Ukážky v tomto návode používajú v každom jazyku malú pomocnú funkciu. Skopírujte tú pre svoj jazyk; ďalšie návody používajú tú istú. Oficiálne klientske knižnice nájdete v časti SDK.

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

3. Overte kľúč

GET /v1/me opisuje volajúceho: organizáciu, kľúč, jeho rolu a rozsahy a limit frekvencie, ktorý sa naň vzťahuje. Funguje s ľubovoľným platným kľúčom, preto je to najlepšia prvá požiadavka každej integrácie.

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ódom auth.not_authenticated znamená, že kľúč chýba, je odvolaný alebo zle zadaný; api_keys.expired znamená, že mu vypršala platnosť.

4. Nájdite kolekciu

Karty sú uložené v kolekciách. GET /v1/collections vypíše kolekcie, ktoré váš kľúč vidí:

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

Poznačte si id a name kolekcie, s ktorou chcete pracovať. Ukážky nižšie používajú kolekciu 3 s názvom support.

5. Pridajte dokument

PUT /v1/cards-by-external-id/{external_id} vytvorí kartu pod vaším vlastným identifikátorom, alebo ju nahradí, ak už karta existuje. Spustiť požiadavku dvakrát je bezpečné: druhýkrát sa obsah nezmenil a odpoveď je skipped s dôvodom unchanged. Ako external_id použite ID záznamu vo svojom systéme.

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žiadavka sa vráti, keď je karta pripravená na vyhľadanie: 201 s "status": "ready" pri novej karte, 200 pri nahradenej. HTML a obyčajný text fungujú rovnako s "content_type": "html" alebo "text". Súbory (PDF, Word, Excel a ďalšie) idú cez tú istú operáciu ako multipart/form-data; súbory, priečinky, metadáta a import veľkého počtu dokumentov opisuje návod Importujte dokumenty.

POST /v1/search nájde pasáže kariet, ktoré zodpovedajú dopytu, od najlepšej zhody:

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 prijíma názov kolekcie. Bez neho vyhľadávanie prehľadáva kolekciu s názvom default.

7. Položte otázku

POST /v1/ask odpovie na otázku položenú bežným jazykom a vráti zdroje odpovede. Asistent nájde potrebné znalosti a odpovedá len z kariet, ktoré kľúč smie čítať.

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

Keď sa nenájde nič relevantné, odpoveď je aj tak 200, s "empty": "no_hits" a krátkym vysvetlením v answer. Čo v takom prípade používateľovi ukáže, rozhoduje váš kód.

Ďalšie kroky