Preskoči na sadržaj
Sursa Developers

Brzi početak

Ovaj vas vodič za pet minuta dovodi od nule do integracije koja radi: stvorit ćete API ključ, provjeriti ga, dodati dokument u bazu znanja, pronaći ga i postaviti pitanje o njemu. Svaki je korak jedan HTTP zahtjev. Jezik odaberite jednom u bilo kojem primjeru; svi primjeri na stranici prebacuju se zajedno s njim.

Primjeri s izbornikom jezika koriste adresu API-ja ovog portala: https://api.sursa.com u oblaku Surse ili adresu API-ja vaše vlastite instalacije. Gdje primjer prikazuje https://api.example.com, umjesto nje upišite svoju adresu API-ja. Ako niste sigurni koju adresu imate, v. Adresa API-ja i okruženja.

1. Stvorite API ključ

Administrator organizacije stvara ključeve u Sursi u Administration → API keys (administracija, API ključevi). Ključu dajte ime koje govori gdje se koristi (na primjer „CRM sync”), odaberite njegovu ulogu i, ako ga želite dodatno suziti, njegove opsege. Ključ može činiti ono što može korisnik s tom ulogom, i ništa više od onoga što dopuštaju njegovi opsezi. Za ovaj je vodič dovoljna uloga editor.

Ključ se prikazuje jednom. Čuvajte ga u spremištu tajni svojeg sustava i proslijedite ga svojem kodu u varijabli okruženja:

export SURSA_API_KEY="kb_…"

Svaki zahtjev šalje ključ u zaglavlju Authorization kao bearer token. API ključevi i opsezi objašnjava uloge, opsege, rok valjanosti i rotaciju.

2. Postavite klijent

Nije potrebna nikakva biblioteka: API je običan HTTPS i JSON. Primjeri u ovom vodiču koriste malu pomoćnu funkciju na svakom jeziku. Kopirajte onu za svoj jezik; kasniji vodiči koriste istu pomoćnu funkciju. Službene klijentske biblioteke navedene su u odjeljku SDK-ovi.

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

3. Provjerite ključ

GET /v1/me opisuje pozivatelja: organizaciju, ključ, njegovu ulogu i opsege te ograničenje učestalosti koje se na njega primjenjuje. Radi s bilo kojim valjanim ključem, pa je najbolji prvi zahtjev svake integracije.

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 kodom auth.not_authenticated znači da ključ nedostaje, da je opozvan ili pogrešno upisan; api_keys.expired znači da je istekao.

4. Pronađite zbirku

Kartice se nalaze u zbirkama. GET /v1/collections navodi zbirke koje vaš ključ može vidjeti:

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

Zabilježite id i name zbirke s kojom želite raditi. Primjeri u nastavku koriste zbirku 3 s imenom support.

5. Dodajte dokument

PUT /v1/cards-by-external-id/{external_id} stvara karticu pod vašim vlastitim ID-om ili je zamjenjuje ako kartica već postoji. Dvostruko pokretanje zahtjeva je sigurno: drugi put sadržaj se nije promijenio, a odgovor je skipped s razlogom unchanged. Kao external_id koristite ID zapisa u svojem sustavu.

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

Zahtjev vraća odgovor kad je kartica spremna za pronalaženje: 201 s "status": "ready" za novu karticu, 200 za zamijenjenu. HTML i običan tekst rade na isti način uz "content_type": "html" ili "text". Datoteke (PDF, Word, Excel i druge) prolaze kroz istu operaciju kao multipart/form-data; Uvoz dokumenata obuhvaća datoteke, mape, metapodatke i uvoz velikog broja dokumenata.

POST /v1/search pronalazi odlomke kartica koji odgovaraju upitu, s najboljim rezultatom na prvom mjestu:

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 prima ime zbirke. Bez njega pretraživanje obuhvaća zbirku s imenom default.

7. Postavite pitanje

POST /v1/ask odgovara na pitanje postavljeno običnim jezikom i vraća izvore odgovora. Asistent pronalazi potrebno znanje i odgovara samo na temelju kartica koje ključ smije čitati.

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

Kad se ne pronađe ništa relevantno, odgovor je i dalje 200, uz "empty": "no_hits" i kratko objašnjenje u answer. Vaš kod odlučuje što će u tom slučaju prikazati korisniku.

Sljedeći koraci