Ligações API

Ligue as suas APIs externas ao enuchat para que a IA e as regras possam obter dados em tempo real dos seus sistemas.

Como funciona

As ligações API permitem-lhe integrar o enuchat com os seus próprios sistemas de backend — motores de reservas, CRM, gestão de encomendas, inventário e mais. Quando um visitante faz uma pergunta, o enuchat pode chamar a sua API para obter dados reais e incluí-los na resposta.

O fluxo

Configure uma ligação — o URL base da sua API e a autenticação
Adicione endpoints — chamadas API específicas com modelos de caminho e mapeamento de resposta
Crie uma regra — uma regra de IA ou estática com uma ação CALL_API
O visitante faz uma pergunta — a regra dispara, chama a sua API, mapeia a resposta para variáveis de sessão
A IA responde com dados reais — as variáveis de sessão ficam disponíveis para a IA gerar uma resposta precisa

Exemplo: disponibilidade de quarto de hotel

Visitante: «O quarto 205 está disponível na próxima semana?»

A regra de IA corresponde: «Quando o visitante pergunta sobre disponibilidade de quartos»

Ação CALL_API: GET https://api.hotel.com/rooms/205/availability

Resposta mapeada: room_available = true, price = «120 €/noite»

A IA responde: «O quarto 205 está disponível na próxima semana a 120 €/noite. Gostaria de reservar?»

Configurar uma ligação

Vá a Definições → Ligações API no painel.

1. Criar uma ligação

Uma ligação representa uma API externa. Precisa de:

Campo	Descrição	Exemplo
Nome	Uma etiqueta para esta ligação	API de reservas de hotel
URL base	O URL raiz da API	`https://api.hotel.com/v1`
Tipo de auth	Como autenticar	Bearer Token, OAuth2, etc.

2. Tipos de autenticação

Nenhuma

Para APIs públicas que não exigem autenticação.

Chave API

Envia uma chave estática como cabeçalho ou parâmetro de consulta.

Campo	Descrição
Chave	O valor da sua chave API
Nome do cabeçalho	Cabeçalho a usar (predefinição: `X-Api-Key`)

A chave é enviada como: X-Api-Key: your_key_here

Bearer Token

Envia um token estático no cabeçalho Authorization.

Enviado como: Authorization: Bearer your_token_here

Basic Auth

Envia utilizador e palavra-passe, codificados em base64.

Enviado como: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

Obtém um access token automaticamente e coloca-o em cache até expirar. Ideal para APIs modernas como Salesforce, Google ou servidores OAuth personalizados.

Campo	Descrição
Token URL	Endpoint de token OAuth (ex. `https://auth.example.com/oauth/token`)
Client ID	O seu ID de cliente OAuth
Client Secret	O seu segredo de cliente OAuth
Scope	Scopes separados por espaços (ex. `read write`)

O enuchat trata do ciclo de vida do token automaticamente — obtém na primeira chamada, coloca em cache até expirar, renova quando necessário.

Segurança: todas as credenciais são encriptadas em repouso usando libsodium. Nunca são expostas nas respostas da API — apenas valores mascarados são mostrados no painel.

Configurar endpoints

Cada ligação pode ter vários endpoints — chamadas API específicas que quer efetuar.

Campo	Descrição	Exemplo
Nome	Etiqueta para este endpoint	Verificar disponibilidade
Método	Método HTTP	GET, POST, PUT, DELETE
Caminho	Caminho do URL (acrescentado ao URL base). Use `{'{'}variable}` para valores dinâmicos	`/rooms/{'{'}roomId}/availability`
Parâmetros de consulta	Parâmetros de URL como pares chave-valor. Os valores suportam `{'{'}variable}`	`date={'{'}checkIn}`
Modelo do corpo	Corpo JSON para POST/PUT. Suporta interpolação `{'{'}variable}`	`{'{'}"guest": "{'{'}name}"}`
Mapeamento da resposta	Mapeie campos da resposta JSON para variáveis de sessão usando notação por ponto	`data.available → room_available`
Descrição	Contexto para a IA (que dados este endpoint retorna)	Retorna disponibilidade e preço do quarto

Interpolação de variáveis

Use {'{'}variableName} em caminhos, parâmetros de consulta e modelos de corpo. As variáveis vêm de:

Variáveis de sessão — definidas por regras anteriores (ação SET_VARIABLE)
Parâmetros de ação — embutidos na ação de regra CALL_API

Mapeamento da resposta

Mapeie campos da resposta JSON para variáveis de sessão usando notação por ponto:

// API returns:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Mapping:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

As variáveis mapeadas são armazenadas como variáveis de sessão na conversa e ficam disponíveis para a IA gerar respostas.

Usar com regras

As chamadas API são acionadas pela ação CALL_API nas regras. Pode combiná-las com outras ações.

Receita: consulta de estado de encomenda

Ligação: API de gestão de encomendas — https://api.shop.com/v2 — Bearer Token

Endpoint: GET /orders/{'{'}orderId} → mapeia data.status → order_status, data.eta → delivery_eta

Regra (tipo IA): «Quando o visitante pergunta sobre o estado da encomenda ou entrega»

Ações:

CALL_API → endpoint de estado de encomenda
REPLY_AI → a IA usa order_status e delivery_eta para responder

Resultado: Visitante: «Onde está a minha encomenda #4521?» — IA: «A sua encomenda #4521 está atualmente a ser expedida e deve chegar na quinta-feira.»

Receita: preços em tempo real

Ligação: API de preços — https://pricing.example.com — Chave API

Endpoint: GET /products/{'{'}productId}/price → mapeia price → current_price, currency → price_currency

Regra (estática): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Ações:

CALL_API → endpoint de preços
REPLY_TEXT → «O preço atual é {'{'}current_price} {'{'}price_currency}.»

Testar

Teste sempre as suas ligações e endpoints antes de os usar em regras:

Testar ligação — verifica se a autenticação funciona (para OAuth2: obtém um token)
Testar endpoint — efetua uma chamada API real com variáveis de exemplo e mostra a resposta
Testar regra (dry-run) — na página Regras, teste se uma regra corresponderia e que ações executaria

Dica: comece por testar a ligação, depois cada endpoint, depois a regra completa. Assim consegue isolar problemas em cada nível.

Segurança

Encriptação em repouso — todas as credenciais são encriptadas usando libsodium antes do armazenamento
Nunca expostas — as respostas da API nunca incluem credenciais desencriptadas, apenas valores mascarados
Proteção SSRF — o enuchat bloqueia chamadas para localhost, IPs privados e nomes de host internos
Timeout — as chamadas a APIs externas têm um timeout de 5 segundos para evitar bloqueios
Cache de tokens OAuth2 — os access tokens são colocados em cache com segurança e renovados automaticamente
Isolamento por tenant — as ligações estão limitadas ao seu tenant, inacessíveis a outros

Pronto para ligar as suas APIs?

Comece hoje a integrar os seus sistemas com o enuchat.

Começar gratuitamente