Bloco Integração API

O que é o Bloco Integração API?

O bloco Integração API permite que o agente de IA consulte sistemas externos (ERP, CRM, catálogos, sistemas de reserva, etc.) durante a conversa. A IA decide automaticamente quando chamar a API, baseado na conversa com o cliente.

Por que usar?

Benefício	Descrição
Respostas em tempo real	Consulta informações atualizadas do seu sistema
IA decide quando usar	O agente sabe quando a API é relevante para a conversa
Sem código	Configure visualmente sem precisar programar
Seguro	Credenciais ficam protegidas e nunca aparecem ao cliente

Este bloco funciona no modo Tool (LLM): a IA decide quando chamar a API. Se você precisa de uma consulta automática e silenciosa (sem IA), use o modo Buscar Dados — veja o Bloco Buscar Dados.

Como funciona?

Cliente faz uma pergunta
        ↓
IA analisa: "preciso consultar a API?"
        ↓
   ┌────┴────┐
   │         │
  Sim       Não
   │         │
   ↓         ↓
Chama a    Responde
 API       diretamente
   │
   ↓
Recebe resposta da API
   │
   ↓
Formata e apresenta ao cliente

A IA usa a descrição que você configurou no bloco para entender quando a API é relevante. Quanto melhor a descrição, mais preciso será o uso.

Configuração

1. Identificação

A primeira seção define como a IA reconhece e usa esta integração:

Campo	Descrição	Exemplo
Nome da Tool	Identificador interno (sem espaços)	`buscar_produto`
Nome de Exibição	Nome amigável	”Buscar Produto”
Descrição	Quando o agente deve usar	”Use quando o cliente perguntar sobre disponibilidade ou preço de um produto”

A descrição é fundamental. Se for vaga, a IA pode usar a API em momentos errados ou não usá-la quando deveria. Seja específico sobre quais situações exigem esta consulta.

2. Endpoint

Configure a URL da API que será chamada:

Escolha o método HTTP

Método	Quando usar
GET	Consultar informações (mais comum)
POST	Enviar dados para criar algo
PUT	Atualizar um recurso existente
PATCH	Atualizar parcialmente
DELETE	Remover um recurso

URL Base

