Manual da API do CRM
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).
- Endereço base:
https://crm.tphconsultoria.com.br - Formato: JSON em UTF-8, cabeçalho
Content-Type: application/json - Quem pode usar: qualquer organização do CRM, com o segredo do webhook dela
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:
| Campo | Obrigatório | Limite | O que é |
|---|---|---|---|
nome | sim | 150 | Nome da pessoa |
email | um dos dois | 150 | E-mail. É a chave que evita contatos repetidos |
telefone | um dos dois | 150 | Telefone ou WhatsApp |
empresa | não | 150 | Empresa da pessoa |
interesse | não | 200 | Produto ou serviço de interesse (no módulo Patyta, o nome da peça) |
mensagem | não | 4000 | Texto escrito pela pessoa |
origem | não | 150 | De onde veio o contato. Padrão: site |
recebido_em | não | 40 | Data e hora do envio no site (ISO 8601) |
consentimento_em | não | 40 | Data 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
- Novo: cria o lead (origem "landing"), guarda origem, interesse, mensagem, data e consentimento nas notas e avisa a equipe.
- E-mail que já existe: não cria outro lead. A nova mensagem entra nas notas do lead existente e a resposta traz
duplicate: true. Considere como sucesso. - Sem e-mail: cria um lead novo (a repetição é detectada pelo e-mail; só as organizações com o módulo Venda de imóveis ligado também detectam pelo telefone).
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.
| Campo | Limite | O que é |
|---|---|---|
produto_id | 60 | Identificador (UUID) da peça no catálogo do CRM |
produto_slug | 120 | Endereço da peça (o mesmo slug do site) |
categoria | 120 | Categoria, usada só se a peça não for encontrada no catálogo |
colecao | 120 | Coleção, usada só se a peça não for encontrada no catálogo |
- Como a peça é encontrada: por
produto_id, depois porproduto_slug, depois pelo nome eminteresse, sempre dentro do catálogo da própria organização. Se não achar, o interesse é guardado com o texto recebido. - Mesma pessoa, outra peça: vira um novo interesse (não sobrescreve o anterior), com aviso à equipe.
- Reenvio idêntico em até 10 minutos (nova tentativa do site) não duplica o interesse.
- Origem: se
origemcontiver "instagram" ou "whatsapp", usa essa; qualquer outra (por exemplo "Patyta Bonecaria") vira "Site". - Tipo de pedido: o CRM lê a mensagem e classifica (personalização, encomenda, presente, preço, prazo, disponibilidade ou informações).
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
| Campo | Limite | O que é |
|---|---|---|
utm_source | 150 | Canal de origem. Exemplos: blog, google, instagram |
utm_medium | 150 | Meio. Exemplos: cta, email, cpc |
utm_campaign | 150 | Campanha. No blog, o identificador (slug) do artigo |
utm_content | 150 | Qual CTA foi clicado. Exemplos: topo, meio, fim, barra |
pagina_entrada | 300 | Primeira página que a pessoa viu no site |
artigo | 150 | Identificador do artigo do blog (o mesmo do utm_campaign) |
Interesse no imóvel
| Campo | Limite | O 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_imovel | 60 | Exemplos: apartamento, casa, lote, sala comercial |
uf | 2 | Sigla do estado. Exemplos: DF, SP (maiúscula ou minúscula) |
cidade | 80 | Cidade |
bairro | 80 | Bairro |
faixa_valor | 60 | Texto 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 |
prazo | 60 | Quando 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
| Campo | Limite | O que é |
|---|---|---|
imovel_url | 300 | Endereço do imóvel no site (só http:// ou https://, sem espaços). Outro formato é descartado |
imovel_titulo | 150 | Tí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:
Compra: até 300 milCompra: 300 a 700 milCompra: 700 mil a 1,5 milhãoCompra: acima de 1,5 milhãoAluguel: até 2 milAluguel: 2 a 4 milAluguel: acima de 4 milAinda não sei
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.
- Convenção do campo
origem: useblog/identificador-do-artigoquando vier do blog,site/paginaquando vier direto do site, ewhatsappouinstagramnos demais casos. - Valor inválido não dá erro: campo desconhecido é ignorado, e um valor que não faz sentido (finalidade ou tipo de contato fora da lista, UF inexistente, quartos fora de 0 a 20, endereço que não é http/https) vira vazio. O contato é criado do mesmo jeito.
- Primeiro contato é preservado: se o lead já existir, o que já estava preenchido não é sobrescrito; só os campos vazios são completados.
- Mesma pessoa pelo telefone: com o módulo ligado, o mesmo telefone em qualquer formato (com ou sem +55, parênteses ou traços) conta como a mesma pessoa e a resposta traz
duplicate: true. - Aviso à equipe: lead novo chega como “Novo lead de imóvel: …” e lead que volta, como “Lead já cadastrado voltou a pedir contato”.
- Segurança: envie sempre pelo servidor do site ou do blog. O segredo nunca pode aparecer no JavaScript da página.
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ódigo | Quando acontece | Corpo |
|---|---|---|
| 200 | Contato novo criado | { "ok": true, "leadId": "…" } |
| 200 | Contato enviado em modo de teste | { "ok": true, "leadId": "…", "teste": true } |
| 200 | E-mail (ou, no módulo Venda de imóveis, telefone) que já existe na organização | { "ok": true, "leadId": "…", "duplicate": true } |
| 400 | JSON inválido, ou faltou nome ou contato (e-mail ou telefone) | { "error": "…" } |
| 401 | Segredo ausente ou inválido | { "error": "Não autorizado" } |
| 500 | Falha 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
- Chame do servidor do site, com timeout (10 segundos é razoável) e tratamento de erro.
- Não mostre detalhes técnicos ao visitante: use mensagens simples e registre o erro no log do servidor, sem gravar o segredo.
- LGPD: só envie dados que a pessoa autorizou e informe
consentimento_em. - Nova tentativa: se o CRM estiver fora do ar, guarde o contato e reenvie depois. O reenvio do mesmo contato não cria lead repetido (pelo e-mail).
- Volume: não há limite fixo publicado; evite rajadas de envios.
- Dúvidas: TPH Consultoria — (61) 99575-6131.
