Siirry sisältöön
Sursa Developers

Pika-aloitus

Tämä opas vie sinut tyhjästä toimivaan integraatioon viidessä minuutissa: luot API-avaimen, tarkistat sen, lisäät asiakirjan tietopankkiin, löydät sen ja kysyt siitä kysymyksen. Jokainen vaihe on yksi HTTP-pyyntö. Valitse kielesi kerran missä tahansa esimerkissä; sivun kaikki esimerkit vaihtuvat sen mukaan.

Kielivalitsimella varustetut esimerkit käyttävät tämän portaalin API-osoitetta: Sursan pilvessä https://api.sursa.com tai oman asennuksesi API-osoitetta. Kun esimerkissä näkyy https://api.example.com, korvaa se omalla API-osoitteellasi. Jos et ole varma, mikä osoitteesi on, katso API-osoite ja ympäristöt.

1. Luo API-avain

Organisaation ylläpitäjä luo avaimia Sursassa kohdassa Administration → API keys (ylläpito → API-avaimet). Anna avaimelle nimi, joka kertoo, missä sitä käytetään (esimerkiksi ”CRM sync”), valitse sen rooli ja, jos haluat rajata sitä lisää, sen käyttöalueet. Avain voi tehdä sen, minkä tämän roolin käyttäjäkin, eikä enempää kuin sen käyttöalueet sallivat. Tähän oppaaseen riittää rooli editor.

Avain näytetään kerran. Säilytä se järjestelmäsi salaisuusvarastossa ja välitä se koodillesi ympäristömuuttujassa:

export SURSA_API_KEY="kb_…"

Jokainen pyyntö lähettää avaimen Authorization-otsakkeessa bearer-tunnuksena. API-avaimet ja käyttöalueet selittää roolit, käyttöalueet, vanhenemisen ja uusimisen.

2. Määritä asiakasohjelma

Kirjastoa ei tarvita: API käyttää pelkkää HTTPS:ää ja JSON-muotoa. Tämän oppaan esimerkit käyttävät jokaisessa kielessä pientä apufunktiota. Kopioi oman kielesi versio; myöhemmät oppaat käyttävät samaa apufunktiota. Viralliset asiakaskirjastot on lueteltu sivulla SDK:t.

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

3. Tarkista avain

GET /v1/me kuvaa kutsujan: organisaation, avaimen, sen roolin ja käyttöalueet sekä siihen sovellettavan nopeusrajoituksen. Se toimii millä tahansa kelvollisella avaimella, joten se on paras ensimmäinen pyyntö jokaiselle integraatiolle.

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-vastaus koodilla auth.not_authenticated tarkoittaa, että avain puuttuu, on peruttu tai on kirjoitettu väärin; api_keys.expired tarkoittaa, että avaimen voimassaolo on päättynyt.

4. Etsi kokoelma

Kortit ovat kokoelmissa. GET /v1/collections listaa kokoelmat, jotka avaimesi näkee:

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

Merkitse muistiin sen kokoelman id ja name, jonka kanssa haluat työskennellä. Alla olevat esimerkit käyttävät kokoelmaa 3, jonka nimi on support.

5. Lisää asiakirja

PUT /v1/cards-by-external-id/{external_id} luo kortin omalla tunnuksellasi tai korvaa sen, jos kortti on jo olemassa. Pyynnön suorittaminen kahdesti on turvallista: toisella kerralla sisältö ei ole muuttunut, ja vastaus on skipped syyllä unchanged. Käytä external_id-arvona järjestelmäsi tietueen tunnusta.

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

Pyyntö palaa, kun kortti on valmis löydettäväksi: uudelle kortille 201 ja "status": "ready", korvatulle 200. HTML ja pelkkä teksti toimivat samalla tavalla arvoilla "content_type": "html" tai "text". Tiedostot (PDF, Word, Excel ja muut) kulkevat saman päätepisteen kautta multipart/form-data-muodossa; Asiakirjojen tuonti käsittelee tiedostot, kansiot, metatiedot ja monen asiakirjan tuonnit.

POST /v1/search löytää korttien tekstikatkelmat, jotka vastaavat kyselyä, paras osuma ensin:

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 ottaa kokoelman nimen. Ilman sitä haku kattaa kokoelman, jonka nimi on default.

7. Esitä kysymys

POST /v1/ask vastaa arkikielellä esitettyyn kysymykseen ja palauttaa vastauksen lähteet. Avustaja löytää tarvittavan tiedon ja vastaa vain korteista, joita avain saa lukea.

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

Kun mitään olennaista ei löydy, vastaus on silti 200, ja siinä on "empty": "no_hits" sekä lyhyt selitys answer-kentässä. Koodisi päättää, mitä käyttäjälle tällöin näytetään.

Seuraavat vaiheet