API de leads

A API de leads serve para outro sistema (sua loja virtual, um ERP, uma landing com formulário próprio ou uma ferramenta de anúncios) mandar compradores direto para o TBA Origem: cada envio vira contato, negócio no funil e tarefa “Responder lead novo” no Hoje, como se a pessoa tivesse preenchido o seu formulário.

Passo a passo

1. Abra Canais › API e clique em Nova chave. Dê um nome que diga onde ela vai ser usada, como “Loja virtual” ou “ERP”.
2. Copie a chave na hora: ela começa com tbo_ e aparece uma vez só. Guarde num lugar seguro e passe para quem cuida do outro sistema.
3. O outro sistema envia cada lead com um POST para https://origem.tbahouse.com.br/api/public/leads, com o cabeçalho Authorization: Bearer seguido da chave e o corpo em JSON (exemplos abaixo).
4. Mande um lead de teste e confira: ele aparece no Funil, no Hoje e na ficha do contato, com a origem “API”.
5. Se a chave vazar ou não for mais usada, clique em Revogar na lista de chaves. Os envios com ela param na hora.

A chave é secreta: use só no servidor do outro sistema, nunca no código de uma página que abre no navegador. Para colocar um formulário pronto no seu site, sem programar, use o Formulário no site.

O que enviar

• Obrigatórios: name (nome) e pelo menos um entre email e phone (telefone com DDD).
• Opcionais: company (empresa), jobTitle (cargo), message (vira uma nota na ficha), origem (site, instagram, whatsapp, indicacao ou outro), utm (source, medium, campaign, term, content), pageUrl e referrer.
• LGPD: se a pessoa aceitou um texto de consentimento, mande consent com granted: true e o text exato que ela viu. Sem consentimento, informe legalBasis: legitimo_interesse, execucao_contrato, procedimentos_preliminares ou consentimento. Sem nenhum dos dois, o contato entra com a base “procedimentos preliminares”.
• Sem repetir: mande o cabeçalho Idempotency-Key com um código único do envio (o número do pedido, por exemplo). Se o mesmo envio chegar duas vezes, o lead não é duplicado e a resposta traz "repetido": true.
• Limites: até 120 envios por minuto por chave e corpo de até 50 KB.

A descrição técnica completa (formato OpenAPI) está em origem.tbahouse.com.br/openapi/leads.yaml.

Exemplo em curl

curl -X POST https://origem.tbahouse.com.br/api/public/leads \
  -H "Authorization: Bearer tbo_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br",
    "phone": "(35) 99999-0000",
    "company": "Empório Exemplo",
    "message": "Quero receber a lista de itens disponíveis.",
    "origem": "site",
    "utm": { "source": "google", "medium": "cpc", "campaign": "safra" },
    "pageUrl": "https://exemplo.com.br/contato",
    "consent": { "granted": true, "text": "Autorizo o contato comercial da Empório Exemplo." }
  }'

Resposta quando o lead é novo (HTTP 201):

{
  "ok": true,
  "id": "cm4x0...",
  "contatoId": "cm4x1...",
  "negocioId": "cm4x2...",
  "contatoNovo": true,
  "negocioNovo": true,
  "repetido": false
}

Quando a pessoa já era contato, ou quando o envio é repetido, a resposta vem com HTTP 200: contatoNovo falso diz que a ficha já existia; repetido verdadeiro diz que aquele Idempotency-Key já tinha sido recebido.

Exemplo em JavaScript

Para rodar no servidor (Node.js 18 ou mais novo, ou uma função da sua hospedagem), com a chave numa variável de ambiente:

const resposta = await fetch("https://origem.tbahouse.com.br/api/public/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TBA_ORIGEM_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `pedido-${pedido.id}`,
  },
  body: JSON.stringify({
    name: pedido.cliente.nome,
    email: pedido.cliente.email,
    phone: pedido.cliente.telefone,
    company: pedido.cliente.empresa,
    message: `Pedido ${pedido.id} na loja virtual`,
    origem: "site",
    legalBasis: "execucao_contrato",
  }),
});

const dados = await resposta.json();
if (!dados.ok) {
  // dados.erro explica o problema; dados.campos diz qual campo corrigir
  console.error(resposta.status, dados.erro, dados.campos);
}

Erros comuns

• 401, “Chave de API ausente, inválida ou revogada.” Confira se o cabeçalho é Authorization: Bearer seguido da chave completa (começa com tbo_) e se a chave não foi revogada em Canais › API.
• 400, “Corpo JSON inválido ou maior que 50 KB.” O corpo não é um JSON válido (aspas, vírgulas) ou passou de 50 KB. Mande Content-Type: application/json e confira o JSON.
• 422, “Falta alguma informação ou há algo para corrigir nos campos marcados.” Falta o nome, ou não veio e-mail nem telefone, ou o e-mail/telefone está incompleto. O campo campos da resposta diz qual corrigir, por exemplo phone: “Confira o telefone, com DDD”.
• 422, “Campos inválidos.” Algum campo veio com tipo errado ou grande demais (nome com mais de 160 caracteres, por exemplo). O campos mostra qual.
• 422, “legalBasis inválida.” Use um destes valores: consentimento, legitimo_interesse, execucao_contrato, procedimentos_preliminares.
• 429, “Limite de 120 envios por minuto atingido.” Espere um minuto e mande de novo; para importar uma lista grande de uma vez, use Importar planilha.
• O mesmo comprador apareceu uma vez só. É assim mesmo: o sistema junta pelo e-mail ou telefone. O envio novo fica registrado na ficha e vira a tarefa “Lead voltou a fazer contato”.
• Não vejo o botão Nova chave. Só o dono da conta cria e revoga chaves.

Veja também

• Formulário no site
• De onde vêm os leads