Pāriet uz saturu
Sursa Developers

Ātrā sākšana

Šis ceļvedis piecās minūtēs ved jūs no nulles līdz strādājošai integrācijai: jūs izveidojat API atslēgu, pārbaudāt to, pievienojat zināšanu bāzei dokumentu, atrodat to un uzdodat par to jautājumu. Katrs solis ir viens HTTP pieprasījums. Izvēlieties savu valodu vienreiz jebkurā piemērā – līdz ar to pārslēgsies visi lapas piemēri.

Piemēri ar valodas pārslēgu izmanto šī portāla API adresi: https://api.sursa.com Sursas mākonī vai jūsu instalācijas API adresi. Kur piemērā redzams https://api.example.com, ierakstiet tā vietā savu API adresi. Ja neesat pārliecināti, kura adrese ir jums, sk. API adrese un vides.

1. Izveidojiet API atslēgu

Organizācijas administrators izveido atslēgas Sursā sadaļā Administration → API keys (administrēšana, API atslēgas). Piešķiriet atslēgai nosaukumu, kas pasaka, kur tā tiek izmantota (piemēram, „CRM sinhronizācija“), izvēlieties tās lomu un, ja vēlaties to vēl vairāk sašaurināt, tvērumus. Atslēga var darīt to, ko var lietotājs ar šo lomu, un ne vairāk, kā atļauj tās tvērumi. Šim ceļvedim pietiek ar lomu editor.

Atslēga tiek parādīta vienreiz. Glabājiet to savas sistēmas noslēpumu krātuvē un nododiet to kodam vides mainīgajā:

export SURSA_API_KEY="kb_…"

Katrs pieprasījums sūta atslēgu galvenē Authorization kā Bearer marķieri. Ceļvedī API atslēgas un tvērumi ir izskaidrotas lomas, tvērumi, derīguma termiņš un rotācija.

2. Sagatavojiet klientu

Bibliotēka nav vajadzīga: API ir vienkāršs HTTPS un JSON. Šī ceļveža piemēri katrā valodā izmanto nelielu palīgfunkciju. Nokopējiet savas valodas palīgfunkciju; nākamie ceļveži izmanto to pašu. Oficiālās klientu bibliotēkas ir uzskaitītas sadaļā SDK.

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

3. Pārbaudiet atslēgu

GET /v1/me apraksta izsaucēju: organizāciju, atslēgu, tās lomu un tvērumus, kā arī tai piemērojamo pieprasījumu biežuma limitu. Operācija darbojas ar jebkuru derīgu atslēgu, tāpēc tas ir labākais pirmais pieprasījums jebkurai integrācijai.

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 ar kodu auth.not_authenticated nozīmē, ka atslēgas nav, tā ir atsaukta vai ievadīta kļūdaini; api_keys.expired nozīmē, ka tās derīguma termiņš ir beidzies.

4. Atrodiet kolekciju

Kartītes atrodas kolekcijās. GET /v1/collections uzskaita kolekcijas, kuras jūsu atslēga var redzēt:

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

Pierakstiet tās kolekcijas id un name, ar kuru vēlaties strādāt. Tālākie piemēri izmanto kolekciju 3 ar nosaukumu support.

5. Pievienojiet dokumentu

PUT /v1/cards-by-external-id/{external_id} izveido kartīti ar jūsu pašu ID vai aizstāj to, ja kartīte jau eksistē. Pieprasījumu var droši izpildīt divreiz: otrajā reizē saturs nav mainījies, un atbilde ir skipped ar iemeslu unchanged. Kā external_id izmantojiet ieraksta ID savā sistēmā.

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

Pieprasījums atgriež atbildi, kad kartīti jau var atrast: 201 ar "status": "ready" jaunai kartītei, 200 – aizstātai. HTML un vienkāršs teksts darbojas tāpat ar "content_type": "html" vai "text". Faili (PDF, Word, Excel un citi) tiek sūtīti caur to pašu operāciju kā multipart/form-data; ceļvedī Dokumentu imports aprakstīti faili, mapes, metadati un daudzu dokumentu imports.

POST /v1/search atrod kartīšu izvilkumus, kas atbilst vaicājumam, sākot ar visatbilstošāko:

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 pieņem kolekcijas nosaukumu. Bez tā meklēšana aptver kolekciju ar nosaukumu default.

7. Uzdodiet jautājumu

POST /v1/ask atbild uz jautājumu, kas uzdots vienkāršā valodā, un atgriež atbildes avotus. Asistents atrod vajadzīgās zināšanas un atbild tikai no kartītēm, kuras atslēgai ir atļauts lasīt.

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

Ja nekas atbilstošs netiek atrasts, atbilde joprojām ir 200 ar "empty": "no_hits" un īsu skaidrojumu laukā answer. Ko šādā gadījumā rādīt lietotājam, izlemj jūsu kods.

Tālākie soļi