Leads (Oportunidades)

Envie leads para o funil comercial do OctaBuild por dois caminhos:

Ambos criam a pessoa (lead), a oportunidade, o touchpoint de conversão e disparam a distribuição automática (roleta) numa única transação — a menos que a requisição peça o contrário (ver Distribuição abaixo).

Rastreabilidade

Todo lead carrega uma hierarquia de atribuição:

Os catálogos de Origem, Canal e Mídia são gerenciados em Configurações → Comercial → Origens & Canais.

Distribuição

Por padrão todo lead novo entra nas roletas ativas, que sorteiam o responsável. Dois campos, aceitos pelos dois caminhos, mudam esse comportamento:

O sdr_id é o id do usuário (o mesmo do painel), e ele precisa ser membro da organização — caso contrário a requisição é recusada com 400 e nada é gravado. Leads com distribuir: false e sem sdr_id ficam sem responsável até alguém assumi-los no painel.

Tags

Os dois caminhos aceitam tags com o código de cada tag. O código aparece ao lado do nome em Configurações → Comercial → Tags, com botão de copiar.

{ "nome": "Maria Silva", "telefone": "+5561999990000", "tags": ["investidor", "feirao-set"] }

A resposta traz o desfecho sempre que a requisição mandou tags:

"tags": {
  "aplicadas": ["investidor"],
  "ignoradas": [{ "codigo": "feirao-set", "motivo": "nao_encontrada" }]
}

Lead duplicado e permitir_alteracao

Telefone, e-mail e CPF são exclusivos entre oportunidades ativas da organização. Por padrão, reenviar um lead já cadastrado é recusado com 409 — nenhum dado do lead existente é alterado (a re-entrada fica registrada como conversão, contando no dashboard).

Envie permitir_alteracao: true (aceito pelos dois caminhos) para que a requisição atualize o lead existente em vez de ser recusada:

Atualização incremental significa: só os campos presentes na requisição são gravados (o valor enviado substitui o atual); campo ausente preserva o que já estava lá. O cônjuge enviado é criado/vinculado normalmente.

O que nunca muda nesse caminho: fase, status, responsável/SDR (o lead não é redistribuído nem troca de dono) e a atribuição de primeiro toque — origem, canal, mídia, campanha e ponto de captação só são preenchidos se estiverem vazios. A atribuição da nova entrada fica no touchpoint da conversão.

{
  "success": true,
  "data": {
    "oportunidade_id": "550e8400-e29b-41d4-a716-446655440000",
    "numero": 169,
    "created": false,
    "updated": true,
    "duplicate_field": "telefone",
    "message": "Já existia a oportunidade #169 cadastrada com este telefone — dados atualizados com sucesso."
  }
}

Lead scoring e temperatura

Formulários de qualificação (landing page, quiz, calculadora) normalmente já calculam uma nota para o lead. Envie essa nota em score — aceito pelos dois caminhos — e o OctaBuild registra a pontuação e classifica o lead automaticamente.

A escala esperada é 0 a 100, inteiro. A faixa (temperatura) é derivada da nota:

A temperatura aparece como etiqueta na lista de oportunidades e no kanban, e serve de critério de ordenação para o time comercial priorizar o atendimento.

Sem score, o lead entra com a nota padrão 10 (frio) — o mesmo comportamento de antes desta funcionalidade, então integrações existentes não mudam.

O corpo inteiro do formulário continua arquivado no lead, então as respostas que geraram a nota ficam disponíveis para auditoria mesmo que só a nota seja exibida na tela.

{
  "nome": "Maria Silva",
  "telefone": "+5561999990000",
  "score": 72
}

No webhook, score também aceita os nomes alternativos lead_score, pontuacao e nota, valor em texto ("72"), e decimal — que é arredondado. Valor negativo ou não numérico é ignorado e o lead cai no padrão 10.

Respostas de qualificação (probabilidade de conversão)

A ficha do lead tem um painel Qualificação com seis perguntas que somam até 10 pontos; a soma × 10 é a probabilidade de conversão. Duas dessas respostas podem chegar direto do formulário, e o painel já abre pontuado:

