Clínica Lindomar Delgado · Guia operacional

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

Serviço que liga o atendimento de WhatsApp (SymplesDesk) ao CRM (Pipedrive) e, desde 26/08, o CRM ao prontuário (Clínica nas Nuvens) — gravando tudo em um banco de dados próprio, em tempo real. Esta página explica o que cada parte faz e o que é preciso configurar para cada uma funcionar — sem precisar abrir o repositório.

Atualizado em 06/11/2026 · o CEP e o número escritos no endereço do Pipedrive passam a valer quando o Pipedrive não os reconhece por dentro, para a mudança de endereço chegar ao Clínica nas Nuvens. No mesmo dia: ligados em produção os campos Sexo, Gênero, Nome social, Estrangeiro, Ramal e a cidade do endereço na sincronização do cadastro. Antes, em 29/10: o RG não vai mais ao Clínica nas Nuvens: o campo "Número de identificação" de lá é para passaporte de estrangeiro, e preenchido em paciente brasileiro a nota fiscal dá erro. A criação do paciente e a sincronização deixaram de escrever nele. Antes, em 27/10: o ganho da Consulta já atualiza a ficha no Clínica nas Nuvens, na hora, sem precisar editar a pessoa; a passada das 20h fica como rede de segurança. No mesmo dia: a sincronização do cadastro passa a tratar o Pipedrive como verdade absoluta: campo preenchido nos dois lados com valores diferentes recebe o do Pipedrive, na primeira vez e sempre; edição feita direto no Clínica nas Nuvens é desfeita na sincronização seguinte; vazio no Pipedrive continua não apagando nada; a lista de divergências saiu do processo (decisão da clínica, 27/10). Antes, em 23/10: o cadastro no Clínica nas Nuvens lê a pessoa do negócio (antes lia a do contato, e parte dos ganhos parava em "não tem pessoa vinculada" num negócio que tinha pessoa). Na sincronização do cadastro, o que vai ao Clínica nas Nuvens passa a ser o da pessoa do negócio de Consulta do paciente, guardada na ligação dele (sem ela, vale a pessoa do contato), e a sincronização tem um sentido só: o Pipedrive é a fonte da verdade e o Clínica nas Nuvens nunca escreve de volta. Ligada em 27/10, com a largada sobre os pacientes ligados e uma cópia de segurança das fichas feita antes. Desde 09/10 o cadastro exige CPF para criar paciente (sem CPF ainda liga a quem já existe, mas não cria, e avisa no negócio); preenchido o CPF na pessoa, o serviço tenta de novo sozinho. Desde 08/10: sem fila de revisão, busca ampliada antes de criar e aviso no próprio negócio

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.

Desde 02/10 o serviço também emite a nota fiscal (NFS-e) dos deals ganhos, pela Bellacare (consulta) e pela Lindomar Delgado (cirurgia e fisioterapia): ele monta a nota, uma pessoa confere e confirma no Pipedrive, e só então ela vai ao governo. Detalhe na seção Emissão automática da NFS-e.

Conceito central: pessoa ≠ ciclo

A regra mais importante de todo o sistema:

Entrada de lead (SDR)

gatilho: webhook "Novo atendimento" (NewTicket) do SymplesDesk

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.

O que precisa para funcionar

  • Criar o webhook no SymplesDesk (um por canal), com o evento de novo atendimento marcado, e adicionar a URL da API: <URL-do-serviço>/webhooks/symplesdesk. Importante: esse evento deve apontar para uma URL só — dois destinos criariam deal duplicado.
  • Preencher a tabela integration_channels no banco (canal → médico → funil/etapa/responsável) — o SQL pronto está em Como adicionar um novo canal.
  • Definir no ambiente: PIPEDRIVE_BASE_URL e PIPEDRIVE_API_TOKEN.

Deal perdido / ganho

gatilho: webhook do Pipedrive (deal.updated, mudança de status)

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). O ganho de Consulta, Procedimentos ou fisioterapia também grava no deal os dados do paciente para a NFS-e e cria a atividade "Emitir NFS-e" (ver Dados para a NFS-e e Emissão automática da NFS-e).
  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).
Mudou em 07/08/2026. Até então a conversa fechava na hora da perda, por uma configuração da tela do SymplesDesk (não pelo código). Isso encurtava a janela de recuperação do paciente. As duas configurações foram trocadas para "Manter aberto", e o fechamento passou a ser o de 24h.

O que precisa para funcionar

  • Criar um webhook no Pipedrive (Configurações → Ferramentas → Webhooks, versão 2): objeto deal, ações create + change, e adicionar a URL da API: <URL-do-serviço>/webhooks/pipedrive, preenchendo usuário e senha (Basic Auth) com os mesmos valores do ambiente.
  • Criar um 2º webhook no Pipedrive para o sync de nome do contato: objeto person, ação change, mesma URL e mesma Basic Auth. Sempre que alguém editar o nome de uma pessoa no Pipedrive, o serviço atualiza o nome no banco (só o nome — o telefone é a identidade do contato e nunca muda por aqui). Com a nota de dados da NFS-e ligada, o mesmo webhook refaz a nota dos deals da pessoa.
  • Definir no ambiente os tokens da API externa do SymplesDesk, um por canal (SYMPLESDESK_TOKEN_T e SYMPLESDESK_TOKEN_A) — já validados contra a produção em 22/07/2026.
  • Opcional: DISCORD_ERROR_WEBHOOK_URL para os alertas de falha.

Captura Concierge e movimentação

gatilho: o mesmo webhook do Pipedrive (deal.added e deal.updated)

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.

O que precisa para funcionar

  • O mesmo webhook do Pipedrive do Fluxo 2 — um único webhook cobre os dois fluxos, nada extra pra criar.
  • Preencher a tabela integration_pipelines com os funis mapeados (Leads, Consulta e Procedimentos por médico) — o SQL pronto está em Como adicionar um novo canal.

Conversas do WhatsApp dentro do deal

gatilho: webhook "Mensagem criada" + job diário 19:00 + fechamento do deal

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

O que precisa para funcionar

  • Criar o webhook "Mensagem criada" nas 2 configurações de API do SymplesDesk (uma por canal) e adicionar a URL da API: <URL-do-serviço>/webhooks/symplesdesk-newmessage, colando no campo "Token de autenticação" o mesmo valor de SYMPLESDESK_WEBHOOK_TOKEN do ambiente.
  • Marcar somente o evento "Mensagem criada" na tela (outros eventos são ignorados com segurança, mas geram tráfego à toa).
  • Definir no ambiente: PIPEDRIVE_ACTIVITY_TYPE_WHATSAPP_KEY — a chave do tipo de atividade "Whatsapp" na conta do Pipedrive (sem ela o job falha de propósito, para nunca criar atividade de tipo errado).

Cards de Oportunidade — o quadro do SymplesDesk

gatilho: mão dupla — deal muda no Pipedrive, ou card muda no quadro

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

A SDR faz no cardAcontece no Pipedrive
Arrasta para outra etapao deal muda de etapa no funil
Marca como ganhoo deal vira ganho
Marca como perdidoo deal vira perdido, com o motivo
Renomeia o cardo nome da pessoa é corrigido no CRM

Do deal para o card

Alguém faz no PipedriveAcontece no quadro
Move o deal de etapao card acompanha
Ganha ou perde o dealo card fecha com o mesmo resultado
Corrige o nome da pessoao card é renomeado
Reabre um deal fechadoo card volta a abrir

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.
Duas regras que evitam confusão. (1) O telefone nunca sobrescreve um nome. Quando o paciente ainda não tem cadastro, o card nasce com o telefone — mas assim que alguém escreve o nome de verdade, o telefone nunca mais volta por cima. (2) Eco não vira pingue-pongue. Toda mudança que chega é comparada com o estado atual: se já está igual, o sistema para. Foi o que impediu 326 idas e voltas desnecessárias em 30 horas.

O que precisa para funcionar

  • Criar o webhook "Oportunidade" nas configurações de API do SymplesDesk, apontando para <URL-do-serviço>/webhooks/oportunidade e colando no campo "Token de autenticação" o valor de SYMPLESDESK_OPORTUNIDADE_WEBHOOK_SECRET.
  • Preencher o mapa de etapas (integration_pipeline_steps) — ver a seção Mapa das etapas. Sem a tradução, o movimento é ignorado com registro: o sistema nunca chuta uma etapa.
  • Definir a SDR dona dos cards de cada canal (symplesdesk_responsible_user_id): é por esse campo que cada uma filtra o quadro compartilhado para ver só os cards dela.
  • Definir o motivo de perda fixo de cada canal (symplesdesk_lost_reason_id): o fornecedor recusa fechar card como perdido sem motivo. O motivo real continua no Pipedrive e na nota — este é só o exigido pela tela.

Cards de Consulta — o quadro da Concierge

gatilho: negócio de Consulta criado no ganho do lead, ou paciente com consulta aberta que volta a falar

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

 Card de Leads (SDR)Card de Consulta (Concierge)
Dona do carda SDR do médicoa Concierge do médico
Nome do cardmontado pelo sistema: nome - siglacópia exata do nome do negócio: CONSULTA DE nome
Etapasas do funil de Leadsas do funil de Consulta
Renomear o cardcorrige o nome da pessoa no CRMnão propaga nada — ver abaixo

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.

Por que renomear não propaga. O card de Consulta copia o nome do negócio letra por letra — é assim que os dois lados ficam reconhecíveis como a mesma coisa. Se o sistema também tentasse "corrigir" nomes por aqui, ele empurraria o texto inteiro ("CONSULTA DE Maria") por cima do nome da paciente no CRM. Já aconteceu uma vez, em 06/08, e foi por isso que a regra virou: nome de card de Consulta nasce colado ao do negócio e ninguém mexe depois.
O nome do card é uma fotografia do momento do ganho. Se a paciente ainda estava cadastrada com o telefone quando o lead foi ganho, o card de Consulta nasce com o telefone — e não muda sozinho depois, mesmo que alguém corrija o cadastro. Para renomear, é na tela, dos dois lados.

