Перейти к содержанию
Sursa для разработчиков

Быстрый старт

Это руководство за пять минут проведёт вас от нуля до работающей интеграции: вы создадите ключ API, проверите его, добавите документ в базу знаний, найдёте его и зададите по нему вопрос. Каждый шаг — один HTTP-запрос. Выберите язык в любом примере один раз — вместе с ним переключатся все примеры на странице.

Примеры с переключателем языка используют адрес API этого портала: https://api.sursa.com в облаке Sursa или адрес API вашей собственной установки. Там, где в примере стоит https://api.example.com, подставьте свой адрес API. Если не уверены, какой он у вас, см. Адрес API и окружения.

1. Создайте ключ API

Администратор организации создаёт ключи в Sursa в разделе Администрирование → API-ключи. Дайте ключу имя, по которому понятно, где он используется (например, «Синхронизация CRM»), выберите его роль и, если хотите сузить доступ ещё больше, области. Ключ может делать то же, что пользователь с этой ролью, и не больше, чем разрешают его области. Для этого руководства достаточно роли 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 используйте идентификатор записи в своей системе.

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. Что показать пользователю в этом случае, решает ваш код.

Что дальше