TPH ConsultoriaTPH Consultoria - Tecnologia humana para negócios reais

Manual da API do CRM

Versão 1.2 · 07/10/2026 · Para quem vai ligar um site ou formulário ao CRM · PDF da versão 1.0 (as versões 1.1 e 1.2, com o módulo Venda de imóveis, estão só nesta página por enquanto)

Visão geral

O CRM da TPH Consultoria recebe contatos de sites e formulários externos por HTTP POST com JSON. Cada contato vira um lead na organização dona do segredo usado, e a equipe é avisada pelos canais que a organização configurou (Telegram, WhatsApp oficial).

Autenticação

Cada organização tem um segredo próprio, mostrado na Administração do CRM. O segredo identifica a organização de destino: quem o tem consegue criar contatos nela, então trate-o como uma senha.

Authorization: Bearer SEU_SEGREDO

Segredo ausente ou inválido devolve 401. Guarde o segredo em variável de ambiente ou no wp-config.php; nunca no código versionado nem no JavaScript do navegador. A chamada ao CRM deve sair sempre do servidor do site.

Enviar um contato — POST /api/webhooks/leads

Use para o formulário de contato de um site (por exemplo, WordPress). Cabeçalhos: Authorization: Bearer SEU_SEGREDO e Content-Type: application/json. Corpo em JSON:

CampoObrigatórioLimiteO que é
nomesim150Nome da pessoa
emailum dos dois150E-mail. É a chave que evita contatos repetidos
telefoneum dos dois150Telefone ou WhatsApp
empresanão150Empresa da pessoa
interessenão200Produto ou serviço de interesse (no módulo Patyta, o nome da peça)
mensagemnão4000Texto escrito pela pessoa
origemnão150De onde veio o contato. Padrão: site
recebido_emnão40Data e hora do envio no site (ISO 8601)
consentimento_emnão40Data e hora do aceite da política de privacidade (LGPD)

Campos de texto acima do limite são cortados. Informe nome e pelo menos um contato (e-mail ou telefone).

O que acontece com o contato

Módulo Patyta Bonecaria (campos opcionais)

Se a organização tem o módulo Patyta Bonecaria ligado, o mesmo endpoint também registra o interesse na peça. Os campos abaixo são opcionais; sem eles, o interesse usa o texto de interesse. Para organizações sem o módulo, nada muda.

CampoLimiteO que é
produto_id60Identificador (UUID) da peça no catálogo do CRM
produto_slug120Endereço da peça (o mesmo slug do site)
categoria120Categoria, usada só se a peça não for encontrada no catálogo
colecao120Coleção, usada só se a peça não for encontrada no catálogo

Módulo Venda de imóveis: origem e interesse (campos opcionais)

Para sites e blogs de corretores e imobiliárias (Tríade Imob TPH). Todos os campos abaixo são opcionais: quem não os envia não muda nada. Eles viram colunas do lead e alimentam o painel Venda de imóveis do CRM (leads por origem, por artigo, por cidade e por faixa de valor).

Origem

CampoLimiteO que é
utm_source150Canal de origem. Exemplos: blog, google, instagram
utm_medium150Meio. Exemplos: cta, email, cpc
utm_campaign150Campanha. No blog, o identificador (slug) do artigo
utm_content150Qual CTA foi clicado. Exemplos: topo, meio, fim, barra
pagina_entrada300Primeira página que a pessoa viu no site
artigo150Identificador do artigo do blog (o mesmo do utm_campaign)

Interesse no imóvel

CampoLimiteO que é
finalidade—Uma de: comprar, vender, alugar (procura imóvel para alugar), anunciar_aluguel (proprietário que quer colocar para alugar) e administrar (proprietário que quer a administração). Outro valor vira vazio
tipo_imovel60Exemplos: apartamento, casa, lote, sala comercial
uf2Sigla do estado. Exemplos: DF, SP (maiúscula ou minúscula)
cidade80Cidade
bairro80Bairro
faixa_valor60Texto livre, mas prefira a lista padrão (veja abaixo): textos iguais a ela, em qualquer combinação de maiúsculas e acentos, são padronizados
quartos—Número inteiro de 0 a 20
prazo60Quando pretende comprar ou vender. Exemplo: 90 dias
financiamento—sim ou não (também aceita true e false)

Imóvel de interesse e tipo de formulário