O que precisa para funcionar

  • Definir a Concierge dona dos cards de cada canal (symplesdesk_concierge_user_id): é o campo que liga esta parte. Vazio, nenhum card de Consulta é criado — e o resto do sistema segue normal.
  • Preencher o mapa de etapas do funil de Consulta (integration_pipeline_steps com pipeline_type = 'consulta') — ver a seção Mapa das etapas.
  • Nada de webhook novo: a captura usa os mesmos que os fluxos 3 e 4 já usam.
A automação do Pipedrive continua sendo a dona do negócio. Quem cria o negócio de Consulta no ganho é ela, como sempre foi — o serviço só acompanha, criando o card e ligando os dois. Se um dia a automação criar dois negócios iguais, aparecerão dois cards: o quadro espelha o CRM, não o corrige.

Fechamento da conversa, 24h depois da perda

gatilho: verificação automática de hora em hora, aos :15

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.
Por que existe um teto por rodada. O sistema fecha no máximo um punhado de conversas por execução. Não é limitação técnica: é proteção do fornecedor, cuja API já desativou um webhook nosso sozinha depois de receber falhas em sequência. Com o teto, o que sobra é fechado na hora seguinte — nada se perde.

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.

O que precisa para funcionar

  • Marcar o evento "Atendimento finalizado" na configuração de webhook do SymplesDesk, apontando para <URL-do-serviço>/webhooks/atendimento-finalizado, com o valor de SYMPLESDESK_ATENDIMENTO_WEBHOOK_SECRET no campo "Token de autenticação".
  • ⚠️ A rota precisa estar no ar ANTES de criar o webhook: o fornecedor desativa sozinho uma configuração que aponta para endereço inexistente.
  • Opcional: CLOSE_LOST_CRON (horário) e CLOSE_LOST_MAX_PER_RUN (teto) — ver Ligar e desligar.

Cadastro no Clínica nas Nuvens

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 buscas não acham a mesma pessoa, o paciente é criado — com ou sem CPF. Sem espera e sem fila de revisão: desde 08/10 nenhum caso fica parado esperando alguém decidir.

Como funciona

  1. O deal de Consulta é marcado como ganho no Pipedrive — em qualquer um dos quatro funis de Consulta (Dr. Lindomar, Dr. Thiago, Dr. Augusto e Dra. Larissa), inclusive deal antigo que nunca passou pelo banco. Ganho de Leads, Procedimentos, fisioterapia e Resgate não dispara o cadastro.
  2. O serviço lê a pessoa do negócio no Pipedrive — CPF, data de nascimento e endereço. É a mesma pessoa que a nota fiscal usa: se o negócio foi passado para outra pessoa, vale a que está nele.
  3. Tem CPF? Procura no Clínica nas Nuvens pelo CPF. Achou? Liga os dois e acabou. Se o CnN tiver mais de um prontuário com aquele CPF, liga ao mais antigo.
  4. Não achou pelo CPF, ou a pessoa ainda não tem CPF no Pipedrive? Procura pelo nome. Se algum paciente parecido tiver a mesma data de nascimento, liga a ele (havendo mais de um assim, ao mais antigo).
  5. Ninguém pelo nome completo? Faz uma busca ampliada: procura pelo primeiro nome e pelo último sobrenome, e liga a quem tiver a mesma data de nascimento e o nome compatível — o primeiro nome e pelo menos mais um batendo, aceitando uma letra trocada. É o que pega nome do meio faltando, sobrenome a mais e erro de digitação.
  6. Ainda ninguém? Cria o paciente no Clínica nas Nuvens e já registra a ligação — só se a pessoa tiver CPF válido. Sem CPF, não cria: avisa no negócio que falta o CPF.
  7. Quando o CPF (ou o que faltava) é preenchido no cadastro da pessoa, o serviço tenta de novo sozinho e atualiza o aviso. Vale para Consulta ganha nos últimos 30 dias.
Sem CPF não se cria paciente (decisão de 09/10). Sem CPF não há como provar que a pessoa ainda não existe no Clínica nas Nuvens — a busca forte de lá é só por CPF —, e era justamente a criação sem CPF que gerava prontuário duplicado. Sem CPF, o serviço ainda liga a quem já existe (por nome e nascimento), mas não cria ninguém.
Onde ainda pode duplicar: quando o prontuário antigo do CnN não tem CPF nem data de nascimento, ou quando o primeiro nome está diferente nos dois sistemas — aí o serviço não tem como reconhecer a pessoa e cria um segundo prontuário. Duplicata assim se resolve juntando os dois prontuários no próprio Clínica nas Nuvens. Espaço sobrando, maiúscula e acento não atrapalham.
A data de nascimento é o que separa mãe e filha. Telefone repetido entre parentes é caso comum numa clínica, então o telefone não decide sozinho — ele no máximo confirma. Medido: o telefone não resolveu um caso sequer que o nascimento já não resolvesse.

O que isso entregou

Em produção, de 26/08 a 07/10, sobre 98 Consultas ganhas: 45 ligadas a prontuários que já existiam (15 pelo CPF, 30 por nome + nascimento), 2 criadas e 50 paradas numa fila de revisão que ninguém resolvia. A fila acabou em 08/10. Refazendo esses casos pelas regras de hoje, a grande maioria liga sozinha: em 32 de 36, o CPF tinha sido preenchido no Pipedrive minutos depois do ganho.

O aviso no negócio

Em todo ganho de Consulta, o serviço deixa uma nota "Cadastro no Clínica nas Nuvens" no próprio negócio dizendo o que aconteceu: paciente criado (com o número do prontuário), já existia e foi ligado (pelo CPF ou por nome e nascimento), ou não cadastrado — e o que falta para cadastrar. A nota fica fixada só quando alguém precisa agir (não cadastrou). Corrigido o cadastro da pessoa, o serviço tenta de novo e a mesma nota é reescrita — nunca empilhada. Ganho repetido também reescreve a mesma nota.

Quando o cadastro não acontece

Em quatro situações o serviço não cria o paciente. Nelas, ele registra o motivo (evento cnn_patient_ensure), avisa no negócio e segue sem cadastrar:

MotivoO que houve
sem_cpfa pessoa não tem CPF válido e não foi achada no CnN — sem CPF não se cria; preenchido o CPF, o serviço tenta de novo sozinho
sem_nascimentofalta a data de nascimento — é obrigatória para criar no CnN
sem_nomeo "nome" no Pipedrive é o próprio telefone; viraria um prontuário chamado "5532991997896"
sem_pessoao negócio não tem pessoa vinculada no Pipedrive (ou ela foi apagada)
Um ganho de Consulta nunca é prejudicado por isto. Se o Clínica nas Nuvens estiver fora do ar, se o CPF estiver errado, se a criação falhar — o deal é ganho normalmente e o erro fica registrado. Esta parte nunca derruba o fluxo principal. E o mesmo paciente nunca é criado duas vezes, mesmo que o ganho seja registrado de novo: a ligação já gravada barra.

Sincronização do cadastro com o Clínica nas Nuvens

Em uso desde 27/10. Antes de ligar, o serviço rodou ensaios somente leitura, a clínica recebeu os números e escolheu o Pipedrive como fonte, uma cópia de segurança das fichas foi guardada e a largada levou à Clínica nas Nuvens o que faltava ou diferia nos pacientes ligados.

Depois que o paciente existe nos dois sistemas, o cadastro dele precisa ser o mesmo nos dois. A clínica escolheu uma fonte da verdade: o Pipedrive. A correção feita no Pipedrive vai para a ficha do paciente no Clínica nas Nuvens; o Clínica nas Nuvens nunca escreve de volta. Vale só para pacientes já ligados a um contato (a ligação é a do cadastro).

Regra para a equipe: cadastro se corrige no Pipedrive. O que for corrigido direto no Clínica nas Nuvens não chega ao Pipedrive e é desfeito na próxima sincronização daquele paciente: o valor do Pipedrive volta. Para um dado ficar, ele tem de estar no Pipedrive.

O que é sincronizado

Nome, CPF, data de nascimento, e-mail e endereço (CEP, rua, número, complemento e bairro). O estado não vai: no Clínica nas Nuvens ele vem junto da cidade.

O RG não vai ao Clínica nas Nuvens. O campo "Número de identificação" de lá é para o passaporte ou documento de paciente estrangeiro: preenchido em paciente brasileiro, a nota fiscal dá erro. Nem a criação do paciente nem a sincronização escrevem nesse campo, e o que estiver nele fica como está.

Campos novos — ligados em 06/11

Em uso desde 06/11/2026. Cada campo abaixo só é sincronizado quando está configurado no .env do servidor (ver a tabela de variáveis); tirar a variável desliga só aquele campo. Os cinco primeiros existem na ficha da pessoa do Pipedrive (criados em 03/11 com o script scripts/criar-campos-pipedrive-cnn.ts, que não duplica campo se rodar de novo).

Valem as mesmas regras dos outros campos: o Pipedrive vence quando tem valor, vazio no Pipedrive não apaga o Clínica nas Nuvens, e opção que não corresponde a nenhuma da lista (renomeada na tela, por exemplo) não é enviada — fica registrada como desconhecida. Os mesmos campos, quando configurados, também entram na ficha do paciente criado no ganho da Consulta.

O telefone nunca é sincronizado. Ele é a identidade do contato no serviço. Se o telefone for diferente nos dois lados, sai um ⚠️ Aviso no Discord, uma vez por contato, e nada é alterado em lado nenhum.

De qual pessoa vem o cadastro

O cadastro que vai ao Clínica nas Nuvens é o da pessoa do negócio de Consulta do paciente — a que a equipe edita e a mesma que a nota fiscal usa. A ligação do paciente guarda esse negócio e essa pessoa. Enquanto a ligação não tem pessoa, vale a pessoa do contato, como antes; sem nenhuma das duas, o paciente fica de fora e nada é escrito.

