Salt la conținut
Sursa Developers

Pornire rapidă

Acest ghid vă duce de la zero la o integrare funcțională în cinci minute: creați o cheie API, o verificați, adăugați un document în baza de cunoștințe, îl găsiți și puneți o întrebare despre el. Fiecare pas este o singură cerere HTTP. Alegeți limbajul o singură dată, în oricare exemplu; toate exemplele de pe pagină se schimbă odată cu el.

Exemplele cu selector de limbaj folosesc adresa API a acestui portal: https://api.sursa.com în cloudul Sursa sau adresa API a propriei instalări. Acolo unde un exemplu arată https://api.example.com, puneți în locul ei adresa API. Vedeți Adresa API și mediile dacă nu știți sigur care este adresa dumneavoastră.

1. Creați o cheie API

Un administrator al organizației creează chei în Sursa, în Administration → API keys (administrare → chei API). Dați cheii un nume care spune unde este folosită (de exemplu „Sincronizare CRM”), alegeți-i rolul și, dacă vreți să o restrângeți și mai mult, domeniile de acces. Cheia poate face ce poate face un utilizator cu acel rol și nimic peste ce permit domeniile ei. Pentru acest ghid, rolul editor este suficient.

Cheia este afișată o singură dată. Păstrați-o în managerul de secrete al sistemului și transmiteți-o codului printr-o variabilă de mediu:

export SURSA_API_KEY="kb_…"

Fiecare cerere trimite cheia în antetul Authorization, ca token Bearer. Chei API și domenii de acces explică rolurile, domeniile de acces, expirarea și reînnoirea.

2. Configurați un client

Nu este nevoie de nicio bibliotecă: API-ul înseamnă simplu HTTPS și JSON. Exemplele din acest ghid folosesc o mică funcție ajutătoare în fiecare limbaj. Copiați-o pe cea pentru limbajul dumneavoastră; ghidurile următoare folosesc aceeași funcție. Bibliotecile client oficiale sunt enumerate la SDK-uri.

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

3. Verificați cheia

GET /v1/me descrie apelantul: organizația, cheia, rolul și domeniile ei de acces, precum și limita de frecvență care i se aplică. Funcționează cu orice cheie validă, așa că este cea mai bună primă cerere a oricărei integrări.

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

Un 401 cu codul auth.not_authenticated înseamnă că cheia lipsește, a fost revocată sau este scrisă greșit; api_keys.expired înseamnă că a expirat.

4. Găsiți o colecție

Fișele se află în colecții. GET /v1/collections enumeră colecțiile pe care cheia le poate vedea:

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

Notați id și name ale colecției cu care vreți să lucrați. Exemplele de mai jos folosesc colecția 3, numită support.

5. Adăugați un document

PUT /v1/cards-by-external-id/{external_id} creează o fișă cu identificatorul dumneavoastră sau o înlocuiește dacă fișa există deja. Executarea cererii de două ori este sigură: a doua oară conținutul nu s-a schimbat, iar răspunsul este skipped cu motivul unchanged. Folosiți ca external_id identificatorul înregistrării din sistemul propriu.

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

Cererea se încheie când fișa este gata să fie găsită: 201 cu "status": "ready" pentru o fișă nouă, 200 pentru una înlocuită. HTML-ul și textul simplu funcționează la fel, cu "content_type": "html" sau "text". Fișierele (PDF, Word, Excel și altele) trec prin același endpoint ca multipart/form-data; Importați documente tratează fișierele, dosarele, metadatele și importurile multor documente.

POST /v1/search găsește pasajele din fișe care corespund unei interogări, cele mai potrivite primele:

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 primește numele colecției. Fără el, căutarea se face în colecția numită default.

7. Puneți o întrebare

POST /v1/ask răspunde la o întrebare formulată în limbaj obișnuit și returnează sursele răspunsului. Asistentul găsește cunoștințele necesare și răspunde doar pe baza fișelor pe care cheia are voie să le citească.

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

Când nu se găsește nimic relevant, răspunsul este tot 200, cu "empty": "no_hits" și o scurtă explicație în answer. Codul dumneavoastră decide ce îi arată utilizatorului în acest caz.

Pașii următori