Anar al contingut
Sursa Developers

Inici ràpid

Aquesta guia us porta de zero a una integració que funciona en cinc minuts: creeu una clau d’API, la comproveu, afegiu un document a la base de coneixement, el trobeu i hi feu una pregunta. Cada pas és una sola sol·licitud HTTP. Trieu el vostre llenguatge una vegada en qualsevol exemple; tots els exemples de la pàgina canvien alhora.

Els exemples amb selector de llenguatge fan servir l’adreça de l’API d’aquest portal: https://api.sursa.com al núvol de Sursa, o l’adreça de l’API de la vostra pròpia instal·lació. Quan un exemple mostri https://api.example.com, poseu-hi la vostra adreça de l’API. Si dubteu de quina és la vostra, vegeu Adreça de l’API i entorns.

1. Crear una clau d’API

Qui administra l’organització crea les claus a Sursa a Administration → API keys (administració, claus d’API). Doneu a la clau un nom que digui on es fa servir (per exemple, «CRM sync»), trieu-ne el rol i, si la voleu restringir més, els àmbits. La clau pot fer el que pot fer un usuari amb aquest rol, i res més enllà del que permeten els seus àmbits. Per a aquesta guia, n’hi ha prou amb el rol editor.

La clau es mostra una sola vegada. Deseu-la al magatzem de secrets del vostre sistema i passeu-la al vostre codi en una variable d’entorn:

export SURSA_API_KEY="kb_…"

Cada sol·licitud envia la clau a la capçalera Authorization com a token bearer. Claus d’API i àmbits explica els rols, els àmbits, la caducitat i la rotació.

2. Preparar un client

No cal cap biblioteca: l’API és HTTPS i JSON, sense res més. Els exemples d’aquesta guia fan servir una petita funció auxiliar en cada llenguatge. Copieu la del vostre llenguatge; les guies posteriors fan servir la mateixa funció. Les biblioteques de client oficials es llisten a SDK.

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

3. Comprovar la clau

GET /v1/me descriu qui fa la crida: l’organització, la clau, el seu rol i els seus àmbits, i el límit de freqüència que s’hi aplica. Funciona amb qualsevol clau vàlida, per això és la millor primera sol·licitud de qualsevol integració.

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 amb el codi auth.not_authenticated vol dir que falta la clau, que s’ha revocat o que està mal escrita; api_keys.expired vol dir que ha caducat.

4. Trobar una col·lecció

Les entrades són dins de col·leccions. GET /v1/collections enumera les col·leccions que pot veure la vostra clau:

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

Anoteu l’id i el name de la col·lecció amb què voleu treballar. Els exemples següents fan servir la col·lecció 3, amb el nom support.

5. Afegir un document

PUT /v1/cards-by-external-id/{external_id} crea una entrada amb el vostre propi ID, o la substitueix si l’entrada ja existeix. Executar la sol·licitud dues vegades no comporta cap risc: la segona vegada el contingut no ha canviat i la resposta és skipped amb el motiu unchanged. Feu servir com a external_id l’ID de l’element al vostre sistema.

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

La sol·licitud retorna quan l’entrada ja es pot trobar: 201 amb "status": "ready" per a una entrada nova, 200 per a una de substituïda. L’HTML i el text pla funcionen de la mateixa manera amb "content_type": "html" o "text". Els fitxers (PDF, Word, Excel i altres) passen pel mateix punt final com a multipart/form-data; Importar documents tracta els fitxers, les carpetes, les metadades i les importacions de molts documents.

POST /v1/search troba els extractes d’entrades que coincideixen amb una consulta, primer els que hi coincideixen més:

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 rep el nom de la col·lecció. Sense aquest paràmetre, la cerca abasta la col·lecció amb el nom default.

7. Fer una pregunta

POST /v1/ask respon una pregunta formulada en llenguatge planer i retorna les fonts de la resposta. L’assistent troba el coneixement necessari i només respon a partir de les entrades que la clau pot llegir.

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

Quan no es troba res rellevant, la resposta continua sent 200, amb "empty": "no_hits" i una explicació breu a answer. En aquest cas, el vostre codi decideix què es mostra a l’usuari.

Passos següents