İçeriğe geç
Sursa Developers

Hızlı başlangıç

Bu kılavuz sizi beş dakikada sıfırdan çalışan bir entegrasyona götürür: bir API anahtarı oluşturur, onu kontrol eder, bilgi tabanına bir belge ekler, belgeyi bulur ve onunla ilgili bir soru sorarsınız. Her adım tek bir HTTP isteğidir. Dilinizi herhangi bir örnekte bir kez seçin; sayfadaki tüm örnekler onunla birlikte değişir.

Dil seçicili örnekler bu portalın API adresini kullanır: Sursa bulutunda https://api.sursa.com, kendi kurulumunuzda ise kurulumunuzun API adresi. Bir örnekte https://api.example.com görünüyorsa onun yerine kendi API adresinizi yazın. Hangi adrese sahip olduğunuzdan emin değilseniz API adresi ve ortamlar sayfasına bakın.

1. API anahtarı oluşturun

Kuruluş yöneticisi anahtarları Sursa’da Administration → API keys (yönetim → API anahtarları) bölümünde oluşturur. Anahtara nerede kullanıldığını belirten bir ad verin (örneğin “CRM sync”), rolünü ve daha da daraltmak isterseniz kapsamlarını seçin. Anahtar, bu role sahip bir kullanıcının yapabildiklerini yapabilir, ancak kapsamlarının izin verdiğinden fazlasını yapamaz. Bu kılavuz için editor rolü yeterlidir.

Anahtar bir kez gösterilir. Onu sisteminizin gizli değer deposunda saklayın ve kodunuza bir ortam değişkeniyle iletin:

export SURSA_API_KEY="kb_…"

Her istek anahtarı Authorization başlığında bearer belirteci olarak gönderir. API anahtarları ve kapsamlar sayfası rolleri, kapsamları, sona ermeyi ve yenilemeyi açıklar.

2. İstemciyi hazırlayın

Hiçbir kütüphane gerekmez: API düz HTTPS ve JSON’dur. Bu kılavuzdaki örnekler her dilde küçük bir yardımcı kullanır. Kendi dilinize ait olanı kopyalayın; sonraki kılavuzlar da aynı yardımcıyı kullanır. Resmî istemci kütüphaneleri SDK’lar sayfasında listelenir.

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

3. Anahtarı kontrol edin

GET /v1/me çağıranı tanımlar: kuruluşu, anahtarı, anahtarın rolünü ve kapsamlarını ve anahtar için geçerli hız sınırını. Her geçerli anahtarla çalışır, bu yüzden her entegrasyon için en iyi ilk istektir.

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

auth.not_authenticated kodlu bir 401 yanıtı anahtarın eksik, iptal edilmiş ya da yanlış yazılmış olduğunu; api_keys.expired ise süresinin dolduğunu gösterir.

4. Bir koleksiyon bulun

Kartlar koleksiyonlarda bulunur. GET /v1/collections anahtarınızın erişebildiği koleksiyonları listeler:

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

Üzerinde çalışmak istediğiniz koleksiyonun id ve name değerlerini not edin. Aşağıdaki örnekler, adı support olan 3 numaralı koleksiyonu kullanır.

5. Bir belge ekleyin

PUT /v1/cards-by-external-id/{external_id} kendi kimliğiniz altında bir kart oluşturur ya da kart zaten varsa onu değiştirir. İsteği iki kez çalıştırmak güvenlidir: ikinci seferde içerik değişmemiştir ve yanıt, unchanged nedeniyle skipped olur. external_id olarak sisteminizdeki kaydın kimliğini kullanın.

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

İstek, kart bulunmaya hazır olduğunda yanıt döner: yeni bir kart için "status": "ready" ile 201, değiştirilen bir kart için 200. HTML ve düz metin de "content_type": "html" ya da "text" ile aynı şekilde çalışır. Dosyalar (PDF, Word, Excel ve diğerleri) aynı uç noktaya multipart/form-data olarak gönderilir; Belgeleri içe aktarma kılavuzu dosyaları, klasörleri, meta verileri ve çok sayıda belgenin içe aktarılmasını anlatır.

POST /v1/search bir sorguyla eşleşen kart pasajlarını, en iyi eşleşme önce gelecek şekilde bulur:

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 koleksiyonun adını alır. Bu parametre olmadan arama, adı default olan koleksiyonda yapılır.

7. Bir soru sorun

POST /v1/ask günlük dilde sorulan bir soruyu yanıtlar ve yanıtın kaynaklarını döndürür. Asistan ilgili bilgiyi bulur ve yalnızca anahtarın okumasına izin verilen kartlara dayanarak yanıt verir.

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

İlgili hiçbir şey bulunamadığında yanıt yine 200 olur; "empty": "no_hits" ve answer alanında kısa bir açıklama içerir. Bu durumda kullanıcıya ne gösterileceğine kodunuz karar verir.

Sonraki adımlar