Introdução à Integração

A plataforma SipPulse AI possui uma REST API projetada para ser o ponto central de comunicação com todos os seus recursos de Inteligência Artificial. Esta API permite que desenvolvedores interajam e integrem programaticamente serviços como modelos de geração de texto (LLMs), reconhecimento de fala (ASR), conversão de texto para fala (TTS) e agentes inteligentes diretamente em suas aplicações.

Para auxiliar na utilização da API, disponibilizamos um Swagger UI e um arquivo OpenAPI.json.

Requisitos

Para começar a integração, você precisará:

• Chave API: Gere uma chave API na seção API Keys da sua conta SipPulse AI. Instruções para criar API Keys
• Conhecimentos em programação: Familiaridade com HTTP requests e manipulação de dados JSON.

Cada seção desta documentação fornecerá exemplos de código em diferentes linguagens de programação para facilitar a integração com nossos serviços.

Autenticação

Para utilizar os serviços da plataforma SipPulse AI, todas as requisições devem ser autenticadas usando uma chave API. Para gerar uma chave API, siga as instruções na seção API Keys da documentação.

Usando a Chave API

Todas as requisições para a plataforma SipPulse AI devem incluir a chave API no cabeçalho da requisição. O cabeçalho utilizado é api-key. Abaixo estão exemplos de como incluir a chave API em requisições utilizando diferentes linguagens de programação.

cURL

curl -X 'GET' \
  'https://api.sippulse.ai/v1/llms/models' \
  -H 'Content-Type: application/json' \
  -H 'api-key: $SIPPULSE_API_KEY'

Python

import requests

url = "https://api.sippulse.ai/v1/llms/models"
headers = {
    "Content-Type": "application/json",
    "api-key": "SIPPULSE_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

JavaScript

const url = "https://api.sippulse.ai/v1/llms/models";
const headers = {
  "Content-Type": "application/json",
  "api-key": "SIPPULSE_API_KEY",
};

fetch(url, {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));

Segurança da Chave API

• Confidencialidade: Nunca compartilhe suas chaves API publicamente. Evite incluí-las em código de navegador ou cliente.
• Rotação de Chaves: Periodicamente, gere novas chaves API e substitua as antigas para melhorar a segurança.
• Revogação: Caso uma chave API seja comprometida, revogue-a imediatamente através da seção API Keys.

---

Endpoints Principais

A API do SipPulse AI está organizada em módulos funcionais. Abaixo estão os principais endpoints disponíveis:

Agentes

Método	Endpoint	Descrição
GET	/agents	Lista todos os agentes da organização
POST	/agents	Cria um novo agente
GET	/agents/{id}	Obtém detalhes de um agente
PATCH	/agents/{id}	Atualiza um agente
DELETE	/agents/{id}	Remove um agente
POST	/agents/{id}/outbound-call	Inicia uma chamada de saída

Conversas (Threads)

Método	Endpoint	Descrição
GET	/threads	Lista conversas (com filtros)
POST	/threads	Cria uma nova conversa
GET	/threads/{id}	Obtém histórico de uma conversa
POST	/threads/{id}/messages	Envia mensagem para uma conversa
POST	/threads/{id}/close	Encerra uma conversa

Modelos de Linguagem (LLM)

Método	Endpoint	Descrição
GET	/llms/models	Lista modelos LLM disponíveis
POST	/llms/completion	Gera uma resposta de texto
POST	/llms/stream	Gera resposta em streaming

Reconhecimento de Fala (ASR)

Método	Endpoint	Descrição
GET	/asr/models	Lista modelos ASR disponíveis
POST	/asr/transcribe	Transcreve áudio para texto

Síntese de Voz (TTS)

Método	Endpoint	Descrição
GET	/tts/models	Lista modelos TTS disponíveis
POST	/tts/synthesize	Converte texto para áudio

Base de Conhecimento

Método	Endpoint	Descrição
GET	/knowledge	Lista tabelas de conhecimento
POST	/knowledge	Cria uma nova tabela
POST	/knowledge/{name}/query	Consulta semântica na tabela
POST	/knowledge/{name}/rows	Adiciona linhas à tabela

Webhooks

Método	Endpoint	Descrição
GET	/webhooks	Lista webhooks configurados
POST	/webhooks	Cria um novo webhook
PATCH	/webhooks/{id}	Atualiza um webhook
DELETE	/webhooks/{id}	Remove um webhook

Documentação Interativa

Para uma referência completa com schemas de request/response e a possibilidade de testar endpoints diretamente, acesse o Swagger UI.

---

Rate Limits

A API implementa limites de taxa para garantir uso justo e estabilidade do serviço. Os limites variam por tipo de endpoint e plano.

Tipos de Limites

Sigla	Descrição	Aplicável a
RPM	Requisições por Minuto	Todos os endpoints
RPD	Requisições por Dia	Todos os endpoints
TPM	Tokens por Minuto	Endpoints de LLM
TPD	Tokens por Dia	Endpoints de LLM
ASH	Segundos de Áudio por Hora	Endpoints de ASR/TTS
ASD	Segundos de Áudio por Dia	Endpoints de ASR/TTS

Headers de Rate Limit

Quando uma requisição é feita, os headers de resposta incluem informações sobre o status do rate limit:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Comportamento ao Exceder Limites

Quando você excede um limite de taxa, a API retorna:

• Status: 429 Too Many Requests
• Header: Retry-After com o tempo em segundos para aguardar

Erro 429

Se você receber um erro 429, implemente um backoff exponencial e respeite o header Retry-After antes de tentar novamente.

Boas Práticas

1. Implemente cache: Armazene respostas que não mudam frequentemente
2. Use streaming: Para LLMs, prefira endpoints de streaming para respostas longas
3. Batch requests: Agrupe operações quando possível
4. Monitore uso: Acompanhe seus limites no Dashboard de Consumo

---

Tratamento de Erros

A API usa códigos HTTP padrão para indicar sucesso ou falha:

Código	Significado
200	Sucesso
201	Recurso criado
400	Requisição inválida
401	Não autenticado
403	Sem permissão
404	Recurso não encontrado
429	Rate limit excedido
500	Erro interno do servidor

Formato de Erro

{
  "error": {
    "statusCode": 400,
    "name": "BadRequestError",
    "message": "Descrição do erro"
  }
}