Manual da API · IPBX Quantum
Integre suas bases de conhecimento a aplicações, agentes de IA, n8n, Typebot, CRMs, websites e sistemas próprios.
API base: https://rag1.ipbx.com.br · Versão /api/v1
1. Comece em três passos
No painel Quantum abra Chaves de API, crie uma chave e salve-a: ela é exibida uma única vez.
Use a página Bases de conhecimento ou liste suas bases via API para obter o identificador.
Envie PDFs ou indexe textos e execute semantic-search para recuperar trechos relevantes.
Sua base de conhecimento — ID para integração
Selecione uma base da sua organização. O ID e a URL para o n8n, Typebot ou outro sistema aparecem abaixo.
ID da base:
URL do HTTP Request (POST):
Os exemplos deste manual usarão automaticamente o ID selecionado. Sua chave de API continua sendo necessária para integrar serviços externos.
Autenticação
Em todas as chamadas de integração envie a chave HTTP Authorization: Bearer SUA_CHAVE_QUANTUM. Nunca coloque a chave diretamente em um website público ou em um Typebot cliente.
curl -sS 'https://rag1.ipbx.com.br/api/v1/knowledge-bases' \ -H 'Authorization: Bearer SUA_CHAVE_QUANTUM'
2. Referência rápida dos endpoints
| Método | Endpoint | Finalidade |
|---|---|---|
| GET | /api/v1/knowledge-bases | Listar bases |
| POST | /api/v1/knowledge-bases | Criar base: {"name":"Suporte"} |
| GET | /api/v1/knowledge-bases/{base_id} | Consultar base |
| GET | /api/v1/knowledge-bases/{base_id}/embedding-profile | Modelo de embeddings da base |
| PUT | /api/v1/knowledge-bases/{base_id}/embedding-profile | Configurar modelo: {"provider":"local"} |
| POST | /api/v1/knowledge-bases/{base_id}/texts | Indexar texto: {"text":"..."} |
| POST | /api/v1/knowledge-bases/{base_id}/semantic-search | Buscar: {"query":"...","limit":5} |
| GET | /api/v1/knowledge-bases/{base_id}/documents | Listar PDFs |
| POST | /api/v1/knowledge-bases/{base_id}/documents | Enviar PDF multipart (file) |
| GET | /api/v1/knowledge-bases/{base_id}/documents/{document_id} | Acompanhar indexação |
| POST | /api/v1/knowledge-bases/{base_id}/documents/{document_id}/retry | Reprocessar PDF |
| DELETE | /api/v1/knowledge-bases/{base_id}/documents/{document_id} | Excluir documento |
| GET | /api/v1/usage | Consultar uso |
| GET | /api/v1/quantum/credits | Consultar créditos (quando habilitado) |
O endpoint legado POST /api/v1/knowledge-bases/{base_id}/search não deve ser usado para pesquisa semântica. Use /semantic-search.
3. Exemplos prontos
Pesquisar — cURL
curl -sS -X POST \
'https://rag1.ipbx.com.br/api/v1/knowledge-bases/SEU_BASE_ID/semantic-search' \
-H 'Authorization: Bearer SUA_CHAVE_QUANTUM' \
-H 'Content-Type: application/json' \
-d '{"query":"Qual é o prazo de suporte?","limit":5}'Pesquisar — JavaScript (Node.js)
const baseId = process.env.QUANTUM_BASE_ID;
const apiKey = process.env.QUANTUM_API_KEY;
const response = await fetch(
`https://rag1.ipbx.com.br/api/v1/knowledge-bases/${baseId}/semantic-search`,
{ method: 'POST', headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}, body: JSON.stringify({ query: 'Qual é o prazo de suporte?', limit: 5 }) }
);
if (!response.ok) throw new Error(`Quantum HTTP ${response.status}`);
const {matches} = await response.json();
console.log(matches);Pesquisar — Python
import os, requests
url = f"https://rag1.ipbx.com.br/api/v1/knowledge-bases/{os.environ['QUANTUM_BASE_ID']}/semantic-search"
response = requests.post(url,
headers={"Authorization": "Bearer " + os.environ['QUANTUM_API_KEY']},
json={"query": "Qual é o prazo de suporte?", "limit": 5},
timeout=30)
response.raise_for_status()
print(response.json().get("matches", []))Enviar PDF — cURL
curl -sS -X POST \ 'https://rag1.ipbx.com.br/api/v1/knowledge-bases/SEU_BASE_ID/documents' \ -H 'Authorization: Bearer SUA_CHAVE_QUANTUM' \ -F 'file=@manual.pdf;type=application/pdf'
O upload retorna HTTP 202 (processamento assíncrono). Consulte o status do documento antes de confiar em sua disponibilidade para buscas.
4. Integrar com n8n
Crie um workflow com Webhook → HTTP Request (Quantum) → Code / IA → Respond to Webhook.
Método POST; URL https://rag1.ipbx.com.br/api/v1/knowledge-bases/SEU_BASE_ID/semantic-search.
Configure uma credencial Header Auth, nome Authorization, valor Bearer SUA_CHAVE. Não fixe a chave no workflow compartilhado.
{"query":"{{$json.body.pergunta}}","limit":5} usando o editor de expressões para o campo de pergunta.
Transformar trechos em contexto para um agente de IA
// Node Code, após HTTP Request
const matches = $input.first().json.matches ?? [];
return [{ json: {
contexto: matches.map((m, i) =>
`[${i + 1}] ${m.text ?? m.payload?.text ?? ''}`
).join('\n\n'),
encontrou: matches.length > 0
}}];Confira no resultado real os campos de cada match antes de mapear o texto. Oriente o agente a responder apenas com base no contexto e admitir quando não encontrou a informação.
5. Integrar com Typebot
Recomendado: Typebot → webhook privado do n8n (ou seu backend) → Quantum → resposta ao Typebot. Essa arquitetura impede expor a chave Quantum aos visitantes.
Use uma entrada de texto no Typebot e salve em uma variável, por exemplo pergunta.
Adicione bloco HTTP Request com método POST apontando ao seu webhook seguro no n8n. Envie JSON {"pergunta":"..."} com a variável do Typebot.
O n8n consulta semantic-search, monta contexto para IA e devolve JSON como {"resposta":"..."}.
Mapeie o campo resposta para uma variável do Typebot e mostre-o no bloco de texto.
// Exemplo de resposta do seu n8n para o Typebot
{
"resposta": "O prazo informado na documentação é ...",
"fontes_encontradas": 3
}O JSON acima é um exemplo do seu workflow intermediário, não o contrato nativo de resposta da API Quantum.
6. Boas práticas e resolução de problemas
Chaves
Use uma chave por integração, guarde-a em credenciais do servidor e revogue-a imediatamente se for exposta. Nunca envie a chave em consultas públicas.
Limites e custo
As buscas e indexações estão sujeitas ao plano e ao consumo de créditos. 1 Crédito Quantum = 250.000 tokens equivalentes.
Respostas confiáveis
Não confunda busca vetorial com chat. Dê ao seu modelo somente o contexto recuperado e peça que declare incerteza se não houver base documental.
Tratamento de erros
401: credencial inválida. 404: base ou documento não encontrado. 409: pré-condição, plano ou configuração. 429/5xx: trate com espera e tentativas limitadas.
Checklist antes de entrar em produção
Teste uma chave dedicada, confira as permissões da organização, envie um PDF pequeno, aguarde indexação, execute uma consulta conhecida e configure timeout/retry na integração. Monitore o consumo e não registre chaves ou dados pessoais em logs.
IPBX Quantum · Documentação de integração para clientes · API v1