Vai al contenuto
Sursa Developers

Avvio rapido

Questa guida ti porta da zero a un’integrazione funzionante in cinque minuti: crei una chiave API, la verifichi, aggiungi un documento alla knowledge base, lo trovi e fai una domanda sul suo contenuto. Ogni passaggio è una sola richiesta HTTP. Scegli il tuo linguaggio una volta in un esempio qualsiasi: tutti gli esempi della pagina passano a quel linguaggio.

Gli esempi con il selettore del linguaggio usano l’indirizzo dell’API di questo portale: https://api.sursa.com nel cloud di Sursa, oppure l’indirizzo dell’API della tua installazione. Dove un esempio mostra https://api.example.com, sostituiscilo con il tuo indirizzo dell’API. Se non sai quale hai, consulta Indirizzo dell’API e ambienti.

1. Creare una chiave API

Un amministratore dell’organizzazione crea le chiavi in Sursa in Administration → API keys (amministrazione, chiavi API). Dai alla chiave un nome che dica dove viene usata (per esempio “CRM sync”), scegli il suo ruolo e, se vuoi restringerla ulteriormente, i suoi ambiti. La chiave può fare ciò che può fare un utente con quel ruolo, e non più di quanto consentono i suoi ambiti. Per questa guida basta il ruolo editor.

La chiave viene mostrata una sola volta. Conservala nell’archivio dei segreti del tuo sistema e passala al codice in una variabile d’ambiente:

export SURSA_API_KEY="kb_…"

Ogni richiesta invia la chiave nell’intestazione Authorization come token bearer. Chiavi API e ambiti spiega ruoli, ambiti, scadenza e rotazione.

2. Preparare un client

Non serve nessuna libreria: l’API è semplice HTTPS e JSON. Gli esempi di questa guida usano una piccola funzione di supporto in ogni linguaggio. Copia quella del tuo linguaggio; le guide successive usano la stessa. Le librerie client ufficiali sono elencate nella pagina SDK.

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

3. Verificare la chiave

GET /v1/me descrive chi effettua la chiamata: l’organizzazione, la chiave, il suo ruolo e i suoi ambiti, e il limite di frequenza che le si applica. Funziona con qualsiasi chiave valida, quindi è la prima richiesta ideale di ogni integrazione.

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 con il codice auth.not_authenticated significa che la chiave manca, è stata revocata o è scritta in modo errato; api_keys.expired significa che è scaduta.

4. Trovare una raccolta

Le schede si trovano nelle raccolte. GET /v1/collections elenca le raccolte che la tua chiave può vedere:

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

Annota l’id e il name della raccolta con cui vuoi lavorare. Gli esempi seguenti usano la raccolta 3, con il nome support.

5. Aggiungere un documento

PUT /v1/cards-by-external-id/{external_id} crea una scheda con il tuo ID, oppure la sostituisce se la scheda esiste già. Eseguire la richiesta due volte è sicuro: la seconda volta il contenuto non è cambiato e la risposta è skipped con il motivo unchanged. Usa come external_id l’ID del record nel tuo 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 richiesta risponde quando la scheda è pronta per essere trovata: 201 con "status": "ready" per una scheda nuova, 200 per una sostituita. HTML e testo semplice funzionano allo stesso modo con "content_type": "html" o "text". I file (PDF, Word, Excel e altri) passano dallo stesso endpoint come multipart/form-data; Importare documenti tratta file, cartelle, metadati e importazioni di molti documenti.

POST /v1/search trova gli estratti delle schede che corrispondono a una query, a partire dal risultato migliore:

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 accetta il nome della raccolta. Senza questo parametro, la ricerca riguarda la raccolta con il nome default.

7. Fare una domanda

POST /v1/ask risponde a una domanda in linguaggio naturale e restituisce le fonti della risposta. L’assistente trova le conoscenze pertinenti e risponde solo in base alle schede che la chiave può leggere.

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

Quando non trova nulla di pertinente, la risposta è comunque 200, con "empty": "no_hits" e una breve spiegazione in answer. In quel caso è il tuo codice a decidere cosa mostrare all’utente.

Passaggi successivi