Editar uma pessoa duplicada não muda mais o prontuário. Se o contato do paciente está numa pessoa repetida no Pipedrive (outra pessoa com o mesmo telefone), a edição feita nessa repetida não vai ao Clínica nas Nuvens: vale a pessoa do negócio de Consulta. Corrija o cadastro na pessoa do negócio.

Como funciona

As regras

Como desfazer

Antes da primeira gravação em massa, o serviço guarda uma cópia da ficha inteira de cada paciente ligado, num arquivo fora do sistema (ela tem CPF e endereço). Se algo sair errado, o caminho de volta é: desligar a chave CNN_SYNC_PUSH_ENABLED e republicar, para a sincronização parar de escrever; depois rodar a restauração, que compara cada ficha com a cópia e devolve a cópia por regravação só onde algo mudou, um paciente ou todos, lendo de novo depois para conferir. O Pipedrive nunca é tocado, nem na ida nem na volta.

A lista de divergências

Deixou de fazer parte do processo em 27/10: a clínica decidiu que o Pipedrive vale sempre que tem valor, então diferença entre os dois sistemas é corrigida pela própria sincronização, não revisada em planilha. O script ainda gera, sob demanda, a lista do que só o Clínica nas Nuvens tem (o Pipedrive vazio), para quem quiser completar o Pipedrive à mão. O que é "só no Clínica nas Nuvens" nunca é apagado.

Apagar um campo no Pipedrive não apaga no Clínica nas Nuvens (a única exceção é o endereço trocado em bloco). O Pipedrive fica vazio e o Clínica nas Nuvens mantém o valor. Para trocar um dado, corrija — não apague.
Nenhum fluxo é prejudicado por isto. Se o Clínica nas Nuvens ou o Pipedrive estiver fora do ar, a edição fica marcada e é refeita na passada diária; a resposta ao Pipedrive e os outros fluxos seguem normais. A escrita do próprio serviço não volta como edição nova: o serviço compara com o último estado que gravou.

Dados do paciente para a NFS-e

gatilho: webhook do Pipedrive — deal de Consulta, Procedimentos ou fisioterapia ganho, e pessoa alterada

Esta parte deixa os dados do tomador prontos e conferidos numa nota fixada no próprio deal: a atendente não precisa abrir a pessoa no Pipedrive, escolher telefone nem procurar CEP no Google. Sozinha, ela não emite nada: quem emite é a emissão automática da NFS-e, a seção seguinte, que usa exatamente estes dados. Para a nota feita à mão no portal nacional (nfse.gov.br), os mesmos dados servem pelo botão descrito abaixo. (No repositório, esta parte é o Fluxo 7.)

Ligada desde 02/10/2026, junto com a emissão automática: a nota nasce em todo deal ganho de Consulta, Procedimentos, "Fisioterapia - Indicação Pacote" e "Fisioterapia Avulsas". Com NFSE_DADOS_ENABLED diferente de true, nenhum dado é montado, nenhuma nota é gravada — e a emissão automática também para, porque depende desta nota.

Como funciona

  1. Um deal de Consulta, de Procedimentos ou de fisioterapia ("Indicação Pacote" ou "Avulsas") é ganho no Pipedrive. Leads e "Fisioterapia - Tratamento" não geram nota.
  2. O serviço lê a pessoa do deal: nome, CPF, e-mail e endereço. O telefone é o da conversa do WhatsApp, sem o 55 — nunca outro telefone do cadastro.
  3. Confere o CEP do endereço numa base pública de CEP (ViaCEP). CEP que não existe, ou que é de outra rua, é recusado; aí o serviço procura o CEP pela rua e pela cidade e só usa o que achar se for um único. Se o paciente tem endereço no Clínica nas Nuvens, ele entra como segunda opção.
  4. Separa "número, apartamento" (120, 403) em número e complemento, e completa o bairro vazio com o bairro do CEP.
  5. Grava a nota "Dados para a NFS-e", fixada no deal e ligada à pessoa, com os campos na ordem da tela "Pessoas" do portal: CPF, nome, telefone, e-mail, CEP, município, bairro, logradouro, número e complemento. No fim vem a linha "Código para o portal", com os mesmos dados numa linha só (começa com NFSE1:).
  6. Quando a pessoa é alterada no Pipedrive (um CEP corrigido, por exemplo), a nota de cada deal dela é reescrita — nunca duplicada. Nota igual à anterior não é reescrita.

Pronta ou pendente

Sem problema nenhum, a nota sai pronta. Com problema, sai pendente e abre com a lista do que corrigir, cada item apontando o campo do cadastro da pessoa:

PendênciaO que houveOnde corrigir
cpfCPF vazio ou inválidocampo "CPF" da pessoa
nomenome vazio ou igual ao telefone"Nome" da pessoa
enderecoa pessoa não tem endereçocampo "Endereço" da pessoa
tomador_exteriortelefone de fora do Brasilconferir o "Telefone" da pessoa; no portal, o tomador é do exterior
cepo CEP não confere com a rua ou a cidade, e a busca pela rua não achou um CEP único"CEP" no endereço da pessoa
cep_indisponivela base de CEP não respondeuconferir o "CEP" no endereço; a próxima alteração da pessoa confere de novo
bairrobairro vazio no cadastro e no CEP — o portal exige"Distrito/sub-localidade" no endereço da pessoa

A nota também avisa quando o CEP do cadastro estava errado ou vazio e foi trocado pelo CEP achado pela rua, e quando o Clínica nas Nuvens tem outro endereço (com o CEP dele) — nos dois casos, para a equipe conferir e corrigir o cadastro.

Corrija no cadastro da pessoa, não na nota. A nota é gerada pelo serviço: editada à mão, ela é sobrescrita na próxima alteração da pessoa. Corrigido o cadastro, a nota se refaz sozinha.

Botão para o portal

Serve para a emissão à mão: deals ganhos antes de 02/10, paciente do exterior, ou quando a equipe decide emitir pelo portal em vez da integração (ver Emissão automática da NFS-e).

A linha "Código para o portal" existe para um favorito do navegador que cola os dados do tomador direto na tela "Pessoas" do portal. A página que instala o favorito é /docs/nfse-botao: basta arrastar o botão verde para a barra de favoritos (Ctrl+Shift+B mostra a barra).

Na hora de usar, a ordem importa — a tela do portal nasce trancada:

  1. na tela "Pessoas", responda "Preencher as informações IBS/CBS?" e escolha a Data de Competência. É isso que libera os campos do tomador;
  2. copie a linha NFSE1: da nota "Dados para a NFS-e" do deal;
  3. clique no favorito e cole o código.

Ele preenche CPF, nome, telefone, e-mail e o endereço inteiro, e abre sozinho o bloco do endereço (marca o "Informar endereço"). Esse é o único clique que ele dá: nunca Avançar, nunca Emitir — quem confere e emite é a atendente. Nada sai do portal: o dado chega por copiar e colar.

É normal o portal trocar o bairro e o logradouro depois do preenchimento. Quando o CEP entra, o portal faz a própria busca e escreve o endereço oficial dele por cima, além de preencher o município sozinho. Número e complemento continuam como vieram da nota. Se o favorito avisar que não achou algum campo, esse se preenche à mão.
Conferido na tela real do portal em 25/09/2026, no ambiente de produção restrita da Receita, com paciente fictício e sem emitir nota nenhuma.

Carga dos ganhos recentes

A nota nasce nos ganhos novos. Para quem já está em tratamento ter a nota desde o primeiro dia, o administrador roda a carga dos ganhos dos últimos 90 dias:

npx tsx scripts/nfse-dados-carga.ts --dias 90 --dry-run   # só conta: nada é gravado
npx tsx scripts/nfse-dados-carga.ts --dias 90             # grava as notas (só com NFSE_DADOS_ENABLED=true)

O --dry-run monta as notas e mostra quantas sairiam prontas e quantas pendentes, por motivo, sem gravar nada no Pipedrive nem no banco. A lista vem do banco (deals ganhos que ainda não têm nota), e rodar de novo não duplica: deal com nota fica de fora. A consulta de CEP espera 400 ms entre uma e outra — uns 15 minutos para 300 deals. A carga de verdade só roda com a chave ligada (NFSE_DADOS_ENABLED=true): com ela desligada, o script recusa com uma mensagem e não grava nada. O --dry-run roda sempre, com a chave ligada ou desligada.

Um ganho nunca é prejudicado por isto. Se o Pipedrive, a base de CEP ou o Clínica nas Nuvens falhar, o deal é ganho normalmente e a resposta do webhook não muda. Base de CEP fora do ar vira a pendência cep_indisponivel; Clínica nas Nuvens fora do ar, a nota sai só com o Pipedrive; falha ao gravar a nota no Pipedrive fica registrada no evento nfse_dados de integration_events, e a próxima alteração da pessoa refaz a nota.

O que precisa para funcionar

  • No banco: a tabela nfse_dados_notas, criada à mão pelo administrador com o DDL pronto em docs/ddl-dados-nfse.sql. Ela guarda só o estado de cada nota (pronta, pendente ou erro) e a trava contra nota duplicada — nunca CPF nem endereço.
  • No ambiente: PIPEDRIVE_CPF_FIELD_KEY e PIPEDRIVE_ADDRESS_FIELD_KEY, as mesmas do cadastro no Clínica nas Nuvens. Sem elas, toda nota sai pendente de CPF e de endereço.
  • Para ligar: NFSE_DADOS_ENABLED=true e reiniciar o serviço. Padrão false — desligado.
  • Opcional: as credenciais do Clínica nas Nuvens (CNN_CLIENT_ID, CNN_CLIENT_SECRET, CNN_CID). Com elas, o endereço do prontuário entra como segunda opção; sem elas, a nota usa só o Pipedrive.
  • Nenhum webhook novo: são os de deal e de pessoa do Pipedrive que já existem (ver Fluxo 2).
  • ⚠️ Ordem: tabela → chaves → --dry-run da carga → ligar → carga de verdade. Até o dry-run precisa da tabela, porque é nela que ele confere quem já tem nota.

