> ## Documentation Index > Fetch the complete documentation index at: https://docs.maketalk.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bloco Integração API > Conecte APIs externas para que o agente consulte sistemas em tempo real durante a conversa ## 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. Configuração do bloco Integração API ### 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](/administradores/flow-builder/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: | 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 | O endereço principal da API (ex: `https://api.meusite.com`). 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 | 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 ``` Configure: * **Usuário**: Nome de usuário * **Senha**: Senha de acesso *** ### 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 **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 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 | 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 agente usa o **template de erro** configurado para informar o cliente. Se houver **tentativas** configuradas, ele tenta novamente antes de mostrar o erro. 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. 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. *** ## Próximos passos Consulte dados automaticamente para decisões sem IA. Direcione conversas por intenção do cliente.