O endereço principal da API (ex: https://api.meusite.com).

Endpoint (path)

O caminho específico do recurso (ex: /api/v1/produtos).Use {param} para parâmetros dinâmicos no path:

/api/v1/pedidos/{numero_pedido}

3. Autenticação

Se a API exige autenticação, configure nesta seção:

Tipo	Como funciona	Quando usar
Nenhuma	Sem autenticação	APIs públicas
API Key	Envia uma chave via header HTTP	A maioria das APIs
Bearer Token	Envia um token de acesso	APIs com OAuth/JWT
Basic Auth	Envia usuário e senha	APIs legadas

API Key
Bearer Token
Basic Auth

Configure:

Nome do Header: O nome do header (ex: X-API-Key, Authorization)
API Key: O valor da chave

A requisição será enviada com:

X-API-Key: sua-chave-aqui

Configure:

Bearer Token: O token de acesso

A requisição será enviada com:

Authorization: Bearer seu-token-aqui

4. Parâmetros

Configure os dados que serão enviados na requisição:

Query Parameters

Dados enviados na URL (ex: ?nome=hotel&cidade=sp).

Campo	Descrição
Nome	Nome do parâmetro
Tipo	string, number, boolean, etc.
Obrigatório	Se a IA deve coletar antes de chamar
Origem	De onde vem o valor
Descrição	Explica para a IA o que é este campo

Body Parameters

Dados enviados no corpo da requisição (para POST, PUT, PATCH).

Path Parameters

Valores para substituir {param} na URL.

Origem dos dados

Origem	Descrição	Exemplo
Do usuário	A IA pergunta ao cliente	”Qual o número do pedido?”
Do contexto	Extraído automaticamente da conversa	Nome, email já informados
Valor fixo	Sempre o mesmo valor	Chave fixa, ID do hotel

5. Resposta

Configure como o agente apresenta o resultado da API ao cliente:

Campo	Descrição
Template de Sucesso	Como formatar a resposta da API
Template de Erro	Mensagem quando a API falha

Variáveis disponíveis no template:

Variável	O que retorna
`{{response}}`	Resposta JSON completa
`{{response.campo}}`	Campo específico da resposta
`{{status}}`	Código HTTP (200, 404, etc.)

6. Configurações Avançadas

Campo	Descrição	Padrão
Timeout	Tempo máximo de espera (ms)	30.000 (30 seg)
Tentativas	Quantas vezes tentar se falhar	1
Cache	Tempo para reutilizar resposta (seg)	0 (sem cache)

Ative o cache para APIs com dados que mudam pouco (ex: catálogo de produtos). Isso reduz a latência e o número de chamadas.

Exemplos por Segmento

E-commerce - Rastreio
Imobiliária - Imóveis
Clínica - Agendamento

Objetivo: Permitir que o cliente consulte o status do pedido.

Campo	Valor
Nome da Tool	`rastrear_pedido`
Descrição	”Use quando o cliente perguntar sobre status do pedido, rastreio ou entrega”
Método	GET
URL	`https://api.meusite.com/v1/pedidos/{numero}`
Parâmetro	`numero` (do usuário, obrigatório)

Conversa:

Cliente: "Quero saber onde está meu pedido"
IA: "Claro! Pode me informar o número do pedido?"
Cliente: "12345"
IA: [chama API] → "Seu pedido #12345 está em trânsito.
     Previsão de entrega: 20/02/2026."

Objetivo: Buscar imóveis disponíveis por critérios.

Campo	Valor
Nome da Tool	`buscar_imoveis`
Descrição	”Use quando o cliente procurar imóvel para compra ou aluguel”
Método	GET
URL	`https://api.imob.com/v1/imoveis`
Query Params	`tipo` (do usuário), `cidade` (do contexto), `quartos` (do usuário)

Conversa:

Cliente: "Procuro apartamento de 2 quartos para alugar"
IA: [chama API com tipo=apartamento, quartos=2] →
    "Encontrei 3 opções de apartamento com 2 quartos:
     1. Rua das Flores - R$ 2.500/mês
     2. Av. Brasil - R$ 2.800/mês
     3. Centro - R$ 2.200/mês
     Quer mais detalhes sobre algum?"

Objetivo: Verificar horários disponíveis para consulta.

Campo	Valor
Nome da Tool	`verificar_horarios`
Descrição	”Use quando o cliente quiser agendar consulta ou ver horários”
Método	POST
URL	`https://api.clinica.com/v1/agenda/disponibilidade`
Body Params	`especialidade` (do usuário), `data` (do usuário)

Conversa:

Cliente: "Quero marcar com o dentista para amanhã"
IA: [chama API] → "Temos os seguintes horários disponíveis
     para amanhã com Dr. Silva:
     - 09:00
     - 14:30
     - 16:00
     Qual você prefere?"

Conectando ao Roteador

O bloco Integração API pode ser conectado ao Roteador para ser usado apenas em contextos específicos:

[Roteador]
    │
    ├─ "Quer rastrear pedido" → [Integração API: Rastreio]
    │
    ├─ "Quer ver produtos" → [Integração API: Catálogo]
    │
    └─ Outras perguntas → IA responde normalmente

Conectar ao Roteador dá mais controle sobre quando a API é usada. Sem essa conexão, a IA pode decidir usar a API em qualquer momento da conversa.

Headers Personalizados

Além da autenticação, você pode adicionar headers HTTP adicionais:

Campo	Descrição
Nome	Nome do header (ex: `Content-Type`)
Valor	Valor do header (ex: `application/json`)
Secreto	Se marcado, o valor fica oculto na interface

O header Content-Type: application/json é adicionado automaticamente para métodos POST/PUT/PATCH. Não é necessário configurá-lo manualmente.

Perguntas Frequentes

Qual a diferença entre Integração API e Buscar Dados?

São dois modos do mesmo bloco:

Aspecto	Integração API (Tool)	Buscar Dados
Quem decide	A IA decide quando chamar	Executa automaticamente
Visível ao cliente	Sim, IA usa o resultado na resposta	Não, executa silenciosamente
Custo de IA	Consome tokens	Não consome tokens
Uso	Consultas durante a conversa	Decisões automáticas no início

A IA pode chamar a API várias vezes na mesma conversa?

Sim. A cada mensagem relevante, a IA pode decidir chamar a API novamente. Use a configuração de cache para evitar chamadas repetidas com os mesmos parâmetros.

O que acontece se a API estiver fora do ar?

O agente usa o template de erro configurado para informar o cliente. Se houver tentativas configuradas, ele tenta novamente antes de mostrar o erro.

Posso ter várias Integrações API no mesmo fluxo?

Sim. Cada bloco funciona como uma “ferramenta” (tool) independente. O agente pode ter acesso a várias APIs e decide qual usar baseado na conversa.

As credenciais ficam seguras?

Sim. As credenciais (API keys, tokens, senhas) são armazenadas de forma segura e nunca são expostas ao cliente nem incluídas nas mensagens do chat. Elas são usadas apenas no servidor ao fazer a chamada HTTP.

Comece Aqui

Treinamento da IA

Operação

Administradores

Relatórios

O que é o Bloco Integração API?

Por que usar?

Como funciona?

Configuração

1. Identificação

2. Endpoint

3. Autenticação

4. Parâmetros

Query Parameters

Body Parameters

Path Parameters

Origem dos dados

5. Resposta

6. Configurações Avançadas

Exemplos por Segmento

Conectando ao Roteador

Headers Personalizados

Perguntas Frequentes

Próximos passos

Bloco Buscar Dados

Bloco Roteador

Comece Aqui

Treinamento da IA

Operação

Administradores

Relatórios

​O que é o Bloco Integração API?

​Por que usar?

​Como funciona?

​Configuração

​1. Identificação

​2. Endpoint

​3. Autenticação

​4. Parâmetros

​Query Parameters

​Body Parameters

​Path Parameters

​Origem dos dados

​5. Resposta

​6. Configurações Avançadas

​Exemplos por Segmento

​Conectando ao Roteador

​Headers Personalizados

​Perguntas Frequentes

​Próximos passos

Bloco Buscar Dados

Bloco Roteador

O que é o Bloco Integração API?

Por que usar?

Como funciona?

Configuração

1. Identificação

2. Endpoint

3. Autenticação

4. Parâmetros

Query Parameters

Body Parameters

Path Parameters

Origem dos dados

5. Resposta

6. Configurações Avançadas

Exemplos por Segmento

Conectando ao Roteador

Headers Personalizados

Perguntas Frequentes

Próximos passos