Aller au contenu
Sursa Developers

Démarrage rapide

Ce guide vous mène de zéro à une intégration qui fonctionne en cinq minutes : vous créez une clé API, vous la vérifiez, vous ajoutez un document à la base de connaissances, vous le retrouvez et vous posez une question à son sujet. Chaque étape correspond à une requête HTTP. Choisissez votre langage une fois dans n’importe quel exemple : tous les exemples de la page basculent en même temps.

Les exemples dotés d’un sélecteur de langage utilisent l’adresse de l’API de ce portail : https://api.sursa.com dans le cloud Sursa, ou l’adresse de l’API de votre propre installation. Là où un exemple affiche https://api.example.com, remplacez-la par votre adresse de l’API. Consultez Adresse de l’API et environnements si vous ne savez pas laquelle est la vôtre.

1. Créer une clé API

Un administrateur de l’organisation crée les clés dans Sursa sous Administration → API keys. Donnez à la clé un nom qui indique où elle est utilisée (par exemple « CRM sync »), choisissez son rôle et, si vous souhaitez la restreindre davantage, ses portées. La clé peut faire ce que peut faire un utilisateur doté de ce rôle, et rien de plus que ce que ses portées autorisent. Pour ce guide, le rôle editor suffit.

La clé n’est affichée qu’une fois. Conservez-la dans le coffre de secrets de votre système et transmettez-la à votre code par une variable d’environnement :

export SURSA_API_KEY="kb_…"

Chaque requête envoie la clé dans l’en-tête Authorization sous forme de jeton Bearer. Clés API et portées explique les rôles, les portées, l’expiration et le renouvellement.

2. Préparer un client

Aucune bibliothèque n’est nécessaire : l’API repose simplement sur HTTPS et JSON. Les exemples de ce guide utilisent une petite fonction utilitaire dans chaque langage. Copiez celle de votre langage ; les guides suivants utilisent la même. Les bibliothèques clientes officielles sont répertoriées dans SDK.

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

3. Vérifier la clé

GET /v1/me décrit l’appelant : l’organisation, la clé, son rôle et ses portées, ainsi que la limite de débit qui s’y applique. Ce point de terminaison fonctionne avec toute clé valide : c’est donc la meilleure première requête de toute intégration.

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 avec le code auth.not_authenticated signifie que la clé est absente, révoquée ou mal saisie ; api_keys.expired signifie qu’elle a expiré.

4. Trouver une collection

Les fiches se trouvent dans des collections. GET /v1/collections liste les collections que votre clé peut voir :

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

Notez l'id et le name de la collection avec laquelle vous voulez travailler. Les exemples ci-dessous utilisent la collection 3, nommée support.

5. Ajouter un document

PUT /v1/cards-by-external-id/{external_id} crée une fiche sous votre propre identifiant, ou la remplace si elle existe déjà. Exécuter la requête deux fois est sans risque : la seconde fois, le contenu n’a pas changé et la réponse est skipped avec le motif unchanged. Utilisez comme external_id l’identifiant de l’enregistrement dans votre système.

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 requête répond quand la fiche est prête à être trouvée : 201 avec "status": "ready" pour une nouvelle fiche, 200 pour une fiche remplacée. Le HTML et le texte brut fonctionnent de la même façon avec "content_type": "html" ou "text". Les fichiers (PDF, Word, Excel et autres) passent par le même point de terminaison en multipart/form-data ; Importer des documents traite des fichiers, des dossiers, des métadonnées et des imports de nombreux documents.

POST /v1/search trouve les extraits de fiches qui correspondent à une requête, du meilleur résultat au moins bon :

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 prend le nom de la collection. Sans ce paramètre, la recherche porte sur la collection nommée default.

7. Poser une question

POST /v1/ask répond à une question formulée en langage courant et renvoie les sources de la réponse. L’assistant trouve les connaissances utiles et ne répond qu’à partir des fiches que la clé a le droit de lire.

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

Quand rien de pertinent n’est trouvé, la réponse reste 200, avec "empty": "no_hits" et une courte explication dans answer. C’est à votre code de décider ce qu’il affiche alors à l’utilisateur.

Étapes suivantes