Pular para o conteúdo
Sursa Developers

Início rápido

Este guia leva você do zero a uma integração funcionando em cinco minutos: você cria uma chave de API, verifica a chave, adiciona um documento à base de conhecimento, encontra esse documento e faz uma pergunta sobre ele. Cada passo é uma requisição HTTP. Escolha a sua linguagem uma vez em qualquer exemplo; todos os exemplos da página mudam junto.

Os exemplos com seletor de linguagem usam o endereço da API deste portal: https://api.sursa.com na nuvem do Sursa ou o endereço da API da sua própria instalação. Onde um exemplo mostrar https://api.example.com, coloque o seu endereço da API no lugar. Veja Endereço da API e ambientes se não tiver certeza de qual é o seu.

1. Criar uma chave de API

Um administrador da organização cria chaves no Sursa em Administration → API keys (administração, chaves de API). Dê à chave um nome que diga onde ela é usada (por exemplo, “Sincronização do CRM”), escolha a função dela e, se quiser restringi-la ainda mais, os escopos. A chave pode fazer o que um usuário com essa função pode fazer, e nada além do que os escopos dela permitem. Para este guia, a função editor basta.

A chave é mostrada uma única vez. Guarde-a no cofre de segredos do seu sistema e passe-a para o seu código em uma variável de ambiente:

export SURSA_API_KEY="kb_…"

Toda requisição envia a chave no cabeçalho Authorization como token bearer. Chaves de API e escopos explica as funções, os escopos, a expiração e a rotação.

2. Configurar um cliente

Nenhuma biblioteca é necessária: a API é HTTPS e JSON simples. Os exemplos deste guia usam uma pequena função auxiliar em cada linguagem. Copie a da sua linguagem; os guias seguintes usam a mesma função auxiliar. As bibliotecas de cliente oficiais estão listadas em SDKs.

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

3. Verificar a chave

GET /v1/me descreve quem faz a chamada: a organização, a chave, a função e os escopos dela e o limite de taxa que se aplica a ela. Ele funciona com qualquer chave válida, por isso é a melhor primeira requisição de qualquer integração.

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

Um 401 com o código auth.not_authenticated significa que a chave está ausente, foi revogada ou foi digitada errado; api_keys.expired significa que ela expirou.

4. Encontrar uma coleção

Os cartões ficam em coleções. GET /v1/collections lista as coleções que a sua chave pode ver:

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

Anote o id e o name da coleção com que você quer trabalhar. Os exemplos abaixo usam a coleção 3, chamada support.

5. Adicionar um documento

PUT /v1/cards-by-external-id/{external_id} cria um cartão com o seu próprio ID ou o substitui, se o cartão já existir. Executar a requisição duas vezes é seguro: na segunda vez, o conteúdo não mudou, e a resposta é skipped com o motivo unchanged. Use como external_id o ID do registro no seu 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."
  }'

A requisição retorna quando o cartão já pode ser encontrado: 201 com "status": "ready" para um cartão novo, 200 para um cartão substituído. HTML e texto simples funcionam da mesma forma com "content_type": "html" ou "text". Os arquivos (PDF, Word, Excel e outros) passam pelo mesmo endpoint como multipart/form-data; Importar documentos trata de arquivos, pastas, metadados e importações de muitos documentos.

POST /v1/search encontra os trechos de cartões que correspondem a uma consulta, com a melhor correspondência primeiro:

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 recebe o nome da coleção. Sem ele, a busca abrange a coleção chamada default.

7. Fazer uma pergunta

POST /v1/ask responde a uma pergunta em linguagem natural e retorna as fontes da resposta. O assistente encontra o conhecimento relevante e responde só com base nos cartões que a chave tem permissão para ler.

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 nada relevante é encontrado, a resposta continua sendo 200, com "empty": "no_hits" e uma explicação curta em answer. O seu código decide o que mostrar ao usuário nesse caso.

Próximos passos