Emissão automática da NFS-e

gatilho: deal ganho no Pipedrive + conclusão das atividades de nota, conferida a cada 5 minutos

A nota fiscal dos deals ganhos sai pela integração, direto no Emissor Nacional, com o certificado digital de cada empresa. Ninguém digita nota: a integração monta, uma pessoa confere e confirma no próprio deal, e só então a nota vai ao governo. Nenhuma nota é enviada sem que alguém conclua a confirmação.

Vale para os deals ganhos a partir de 02/10/2026. Deal ganho antes disso não ganha atividade e segue emitido à mão no portal, como antes. E o contrário também vale: deal que tem a atividade "Emitir NFS-e" não é emitido à mão — duas emissões do mesmo serviço são nota em dobro, que só se desfaz cancelando no portal.

Quem emite o quê

Funil do deal ganhoEmpresa que emiteConcluir a atividade…
Consulta (de todos os médicos)Bellacaresó depois que o paciente veio e pagou a consulta inteira
Procedimentos (cirurgia)Lindomar Delgadosó depois que a cirurgia foi realizada
Fisioterapia - Indicação PacoteLindomar Delgadodepois da primeira sessão do pacote
Fisioterapia AvulsasLindomar Delgadodepois da sessão realizada

Não geram nota: Leads e "Fisioterapia - Tratamento" — esse funil acompanha as sessões; a venda do pacote é o "Indicação Pacote".

Quem recebe as atividades de nota

A atividade "Emitir NFS-e" não vai para a vendedora: vai para quem emite aquele tipo de nota daquele médico. O médico e o tipo saem do funil do deal (Consulta ou Procedimentos), não do canal de WhatsApp do paciente.

Funil do deal ganhoRecebe a "Emitir NFS-e"
Dr. Thiago — Consulta (10)Mayze Freitas
Dr. Thiago — Procedimentos (7)Isabella Salomão
Dr. Augusto — Consulta (12)Luiza
Dr. Augusto — Procedimentos (9)Leticia Rodrigues
Fisioterapia — Indicação Pacote (13) e Avulsas (19)Leticia de Paula (a Letícia Beatriz), sempre
Dr. Lindomar (11 e 4) e L.R (16 e 17)o dono do deal, como antes — ainda não há regra para eles

Trocar, tirar ou incluir uma responsável administrador

As listas são linhas no banco, na tabela nfse_responsaveis: uma por pessoa, com o grupo ('T:consulta', 'T:cirurgia', 'A:consulta', 'A:cirurgia' ou 'fisio'), a posição no rodízio, o id do usuário no Pipedrive (Configurações → Usuários) e o nome. Não precisa de deploy nem de reiniciar: a mudança vale a partir da próxima atividade. Exemplos:

-- trocar quem emite as notas de cirurgia do Dr. Thiago
UPDATE nfse_responsaveis SET pipedrive_user_id = 'ID_DO_USUARIO_NO_PIPEDRIVE', nome = 'NOME'
 WHERE grupo = 'T:cirurgia' AND posicao = 1;

-- incluir uma segunda pessoa nas consultas do Dr. Augusto (as duas passam a alternar)
INSERT INTO nfse_responsaveis (grupo, posicao, pipedrive_user_id, nome)
VALUES ('A:consulta', 2, 'ID_DO_USUARIO_NO_PIPEDRIVE', 'NOME');

-- tirar essa segunda pessoa depois (a linha fica, desligada)
UPDATE nfse_responsaveis SET is_active = false
 WHERE grupo = 'A:consulta' AND posicao = 2;

-- trocar quem está na posição 1 da fisioterapia
UPDATE nfse_responsaveis SET pipedrive_user_id = 'ID_DO_USUARIO_NO_PIPEDRIVE', nome = 'NOME'
 WHERE grupo = 'fisio' AND posicao = 1;

-- conferir
SELECT grupo, posicao, pipedrive_user_id, nome, is_active
  FROM nfse_responsaveis ORDER BY grupo, posicao;

Como funciona, passo a passo

  1. O deal é ganho. Nasce nele a atividade "Emitir NFS-e (Bellacare) — conferir e concluir" (ou "(Lindomar)"), para a responsável pela nota daquele médico (ver Quem recebe as atividades de nota), dizendo a empresa, o serviço, o valor atual e quando concluir. Junto, a nota fixada "Dados para a NFS-e" (seção anterior).
  2. Valor. Na consulta, se o deal está com R$ 0, a integração preenche com o preço da consulta daquele médico na tabela do Clínica nas Nuvens, e a atividade avisa "(preenchido pela tabela do Clínica nas Nuvens)". Na cirurgia e na fisioterapia, vale o valor do deal como está. Nos dois casos: se houve desconto ou cortesia, corrija o valor do deal antes de concluir.
  3. A atendente confere os dados do paciente na nota "Dados para a NFS-e" e corrige no cadastro da pessoa o que estiver errado.
  4. Prestado o serviço, ela conclui a atividade "Emitir NFS-e".
  5. Em até 5 minutos, a integração monta a nota com o valor do deal naquele momento e cria a atividade "Confirmar emissão da NFS-e (Bellacare) — R$ 1.200,00" (com a empresa e o valor do caso), para quem está com a "Emitir NFS-e" naquele momento. Nela está a nota inteira, por escrito: a primeira linha diz "Ambiente: produção", depois a empresa e o CNPJ, o tomador (nome, CPF, endereço, telefone e e-mail), o serviço com os códigos, o valor e os tributos.
  6. A atendente confere e conclui a confirmação. Em até 5 minutos a nota vai ao governo — exatamente a que foi mostrada, sem remontar.
  7. Saiu: o deal ganha a nota "NFS-e emitida nº … — chave …", e a nota aparece no portal nacional, em "Notas emitidas".
Uma nota só por deal, pelo valor total — nunca uma por parcela. Concluir de novo, reabrir e ganhar o deal outra vez, o mesmo evento do Pipedrive chegando duas vezes: nada disso gera segunda nota. Dois deals do mesmo paciente (uma consulta e uma cirurgia, por exemplo) são duas notas, uma em cada deal.
O que se confirma é o que sai. Depois que a confirmação nasceu, mudar o cadastro da pessoa ou o valor do deal não muda a nota. Para valer a mudança, refaça a nota (abaixo).

A descrição da nota

A descrição sai sempre com a mesma grafia:

ServiçoDescrição
ConsultaConsulta médica
CirurgiaProcedimento cirúrgico realizado no paciente NOME / na paciente NOME
Fisioterapia (pacote ou avulsa)Tratamento pós cirúrgico realizado no paciente NOME / na paciente NOME

O "no" ou "na" vem do sexo registrado no prontuário do Clínica nas Nuvens. Quando o prontuário não informa, a frase sai neutra — "realizado em NOME" —, nunca adivinhada pelo nome. O nome vai como está no cadastro da pessoa no Pipedrive.

Quando a nota não sai

A integração não chuta e não força. Quando a nota não pode sair, a atividade volta a ficar aberta, com o motivo, a data e a hora no topo (⚠️ … — a nota não saiu: …), e o grupo da clínica no WhatsApp recebe um aviso com o nome do paciente, o serviço, o valor, o motivo e o link do deal — nunca CPF, endereço, telefone ou e-mail.

MotivoO que fazer
Pendência no cadastro: CPF, nome, endereço, CEP ou bairrocorrigir no cadastro da pessoa e concluir a atividade de novo
Telefone de fora do Brasilpaciente do exterior: a nota é feita à mão
Valor do deal zeradopreencher o valor do deal e concluir de novo
O deal não está ganho (foi perdido ou reaberto)conferir o deal; se o serviço foi prestado, ganhar de novo e concluir
Recusada pelo governoa confirmação volta aberta com "Recusada pelo governo:" e o texto que o governo devolveu. Concluir a confirmação de novo não emite: corrija e reabra a "Emitir NFS-e" (refazer, abaixo), ou emita à mão
Governo fora do ar por mais de 1 horaa integração tenta a cada 5 minutos; passada 1 hora, reabre a confirmação e para de tentar. Concluir a confirmação de novo tenta outra vez; ou emita à mão e exclua a confirmação
Falha técnica da integração por mais de 1 horaconcluir de novo mais tarde, ou emitir à mão e apagar a atividade
Configuração fiscal incompletaavisar o suporte — é ajuste do administrador, não do cadastro

Refazer, emitir à mão ou desistir

Nada sai em dobro. Cada deal tem um número de nota fixo e, antes de enviar, a integração pergunta ao governo se aquela nota já existe — se já existe, só registra. Por isso evento repetido, queda no meio do envio ou conclusão repetida nunca geram segunda nota. O que duplica nota é emitir à mão um deal sem antes excluir a atividade da integração.

O que ainda não faz: não manda a nota para o e-mail do paciente (quem precisar, baixa no portal nacional) e não cancela nota.

O que precisa para funcionar

  • No banco: as tabelas nfse_emissoes e nfse_funis_fisio e, para as responsáveis pela nota, nfse_responsaveis e nfse_responsaveis_vez (ver O que a API precisa).
  • Ligada: NFSE_DADOS_ENABLED=true, NFSE_ATIVIDADE_ENABLED=true e NFSE_ATIVIDADE_ESCOPO=todos. Em produção: NFSE_AMBIENTE=producao e NFSE_ENVIO_ENABLED=true. Com confirmação: NFSE_EMISSAO_MODO ausente (ver Ligar e desligar).
  • Os dois certificados A1, Bellacare e Lindomar, e a configuração fiscal (NFSE_SERIE_DPS, NFSE_BELLACARE_PTOTTRIBSN) — ver as variáveis em O que a API precisa.
  • Avisos: o número da FZAP conectado (o mesmo da agenda) e NFSE_AVISO_DESTINO apontando para o grupo da clínica.
  • Para o preço da consulta: as credenciais do Clínica nas Nuvens e CNN_CONVENIO_PARTICULAR_ID. Sem eles, o valor da consulta não é preenchido e a atividade avisa para preencher à mão.
  • Nenhum webhook novo: a conclusão das atividades é lida por uma varredura a cada 5 minutos, só das atividades que a integração criou.
  • Alertas no Discord: certificado ausente, com senha errada ou de outro CNPJ; certificado vencendo em menos de 30 dias (Bellacare vence em 22/06/2027, Lindomar em 25/06/2027); nota que não passa na validação antes do envio; certificado recusado pelo governo.
  • Conferência sem risco: npx tsx scripts/sonda-nfse-envio.ts lista as notas montadas e em envio e reconfere a validação e a assinatura — somente leitura.

