Ir al contenido
Sursa Developers

Inicio rápido

Esta guía le lleva de cero a una integración que funciona en cinco minutos: creará una clave de API, la comprobará, añadirá un documento a la base de conocimiento, lo encontrará y hará una pregunta sobre él. Cada paso es una solicitud HTTP. Elija su lenguaje una vez en cualquier ejemplo; todos los ejemplos de la página cambian con él.

Los ejemplos con selector de lenguaje usan la dirección de la API de este portal: https://api.sursa.com en la nube de Sursa o la dirección de la API de su propia instalación. Donde un ejemplo muestra https://api.example.com, ponga en su lugar su dirección de la API. Consulte Dirección de la API y entornos si no está seguro de cuál tiene.

1. Crear una clave de API

Un administrador de la organización crea las claves en Sursa, en Administration → API keys (administración, claves de API). Dé a la clave un nombre que indique dónde se usa (por ejemplo, «CRM sync»), elija su rol y, si quiere restringirla más, sus ámbitos. La clave puede hacer lo que puede hacer un usuario con ese rol, y no más de lo que permiten sus ámbitos. Para esta guía basta con el rol editor.

La clave se muestra una sola vez. Guárdela en el almacén de secretos de su sistema y pásela a su código en una variable de entorno:

export SURSA_API_KEY="kb_…"

Cada solicitud envía la clave en el encabezado Authorization como token bearer. Claves de API y ámbitos explica los roles, los ámbitos, la caducidad y la rotación.

2. Preparar un cliente

No hace falta ninguna biblioteca: la API es HTTPS y JSON sin más. Los ejemplos de esta guía usan una pequeña función auxiliar en cada lenguaje. Copie la de su lenguaje; las guías posteriores usan la misma. Las bibliotecas cliente oficiales se enumeran en SDK.

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

3. Comprobar la clave

GET /v1/me describe a quien llama a la API: la organización, la clave, su rol y sus ámbitos, y el límite de frecuencia que se le aplica. Funciona con cualquier clave válida, así que es la mejor primera solicitud de cualquier integración.

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 el código auth.not_authenticated significa que falta la clave, que se ha revocado o que está mal escrita; api_keys.expired significa que ha caducado.

4. Encontrar una colección

Las tarjetas están en colecciones. GET /v1/collections enumera las colecciones que puede ver su clave:

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

Anote el id y el name de la colección con la que quiere trabajar. Los ejemplos siguientes usan la colección 3, llamada support.

5. Añadir un documento

PUT /v1/cards-by-external-id/{external_id} crea una tarjeta con su propio ID o la sustituye si la tarjeta ya existe. Ejecutar la solicitud dos veces no supone ningún riesgo: la segunda vez el contenido no ha cambiado y la respuesta es skipped con el motivo unchanged. Use como external_id el ID del registro en su 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 solicitud responde cuando la tarjeta ya se puede encontrar: 201 con "status": "ready" para una tarjeta nueva, 200 para una sustituida. HTML y texto sin formato funcionan igual, con "content_type": "html" o "text". Los archivos (PDF, Word, Excel y otros) pasan por el mismo endpoint como multipart/form-data; Importar documentos trata los archivos, las carpetas, los metadatos y las importaciones de muchos documentos.

POST /v1/search encuentra los extractos de tarjetas que coinciden con una consulta, empezando por la mejor coincidencia:

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 recibe el nombre de la colección. Sin él, la búsqueda abarca la colección llamada default.

7. Hacer una pregunta

POST /v1/ask responde a una pregunta en lenguaje natural y devuelve las fuentes de la respuesta. El asistente encuentra el conocimiento necesario y responde solo a partir de las tarjetas que la clave puede leer.

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

Cuando no se encuentra nada pertinente, la respuesta sigue siendo 200, con "empty": "no_hits" y una breve explicación en answer. Su código decide qué mostrar al usuario en ese caso.

Próximos pasos