Langsung ke konten
Sursa Developers

Mulai cepat

Panduan ini membawa Anda dari nol hingga integrasi yang berfungsi dalam lima menit: Anda membuat kunci API, memeriksanya, menambahkan dokumen ke basis pengetahuan, menemukannya, dan mengajukan pertanyaan tentangnya. Setiap langkah adalah satu permintaan HTTP. Pilih bahasa pemrograman Anda sekali di contoh mana pun; semua contoh di halaman ikut beralih.

Contoh dengan pengalih bahasa memakai alamat API portal ini: https://api.sursa.com di cloud Sursa, atau alamat API instalasi Anda sendiri. Jika contoh menampilkan https://api.example.com, ganti dengan alamat API Anda. Lihat Alamat API dan lingkungan jika Anda tidak yakin alamat mana yang Anda miliki.

1. Buat kunci API

Administrator organisasi membuat kunci di Sursa melalui Administration → API keys (Administrasi → Kunci API). Beri kunci nama yang menjelaskan tempat pemakaiannya (misalnya “CRM sync”), pilih perannya dan, jika Anda ingin mempersempitnya lebih jauh, cakupannya. Kunci dapat melakukan apa yang dapat dilakukan pengguna dengan peran itu, dan tidak lebih dari yang diizinkan cakupannya. Untuk panduan ini, peran editor sudah cukup.

Kunci ditampilkan sekali. Simpan kunci di penyimpanan rahasia sistem Anda dan berikan ke kode Anda melalui variabel lingkungan:

export SURSA_API_KEY="kb_…"

Setiap permintaan mengirim kunci di header Authorization sebagai token bearer. Kunci API dan cakupan menjelaskan peran, cakupan, kedaluwarsa, dan rotasi.

2. Siapkan klien

Tidak perlu pustaka: API ini hanyalah HTTPS dan JSON biasa. Contoh dalam panduan ini memakai fungsi bantu kecil di setiap bahasa. Salin fungsi untuk bahasa Anda; panduan berikutnya memakai fungsi bantu yang sama. Pustaka klien resmi tercantum di SDK.

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

3. Periksa kunci

GET /v1/me menjelaskan pemanggil: organisasi, kunci, peran dan cakupannya, serta batas laju yang berlaku untuknya. Endpoint ini berfungsi dengan kunci valid apa pun, jadi inilah permintaan pertama terbaik untuk setiap integrasi.

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 dengan kode auth.not_authenticated berarti kunci tidak ada, sudah dicabut, atau salah ketik; api_keys.expired berarti kunci sudah kedaluwarsa.

4. Temukan koleksi

Kartu berada di dalam koleksi. GET /v1/collections mencantumkan koleksi yang dapat dilihat kunci Anda:

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

Catat id dan name koleksi yang ingin Anda pakai. Contoh di bawah memakai koleksi 3, yang bernama support.

5. Tambahkan dokumen

PUT /v1/cards-by-external-id/{external_id} membuat kartu dengan ID Anda sendiri, atau menggantinya jika kartu sudah ada. Menjalankan permintaan dua kali aman: pada kali kedua kontennya tidak berubah, dan jawabannya adalah skipped dengan alasan unchanged. Pakai ID catatan di sistem Anda sebagai 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."
  }'

Permintaan kembali saat kartu siap ditemukan: 201 dengan "status": "ready" untuk kartu baru, 200 untuk kartu yang diganti. HTML dan teks biasa bekerja dengan cara yang sama dengan "content_type": "html" atau "text". File (PDF, Word, Excel, dan lainnya) melalui endpoint yang sama sebagai multipart/form-data; Mengimpor dokumen membahas file, folder, metadata, dan impor banyak dokumen.

POST /v1/search menemukan petikan kartu yang cocok dengan kueri, dengan kecocokan terbaik lebih dulu:

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 menerima nama koleksi. Tanpa parameter itu, pencarian mencakup koleksi yang bernama default.

7. Ajukan pertanyaan

POST /v1/ask menjawab pertanyaan dalam bahasa sehari-hari dan mengembalikan sumber jawabannya. Asisten menemukan pengetahuan yang relevan dan hanya menjawab dari kartu yang boleh dibaca oleh kunci.

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

Jika tidak ada yang relevan ditemukan, responsnya tetap 200, dengan "empty": "no_hits" dan penjelasan singkat di answer. Kode Anda yang menentukan apa yang ditampilkan kepada pengguna dalam kasus itu.

Langkah berikutnya