Agenda do dia seguinte no WhatsApp

gatilho: cron diário às 18h (America/Sao_Paulo)

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.
Só profissional, horários e nomes. A mensagem não traz procedimento nem resumo de conversa — e não chega à paciente em nenhuma hipótese: o destino é sempre um número da equipe. Exemplo:
📅 *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
Os médicos de AGENDA_MEDICOS recebem exatamente esse mesmo texto. (no WhatsApp, o texto entre asteriscos aparece em negrito)
Se alguma coisa falha, o Discord avisa. Falha ao ler a agenda no Clínica nas Nuvens, número da FZAP desconectado (é preciso reconectar pelo QR code) ou envio que não vingou: os três casos geram alerta. Nos dois primeiros, nada é enviado. Uma lista acima de 4.000 caracteres sai em partes — se o envio falhar no meio, as partes que já saíram ficam no destino, e o alerta diz quantas. Se o envio para um médico falhar, o alerta diz qual médico, e o grupo e os outros médicos recebem normalmente.

O que precisa para funcionar

  • Definir no ambiente AGENDA_DESTINO (quem recebe a lista geral: o grupo 120363411914071233@g.us, ou um telefone só com dígitos e DDI) e TOKEN_FZAP (o token da instância) — o job só é agendado quando os dois existem (ver Ligar e desligar).
  • A instância FZAP precisa estar conectada (sessão ativa por QR code) na hora do disparo — desconectada, o serviço não envia e alerta pedindo a reconexão.
  • Opcional: AGENDA_CRON muda o horário do disparo (padrão 0 18 * * *, 18h) e FZAP_BASE_URL muda o endereço da instância, se um dia precisar trocar.
  • Opcional: AGENDA_MEDICOS manda a lista completa também ao WhatsApp de cada médico. Formato idpessoa:telefone, separados por vírgula — por exemplo 20689417:5532999999999. Par escrito errado é ignorado (e avisado no log), sem derrubar nada. Para incluir um médico: acrescentar o par e fazer redeploy. Os códigos:
    idpessoaProfissional
    20689417Dr. Thiago Ferreira Delgado
    20741719Dr. Augusto Cesar de Melo Almeida
    22509355Dr. Lindomar Delgado
    22647395Dra Larissa
    16918290Melissa Monica de Castro Teixeira
    27210466Riviane Marques da Costa Alves

SymplesDesk novo — a conta 142

gatilho: webhook da conta 142 — Conversa Criada, Mensagem criada e Status de conversa alterado

Em 17/09/2026 o fornecedor migrou a clínica do SymplesDesk antigo (serv2) para a plataforma nova, chat.simplesdesk.com.br, conta 142 — baseada no Chatwoot. Os avisos do sistema antigo pararam de chegar e, desde então, nenhum lead entra sozinho no Pipedrive. Esta parte liga o serviço à conta nova sem mudar nenhuma regra: o que chega é traduzido na porta de entrada e segue pelo mesmo Fluxo 1 e pela mesma gravação de mensagens de sempre; e as duas escritas no atendimento — a nota da perda e o fechamento de 24h — passam a ir para a conta 142.

No ar desde 22/09/2026, 10:40. Na primeira meia hora, 4 conversas novas de pacientes viraram lead sozinhas. O teste com o número de teste passou por conversa nova, mensagens, áudio, encerramento na tela e nota da perda. O passo a passo seguido e o registro do go-live estão na spec da feature (.specs/features/symplesdesk-chatwoot/spec.md, seções 8 e 9).
A conta 142 não encerra conversa parada sozinha. O "Resolver conversas automaticamente" está desligado. Enquanto a conversa de um paciente continuar aberta, a mensagem nova dele cai nela e não vira lead — só conversa nova vira. No SymplesDesk antigo, o encerramento em 24h resolvia isso. Ligar é decisão da clínica, feita na tela da conta 142.

A entrada: o que chega da conta 142

  1. Conversa nova (Conversa Criada) → vira lead no Pipedrive pelo Fluxo 1 de sempre — mesmo funil, mesmo dono, mesma checagem de ciclo ativo. O médico sai da caixa da conversa: 872 é o Dr. Thiago e 873 o Dr. Augusto.
  2. Mensagem (Mensagem criada) → gravada no banco como antes e, às 19h, vira a atividade do dia no deal (Fluxo 4). Quem falou vem do tipo da mensagem: paciente, atendente ou nota interna (que fica fora da atividade). Áudio, foto ou documento nunca somem: sem formato reconhecido, a mensagem entra como [anexo], com o aviso original guardado.
  3. Conversa encerrada na tela (Status de conversa alterado, para resolvida) → registrada como encerramento manual, exatamente como o "Atendimento finalizado" fazia (ver Fechamento da conversa).
Três travas contra lead falso. (1) Contato criado ou atualizado nunca vira lead — só conversa nova: a importação da base antiga, em 18/09, mandou 1.731 avisos de contato em 20 minutos. (2) Conversa criada há mais de 15 minutos é ignorada — uma importação futura de conversas não vira lead em massa. (3) Caixa que não seja a 872 nem a 873 fica de fora.
O endereço tem um segredo. A conta 142 não assina os avisos que manda, então a senha vai no final da URL do webhook (/webhooks/symplesdesk-chatwoot/<segredo>). Segredo errado ou ausente = 404, sem processar nada. O segredo nunca aparece no log do servidor — a URL sai mascarada, com ***. Não mande a URL nem print da tela do webhook pelo chat.

A saída: nota da perda e fechamento de 24h pela conta 142

As duas escritas que o serviço faz no atendimento passam a ir para a conta 142, direto na conversa, pelo número dela — não mais pelo telefone:

  1. Deal perdido → a mesma nota interna de sempre (Deal perdido no Pipedrive: … / Motivo: …), na conversa mais recente do paciente na conta 142 — se ela teve mensagem nas últimas 24h.
  2. 24h depois da perda → a nota "Conversa encerrada automaticamente — lead perdido há 24h." e a conversa é resolvida, com as mesmas travas de antes. Só conversa da conta 142 é alvo: os tickets do SymplesDesk antigo ficam de fora.

A integração escreve com o token de acesso pessoal da Jéssica — decisão da clínica, provisória até o Chatwoot próprio. Por isso a nota e o encerramento aparecem na conversa como feitos por ela.

Os cards de Oportunidade ficam desligados

Decisão da clínica (18/09): o quadro de Oportunidades não vem para a conta 142. Uma chave única, SYMPLESDESK_CARDS_LIGADOS=false, desliga os 7 pontos de card — criar, fechar, espelhar, renomear e aplicar — em silêncio: sem erro, sem alerta, sem registro. Nada é apagado no banco; religar é tirar a variável (ou pôr true) e reiniciar.

Se chegar o 🚨 ERRO SYMPLESDESK_TOKEN_INVALIDO

É o token da Jéssica que deixou de valer — ela trocou a senha, gerou outro token ou saiu da clínica. O que parou: a nota da perda e o fechamento de 24h. O que não parou: leads e conversas continuam entrando, porque chegam pelo webhook, que não usa token.

  1. A Jéssica gera um token novo no SymplesDesk: Configurações do perfil → Token de acesso.
  2. Atualizar a variável SYMPLESDESK_CW_API_TOKEN no Coolify — o token nunca vai para chat nem para o repositório.
  3. Reiniciar o serviço. O fechamento de 24h volta sozinho na rodada seguinte e pega os atrasados; a nota das perdas que aconteceram no meio-tempo não é reenviada.

Com o token inválido, o fechamento de 24h para no primeiro recusado da rodada, em vez de insistir conversa por conversa, e o Discord recebe um alerta só — o do token.

Se chegar o 🚨 ERRO SYMPLESDESK_CW_SEGREDO_INVALIDO

Chega na subida do serviço quando o segredo do webhook da conta 142 está fora do formato — só letras e números, de 32 a 256 caracteres. A entrada da conta 142 fica desligada: nenhum lead novo e nenhuma conversa entram pela conta 142 até corrigir. O alerta nunca mostra o segredo.

  1. Gerar um segredo novo: openssl rand -hex 32 (64 caracteres, só letras e números).
  2. Pôr em SYMPLESDESK_CW_WEBHOOK_SECRET no Coolify e reiniciar o serviço.
  3. Atualizar a URL do webhook na conta 142 (Configurações → Integrações → Webhooks) com o segredo novo no final — senão os avisos dela passam a ser recusados.

Por que o formato existe: o servidor corta partes do endereço acima de um tamanho, e um segredo longo demais faria a entrada parar sem aviso nenhum — a mesma pane silenciosa de 17/09.

O alarme de silêncio olha a conta 142. Às 12h e às 17h dos dias úteis, zero mensagem de paciente nas últimas 4 horas gera o 🚨 ERRO NEWMESSAGE_SILENCIO, que manda conferir o webhook da conta 142 e o segredo no Coolify. As notas que o próprio serviço escreve não contam mais: foram elas que esconderam a parada de 17/09.

