Integração SymplesDesk ↔ Pipedrive

Visão geral

A configuração de cada médico (funil, etapa, responsável, canal de WhatsApp) mora em três tabelas do banco (integration_channels, integration_pipelines e integration_pipeline_steps) — trocar de ambiente de teste para produção é editar essas linhas e o .env, nunca o código.

Além dos 4 fluxos, o serviço mantém o quadro de Oportunidades do SymplesDesk espelhando o CRM nos dois sentidos — hoje em dois funis: o de Leads, das SDRs, e o de Consulta, das Concierges — e encerra a conversa 24h depois de um lead ser dado como perdido. Essas partes não são "Fluxo 5 e 6": nasceram depois e funcionam em paralelo aos quatro.

Conceito central: pessoa ≠ ciclo

A regra mais importante de todo o sistema:

• Contato (pessoa) é durável — existe uma única vez por paciente, identificado pelo telefone. O mesmo paciente pode voltar quantas vezes for.
• Ciclo comercial (lead/deal) é repetível — cada retorno do paciente pode abrir um ciclo novo. Cada deal é uma linha própria no banco (1 pessoa : N deals), de propósito, para controle.
• Deal ganho ou perdido não bloqueia um novo ciclo. Só um ciclo ativo bloqueia duplicata — e quem responde "existe ciclo ativo?" é o banco, nunca uma varredura no Pipedrive.
• O telefone é comparado pela chave DDD + últimos 8 dígitos — o sistema ignora +55, nono dígito, hífen e espaço. +55 (32) 99811-7881 e 3298117881 são a mesma pessoa.

Quando um paciente inicia conversa no WhatsApp, o SymplesDesk abre um ticket e avisa o serviço, que cria o lead no funil certo do médico certo — sem duplicar paciente nem ciclo.

Como funciona

1. Confere se esse ticket já foi processado (reenvio do SymplesDesk não duplica nada).
2. Identifica o médico pelo canal de WhatsApp que recebeu a mensagem (config no banco).
3. Normaliza o telefone e acha ou cria o contato no banco.
4. Se o contato já tem ciclo ativo com esse médico → não cria nada (evita deal duplicado).
5. Se não tem: busca a pessoa no Pipedrive pelo telefone, em qualquer formato (+55, hífen, 9º dígito), varrendo até 300 candidatos. Quem já tem cadastro (com DDD válido) é vinculado — e o nome do cadastro preenche o banco. Cadastro sem DDD é ignorado de propósito (está errado no CRM): cria-se pessoa nova no formato correto 55+DDD+número.
6. Cria o deal no funil de Leads do médico — título telefone - sigla, responsável, etapa e etiqueta vindos da config.
7. Grava tudo no banco: ciclo ativo, deal, conversa e trilha de auditoria.

Quando a equipe marca um deal como perdido ou ganho no Pipedrive, o serviço reage:

Como funciona

1. Perdido: o serviço deixa uma nota interna no atendimento com o motivo —
   Deal perdido no Pipedrive: [título] / Motivo: [motivo da perda] — e o ciclo vira closed_lost no banco. A conversa NÃO fecha neste momento: ela fecha 24 horas depois, se o paciente não voltar (ver Fechamento da conversa).
2. Ganho: atualiza o banco (closed_won) e a conversa até o momento do ganho entra no deal na hora (ver Fluxo 4). Não fecha a conversa — o atendimento pós-ganho continua no WhatsApp (decisão da clínica).
3. Deal perdido que o banco ainda não conhece (criado à mão, ou anterior à integração) não é ignorado: o serviço busca a pessoa no Pipedrive, resolve o contato pelo telefone e fecha mesmo assim.
4. Se a API do SymplesDesk falhar, o banco é atualizado mesmo assim e um alerta no Discord avisa a equipe (a conversa não fica esquecida aberta sem ninguém saber).
5. O card da SDR também fecha, com o mesmo resultado do deal — ganho ou perdido (ver Cards de Oportunidade).

A automação só cria deal no funil de Leads (Fluxo 1). Nos funis de Consulta e Procedimentos, os deals são criados à mão pela equipe Concierge — este fluxo os captura para o banco, rastreando a jornada completa do paciente.

Como funciona

