Chuyển tới nội dung
Sursa Developers

Bắt đầu nhanh

Hướng dẫn này đưa bạn từ con số không tới một tích hợp hoạt động được trong năm phút: bạn tạo khóa API, kiểm tra khóa, thêm một tài liệu vào cơ sở tri thức, tìm thấy nó và đặt một câu hỏi về nó. Mỗi bước là một yêu cầu HTTP. Chọn ngôn ngữ của bạn một lần trong bất kỳ ví dụ nào; mọi ví dụ trên trang sẽ chuyển theo.

Các ví dụ có nút chọn ngôn ngữ dùng địa chỉ API của cổng này: https://api.sursa.com trên đám mây Sursa, hoặc địa chỉ API của bản cài đặt của bạn. Ở chỗ ví dụ ghi https://api.example.com, hãy thay bằng địa chỉ API của bạn. Xem Địa chỉ API và môi trường nếu bạn không chắc mình có địa chỉ nào.

1. Tạo khóa API

Quản trị viên của tổ chức tạo khóa trong Sursa tại Administration → API keys (Quản trị → Khóa API). Hãy đặt cho khóa một cái tên cho biết nó được dùng ở đâu (ví dụ “CRM sync”), chọn vai trò và, nếu muốn thu hẹp thêm, các phạm vi quyền của nó. Khóa làm được những gì người dùng có vai trò đó làm được, và không vượt quá những gì phạm vi quyền cho phép. Với hướng dẫn này, vai trò editor là đủ.

Khóa chỉ hiển thị một lần. Hãy giữ nó trong kho bí mật của hệ thống và truyền nó cho mã của bạn qua một biến môi trường:

export SURSA_API_KEY="kb_…"

Mọi yêu cầu đều gửi khóa trong header Authorization dưới dạng bearer token. Khóa API và phạm vi quyền giải thích vai trò, phạm vi quyền, thời hạn và việc xoay vòng khóa.

2. Thiết lập client

Không cần thư viện nào: API là HTTPS và JSON thuần. Các ví dụ trong hướng dẫn này dùng một hàm hỗ trợ nhỏ cho mỗi ngôn ngữ. Hãy sao chép hàm cho ngôn ngữ của bạn; các hướng dẫn sau dùng cùng hàm hỗ trợ đó. Các thư viện client chính thức được liệt kê trong mục SDK.

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

3. Kiểm tra khóa

GET /v1/me mô tả bên gọi: tổ chức, khóa, vai trò và phạm vi quyền của khóa, và giới hạn tốc độ áp dụng cho nó. Endpoint này hoạt động với mọi khóa hợp lệ, nên đây là yêu cầu đầu tiên tốt nhất cho mọi tích hợp.

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 với mã auth.not_authenticated nghĩa là khóa bị thiếu, đã bị thu hồi hoặc bị gõ sai; api_keys.expired nghĩa là khóa đã hết hạn.

4. Tìm bộ sưu tập

Thẻ nằm trong bộ sưu tập. GET /v1/collections liệt kê các bộ sưu tập mà khóa của bạn nhìn thấy:

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

Hãy ghi lại id và name của bộ sưu tập bạn muốn làm việc. Các ví dụ dưới đây dùng bộ sưu tập 3, có tên support.

5. Thêm tài liệu

PUT /v1/cards-by-external-id/{external_id} tạo một thẻ với ID của riêng bạn, hoặc thay thế nó nếu thẻ đã tồn tại. Chạy yêu cầu hai lần vẫn an toàn: ở lần thứ hai nội dung không thay đổi, và câu trả lời là skipped với lý do unchanged. Hãy dùng ID của bản ghi trong hệ thống của bạn làm 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."
  }'

Yêu cầu trả về khi thẻ đã sẵn sàng để được tìm thấy: 201 với "status": "ready" cho thẻ mới, 200 cho thẻ được thay thế. HTML và văn bản thuần hoạt động theo cùng cách với "content_type": "html" hoặc "text". Tệp (PDF, Word, Excel và các loại khác) đi qua cùng endpoint dưới dạng multipart/form-data; Nhập tài liệu trình bày về tệp, thư mục, siêu dữ liệu và việc nhập nhiều tài liệu.

POST /v1/search tìm các đoạn văn của thẻ khớp với truy vấn, kết quả khớp nhất trước:

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 nhận tên của bộ sưu tập. Khi không có tham số này, tìm kiếm bao quát bộ sưu tập có tên default.

7. Đặt câu hỏi

POST /v1/ask trả lời câu hỏi bằng ngôn ngữ tự nhiên và trả về các nguồn của câu trả lời. Trợ lý tìm tri thức cần thiết và chỉ trả lời dựa trên những thẻ mà khóa được phép đọc.

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

Khi không tìm thấy gì liên quan, phản hồi vẫn là 200, với "empty": "no_hits" và một lời giải thích ngắn trong answer. Mã của bạn quyết định hiển thị gì cho người dùng trong trường hợp đó.

Bước tiếp theo