Пређите на садржај
Sursa Developers

Брзи почетак

Овај водич вас за пет минута води од нуле до интеграције која ради: креирате API кључ, проверите га, додате документ у базу знања, пронађете га и поставите питање о њему. Сваки корак је један HTTP захтев. Језик изаберите једном, у било ком примеру; сви примери на страници мењају се заједно са њим.

Примери са избором језика користе адресу API интерфејса овог портала: https://api.sursa.com у облаку платформе Sursa или адресу API интерфејса ваше сопствене инсталације. Где пример приказује https://api.example.com, уместо ње упишите своју адресу API интерфејса. Ако нисте сигурни коју адресу имате, погледајте Адреса API интерфејса и окружења.

1. Креирајте API кључ

Администратор организације креира кључеве у платформи Sursa у Administration → API keys (администрација, API кључеви). Дајте кључу име које говори где се користи (на пример „CRM sync“), изаберите његову улогу и, ако желите да га додатно сузите, опсеге. Кључ може да ради оно што може корисник са том улогом, и не више од онога што дозвољавају његови опсези. За овај водич довољна је улога editor.

Кључ се приказује само једном. Чувајте га у складишту тајни свог система и проследите га коду у променљивој окружења:

export SURSA_API_KEY="kb_…"

Сваки захтев шаље кључ у заглављу Authorization као bearer токен. API кључеви и опсези објашњава улоге, опсеге, рок важења и ротацију.

2. Подесите клијента

Библиотека није потребна: API је обичан HTTPS и JSON. Примери у овом водичу користе малу помоћну функцију у сваком језику. Копирајте ону за свој језик; каснији водичи користе исту функцију. Званичне клијентске библиотеке наведене су у одељку SDK пакети.

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

3. Проверите кључ

GET /v1/me описује позиваоца: организацију, кључ, његову улогу и опсеге и ограничење учесталости које за њега важи. Ради са сваким важећим кључем, па је најбољи први захтев сваке интеграције.

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 са кодом auth.not_authenticated значи да кључ недостаје, да је опозван или погрешно унет; api_keys.expired значи да му је истекао рок важења.

4. Пронађите колекцију

Картице се налазе у колекцијама. GET /v1/collections наводи колекције које ваш кључ може да види:

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

Запамтите id и name колекције са којом желите да радите. Примери у наставку користе колекцију 3, са именом support.

5. Додајте документ

PUT /v1/cards-by-external-id/{external_id} креира картицу под вашим сопственим идентификатором или је замењује ако картица већ постоји. Двоструко слање захтева је безбедно: други пут садржај није промењен и одговор је skipped са разлогом unchanged. Као external_id користите ID записа у свом систему.

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

Захтев се враћа када је картица спремна да буде пронађена: 201 са "status": "ready" за нову картицу, 200 за замењену. HTML и обичан текст раде на исти начин, са "content_type": "html" или "text". Фајлови (PDF, Word, Excel и други) иду кроз исту операцију као multipart/form-data; Увоз докумената обухвата фајлове, фолдере, метаподатке и увоз великог броја докумената.

POST /v1/search проналази одломке картица који одговарају упиту, поређане од најбољег поклапања:

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 прима име колекције. Без њега претрага обухвата колекцију са именом default.

7. Поставите питање

POST /v1/ask одговара на питање постављено обичним језиком и враћа изворе одговора. Асистент проналази потребно знање и одговара само на основу картица које кључ сме да чита.

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

Када ништа релевантно није пронађено, одговор је и даље 200, са "empty": "no_hits" и кратким објашњењем у answer. Ваш код одлучује шта ће у том случају приказати кориснику.

Следећи кораци