O que precisa para funcionar

  • No Coolify: SYMPLESDESK_CW_BASE_URL (https://chat.simplesdesk.com.br), SYMPLESDESK_CW_ACCOUNT_ID (142) e SYMPLESDESK_CW_API_TOKEN (o token da Jéssica) — as três juntas ligam a saída; faltando uma, a nota e o fechamento seguem pelo caminho antigo. SYMPLESDESK_CW_WEBHOOK_SECRET — gerado com openssl rand -hex 32 (só letras e números, de 32 a 256 caracteres) — liga a entrada. SYMPLESDESK_CARDS_LIGADOS=false desliga os cards.
  • No banco: as caixas 872 (T) e 873 (A) em integration_channels.symplesdesk_chatwoot_inbox_id — o SQL pronto é o docs/golive-symplesdesk-chatwoot.sql, rodado à mão pelo administrador antes do restart (a configuração dos canais é lida na inicialização).
  • Na conta 142 (Configurações → Integrações → Webhooks → Configurar → Adicionar): a URL <URL-do-serviço>/webhooks/symplesdesk-chatwoot/<segredo>, Todas as caixas e só os 3 eventos: Conversa Criada, Mensagem criada e Status de conversa alterado. Contato criado e contato atualizado ficam desmarcados.
  • ⚠️ Ordem: variáveis → SQL → restart → webhook. O webhook só depois que a rota estiver no ar com o segredo.

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)

EtapaNo quadro (SymplesDesk)Dr. ThiagoDr. Augusto
Cliente Potencial524637
Em conversa502736
Aguardando Pagamento483039

Funil de Consulta (Concierge)

EtapaNo quadro (SymplesDesk)Dr. ThiagoDr. Augusto
Consulta Agendada574755
Reagendamento584956
Consulta Confirmada594857

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.

Cuidado ao ler números soltos. Os dois sistemas numeram por conta própria, e os números se repetem entre funis: 48 é "Aguardando Pagamento" no quadro e "Consulta Confirmada" no funil de Consulta do Dr. Thiago — dois lugares completamente diferentes. Por isso a tradução leva sempre três informações: o médico, o funil e o número. Nunca cite um número sem dizer de que lado e de que funil ele é.

Responsáveis pela nota fiscal, por funil

Não é tradução de etapa, mas também é configuração por funil: o grupo da tabela nfse_responsaveis sai do funil do deal ganho.

Funis do PipedriveGrupo em nfse_responsaveisDe onde vem o grupo
10 (Consulta, Dr. Thiago)T:consultadoctor_code do funil em integration_pipelines + : + tipo de nota
7 (Procedimentos, Dr. Thiago)T:cirurgiadoctor_code do funil em integration_pipelines + : + tipo de nota
12 (Consulta, Dr. Augusto)A:consultadoctor_code do funil em integration_pipelines + : + tipo de nota
9 (Procedimentos, Dr. Augusto)A:cirurgiadoctor_code do funil em integration_pipelines + : + tipo de nota
13 e 19 (fisioterapia)fisiofunis de nfse_funis_fisio
11 e 4 (Dr. Lindomar), 16 e 17 (L.R)sem linhas hojedono do deal
Etapa fora do mapa não quebra nada — e não passa despercebida. Se alguém criar uma etapa nova em qualquer um dos lados sem cadastrar a tradução, o movimento é ignorado com registro. O sistema prefere não fazer nada a chutar a etapa errada; mas o card para de acompanhar aquele deal em silêncio até alguém completar o mapa.

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.

DesligarComoEfeito
Um médico inteiro integration_channels.is_active = false o canal some da configuração; nada daquele médico é processado
Criação de cards de Leads symplesdesk_responsible_user_id = NULL nenhum card novo de Leads é criado; os existentes seguem funcionando
Criação de cards de Consulta symplesdesk_concierge_user_id = NULL nenhum card novo de Consulta é criado; o funil de Leads não é afetado
Fechar card na perda symplesdesk_lost_reason_id = NULL o deal é perdido normalmente, o card fica aberto
Fechamento de 24h CLOSE_LOST_MAX_PER_RUN=0 a verificação roda e não fecha nada
Conversa diária no deal CONVERSATION_SYNC_CRON=0 0 30 2 * 30 de fevereiro nunca chega — o job nunca dispara
Criação de paciente no CnN CNN_CADASTRO_MODE=link continua procurando e ligando quem já é paciente, mas para de criar
Cadastro no CnN, por inteiro CNN_CADASTRO_MODE=off o ganho da Consulta segue normal; nada é procurado, ligado nem criado lá
Sincronização do cadastro, Pipedrive → Clínica nas Nuvens CNN_SYNC_PUSH_ENABLED diferente de true (o padrão) edição de pessoa no Pipedrive não vai ao Clínica nas Nuvens, o ganho da Consulta não atualiza a ficha, a passada diária das 20h não é agendada, a ligação do paciente não acompanha o negócio de Consulta (ganho ou troca de pessoa) e o script recusa gravar. O passo único da pessoa (cnn-pessoa-vinculo.ts) não depende dela. O Clínica nas Nuvens nunca escreve no Pipedrive, com a chave ligada ou não. Ligada desde 27/10
Um campo novo da sincronização (Sexo, Gênero, Nome social, Estrangeiro, Ramal) apagar a variável PIPEDRIVE_…_FIELD_KEY do campo o campo sai da leitura, da sincronização e da criação do paciente; os outros seguem como estão. Todos ligados desde 06/11
Cidade na sincronização e na criação CNN_SYNC_CIDADE_ENABLED diferente de true (o padrão) a cidade do Clínica nas Nuvens não é tocada e o catálogo de cidades não é consultado. Ligada desde 06/11
Nota de dados da NFS-e NFSE_DADOS_ENABLED diferente de true (o padrão) o ganho segue normal; nenhum dado é montado e nenhuma nota é gravada nem reescrita. As notas já gravadas ficam no deal. A carga dos ganhos recentes também recusa gravar; o --dry-run dela roda mesmo assim. Desliga junto a emissão automática da NFS-e, que depende desta nota
Emissão automática da NFS-e, por inteiro NFSE_ATIVIDADE_ENABLED diferente de true (ou NFSE_DADOS_ENABLED diferente de true) nenhuma atividade "Emitir NFS-e" nasce e a varredura de 5 minutos nem é agendada: as atividades que já existem ficam paradas — concluí-las não monta nem envia nada até religar
Atividade de nota nos deals reais NFSE_ATIVIDADE_ESCOPO diferente de todos (vira o piloto) só os deals listados em NFSE_ATIVIDADE_PILOTO_DEALS ganham atividade e nota de dados; lista vazia = nenhum. As atividades já criadas seguem até o fim
Envio da NFS-e ao governo NFSE_ENVIO_ENABLED diferente de true vira ensaio: a confirmação concluída monta, valida e assina a nota e grava no banco, mas não envia. ⚠️ Ao religar, as notas ensaiadas nesse meio-tempo vão ao governo na rodada seguinte, sem nova confirmação — confira antes com npx tsx scripts/sonda-nfse-envio.ts
NFS-e de verdade (produção) NFSE_AMBIENTE diferente de producao volta para a homologação (produção restrita do governo): as notas não têm valor fiscal e a confirmação abre com "HOMOLOGAÇÃO — nota sem valor fiscal". Nota já montada no outro ambiente é recusada por "configuração" até ser refeita
Confirmação humana antes do envio NFSE_EMISSAO_MODO=automatica pula a atividade "Confirmar emissão": a nota vai ao governo logo depois de montada. Não está em uso — ausente (ou qualquer outro valor) é a confirmação manual, o modo de hoje
NPS da consulta remover PIPEDRIVE_NPS_CONSULTA_OWNER_ID a Consulta ganha não cria mais a tarefa "APLICAR NPS CONSULTA"
Tarefas de NPS remover PIPEDRIVE_SURGERY_DATE_FIELD_KEY o job roda sem fazer nada
Agenda do dia seguinte deixar AGENDA_DESTINO ou TOKEN_FZAP vazio o job nem é agendado — nenhuma lista sai
Entrada pela conta 142 tirar SYMPLESDESK_CW_WEBHOOK_SECRET a porta nova responde 404 para tudo — nada da conta 142 entra
Saída pela conta 142 tirar SYMPLESDESK_CW_API_TOKEN a nota da perda e o fechamento de 24h voltam ao caminho do SymplesDesk antigo
Cards de Oportunidade, todos SYMPLESDESK_CARDS_LIGADOS=false nenhum card é criado, fechado, espelhado, renomeado ou aplicado — em silêncio, sem apagar nada
Depois de mexer no banco, reinicie o serviço. A configuração dos canais é lida uma vez, na inicialização. Sem o restart, a mudança não vale — e o comportamento antigo continua, dando a impressão de que a chave não funcionou. O mesmo vale para as variáveis de ambiente (as NFSE_*, por exemplo): só valem depois do redeploy.
Teste a agenda antes de ligar de verdade. npx tsx scripts/agenda-dia-seguinte.ts mostra a mensagem que sairia hoje, sem mandar nada e sem gravar evento. Só envia de verdade com a flag --enviar.
Ensaie a sincronização do cadastro antes de ligar. npx tsx scripts/cnn-sync.ts roda em ensaio por padrão: lê o Clínica nas Nuvens e o Pipedrive reais, não escreve em lado nenhum e imprime, por campo, o que faria — inclusive cleared e pipedriveWrites, que têm de ser 0. --lista arquivo.csv grava a lista do que só o Clínica nas Nuvens tem (com CPF inteiro: guarde fora do repositório). Gravar exige --gravar e a chave CNN_SYNC_PUSH_ENABLED=true; sem a chave, o script recusa. --aplicar-divergencias segue aceito e não muda nada desde 27/10: o padrão já leva o valor do Pipedrive onde os dois lados diferem; fica só para o comando antigo não quebrar. O ensaio também conta de onde veio a pessoa de cada paciente: do negócio de Consulta, do contato, ou de lugar nenhum (fica de fora).
Antes de ligar a sincronização, ensaie a pessoa de cada paciente. npx tsx scripts/cnn-pessoa-vinculo.ts roda em ensaio por padrão e não grava nada: para cada paciente ligado, procura o negócio de Consulta e a pessoa atual dele no Pipedrive e conta quantos ficam com a pessoa igual à do contato, quantos com o contato sem pessoa, quantos com uma pessoa diferente, sem negócio de Consulta, com o negócio sem pessoa (ou apagado) e em conflito com outro paciente — e lista os que não são iguais. --gravar grava a pessoa em cada ligação: só com o aval da clínica e depois do ajuste no banco desta mudança. Não depende da chave CNN_SYNC_PUSH_ENABLED e nunca escreve no Pipedrive nem no Clínica nas Nuvens.

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.

