Integração da API

Envie dados programaticamente para sua base de conhecimento AI SmartTalk usando nossa API REST. Ideal para integrações personalizadas, pipelines automatizados e qualquer fonte de dados não coberta por nossos conectores nativos.

---

Visão Geral

A integração da API permite que você:

• Envie documentos diretamente para sua base de conhecimento
• Atualize conteúdo programaticamente
• Exclua entradas desatualizadas
• Construa pipelines de dados personalizados
• Integre-se com qualquer sistema que possa fazer requisições HTTP

---

Pré-requisitos

Antes de começar, certifique-se de que você possui:

• Uma conta ativa do AI SmartTalk
• Acesso à API habilitado (verifique seu plano)
• Conhecimento básico sobre APIs REST
• Uma ferramenta para fazer requisições HTTP (curl, Postman ou seu código de aplicação)

---

Obtendo suas Credenciais da API

Passo 1: Acessar Configurações da API

1. Faça login na sua conta do AI SmartTalk
2. Navegue até Configurações → Integrações
3. Encontre API e clique em Configurar

Passo 2: Gerar Token da API

1. Clique em Gerar Novo Token
2. Copie seu ID do Modelo de Chat e Token da API
3. Armazene esses dados com segurança—o token é exibido apenas uma vez!

⚠️ Aviso de Segurança: Nunca exponha seu token da API em código do lado do cliente ou repositórios públicos.

---

Endpoints da API

URL Base

https://api.aismarttalk.tech/v1

Autenticação

Todas as requisições requerem seu token da API no cabeçalho:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Todas as requisições requerem seu token de API no cabeçalho:

Authorization: Bearer YOUR_API_TOKEN

---

Importar Documentos

Endpoint

POST /documents/import

Corpo da Requisição

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Documentação do Produto",
      "content": "Conteúdo completo do seu documento vai aqui...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
chatModelId	string	✅	Seu identificador único do modelo de chat
documents	array	✅	Array de objetos de documento
documents[].title	string	✅	Título do documento para identificação
documents[].content	string	✅	Conteúdo de texto completo
documents[].url	string	❌	URL de origem (para referência)
documents[].metadata	object	❌	Pares chave-valor personalizados

Resposta

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Documentação do Produto",
      "status": "processing"
    }
  ]
}

Exemplo: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Guia de Introdução",
        "content": "Bem-vindo à nossa plataforma. Aqui está como começar...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Consultar Documentos

Faça perguntas à sua base de conhecimento programaticamente.

Endpoint

POST /chat/query

Corpo da Requisição

{
  "chatModelId": "your-chat-model-id",
  "query": "Como redefinir minha senha?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Resposta

{
  "success": true,
  "response": "Para redefinir sua senha, navegue até Configurações > Segurança > Alterar Senha...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Guia de Segurança",
      "relevance": 0.95
    }
  ]
}

---

Recuperar Documentos

Obtenha documentos que correspondam a uma consulta (sem resposta de IA).

Endpoint

POST /documents/search

Corpo da Requisição

{
  "chatModelId": "your-chat-model-id",
  "query": "segurança da senha",
  "limit": 10
}

Resposta

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Melhores Práticas de Segurança",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Exemplos de Código

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Importar um documento
result = import_document(
    title="FAQ: Envio",
    content="Oferecemos frete grátis em pedidos acima de $50...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Importar um documento
importDocument(
  'FAQ: Devoluções',
  'Você pode devolver itens dentro de 30 dias após a compra...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Especificações do Produto',
            'content' => 'Nosso widget tem as seguintes especificações...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Casos de Uso

Integração de CMS Personalizado

Sincronizar conteúdo de um CMS proprietário:

• Conectar-se a eventos de publicação do CMS
• Enviar conteúdo novo/atualizado para o AI SmartTalk
• Remover conteúdo deletado

Pipeline de Dados

Importar de armazéns de dados:

• Exportar dados relevantes para JSON
• Importação em lote via API
• Agendar atualizações regulares

Produtos de E-commerce

Sincronizar dados de produtos de sistemas personalizados:

• Descrições de produtos
• Especificações
• Informações de preços

Sistemas Internos

Conectar ferramentas internas não suportadas nativamente:

• Wikis personalizados
• Bancos de dados legados
• Aplicações proprietárias

---

Limites de Taxa

Endpoint	Limite de Taxa
Importação de Documentos	100 requisições/minuto
Consulta	60 requisições/minuto
Pesquisa	60 requisições/minuto

Nota: Os limites de taxa variam conforme o plano. Entre em contato com o suporte para limites mais altos.

---

Tratamento de Erros

Formato de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "O token da API fornecido é inválido ou expirou"
  }
}

Códigos de Erro Comuns

Código	Descrição	Solução
INVALID_TOKEN	Token inválido ou expirado	Regenerar token da API
INVALID_MODEL_ID	ID de modelo de chat desconhecido	Verifique seu ID de Modelo de Chat
RATE_LIMITED	Muitas requisições	Implemente backoff, tente novamente mais tarde
INVALID_REQUEST	Corpo da requisição malformado	Verifique a estrutura do JSON
DOCUMENT_TOO_LARGE	Conteúdo excede o limite	Divida em documentos menores
QUOTA_EXCEEDED	Limites do plano atingidos	Faça upgrade ou entre em contato com o suporte

---

Solução de Problemas

Falhas de Autenticação

Problema	Solução
401 Não Autorizado	Verifique se o token está correto e ativo
Token não funcionando	Regenerar token nas configurações
Token expirado	Tokens não expiram, mas podem ser revogados

Problemas de Importação

Problema	Solução
Resposta vazia	Verifique se o Content-Type é application/json
Documento não aparecendo	Aguarde o processamento; verifique a seção de Conhecimento
Importação parcial	Alguns documentos podem ter erros de validação

Problemas de Desempenho

Problema	Solução
Importações lentas	Agrupe documentos (máx. 100 por requisição)
Timeouts	Reduza o tamanho do lote, tente novamente com backoff
Limite de taxa atingido	Implemente backoff exponencial

---

Melhores Práticas

1. Importações em lote: Envie vários documentos por requisição (até 100)
2. Títulos únicos: Use títulos descritivos e únicos para cada documento
3. Conteúdo estruturado: Conteúdo bem formatado melhora as respostas da IA
4. Tagueamento de metadados: Use metadados para categorização e filtragem
5. Tokens seguros: Armazene tokens em variáveis de ambiente
6. Tratar erros: Implemente lógica de repetição com backoff exponencial
7. Monitorar uso: Acompanhe chamadas da API em relação aos limites do seu plano

---

Documentação Relacionada

• Visão Geral de Integrações
• Documentação Completa da API
• Gerenciamento da Base de Conhecimento
• Webhooks do SmartFlow — Receba eventos