Към съдържанието
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. Използвайте ID на записа във вашата система като external_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. В такъв случай кодът ви решава какво да покаже на потребителя.

Следващи стъпки