VariávelObrigatória?Para quê
DATABASE_URLSimConexão com o Postgres (fonte da verdade)
PIPEDRIVE_BASE_URLSimDomínio da conta Pipedrive (teste ou produção)
PIPEDRIVE_API_TOKENSimToken da API do Pipedrive
PIPEDRIVE_WEBHOOK_BASIC_USER / _PASSSimUsuário/senha que o webhook do Pipedrive usa para se autenticar
SYMPLESDESK_TOKEN_T / _AFluxo 2Tokens da API de fechar conversa, um por canal/médico
SYMPLESDESK_WEBHOOK_TOKENFluxo 4Token que autentica o webhook de mensagem (sem ele a rota recusa tudo)
PIPEDRIVE_ACTIVITY_TYPE_WHATSAPP_KEYFluxo 4Chave do tipo de atividade "Whatsapp" na conta
PIPEDRIVE_PROCEDURE_FIELD_KEYProduçãoCampo personalizado "Procedimento" do deal (não existe na conta de teste)
SYMPLESDESK_OPORTUNIDADE_WEBHOOK_SECRETCardsToken que autentica o webhook de Oportunidade (sem ele a rota recusa tudo)
SYMPLESDESK_ATENDIMENTO_WEBHOOK_SECRETFechamentoToken do webhook "Atendimento finalizado"
SYMPLESDESK_CW_BASE_URL / SYMPLESDESK_CW_ACCOUNT_ID / SYMPLESDESK_CW_API_TOKENConta 142As três juntas ligam a saída pela conta 142 (nota da perda e fechamento de 24h): https://chat.simplesdesk.com.br, 142 e o token de acesso da Jéssica. Faltando uma, a saída segue pelo SymplesDesk antigo
SYMPLESDESK_CW_WEBHOOK_SECRETConta 142Segredo no final da URL do webhook da conta 142 — liga a entrada. Só letras e números, de 32 a 256 caracteres (openssl rand -hex 32). Ausente = a rota responde 404 para tudo; fora do formato = entrada desligada e 🚨 ERRO SYMPLESDESK_CW_SEGREDO_INVALIDO na subida
SYMPLESDESK_CW_CONVERSA_RECENTE_MINOpcionalConversa criada há mais que isto, em minutos, não vira lead (padrão 15)
SYMPLESDESK_CARDS_LIGADOSOpcionalChave única dos cards de Oportunidade: ausente = ligados; false desliga todos, em silêncio
PIPEDRIVE_SURGERY_DATE_FIELD_KEYNPSCampo "Data da cirurgia". Com ele, o job das 7h garante "APLICAR NPS 15 DIAS" e "APLICAR NPS 60 DIAS" no deal de cirurgia (para a Concierge do médico) e "APLICAR NPS 15 DIAS" no deal de fisioterapia da mesma pessoa (para a dona do deal de fisio), todas contadas da data da cirurgia. Até 13/11/2026 a do deal de cirurgia era de 30 dias. Ausente = tarefas de NPS desligadas
PIPEDRIVE_NPS_CONSULTA_OWNER_IDNPS da consultaUsuário do Pipedrive dono da tarefa "APLICAR NPS CONSULTA - {nome}", criada no dia útil seguinte ao ganho da Consulta (a Mayze, para todos os médicos). Ausente = desligado. Com isto ligado, as automações "NPS CONSULTA" do Pipedrive ficam desligadas, senão a tarefa sai em dobro
CONVERSATION_SYNC_CRONOpcionalHorário do job da conversa (cron, fuso Brasília; padrão 0 19 * * * = 19h)
CLOSE_LOST_CRONOpcionalQuando checar conversas a fechar (padrão 15 * * * * = de hora em hora, aos :15)
CLOSE_LOST_MAX_PER_RUNOpcionalTeto de fechamentos por rodada (padrão 25; 0 desliga)
NPS_SYNC_CRONOpcionalHorário do job de NPS (padrão 0 7 * * * = 7h)
CNN_CADASTRO_MODECadastro CnNNível do cadastro: off (padrão) · link (só reconhece) · full (reconhece e cria). Qualquer outro valor vira off — inclusive LINK em maiúscula
CNN_CLIENT_ID / CNN_CLIENT_SECRET / CNN_CIDCadastro CnNCredenciais da API do Clínica nas Nuvens. Faltando qualquer uma, todo ganho de Consulta vira evento de erro
CNN_SYNC_PUSH_ENABLEDSincronização CnNLiga a sincronização do cadastro, Pipedrive → Clínica nas Nuvens (um sentido só): a ida da edição de pessoa, a passada diária, a ligação do paciente acompanhando o negócio de Consulta e a gravação do script. Padrão false; só o valor exato true liga, e só com as três credenciais do CnN. Ligada desde 27/10
CNN_SYNC_CRONOpcionalHorário da passada diária da sincronização do cadastro (padrão 0 20 * * * = 20h). Só é agendada com CNN_SYNC_PUSH_ENABLED=true, e não depende do CNN_POLL_ENABLED
PIPEDRIVE_SEXO_FIELD_KEY / PIPEDRIVE_GENERO_FIELD_KEY / PIPEDRIVE_NOME_SOCIAL_FIELD_KEY / PIPEDRIVE_ESTRANGEIRO_FIELD_KEY / PIPEDRIVE_RAMAL_FIELD_KEYOpcional · Sincronização CnNChave de cada campo novo da pessoa (Sexo, Gênero, Nome social, Estrangeiro, Ramal). Sem chave, o campo fica fora da leitura, da sincronização e da criação do paciente. Os 5 campos existem no Pipedrive de produção desde 03/11 (criados por scripts/criar-campos-pipedrive-cnn.ts, que não duplica e imprime as 5 linhas prontas para o .env). Cada chave liga um campo. As 5 ligadas desde 06/11
CNN_SYNC_CIDADE_ENABLEDOpcional · Sincronização CnNLeva a cidade do endereço ao Clínica nas Nuvens (pelo catálogo de cidades de lá), na sincronização e na criação do paciente. Padrão false; só o valor exato true liga. Ligada desde 06/11
PIPEDRIVE_CPF_FIELD_KEYCadastro CnN · NFS-eCampo "CPF" da pessoa. Sem ele, ninguém é procurado por CPF: o cadastro vai só por nome + nascimento e cria sem CPF — muito mais risco de duplicar prontuário —, e toda nota de dados da NFS-e sai pendente de CPF
PIPEDRIVE_BIRTH_DATE_FIELD_KEYCadastro CnNCampo "Data de Nascimento" da pessoa. Sem ele, ninguém é ligado por nome + nascimento e ninguém é criado (o nascimento é obrigatório no CnN)
PIPEDRIVE_ADDRESS_FIELD_KEYOpcional · NFS-eCampo "Endereço" da pessoa (preenchido em ~5% da base; o cadastro no CnN funciona sem). A nota de dados da NFS-e depende dele: sem ele, toda nota sai pendente de endereço
PIPEDRIVE_RG_FIELD_KEYSem efeitoCampo "RG" da pessoa. Desde 29/10 não alimenta nada: o RG não vai ao Clínica nas Nuvens (o "Número de identificação" de lá é de estrangeiro). Pode ficar vazia
NFSE_DADOS_ENABLEDNFS-eLiga a nota "Dados para a NFS-e" no deal ganho de Consulta, Procedimentos e fisioterapia. Padrão false; só o valor exato true liga. Depende de PIPEDRIVE_CPF_FIELD_KEY, PIPEDRIVE_ADDRESS_FIELD_KEY e da tabela nfse_dados_notas. A emissão automática também depende dela
NFSE_ATIVIDADE_ENABLEDEmissão NFS-eLiga a emissão automática: a atividade "Emitir NFS-e" no ganho e a varredura a cada 5 minutos. Só o valor exato true liga, e só junto com NFSE_DADOS_ENABLED=true
NFSE_ATIVIDADE_ESCOPOEmissão NFS-etodos = todo deal ganho que gera nota (o valor em produção desde 02/10). Ausente ou qualquer outro valor = piloto, só os deals de NFSE_ATIVIDADE_PILOTO_DEALS
NFSE_ATIVIDADE_PILOTO_DEALSOpcionalIds de deal separados por vírgula, para teste. Só é lida no piloto; com o escopo todos, é ignorada
NFSE_AMBIENTEEmissão NFS-eproducao = Emissor Nacional de verdade, nota com valor fiscal. Ausente ou qualquer outro valor = homologação (produção restrita, sem valor fiscal)
NFSE_ENVIO_ENABLEDEmissão NFS-eSó o valor exato true envia a nota ao governo; fora isso é o ensaio (monta, valida, assina e grava, sem enviar)
NFSE_EMISSAO_MODOOpcionalAusente = confirmação por uma pessoa antes de cada envio (o modo em uso). automatica pula a confirmação
NFSE_CERT_BELLACARE_PFX_BASE64 / NFSE_CERT_BELLACARE_SENHAEmissão NFS-e · secretasCertificado A1 (e-CNPJ) da Bellacare: o arquivo .pfx convertido em base64 e a senha dele. Só no ambiente do servidor, nunca em arquivo. Ausente, com senha errada ou de outro CNPJ: a nota da Bellacare não sai e o Discord avisa a causa — a da Lindomar segue
NFSE_CERT_LINDOMAR_PFX_BASE64 / NFSE_CERT_LINDOMAR_SENHAEmissão NFS-e · secretasO mesmo, para a Lindomar Delgado (cirurgia e fisioterapia)
NFSE_SERIE_DPSEmissão NFS-eSérie das notas emitidas pela integração: 900. Tem de estar entre 1 e 49999 (faixa de sistema próprio) e não colide com a 70000 do portal. Ausente ou fora da faixa: nenhuma nota sai, motivo "configuração"
NFSE_BELLACARE_PTOTTRIBSNEmissão NFS-ePercentual aproximado do Simples Nacional nas notas da Bellacare (10.88 hoje). Muda com a faixa de faturamento — o contador avisa. Ausente ou não numérico: a nota da Bellacare não sai, motivo "configuração"
NFSE_AVISO_DESTINOEmissão NFS-eQuem recebe o aviso de nota que não saiu: o grupo da clínica (…@g.us) ou um telefone (só dígitos, com DDI). Ausente = o mesmo destino de AGENDA_DESTINO. Sai pela FZAP, então depende de TOKEN_FZAP
NFSE_CONFIRMACAO_OWNER_IDOpcionalId do usuário do Pipedrive que recebe todas as atividades "Confirmar emissão", passando por cima da regra das responsáveis. Ausente (o caso de produção) = quem está com a "Emitir NFS-e" do deal; "Emitir" sem dono = o dono do deal
PIPEDRIVE_ACTIVITY_TYPE_NFSE_KEYOpcionalTipo de atividade usado nas duas atividades de nota (padrão task, "Tarefa")
CNN_CONVENIO_PARTICULAR_IDEmissão NFS-eId do convênio particular no Clínica nas Nuvens, para ler o preço da consulta. Sem ele, o valor da consulta não é preenchido e a atividade pede para preencher à mão
TOKEN_FZAPAgendaToken da instância FZAP (WhatsApp conectado por QR code) que envia a lista do dia seguinte
FZAP_BASE_URLOpcionalEndereço da instância FZAP; tem valor padrão de fábrica, só precisa ser definida se o endereço mudar
AGENDA_DESTINOAgendaQuem recebe a lista geral: o JID do grupo (…@g.us) ou um telefone (só dígitos, com DDI). Sem ele ou sem TOKEN_FZAP, o job nem é agendado
AGENDA_MEDICOSOpcionalMédicos que também recebem a lista completa no próprio WhatsApp: idpessoa:telefone separados por vírgula (ver a seção da agenda)
AGENDA_CRONOpcionalHorário do envio (cron, fuso Brasília; padrão 0 18 * * * = 18h)
DISCORD_ERROR_WEBHOOK_URLOpcionalAlertas operacionais de erro
PORTOpcionalPorta HTTP (padrão 3000)
Chave de campo personalizado errada derruba a leitura inteira. As chaves acima são hashes de 40 caracteres, e o Pipedrive responde HTTP 400 quando recebe uma que não existe — não é o campo que fica vazio, é a pessoa que não é lida. Variável de chave que você não tem, deixe fora (ausente é tratado como "não configurado", e funciona). Para descobrir as chaves reais: npx tsx scripts/sonda-cnn-prontidao.ts, que é somente leitura.

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.)

