Integração de Formulários de Hotsite (Lead API Key)

A Caramelo AI oferece uma forma simples e segura para você enviar os contatos (leads) capturados em suas Landing Pages, Hotsites e formulários externos diretamente para o seu painel de Customers e automatizar seus fluxos de atendimento.

Para fazer isso sem expor dados sensíveis do seu projeto, utilizamos as Chaves de Hotsite (Lead API Keys).

Essas chaves são “públicas”, ou seja, foram desenhadas especificamente para serem colocadas no código JavaScript das suas páginas. Elas só possuem permissão para criar e atualizar contatos, sendo incapazes de ler ou excluir qualquer dado do sistema.

1. Como Gerar sua Chave de Hotsite

1. Acesse o Painel (Dashboard) da Caramelo AI e entre no seu Projeto.
2. No menu lateral esquerdo, clique em Integrações > Chaves de Hotsite (Leads).
3. Clique no botão Criar.
4. Insira um Nome (ex: “Landing Page Black Friday”) e uma breve descrição opcional.
5. Após criar, a sua chave (começando com lfk_) será exibida. Copie esta chave.

2. Como Integrar no seu Hotsite (JavaScript)

O envio dos dados é feito via requisição HTTP POST para nossa API pública, enviando a chave no cabeçalho X-Lead-Key.

Adicione o código abaixo no JavaScript que processa o clique no botão do seu formulário:

// Substitua o PROJECT_ID e a CHAVE_AQUI pelos seus dados reais.
const PROJECT_ID = "id_do_seu_projeto";
const LEAD_API_KEY = "lfk_sua_chave_aqui";

// Monta o payload com os dados do formulário
const leadData = {
	name: "João Silva", // Opcional: Nome do Lead
	email: "joao@exemplo.com", // Obrigatório: E-mail (usado como identificador único)
	phone: "11999999999", // Opcional: Telefone
	interests: "produto-x", // Opcional: Produto de interesse

	// Campo 'data' é livre. Use para campos personalizados que ficarão salvos permanentemente no perfil do cliente
	data: {
		plano_escolhido: "Plano Pro",
	},

	// Tags que serão adicionadas ao Lead
	tags: ["hotsite", "black-friday"],

	// Honeypot: Campo de segurança anti-robô (Deixe sempre VAZIO no envio via código!)
	_hp: "",
};

// Dados atrelados ao evento de conversão que aparecerão na "Timeline" do cliente
const eventData = {
	utm_source: "google",
	utm_campaign: "black-friday",
	page_url: window.location.href,
};

// Faz o disparo para a Caramelo AI
fetch(`https://api.carameloai.com/api/ext/project/${PROJECT_ID}/lead`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-Lead-Key": LEAD_API_KEY,
	},
	body: JSON.stringify({ 
		lead: leadData,
		event: eventData
	}),
})
	.then((response) => response.json())
	.then((data) => {
		if (data.success) {
			console.log("Lead enviado com sucesso! ID:", data.customer_id);
			// Redirecionar usuário ou exibir mensagem de sucesso
		}
	})
	.catch((error) => {
		console.error("Erro ao enviar lead:", error);
	});

3. Segurança Anti-Robô (Honeypot)

O endpoint de Leads conta com proteção nativa contra Spams através da técnica de “Honeypot” (Pote de mel) + Rate Limiting por IP.

O campo _hp presente no código acima deve ser enviado vazio. Se algum robô de spam varrer o seu código e preencher esse campo automaticamente com algum texto, a requisição será invalidada silenciosamente. O sistema fingirá que deu tudo certo para o robô, mas o Lead não será inserido no banco de dados da Caramelo.

4. Proteção por Domínio (Origem)

Para evitar que outras pessoas usem a sua chave em sites não autorizados, você pode restringir de quais domínios a sua chave aceita requisições.

Ao criar ou editar a sua Chave de Hotsite no Dashboard, existe um campo opcional para Domínios Permitidos (Origem).

• Se deixado em branco, a chave aceita requisições de qualquer lugar (útil para testes).
• Se você preencher com https://meuhotsite.com, https://outrosite.com, a API Caramelo AI validará o cabeçalho Origin da requisição e bloqueará automaticamente qualquer envio que venha de um domínio não listado.

5. Disparo de Fluxos (Automações)

Ao receber o post, a API fará uma busca no seu projeto:

1. A API fará a busca do contato usando estritamente o email fornecido.
2. Se o Lead não existir na base, ele será Criado usando todos os dados enviados (Nome, Telefone, WhatsApp, etc.).
3. Se o Lead já existir, o sistema focará na Integridade dos Dados: os campos principais (name, phone, whatsapp) não serão sobrescritos. Apenas os campos complementares (interests, observations, tags e data) serão atualizados ou mesclados com os dados já existentes no cliente.

Ativando o Fluxo: Não é necessário configurar nenhum webhook especial. Ao enviar os dados do Hotsite, a API naturalmente dispara o gatilho interno database__record_created ou database__record_updated. Basta criar um fluxo na Caramelo que seja “Iniciado ao criar ou atualizar cliente” e ele será ativado automaticamente, podendo enviar e-mails de boas vindas, avisar o time comercial, etc.

6. Timeline de Eventos

Sempre que um contato é criado ou atualizado via Hotsite utilizando essa API, a Caramelo AI registrará automaticamente um evento na aba “Timeline” dentro do perfil deste cliente no Painel.

• Histórico Completo (Payload Salvo): Independente de atualizar ou não os campos vitais do cliente, todos os dados enviados na requisição (tanto do objeto lead quanto do event) ficam guardados no evento da timeline. Isso garante que a sua equipe sempre conseguirá ver exatamente o que o Lead digitou em um determinado formulário, sem comprometer os dados oficiais do contato no sistema.
• Payload Adicional: O objeto event enviado na requisição (fora do objeto lead) é perfeito para armazenar informações pontuais e transitórias (ex: a URL onde ele converteu, as UTMs específicas daquela sessão ou informações temporárias do dispositivo).

Atenção (Limite de Payload): Para proteger a integridade do sistema, o endpoint de submissão de leads possui um limite estrito de 1MB de tamanho do corpo da requisição (payload size limit). Evite enviar arquivos encodados em Base64 através dessa rota.