Ugrás a tartalomra
Sursa Developers

Gyorsindítás

Ez az útmutató öt perc alatt elvezet a semmitől egy működő integrációig: létrehozol egy API-kulcsot, ellenőrzöd, hozzáadsz egy dokumentumot a tudásbázishoz, megkeresed, és kérdést teszel fel róla. Minden lépés egyetlen HTTP-kérés. Bármelyik példában válaszd ki egyszer a nyelvedet; az oldal összes példája vele együtt vált.

A nyelvváltóval ellátott példák ennek a portálnak az API-címét használják: a Sursa-felhőben https://api.sursa.com, saját telepítésnél pedig a telepítésed API-címét. Ahol egy példában https://api.example.com áll, írd a helyére a saját API-címedet. Ha nem vagy biztos benne, melyik a tiéd, lásd: API-cím és környezetek.

1. API-kulcs létrehozása

A kulcsokat a szervezet adminisztrátora hozza létre a Sursában, az Administration → API keys (adminisztráció → API-kulcsok) alatt. Adj a kulcsnak olyan nevet, amely elárulja, hol használják (például „CRM sync”), válaszd ki a szerepkörét, és ha tovább szeretnéd szűkíteni, a hatóköreit is. A kulcs azt teheti, amit egy ilyen szerepkörű felhasználó, és nem többet, mint amit a hatókörei megengednek. Ehhez az útmutatóhoz az editor szerepkör elég.

A kulcs egyszer jelenik meg. Tárold a rendszered titoktárában, és környezeti változóban add át a kódodnak:

export SURSA_API_KEY="kb_…"

Minden kérés bearer tokenként, az Authorization fejlécben küldi el a kulcsot. Az API-kulcsok és hatókörök útmutató elmagyarázza a szerepköröket, a hatóköröket, a lejáratot és a megújítást.

2. Kliens beállítása

Nincs szükség könyvtárra: az API egyszerű HTTPS és JSON. Az útmutató példái minden nyelven egy kis segédfüggvényt használnak. Másold ki a nyelvedhez tartozót; a további útmutatók is ugyanezt a segédfüggvényt használják. A hivatalos klienskönyvtárakat az SDK-k oldal sorolja fel.

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

3. A kulcs ellenőrzése

A GET /v1/me leírja a hívót: a szervezetet, a kulcsot, a szerepkörét és a hatóköreit, valamint a rá vonatkozó gyakorisági korlátot. Bármely érvényes kulccsal működik, ezért ez minden integráció legjobb első kérése.

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

Az auth.not_authenticated kódú 401 válasz azt jelenti, hogy a kulcs hiányzik, visszavonták, vagy elírták; az api_keys.expired azt, hogy lejárt.

4. Gyűjtemény keresése

A kártyák gyűjteményekben vannak. A GET /v1/collections felsorolja azokat a gyűjteményeket, amelyeket a kulcsod lát:

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

Jegyezd fel annak a gyűjteménynek az id és name értékét, amellyel dolgozni szeretnél. Az alábbi példák a 3 azonosítójú, support nevű gyűjteményt használják.

5. Dokumentum hozzáadása

A PUT /v1/cards-by-external-id/{external_id} létrehoz egy kártyát a saját azonosítóddal, vagy lecseréli, ha a kártya már létezik. A kérést kétszer lefuttatni is biztonságos: másodszorra a tartalom nem változott, és a válasz skipped lesz unchanged indoklással. external_id értékként a rekord azonosítóját használd a saját rendszeredből.

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

A kérés akkor tér vissza, amikor a kártya már megtalálható: új kártyánál 201 válasszal és "status": "ready" értékkel, lecserélt kártyánál 200 válasszal. A HTML és az egyszerű szöveg ugyanígy működik a "content_type": "html" vagy "text" értékkel. A fájlok (PDF, Word, Excel és mások) ugyanezen a végponton mennek át multipart/form-data formátumban; a Dokumentumok importálása útmutató a fájlokat, a mappákat, a metaadatokat és a sok dokumentumot érintő importálásokat is bemutatja.

A POST /v1/search megkeresi a kártyák azon szövegrészleteit, amelyek illeszkednek a lekérdezéshez, a legjobb találattal kezdve:

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

A collection a gyűjtemény nevét várja. Nélküle a keresés a default nevű gyűjteményre terjed ki.

7. Kérdés feltevése

A POST /v1/ask természetes nyelven válaszol egy kérdésre, és visszaadja a válasz forrásait. Az asszisztens megtalálja a szükséges tudást, és csak azokból a kártyákból válaszol, amelyeket a kulcs olvashat.

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

Ha semmi releváns nem található, a válasz akkor is 200, "empty": "no_hits" értékkel és egy rövid magyarázattal az answer mezőben. Hogy ilyenkor mit mutatsz a felhasználónak, azt a kódod dönti el.

Következő lépések