Integrações — conexões de API externa | Documentações

A tela Integrações guarda conexões HTTP reutilizáveis para sistemas externos (CRM, ERP e outras ferramentas). Você cadastra a URL base e a autenticação uma vez.

Importante: a conexão aponta para a raiz da API, e não para uma operação específica. Por exemplo, cadastre https://api.exemplo.com (ou https://api.exemplo.com/v1), e não https://api.exemplo.com/v1/leads. O caminho de cada chamada (como /leads) e o tipo de chamada são definidos depois, no bot. Nos bots, na ação REST de outcome, basta escolher a conexão e informar só o caminho da chamada.

Para conectar canais de atendimento (WhatsApp, Instagram, Telegram, web), use a tela Canais: veja Visão geral das integrações.

Criar uma conexão

Clique em Nova conexão (canto superior direito, na linha do título). Abre uma página de cadastro, com o botão Salvar no topo, e você preenche:

Campo	O que informar
Nome	Como você identifica a conexão (ex.: "CRM produção").
URL base	Endereço raiz da API, sem o caminho final (ex.: `https://api.exemplo.com`). Precisa começar com `http://` ou `https://`.
Autenticação	Nenhuma, Bearer token ou Header de API key (uma chave enviada em um cabeçalho, conforme o seu sistema pedir).
Nome do header	Só para API key: o header que leva a chave (ex.: `X-API-Key`).
Token / valor	O segredo. Obrigatório para Bearer e API key. Só aparece quando a autenticação não é "Nenhuma".
Headers padrão	JSON opcional com headers enviados em toda chamada (ex.: `{"Accept":"application/json"}`). Deve ser um objeto.
Ativo	Desative para impedir o uso da conexão sem apagá-la.

Testar a conexão

Antes de salvar (ou ao editar), use Testar conexão. O OSBChat faz uma consulta simples ao endereço cadastrado, com a autenticação escolhida, e mostra o resultado:

Resultado	Significado
Conexão funcionando	O servidor respondeu com sucesso.
Credenciais recusadas	O servidor foi encontrado, mas o token ou o nome do header estão errados.
Nada neste caminho	O servidor foi encontrado, mas a raiz não responde a nada. É comum em APIs; informe em Caminho para o teste um endereço de verificação (como `/health`) para confirmar.
Erro do servidor	O sistema de destino está com problema. Tente de novo mais tarde.
Não conectou / demorou demais	Confira se a URL está correta e se o sistema está no ar.

O caminho de teste vale só para o teste e não é salvo. O teste não envia dados e não mostra o conteúdo da resposta. Por segurança, endereços de rede interna não podem ser testados.

Depois de salvar, a conexão aparece na lista com nome, URL base, tipo de autenticação, situação (ativa ou inativa) e o número de chamadas e erros dos últimos 7 dias.

Acompanhar o uso

Ao abrir uma conexão, o topo da página mostra como ela está sendo usada, nos últimos 7 ou 30 dias:

Chamadas: quantas vezes os bots usaram a conexão, seja para enviar um resultado ou para consultar dados durante a conversa.
Erros: quantas dessas chamadas falharam.
Taxa de sucesso e tempo médio de resposta.
Um gráfico por dia, com as chamadas que deram certo e as que deram erro.
Os últimos erros, com data, origem, código e mensagem.

Use o gráfico para perceber cedo quando um sistema começa a falhar. Se o número de erros sobe de repente, confira o token, o endereço e se o sistema de destino está no ar. O OSBChat não guarda o conteúdo das chamadas, apenas se deram certo e quanto tempo levaram.

Só aparecem chamadas feitas depois que o registro foi ativado no seu ambiente.

Segredos

O segredo nunca é exibido de novo depois de salvo; a lista só indica se está Configurado.
Ao editar, deixe o campo em branco para manter o segredo atual, digite um novo valor para trocá-lo ou ligue Remover segredo para apagá-lo.
Ao trocar a autenticação para Nenhuma, remova também o segredo antigo.

Usar a conexão em um bot

Na configuração do bot, na ação de enviar o resultado a outro sistema (e na consulta de dados durante a conversa), escolha a conexão e informe apenas o caminho (ex.: /leads). O OSBChat monta a chamada com a URL base, a autenticação e os headers padrão da conexão.

Editar e excluir

O lápis abre a página da conexão, com o uso e a configuração.
Dentro da página, os ícones do topo atualizam os dados (descartando o que você mudou e ainda não salvou), salvam e excluem.
A lixeira exclui a conexão, com confirmação. Se algum bot ainda a usa para enviar resultados, a exclusão é bloqueada e a tela avisa quantos usos existem: troque a conexão nesses bots antes de excluir.
Uma conexão desativada (ou excluída) faz as chamadas dos bots que dependem dela deixarem de sair.

Dúvidas comuns

Situação	O que verificar
"Headers padrão: JSON inválido"	O texto precisa ser um objeto JSON válido, com aspas duplas.
Não consigo salvar com Bearer	Informe o token; ele é obrigatório ao criar.
"Endereço válido começando com http://"	A URL base precisa incluir `https://` (ou `http://`).
O teste dá "nada neste caminho"	Normal na raiz de muitas APIs. Informe um caminho de teste, como `/health`.
Chamada retorna 401/403	Confira o token, o nome do header e se a conexão está ativa.
A lista não carrega	Recarregue a página. Se continuar, fale com o suporte.