01 · Comece aqui
Uma entrada, um contexto, uma próxima ação
Esta página documenta somente a Parte 1: receber o lead e deixá-lo pronto no CRM. A origem é a conexão, o agente é resolvido no servidor e o payload nasce no backend do parceiro.
Backend parceiro
Envia o evento assinado para a URL pública da conexão.
Agente de destino
A conexão aponta para um agente primary ativo com instância válida.
CRM preparado
Lead, observação, origem, tags e atribuição ficam disponíveis para a etapa futura.
02 · Configuração
O frontend configura; o parceiro envia
A área administrativa cadastra a conexão e fornece credenciais. Nome, telefone, observação e tags não são campos para o usuário preencher nesta tela: eles pertencem ao contrato enviado pelo backend parceiro.
| Campo | Obrigatório | Uso editorial |
|---|---|---|
name | Sim | Nome exibido no CRM. |
phone | Sim | Telefone normalizado antes da busca do lead. |
email | Não | Contato complementar, quando disponível. |
observation | Não | Texto acrescentado ao histórico de notas. |
tags | Não | Nomes de tags existentes no catálogo da empresa. |
Configuração da conexão
Nome, agente primary ativo, etapa padrão, status ativo/pausado, URL pública e segredo.
Instância derivada
A instância não é escolhida no formulário; ela vem de agent.instance_name.
03 · Contrato
Um evento enxuto para o CRM
O parceiro envia apenas os dados do lead. Empresa, agente, instância, etapa, vendedor e status são resolvidos pela conexão e nunca vêm no payload.
POST https://api.itstime.pro/api/integrations/leads/v1/connections/{publicConnectionId}/events{
"name": "Maria Silva",
"phone": "5511999999999",
"email": "maria@example.com",
"observation": "Tem interesse em lentes multifocais.",
"tags": ["multifocal", "campanha-maio"]
}04 · Segurança
Assinar o corpo exato
O segredo fica no backend parceiro. Cada requisição deve usar timestamp, chave de idempotência e HMAC calculado sobre o corpo bruto.
signature = HMAC-SHA256(secret, timestamp + "." + rawBody)
X-Leads-Signature: sha256=<hash_hexadecimal>Use Idempotency-Key, X-Leads-Timestamp e X-Leads-Signature. A janela de timestamp evita replays; a chave evita duplicar o lead e a nota.
05 · Processamento
O que acontece depois do POST
Localizar a conexão e confirmar que está ativa.
Validar assinatura, timestamp, idempotência e agente.
Derivar a instância e normalizar o telefone.
Criar ou atualizar o lead dentro da mesma empresa.
Aplicar etapa e instância padrão somente na criação.
Acrescentar nota, vincular tags existentes e registrar o agente.
Tags inexistentes são ignoradas e retornadas em ignored_tags. Tags existentes são acumuladas; nenhuma tag antiga é removida.
06 · Rastreabilidade
O lead já nasce com memória do agente
Como o lead ainda não possui uma relação direta com o agente, o recebimento registra a atribuição inicial em first_touch_attribution.
{
"sourceType": "lead_webhook",
"connectionName": "Campanha Maio",
"agentId": "uuid-do-agente",
"agentName": "Bento",
"instanceName": "Loja Centro"
}07 · Operação
Respostas previsíveis e retentativas seguras
202 Accepted
Evento aceito ou reconhecido como duplicado idempotente.
401 / 409
Credencial inválida, conflito de idempotência ou conexão inconsistente.
429 / 503
Falha temporária: repetir com backoff e a mesma chave.
O mesmo evento reenviado com a mesma chave não duplica lead, observação ou vínculo de tags. Para falhas temporárias, o parceiro pode repetir mantendo a chave e gerando timestamp e assinatura novos.
08 · Visão futura
Parte 2 — atendimento do lead
Esta rodada não gera mensagem nem executa IA. A estrutura editorial, porém, já reserva o próximo passo: o agente analisa o contexto recebido e decide o primeiro contato.
Mensagem de texto
Usar a observação, tags e atribuição como contexto para gerar uma abordagem coerente.
Disparo de imagem
A mensagem poderá apontar para uma imagem hospedada no storage do usuário, desde que o link seja público, direto, HTTPS e acessível pelo provedor.
{
"type": "image",
"url": "https://storage.example.com/material/guia.jpg",
"caption": "Veja as opções que separamos para você."
}09 · Referência
OpenAPI como contrato; editorial como guia
Swagger/OpenAPI se aplica à parte técnica: descreve endpoint, headers, payloads e respostas para quem vai programar. A explicação de contexto, decisões e limites continua nesta página editorial.
10 · Finalização
Checklist da integração
- Conexão vinculada a agente primary ativo e com instance_name válido.
- Etapa padrão pertence à mesma empresa.
- URL e segredo guardados somente no backend parceiro.
- Payload contém nome e telefone, sem dados de roteamento.
- HMAC calculado sobre o corpo bruto.
- Idempotency-Key preservada nas retentativas.
- Fonte, instância, etapa, observação e tags aparecem no Kanban.
- Nenhum agente ou provedor de mensagens é executado na Parte 1.