CampoLimiteO que é
imovel_url300Endereço do imóvel no site (só http:// ou https://, sem espaços). Outro formato é descartado
imovel_titulo150Título do imóvel. O painel mostra os imóveis mais procurados por este campo
tipo_contato—Qual formulário originou o contato: cadastro, interesse_imovel, anunciar, avaliacao, administracao ou contato. Outro valor vira vazio

Modo de teste

Para testar sem incomodar o atendimento, envie "teste": true (ou uma origem começando por teste/, por exemplo teste/integracao). O lead de teste é criado, mas não avisa a equipe, não se junta a um lead de verdade (mesmo e-mail ou telefone) e não entra nos números do painel. Aparece marcado como “Lead de teste” e o painel tem o botão Apagar leads de teste. A resposta traz teste: true.

Faixas de valor padrão

Para o painel não fragmentar a mesma faixa em textos diferentes, use exatamente:

Outros textos continuam aceitos como vieram. Cidades e bairros são agrupados no painel sem diferenciar maiúsculas e acentos (Brasília e Brasilia contam juntos). Para o Distrito Federal, a convenção é uf: DF, cidade: Brasília e bairro com a região administrativa; para o entorno de Goiás, uf: GO e a cidade.

Exemplo

curl -X POST https://crm.tphconsultoria.com.br/api/webhooks/leads \
  -H "Authorization: Bearer SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Silva",
    "telefone": "(61) 99999-0000",
    "email": "maria@exemplo.com",
    "interesse": "Comprar apartamento",
    "mensagem": "Quero ver opções de 3 quartos",
    "origem": "blog/guia-aguas-claras",
    "consentimento_em": "2026-10-06T14:30:00-03:00",
    "utm_source": "blog",
    "utm_medium": "cta",
    "utm_campaign": "guia-aguas-claras",
    "utm_content": "topo",
    "pagina_entrada": "/guia-aguas-claras",
    "artigo": "guia-aguas-claras",
    "finalidade": "comprar",
    "tipo_imovel": "apartamento",
    "uf": "DF",
    "cidade": "Brasília",
    "bairro": "Águas Claras",
    "faixa_valor": "300 a 500 mil",
    "quartos": 3,
    "prazo": "90 dias",
    "financiamento": "sim"
  }'

Respostas

CódigoQuando aconteceCorpo
200Contato novo criado{ "ok": true, "leadId": "…" }
200Contato enviado em modo de teste{ "ok": true, "leadId": "…", "teste": true }
200E-mail (ou, no módulo Venda de imóveis, telefone) que já existe na organização{ "ok": true, "leadId": "…", "duplicate": true }
400JSON inválido, ou faltou nome ou contato (e-mail ou telefone){ "error": "…" }
401Segredo ausente ou inválido{ "error": "Não autorizado" }
500Falha ao gravar no CRM{ "error": "…" }

Exemplos

curl

curl -X POST https://crm.tphconsultoria.com.br/api/webhooks/leads \
  -H "Authorization: Bearer SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "telefone": "11999990000",
    "interesse": "Boneca Jardim Encantado",
    "mensagem": "Tenho interesse nesta peça",
    "origem": "Patyta Bonecaria",
    "recebido_em": "2026-10-05T12:00:00Z",
    "consentimento_em": "2026-10-05T12:00:00Z",
    "produto_slug": "jardim-encantado"
  }'

WordPress (PHP)

<?php
// WordPress: rode no servidor (nunca no navegador). O segredo vem de variável
// de ambiente ou do wp-config.php, jamais do código versionado.
$segredo = getenv('CRM_WEBHOOK_SECRET');

$resposta = wp_remote_post('https://crm.tphconsultoria.com.br/api/webhooks/leads', [
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . $segredo,
        'Content-Type'  => 'application/json',
    ],
    'body' => wp_json_encode([
        'nome'             => sanitize_text_field($_POST['nome']),
        'email'            => sanitize_email($_POST['email']),
        'telefone'         => sanitize_text_field($_POST['telefone']),
        'interesse'        => sanitize_text_field($_POST['produto']),
        'produto_slug'     => sanitize_title($_POST['produto_slug']),
        'mensagem'         => sanitize_textarea_field($_POST['mensagem']),
        'origem'           => 'Patyta Bonecaria',
        'recebido_em'      => gmdate('c'),
        'consentimento_em' => gmdate('c'),
    ]),
]);

$codigo = wp_remote_retrieve_response_code($resposta);
$json   = json_decode(wp_remote_retrieve_body($resposta), true);
// 200 (novo ou duplicate=true): trate como sucesso. 400/401/500: registre o
// erro técnico no log do servidor e mostre uma mensagem simples ao visitante.

Formulário do Google (legado) — POST /api/webhooks/briefing

Para quem ainda usa o Google Forms com Apps Script. O caminho recomendado hoje é o formulário do próprio CRM, em /formulario/<link-da-organização>. Aqui o segredo vai no corpo, não no cabeçalho:

{
  "secret": "SEU_SEGREDO",
  "submittedAt": "2026-10-05T12:00:00Z",
  "answers": {
    "Nome completo": "Maria Silva",
    "E-mail": "maria@exemplo.com"
  }
}

answers é obrigatório. Nome, e-mail, telefone e empresa são extraídos das respostas. Com e-mail, o lead é criado ou atualizado e classificado pela IA. Respostas: 200 { ok, briefingId, leadId }, 400 (sem respostas ou JSON inválido) e 401 (segredo inválido).

Boas práticas