1. Deal novo criado à mão (Consulta/Procedimentos): o serviço resolve o paciente pelo telefone da pessoa do Pipedrive e grava o deal no banco. Nunca captura no funil de Leads (esse é papel do Fluxo 1) e nunca cria nada no Pipedrive — só observa.
2. Qualquer movimentação de deal (troca de etapa, troca de funil, reabertura): o banco sobrescreve a etapa atual do deal — ele espelha sempre o estado de agora, sem histórico de etapas.
3. Deal desconhecido que se move: é capturado na hora, com a etapa atual. Se for um deal aberto no funil de Leads, também ganha um ciclo ativo no banco.
4. Deal de funil que não é da integração (qualquer outro funil da conta) é ignorado.

Todas as mensagens trocadas no WhatsApp aparecem dentro do deal do paciente no Pipedrive, como uma atividade por dia de conversa. São duas partes:

Parte A — cada mensagem entra no banco

1. O SymplesDesk envia um webhook a cada mensagem (recebida ou enviada), autenticado por token.
2. O serviço grava a mensagem em symplesdesk_messages, vinculada ao contato certo (pelo ticket ou pelo telefone). Mensagens repetidas (reenvio) e apagadas não duplicam nem entram.
3. Segurança: o bloco de configuração que o fornecedor ecoa no payload (contém tokens) é removido antes de gravar.

Parte B — a conversa vira Activity no deal (dois gatilhos)

1. Todo dia às 19:00 (Brasília) — horário ajustável pela variável CONVERSATION_SYNC_CRON, sem mexer em código: o job agrupa as mensagens pendentes por paciente e por dia (incluindo o próprio dia até o horário do disparo) e cria uma Activity "Whatsapp - DD/MM/AAAA" por dia de conversa — somente em deals ABERTOS dos funis de Leads e Consulta. Paciente sem deal aberto: as mensagens aguardam (nada se perde) e entram no próximo deal.
2. Na hora do fechamento: quando um deal de Leads/Consulta é marcado como ganho ou perdido, toda a conversa pendente até aquele instante entra imediatamente nesse deal — sem esperar as 19h. (Ganho na SDR = a conversa completa até o ganho já fica no deal.)
3. Cada mensagem sincronizada guarda no banco qual deal a recebeu e quando — uma mensagem nunca vai pra dois deals nem é enviada duas vezes.
4. Se o serviço ficou fora do ar no horário, a próxima execução recupera os dias perdidos sozinha. Dias gigantes são divididos em partes ("Parte 1/2, 2/2…"). Falha em um paciente não derruba os demais e dispara alerta no Discord.

Formato da nota (mensagens do mesmo minuto são agrupadas, com o horário uma vez no fim; atendente aparece pelo nome):

Oi, tudo bem? Queria marcar.
15:07

Gabriel:
Oi! Claro, vou te passar as opções.
15:07

As SDRs trabalham no quadro de Oportunidades do SymplesDesk, sem precisar abrir o Pipedrive. Cada deal de Leads tem um card espelho, e os dois lados se acompanham nos dois sentidos: mover o card move o deal, e mover o deal move o card.

Do card para o deal

Do deal para o card

Quando o card aparece

1. Lead novo: o card nasce junto com o deal, na etapa de entrada.
2. Paciente antigo que volta a falar: o card é criado na hora da mensagem, já na etapa em que o deal está hoje — nunca na etapa de entrada, para o quadro não mentir sobre o estado do lead.
3. Paciente que nunca voltou a falar fica sem card de propósito: sem conversa não há o que trabalhar no quadro.

Quando um lead é ganho, o Pipedrive cria sozinho o negócio no funil de Consulta — isso já acontecia e continua igual. A novidade é que esse negócio agora também ganha um card, no funil "Funil de Consulta - Concierge" do quadro, com a Concierge do médico como dona. A Concierge passa a trabalhar no mesmo lugar que a SDR, sem abrir o Pipedrive.

Quando o card aparece

1. No ganho do lead: assim que o Pipedrive cria o negócio de Consulta, o card nasce — em poucos segundos, na primeira etapa do funil.
2. Paciente que já tinha consulta aberta: o card nasce na hora em que ele manda mensagem, já na etapa em que o negócio está hoje. É assim que a fila antiga entra no quadro: aos poucos, conforme cada paciente volta a falar — sem despejar centenas de cards de uma vez.

O que muda em relação ao card de Leads

O que funciona igual

Mover o card de etapa move o negócio no funil de Consulta, e vice-versa. Ganhar ou perder o card fecha o negócio com o mesmo resultado, e reabrir também acompanha. É a mesma mão dupla dos cards de Leads — só o renomear ficou de fora.

Quando um lead é dado como perdido, a conversa dele no WhatsApp não fecha na hora: fecha 24 horas depois. A janela existe para o paciente ter tempo de responder — muita reversão acontece nesse intervalo.

Ao fechar, o sistema deixa uma nota interna no atendimento: "Conversa encerrada automaticamente — lead perdido há 24h." O paciente não recebe nada.

Duas travas antes de fechar

1. Se o paciente voltou — tem qualquer negócio aberto — a conversa segue viva. Perdeu um lead mas abriu outro é paciente ativo, não caso encerrado.
2. Se existe conversa mais recente que a do lead perdido, o sistema não fecha: fechar a errada seria pior que não fechar.

Quando a SDR fecha na mão

Se alguém encerra o atendimento manualmente no SymplesDesk, o sistema fica sabendo e registra — e por isso não tenta fechar de novo o que já está fechado.

Mapa das etapas — Pipedrive ↔ quadro do SymplesDesk administrador

Os dois sistemas nomeiam as etapas de formas diferentes e usam números próprios. A tabela integration_pipeline_steps é a tradução entre eles — e é ela que faz o card acompanhar o deal e vice-versa.

Funil de Leads (SDR)

Funil de Consulta (Concierge)

O quadro é um só para os dois médicos — por isso a mesma etapa (52, por exemplo) traduz para funis diferentes conforme o médico do deal. Quem separa o trabalho de cada SDR e de cada Concierge é o filtro por responsável, não o quadro.

Ligar e desligar cada parte administrador

Toda automação pode ser desligada sem mexer em código e sem derrubar o resto. Útil para manutenção, teste, ou quando a clínica quer pausar um comportamento.

O que a API precisa para funcionar administrador

Quem vai apenas integrar com a API não precisa desta seção — toda interação de fora é pelos endpoints e webhooks. Os blocos abaixo são de quem opera o serviço: variáveis de ambiente (segredos) e os webhooks apontados para a URL pública.

1 · Variáveis de ambiente (.env)

Os valores reais nunca ficam no código nem nesta página — vivem só no .env do servidor.

2 · Banco de dados

O banco Postgres é parte interna do serviço e é imutável para terceiros: somente o administrador da integração cria as tabelas e mantém a configuração de canais e funis. Quem consome a API não precisa — nem consegue — acessar o banco; tudo acontece pelos endpoints. (Administrador: o passo a passo do banco está em Adicionar um médico e em Colocando no ar.)

3 · Webhooks

São 3 webhooks — cada um é criar na tela do sistema de origem e adicionar a URL da API. O passo a passo campo a campo de cada tela está no guia docs/WEBHOOKS.md do repositório.

Como adicionar um novo canal / médico administrador

Somente o administrador da integração executa estes passos — o banco é imutável para qualquer outra pessoa. Toda a configuração por médico é dado, não código: adicionar um médico novo é inserir linhas em duas tabelas, guardar um token no ambiente e criar os webhooks do canal. Nenhum deploy de código novo.

Passo 1 · Inserir o canal em public.integration_channels

Troque os valores em MAIÚSCULAS pelos reais (a tabela abaixo do SQL explica onde encontrar cada um):

INSERT INTO integration_channels
  (doctor_code, doctor_name, symplesdesk_account_id, symplesdesk_whatsapp_id,
   symplesdesk_base_url, symplesdesk_api_id, symplesdesk_token_secret_name,
   pipedrive_owner_id, pipedrive_pipeline_id, pipedrive_stage_id,
   pipedrive_label_id, is_active)
VALUES
  ('SIGLA', 'NOME DO MÉDICO', 'ACCOUNT_ID_SYMPLESDESK', 'WHATSAPP_ID',
   'https://serv2api.simplesdesk.com.br', 'API_ID_DA_CONFIG_DE_API',
   'SYMPLESDESK_TOKEN_SIGLA', 'OWNER_ID_PIPEDRIVE', 'ID_FUNIL_LEADS',
   'ID_ETAPA_ENTRADA', 'ID_ETIQUETA', true);

Passo 2 · Mapear os funis em public.integration_pipelines

Três linhas por médico — Leads (o funil onde o Fluxo 1 cria), Consulta e Procedimentos (funis que os Fluxos 2 e 3 rastreiam). Só o funil de Leads precisa de etapa:

INSERT INTO integration_pipelines
  (doctor_code, pipeline_type, pipedrive_pipeline_id, pipedrive_stage_id, is_active)
VALUES
  ('SIGLA', 'leads',         'ID_FUNIL_LEADS',         'ID_ETAPA_ENTRADA', true),
  ('SIGLA', 'consulta',      'ID_FUNIL_CONSULTA',      NULL,               true),
  ('SIGLA', 'procedimentos', 'ID_FUNIL_PROCEDIMENTOS', NULL,               true);

Passo 3 · Traduzir as etapas em public.integration_pipeline_steps

Sem esta tradução o card não acompanha o deal: o movimento é ignorado com registro, em silêncio. Uma linha por etapa, em cada funil que o médico novo vai usar (ver Mapa das etapas):

INSERT INTO integration_pipeline_steps
  (doctor_code, pipeline_type, step_name, symplesdesk_step_id, pipedrive_stage_id, step_order, is_active)
VALUES
  -- funil de Leads (SDR)
  ('SIGLA', 'leads',    'Cliente Potencial',    '52', 'ID_ETAPA_ENTRADA',    1, true),
  ('SIGLA', 'leads',    'Em conversa',          '50', 'ID_ETAPA_CONVERSA',   2, true),
  ('SIGLA', 'leads',    'Aguardando Pagamento', '48', 'ID_ETAPA_PAGAMENTO',  3, true),
  -- funil de Consulta (Concierge)
  ('SIGLA', 'consulta', 'Consulta Agendada',    '57', 'ID_ETAPA_AGENDADA',   1, true),
  ('SIGLA', 'consulta', 'Reagendamento',        '58', 'ID_ETAPA_REAGENDA',   2, true),
  ('SIGLA', 'consulta', 'Consulta Confirmada',  '59', 'ID_ETAPA_CONFIRMADA', 3, true);

As etapas do quadro (52, 50, 48 em Leads; 57, 58, 59 em Consulta) são as mesmas para todos os médicos — o quadro é único. O que muda por médico são os ids das etapas do funil no Pipedrive. A coluna pipeline_type é o que impede os números de se confundirem entre um funil e outro — nunca deixe de preenchê-la.

Passo 4 · Guardar o token no ambiente

No .env do serviço, crie a variável com o mesmo nome usado em symplesdesk_token_secret_name, com o token JWT gerado na config de API do canal:

SYMPLESDESK_TOKEN_SIGLA=<token JWT gerado na tela de APIs do SymplesDesk>

Passo 5 · Criar os webhooks do canal novo

• No SymplesDesk, na config de API do canal: webhook "Mensagem criada" → <URL-do-serviço>/webhooks/symplesdesk-newmessage (com o token do ambiente), o evento de novo atendimento → <URL-do-serviço>/webhooks/symplesdesk, o de Oportunidade → <URL-do-serviço>/webhooks/oportunidade e o de Atendimento finalizado → <URL-do-serviço>/webhooks/atendimento-finalizado.
• No Pipedrive não precisa de nada: o webhook de deals é um só para a conta inteira — o funil novo já entra pelo mapeamento do Passo 2.

Passo 6 · Reiniciar o serviço

A configuração de canais e funis é carregada na inicialização (fica em memória para não consultar o banco a cada mensagem). Depois de inserir as linhas, reinicie o serviço para o canal novo valer.

Endpoints

Se você vai integrar com a API, esta é a sua seção. Toda interação de fora é por HTTP — ninguém além do administrador acessa o banco.

Todos os webhooks respondem 200 mesmo em erro interno (o erro fica registrado no banco, em integration_events): se respondessem erro, o remetente reenviaria o evento e criaria duplicatas. A exceção é autenticação inválida, que responde 401 — ou 404 nas duas rotas mais novas, que não confirmam sequer a própria existência para quem não tem o token.

Cada resposta traz um outcome dizendo o que aconteceu (ex.: created, duplicate_ticket, active_session_exists, ignored_event) — a lista completa por endpoint está no docs/API.md do repositório.

Colocando no ar — passo a passo administrador

1. Deploy do serviço com o .env completo → gera a URL pública fixa da API.
2. Preparar o banco: rodar db/schema.sql + db/seed_prod.sql (limpo — os dados atuais são de teste).
3. Backfill: importar o histórico de deals do Pipedrive para o banco (npm run backfill, com --dry-run antes para conferir os números).
4. Criar o webhook "Mensagem criada" nos 2 canais do SymplesDesk com a URL da API (Fluxo 4).
5. Criar o webhook de deals no Pipedrive e apontar o evento de novo atendimento dos 2 canais para a URL da API (Fluxos 1, 2 e 3) — lembrando a regra de ouro: um destino por evento.
6. Validar com um atendimento real e acompanhar integration_events e os alertas do Discord.