A emissão automática da NFS-e usa quatro tabelas próprias, criadas pelo administrador com os DDL do repositório (docs/ddl-emissao-nfse.sql, docs/ddl-emissao-nfse-p2.sql, docs/ddl-emissao-nfse-p4.sql e docs/ddl-responsavel-nota.sql, nessa ordem; rodar de novo não duplica nada):

TabelaO que guarda
nfse_emissoesUma linha por deal com nota: a empresa, o tipo de serviço, as duas atividades, a situação (aguardando, bloqueada, montada, enviando, emitida, rejeitada, descartada…), a nota montada, o número, a chave, o XML devolvido pelo governo e os erros. É ela que impede atividade e nota em dobro
nfse_funis_fisioQuais funis do Pipedrive são de fisioterapia e geram nota: 13 "Fisioterapia - Indicação Pacote" e 19 "Fisioterapia Avulsas". O 14 "Fisioterapia - Tratamento" fica de fora de propósito
nfse_responsaveisQuem recebe a atividade "Emitir NFS-e", por grupo — médico e tipo de nota ('T:consulta', 'T:cirurgia', 'A:consulta', 'A:cirurgia') ou 'fisio': posição no rodízio, id do usuário no Pipedrive, nome e is_active. Editável a qualquer momento (ver Quem recebe as atividades de nota)
nfse_responsaveis_vezA vez do rodízio de cada grupo: a posição de quem recebeu a última atividade. Preenchida sozinha — não editar

O preço da consulta vem do id do procedimento no Clínica nas Nuvens gravado em cada funil de Consulta (coluna cnn_tipo_procedimento_id de integration_pipelines, preenchida pelo primeiro DDL).

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.

Onde criarEventoURL da APIAutenticação
SymplesDesk (2 canais)Mensagem criada/webhooks/symplesdesk-newmessageToken de autenticação
Pipedrive (Webhooks v2)deal: create + change/webhooks/pipedriveUsuário e senha (Basic Auth)
Pipedrive (Webhooks v2)person: change (sync de nome e nota de dados da NFS-e)/webhooks/pipedriveUsuário e senha (Basic Auth)
SymplesDesk (2 canais)Novo atendimento/webhooks/symplesdesk—
SymplesDesk (2 canais)Oportunidade (card)/webhooks/oportunidadeToken de autenticação
SymplesDesk (2 canais)Atendimento finalizado/webhooks/atendimento-finalizadoToken de autenticação
SymplesDesk conta 142 (Configurações → Integrações → Webhooks)Conversa Criada, Mensagem criada e Status de conversa alterado — todas as caixas/webhooks/symplesdesk-chatwoot/<segredo>Segredo no final da URL
Regra de ouro: cada evento deve ter um destino só. Se algum desses eventos já dispara para outra automação, troque a URL pela da API em vez de criar um webhook em paralelo — dois destinos processando o mesmo evento duplicam deals e fecham conversas duas vezes.
Crie o webhook só depois que a rota estiver no ar. O SymplesDesk desativa sozinho uma configuração que recebe falhas seguidas — já aconteceu aqui, com um webhook apontado para uma URL que ainda não existia.

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);
CampoO que é / onde encontrar
doctor_codeSigla única do médico (1 letra, ex.: 'T'). Aparece no título do deal (telefone - SIGLA) e amarra todas as outras configs.
doctor_nameNome de exibição (ex.: 'Dr. Thiago Delgado').
symplesdesk_account_idID da conta do canal no SymplesDesk (vem no payload dos webhooks do canal).
symplesdesk_whatsapp_idID do canal de WhatsApp no SymplesDesk (ex.: '139'). É por ele que o Fluxo 1 descobre de qual médico é o lead.
symplesdesk_base_urlSempre 'https://serv2api.simplesdesk.com.br' (base da API externa).
symplesdesk_api_idID (uuid) da configuração de API criada no SymplesDesk para este canal (tela APIs → a config de fechamento de conversa). Usado pelo Fluxo 2.
symplesdesk_token_secret_nameNome da variável de ambiente que guarda o token JWT dessa config — padrão 'SYMPLESDESK_TOKEN_SIGLA'. O token em si nunca vai no banco (só o nome da variável).
pipedrive_owner_idID do usuário do Pipedrive que será o dono dos deals criados (Configurações → Usuários).
pipedrive_pipeline_id / pipedrive_stage_idID do funil de Leads do médico e da etapa de entrada (aparecem na URL do Pipedrive ao abrir o funil/etapa).
pipedrive_label_idID da etiqueta aplicada à pessoa (produção usa a etiqueta "WhatsApp"). Pode ser NULL se não houver.
is_activetrue para ligar o canal; false desliga sem apagar a linha.

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

Passo 6 · Quem recebe a nota fiscal do médico novo (opcional)

Sem este passo, as atividades de nota dos funis do médico novo vão para o dono do deal. Para mandar para quem emite nota, uma linha por pessoa em nfse_responsaveis, com a sigla do médico e o tipo de nota no grupo (ver Quem recebe as atividades de nota):

INSERT INTO nfse_responsaveis (grupo, posicao, pipedrive_user_id, nome)
VALUES
  ('SIGLA:consulta', 1, 'ID_DO_USUARIO_NO_PIPEDRIVE', 'NOME'),
  ('SIGLA:cirurgia', 1, 'ID_DO_USUARIO_NO_PIPEDRIVE', 'NOME');

Passo 7 · 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.

Conferência rápida: mande uma mensagem de teste pro canal novo e confira o deal criado no funil certo, com o dono certo e o título telefone - SIGLA. Qualquer erro fica registrado em integration_events.

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.

EndpointAutenticaçãoO que faz
GET /health—Confirma que o serviço está no ar ({"ok":true})
POST /webhooks/symplesdesk— (limitação da tela antiga)Fluxo 1: entrada de lead
POST /webhooks/pipedriveBasic AuthFluxos 2, 3 e 5-B: status, captura e movimentação de deals + sync de nome do contato (person) + nota de dados da NFS-e (ganho e pessoa alterada) + atividade de emissão da NFS-e (ganho)
POST /webhooks/symplesdesk-newmessageToken no headerFluxo 4: ingestão de cada mensagem
POST /webhooks/oportunidadeToken no headerCards: movimento, ganho, perda e renome feitos no quadro
POST /webhooks/atendimento-finalizadoToken no headerRegistra que alguém encerrou o atendimento na mão
POST /webhooks/symplesdesk-chatwoot/<segredo>Segredo no final da URLConta 142: conversa nova (Fluxo 1), mensagem (Fluxo 4) e conversa encerrada na tela
GET /docs—Esta página
GET /docs/nfse-botao—Página que instala o favorito da NFS-e, que preenche o tomador na tela "Pessoas" do portal (ver Dados para a NFS-e)

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 três rotas mais novas, que não confirmam sequer a própria existência para quem não tem o token (na da conta 142, o segredo).

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

Estado atual: os 4 fluxos estão completos, com verificação independente e teste ponta a ponta com mensagens e conversas reais (22/07/2026).
  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.