Integração SymplesDesk ↔ Pipedrive ↔ Clínica nas Nuvens

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.

Desde 26/08 o serviço também cuida do prontuário no Clínica nas Nuvens quando uma Consulta é ganha: procura o paciente lá, liga ao contato se já existir e cria o cadastro se não existir. Detalhe na seção Cadastro no Clínica nas Nuvens.

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.

Quando uma Consulta é ganha — ou seja, o paciente passou de "Aguardando pagamento" e o negócio foi ganho no Pipedrive — o serviço procura essa pessoa no Clínica nas Nuvens. Já é paciente? Só registra a ligação. Não é? Cria o prontuário na hora, com os dados que já estão no Pipedrive.

Procurar antes de criar, e por quê

O Clínica nas Nuvens tem 42.126 pacientes e é a base da clínica há anos. Medimos a população exata deste gatilho: de cada 10 pessoas que ganham uma Consulta, 9 já são pacientes de lá. Criar sem procurar duplicaria prontuário em 9 de cada 10 vezes — e prontuário duplicado quebra histórico clínico, agenda e faturamento.

Por isso a busca vem primeiro, e ela é dupla: por CPF e, se não achar, por nome. A segunda existe porque só 20% dos prontuários do CnN têm CPF preenchido — "não achei pelo CPF" quase nunca significa "não existe". Na medição, sem a busca por nome o sistema teria criado 7 pacientes que já existiam, todos com prontuário antigo e sem CPF.

Quando as duas buscas não acham ninguém, o paciente é criado. Sem espera e sem fila.

Como funciona

1. O deal de Consulta é marcado como ganho no Pipedrive.
2. O serviço lê a pessoa no Pipedrive — CPF, data de nascimento e endereço.
3. Procura no Clínica nas Nuvens pelo CPF. Achou exatamente um? Liga os dois e acabou.
4. Não achou pelo CPF? Procura pelo nome. Se vier um único paciente e a data de nascimento bater, liga também.
5. O nome também não achou ninguém? Cria o paciente no Clínica nas Nuvens e já registra a ligação.
6. Achou dois ou mais parecidos, ou um só com nascimento diferente? Aí vai para a fila de revisão — ninguém escolhe entre prontuários parecidos sozinho.

O que isso entrega hoje

Rodado contra a base real, sobre 70 Consultas ganhas:

A fila de revisão

A fila não é onde o paciente novo espera — esse é criado direto. Ela guarda só o que o sistema não pode decidir sozinho, na tabela cnn_match_reviews, com o motivo de cada caso, e serve de relatório para a clínica:

Todo dia às 18h, o serviço lê a agenda de amanhã no Clínica nas Nuvens e manda, por WhatsApp, a lista para o grupo da clínica e, para cada médico configurado, a mesma lista no WhatsApp dele — sem passar pelo SymplesDesk nem pela Meta, e sem que a paciente veja nada.

Como funciona

1. Lê no Clínica nas Nuvens os agendamentos do dia seguinte.
2. Descarta quem não vai aparecer: agendamento cancelado ou marcado como faltou.
3. Busca o nome de cada paciente no cadastro do Clínica nas Nuvens — é o nome que a recepção reconhece, não o nome do CRM (que às vezes é só o telefone).
4. Busca o nome de cada profissional (médico ou fisioterapeuta) no catálogo de profissionais do Clínica nas Nuvens.
5. Monta uma mensagem que abre com 📅 *Agenda de <dia da semana>, <dd/mm>* — <N> atendimentos no total e, logo abaixo, os atendimentos agrupados por profissional: o nome do profissional em negrito, com 🩺 na frente e quantos atendimentos ele tem no dia, e, embaixo dele, uma linha por atendimento no formato HH:MM Nome, por horário. Quem atende mais cedo aparece primeiro. Se o profissional de um atendimento não for encontrado, a linha sai assim mesmo, sob (profissional indisponível).
6. Envia pela instância FZAP — um número de WhatsApp conectado por QR code, fora do SymplesDesk — ao destino de AGENDA_DESTINO: o grupo Agenda Pacientes Clínica Lindomar Delgado (ou um telefone).
7. Para cada médico de AGENDA_MEDICOS, manda ao WhatsApp dele a mesma lista completa que foi para o grupo — tenha ele atendimento no dia ou não. A leitura da agenda é uma só para todos.
8. Dia sem nenhum atendimento não gera mensagem alguma. E, depois de um envio que deu certo, a mesma data-alvo não sai de novo para aquele destino, mesmo que o job rode outra vez ou seja disparado à mão — cada destino (o grupo e cada médico) tem a sua própria trava.

📅 *Agenda de quarta, 16/09* — 3 atendimentos no total

🩺 *Dr. Fulano de Tal* - 2 atendimentos
08:00 Maria Silva
11:00 Ana Souza

🩺 *Beltrana Fisioterapeuta* - 1 atendimento
08:15 Joana Lima

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.