O rótulo é lido pelo sentido, não por igualdade exata: variações como "Até R$ 2.500", "Entre 3500 e 4500" ou "CLT" também são reconhecidas. Valor que não se reconhece fica em branco (o lead é criado normalmente e o corpo segue arquivado). Com permitir_alteracao: true, a resposta nova substitui a anterior; numa reentrada sem essa flag, só preenche o que estava vazio.

Esta pontuação é independente de score: score define a temperatura (quente/morno/frio), e as respostas definem a probabilidade de conversão do painel.

{
  "nome": "Maria Silva",
  "whatsapp": "+5561999990000",
  "situacao_trabalho": "Renda Formal",
  "renda_faixa": "Abaixo de R$2.500/mês"
}

POST /v1/oportunidades

Cria (ou detecta duplicidade de) uma oportunidade. Requer API Key.

Body

Objeto conjuge

Quando o lead é casado, envie os dados do cônjuge — o OctaBuild cria (ou reusa, por CPF e depois telefone) o cadastro da pessoa e a vincula à oportunidade como conjuge:

Request

curl -X POST "https://api.octabuild.ai/v1/oportunidades" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Silva",
    "telefone": "+5561999990000",
    "email": "maria@email.com",
    "channel": "instagram",
    "media_type": "midia_paga",
    "campaign_name": "Lançamento Jardins",
    "ad_set_name": "Publico frio DF",
    "ad_name": "Video 30s",
    "utm_source": "instagram",
    "utm_medium": "paid_social",
    "utm_campaign": "lancamento-jardins",
    "documento": "123.456.789-00",
    "estado_civil": "casado",
    "renda_mensal": 8500,
    "cep": "71900-000",
    "logradouro": "Rua das Palmeiras",
    "numero": "120",
    "bairro": "Águas Claras",
    "cidade": "Brasília",
    "uf": "DF",
    "conjuge": {
      "nome": "João Silva",
      "telefone": "+5561988880000",
      "documento": "987.654.321-00"
    },
    "tags": ["investidor", "feirao-set"]
  }'

Response — 201 Created (ou 200 se já existia em modo merge)

{
  "success": true,
  "data": {
    "oportunidade_id": "550e8400-e29b-41d4-a716-446655440000",
    "numero": 42,
    "created": true,
    "tags": {
      "aplicadas": ["investidor", "feirao-set"],
      "ignoradas": []
    }
  }
}

Response — 409 Conflict (duplicado)

Telefone, e-mail ou CPF já usados em oportunidade ativa bloqueiam o cadastro (nada é gravado). Para atualizar o lead existente em vez de receber o erro, envie permitir_alteracao: true (ver Lead duplicado acima):

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TELEFONE",
    "message": "Já existe uma oportunidade ativa com este telefone (#42)."
  }
}

Códigos possíveis: DUPLICATE_TELEFONE, DUPLICATE_EMAIL, DUPLICATE_CPF, VALIDATION_ERROR (400), RATE_LIMITED (429).

POST /api/webhooks/inbound/{token}

Webhook de entrada para fontes low-code (Typebot, Zapier, n8n, landing pages). Crie a fonte em Configurações → Integrações → Webhooks — a URL com o token é exibida na criação.

• Origem e Canal dos leads desta fonte são definidos no cadastro do webhook (não no corpo).
• Se a fonte tiver segredo, envie o header x-webhook-secret.
• Rate limit: 120 requisições/minuto por fonte.

Body (contrato fixo)

Além dos campos de atribuição (utm_*, ad_id, form_id, referrer_url, landing_url, campaign_name, ad_set_name, ad_name — mesmos significados da API v1), o webhook aceita campos de qualificação:

O corpo inteiro da requisição é arquivado no lead para auditoria (payload do touchpoint), então campos extras não são perdidos — apenas não são estruturados.

Request

curl -X POST "https://app.octabuild.ai/api/webhooks/inbound/wh_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: whsec_seu_segredo" \
  -d '{
    "nome": "Maria Silva",
    "telefone": "+5561999990000",
    "email": "maria@email.com",
    "utm_source": "instagram",
    "utm_campaign": "lancamento-jardins",
    "campaign_name": "Lançamento Jardins"
  }'

Response

201 (criado) / 200 (fundido ou atualizado) com { success, data: { oportunidade_id, numero, created, updated } }, ou: