Clínica Lindomar Delgado · Guia operacional
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
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.
A regra mais importante de todo o sistema:
+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.
55+DDD+número.telefone - sigla,
responsável, etapa e etiqueta vindos da config.<URL-do-serviço>/webhooks/symplesdesk. Importante: esse evento deve apontar
para uma URL só — dois destinos criariam deal duplicado.integration_channels no banco (canal → médico →
funil/etapa/responsável) — o SQL pronto está em
Como adicionar um novo canal.PIPEDRIVE_BASE_URL e PIPEDRIVE_API_TOKEN.Quando a equipe marca um deal como perdido ou ganho no Pipedrive, o serviço reage:
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).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).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.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.SYMPLESDESK_TOKEN_T e SYMPLESDESK_TOKEN_A) — já validados contra a
produção em 22/07/2026.DISCORD_ERROR_WEBHOOK_URL para os alertas de falha.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.
integration_pipelines com os funis mapeados
(Leads, Consulta e Procedimentos por médico) — o SQL pronto está em
Como adicionar um novo canal.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:
symplesdesk_messages, vinculada ao contato certo
(pelo ticket ou pelo telefone). Mensagens repetidas (reenvio) e apagadas não duplicam nem entram.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.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
<URL-do-serviço>/webhooks/symplesdesk-newmessage, colando no campo "Token de
autenticação" o mesmo valor de SYMPLESDESK_WEBHOOK_TOKEN do 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).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.
| A SDR faz no card | Acontece no Pipedrive |
|---|---|
| Arrasta para outra etapa | o deal muda de etapa no funil |
| Marca como ganho | o deal vira ganho |
| Marca como perdido | o deal vira perdido, com o motivo |
| Renomeia o card | o nome da pessoa é corrigido no CRM |
| Alguém faz no Pipedrive | Acontece no quadro |
|---|---|
| Move o deal de etapa | o card acompanha |
| Ganha ou perde o deal | o card fecha com o mesmo resultado |
| Corrige o nome da pessoa | o card é renomeado |
| Reabre um deal fechado | o card volta a abrir |
<URL-do-serviço>/webhooks/oportunidade e colando no campo "Token de
autenticação" o valor de SYMPLESDESK_OPORTUNIDADE_WEBHOOK_SECRET.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.symplesdesk_responsible_user_id): é por esse campo que cada uma filtra o quadro
compartilhado para ver só os cards dela.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.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.
| Card de Leads (SDR) | Card de Consulta (Concierge) | |
|---|---|---|
| Dona do card | a SDR do médico | a Concierge do médico |
| Nome do card | montado pelo sistema: nome - sigla | cópia exata do nome do negócio: CONSULTA DE nome |
| Etapas | as do funil de Leads | as do funil de Consulta |
| Renomear o card | corrige o nome da pessoa no CRM | não propaga nada — ver abaixo |
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.
symplesdesk_concierge_user_id): é o campo que liga esta parte. Vazio,
nenhum card de Consulta é criado — e o resto do sistema segue normal.integration_pipeline_steps com pipeline_type = 'consulta') — ver a
seção Mapa das etapas.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.
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.
<URL-do-serviço>/webhooks/atendimento-finalizado, com o valor
de SYMPLESDESK_ATENDIMENTO_WEBHOOK_SECRET no campo "Token de autenticação".CLOSE_LOST_CRON (horário) e CLOSE_LOST_MAX_PER_RUN
(teto) — ver Ligar e desligar.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.
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.
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.
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.
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:
| Motivo | O que houve |
|---|---|
sem_cpf | a 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_nascimento | falta a data de nascimento — é obrigatória para criar no CnN |
sem_nome | o "nome" no Pipedrive é o próprio telefone; viraria um prontuário chamado "5532991997896" |
sem_pessoa | o negócio não tem pessoa vinculada no Pipedrive (ou ela foi apagada) |
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).
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á.
.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).
M ou F.CNN_SYNC_CIDADE_ENABLED=true) → a cidade e o estado do
endereço do Pipedrive são procurados no catálogo de cidades do Clínica nas Nuvens. Vale só quando
exatamente uma cidade do catálogo tem o mesmo nome (sem acento, sem diferenciar maiúscula) no mesmo
estado. Se não acha, acha mais de uma ou o catálogo está fora do ar, a cidade do Clínica nas Nuvens fica
como está, o resto do cadastro vai normalmente e o motivo fica registrado. O conserto é corrigir o
endereço no Pipedrive. A cidade só preenche o que está vazio no Clínica nas Nuvens: se lá já há uma
cidade diferente e o endereço é o mesmo, ela não é trocada (fica registrado como "cidade diferente"). Ela só
muda quando o endereço inteiro muda — paciente que se mudou —, e aí vai junto com o endereço 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.
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.
CNN_SYNC_PUSH_ENABLED. Desligada, nada é escrito no
Clínica nas Nuvens e a passada diária nem é agendada.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.
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.
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.)
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.
120, 403) em número e complemento, e completa o
bairro vazio com o bairro do CEP.NFSE1:).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ência | O que houve | Onde corrigir |
|---|---|---|
cpf | CPF vazio ou inválido | campo "CPF" da pessoa |
nome | nome vazio ou igual ao telefone | "Nome" da pessoa |
endereco | a pessoa não tem endereço | campo "Endereço" da pessoa |
tomador_exterior | telefone de fora do Brasil | conferir o "Telefone" da pessoa; no portal, o tomador é do exterior |
cep | o 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_indisponivel | a base de CEP não respondeu | conferir o "CEP" no endereço; a próxima alteração da pessoa confere de novo |
bairro | bairro 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.
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:
NFSE1: da nota "Dados para a NFS-e" do deal;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.
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.
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.
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.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.NFSE_DADOS_ENABLED=true e reiniciar o serviço. Padrão
false — desligado.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.--dry-run da carga → ligar → carga de verdade.
Até o dry-run precisa da tabela, porque é nela que ele confere quem já tem nota.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.
| Funil do deal ganho | Empresa que emite | Concluir a atividade… |
|---|---|---|
| Consulta (de todos os médicos) | Bellacare | só depois que o paciente veio e pagou a consulta inteira |
| Procedimentos (cirurgia) | Lindomar Delgado | só depois que a cirurgia foi realizada |
| Fisioterapia - Indicação Pacote | Lindomar Delgado | depois da primeira sessão do pacote |
| Fisioterapia Avulsas | Lindomar Delgado | depois 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".
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 ganho | Recebe 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 |
T:consulta, T:cirurgia,
A:consulta, A:cirurgia, fisio) tem hoje uma pessoa, que recebe
todas as notas daquele grupo.NFSE_CONFIRMACAO_OWNER_ID
preenchida, todas as confirmações vão para esse usuário (ver
variáveis) — em produção ela está ausente.integration_events o evento
nfse_responsavel_fallback. Acontece quando a lista de responsáveis não pôde ser lida
(leitura_responsaveis), quando o Pipedrive recusa a responsável como dono — usuário
desativado ou id errado (owner_recusado, com o id recusado na mensagem) — e quando a
"Emitir NFS-e" não tem dono na hora de criar a confirmação (dono_emitir_ausente).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;
doctor_code dos funis dele em integration_pipelines) seguida do
tipo de nota — 'SIGLA:consulta' para o funil de Consulta e 'SIGLA:cirurgia'
para o de Procedimentos —, como no exemplo do Dr. Augusto acima, com posicao 1, 2…
Um grupo só com a sigla (sem o tipo) nunca é lido.A descrição sai sempre com a mesma grafia:
| Serviço | Descrição |
|---|---|
| Consulta | Consulta médica |
| Cirurgia | Procedimento 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.
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.
| Motivo | O que fazer |
|---|---|
| Pendência no cadastro: CPF, nome, endereço, CEP ou bairro | corrigir no cadastro da pessoa e concluir a atividade de novo |
| Telefone de fora do Brasil | paciente do exterior: a nota é feita à mão |
| Valor do deal zerado | preencher 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 governo | a 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 hora | a 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 hora | concluir de novo mais tarde, ou emitir à mão e apagar a atividade |
| Configuração fiscal incompleta | avisar o suporte — é ajuste do administrador, não do cadastro |
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.
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).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).NFSE_SERIE_DPS, NFSE_BELLACARE_PTOTTRIBSN) — ver as variáveis em
O que a API precisa.NFSE_AVISO_DESTINO apontando para o grupo da clínica.CNN_CONVENIO_PARTICULAR_ID. Sem eles, o valor da consulta não é preenchido e a
atividade avisa para preencher à mão.npx tsx scripts/sonda-nfse-envio.ts lista as notas montadas e
em envio e reconfere a validação e a assinatura — somente leitura.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.
📅 *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).AGENDA_DESTINO: o grupo Agenda Pacientes Clínica
Lindomar Delgado (ou um telefone).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.📅 *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 LimaOs médicos de
AGENDA_MEDICOS recebem exatamente esse mesmo texto.
(no WhatsApp, o texto entre asteriscos aparece em negrito)
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).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.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:
| idpessoa | Profissional |
|---|---|
20689417 | Dr. Thiago Ferreira Delgado |
20741719 | Dr. Augusto Cesar de Melo Almeida |
22509355 | Dr. Lindomar Delgado |
22647395 | Dra Larissa |
16918290 | Melissa Monica de Castro Teixeira |
27210466 | Riviane Marques da Costa Alves |
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.
.specs/features/symplesdesk-chatwoot/spec.md, seções 8 e 9).
[anexo], com o aviso original guardado./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.
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:
Deal perdido no Pipedrive: … /
Motivo: …), na conversa mais recente do paciente na conta 142 — se ela teve mensagem nas
últimas 24h.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.
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.
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.
SYMPLESDESK_CW_API_TOKEN no Coolify — o token nunca vai
para chat nem para o repositório.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.
SYMPLESDESK_CW_SEGREDO_INVALIDOChega 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.
openssl rand -hex 32 (64 caracteres, só letras e números).SYMPLESDESK_CW_WEBHOOK_SECRET no Coolify e reiniciar o serviço.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.
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.
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.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).<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.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.
| Etapa | No quadro (SymplesDesk) | Dr. Thiago | Dr. Augusto |
|---|---|---|---|
| Cliente Potencial | 52 | 46 | 37 |
| Em conversa | 50 | 27 | 36 |
| Aguardando Pagamento | 48 | 30 | 39 |
| Etapa | No quadro (SymplesDesk) | Dr. Thiago | Dr. Augusto |
|---|---|---|---|
| Consulta Agendada | 57 | 47 | 55 |
| Reagendamento | 58 | 49 | 56 |
| Consulta Confirmada | 59 | 48 | 57 |
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.
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 Pipedrive | Grupo em nfse_responsaveis | De onde vem o grupo |
|---|---|---|
| 10 (Consulta, Dr. Thiago) | T:consulta | doctor_code do funil em integration_pipelines + : + tipo de nota |
| 7 (Procedimentos, Dr. Thiago) | T:cirurgia | doctor_code do funil em integration_pipelines + : + tipo de nota |
| 12 (Consulta, Dr. Augusto) | A:consulta | doctor_code do funil em integration_pipelines + : + tipo de nota |
| 9 (Procedimentos, Dr. Augusto) | A:cirurgia | doctor_code do funil em integration_pipelines + : + tipo de nota |
| 13 e 19 (fisioterapia) | fisio | funis de nfse_funis_fisio |
| 11 e 4 (Dr. Lindomar), 16 e 17 (L.R) | sem linhas hoje | dono do deal |
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.
| Desligar | Como | Efeito |
|---|---|---|
| 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 |
NFSE_*, por exemplo): só valem depois do redeploy.
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.
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).
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.
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.
.env)Os valores reais nunca ficam no código nem nesta página — vivem só no .env do servidor.
| Variável | Obrigatória? | Para quê |
|---|---|---|
DATABASE_URL | Sim | Conexão com o Postgres (fonte da verdade) |
PIPEDRIVE_BASE_URL | Sim | Domínio da conta Pipedrive (teste ou produção) |
PIPEDRIVE_API_TOKEN | Sim | Token da API do Pipedrive |
PIPEDRIVE_WEBHOOK_BASIC_USER / _PASS | Sim | Usuário/senha que o webhook do Pipedrive usa para se autenticar |
SYMPLESDESK_TOKEN_T / _A | Fluxo 2 | Tokens da API de fechar conversa, um por canal/médico |
SYMPLESDESK_WEBHOOK_TOKEN | Fluxo 4 | Token que autentica o webhook de mensagem (sem ele a rota recusa tudo) |
PIPEDRIVE_ACTIVITY_TYPE_WHATSAPP_KEY | Fluxo 4 | Chave do tipo de atividade "Whatsapp" na conta |
PIPEDRIVE_PROCEDURE_FIELD_KEY | Produção | Campo personalizado "Procedimento" do deal (não existe na conta de teste) |
SYMPLESDESK_OPORTUNIDADE_WEBHOOK_SECRET | Cards | Token que autentica o webhook de Oportunidade (sem ele a rota recusa tudo) |
SYMPLESDESK_ATENDIMENTO_WEBHOOK_SECRET | Fechamento | Token do webhook "Atendimento finalizado" |
SYMPLESDESK_CW_BASE_URL / SYMPLESDESK_CW_ACCOUNT_ID / SYMPLESDESK_CW_API_TOKEN | Conta 142 | As 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_SECRET | Conta 142 | Segredo 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_MIN | Opcional | Conversa criada há mais que isto, em minutos, não vira lead (padrão 15) |
SYMPLESDESK_CARDS_LIGADOS | Opcional | Chave única dos cards de Oportunidade: ausente = ligados; false desliga todos, em silêncio |
PIPEDRIVE_SURGERY_DATE_FIELD_KEY | NPS | Campo "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_ID | NPS da consulta | Usuá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_CRON | Opcional | Horário do job da conversa (cron, fuso Brasília; padrão 0 19 * * * = 19h) |
CLOSE_LOST_CRON | Opcional | Quando checar conversas a fechar (padrão 15 * * * * = de hora em hora, aos :15) |
CLOSE_LOST_MAX_PER_RUN | Opcional | Teto de fechamentos por rodada (padrão 25; 0 desliga) |
NPS_SYNC_CRON | Opcional | Horário do job de NPS (padrão 0 7 * * * = 7h) |
CNN_CADASTRO_MODE | Cadastro CnN | Ní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_CID | Cadastro CnN | Credenciais da API do Clínica nas Nuvens. Faltando qualquer uma, todo ganho de Consulta vira evento de erro |
CNN_SYNC_PUSH_ENABLED | Sincronização CnN | Liga 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_CRON | Opcional | Horá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_KEY | Opcional · Sincronização CnN | Chave 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_ENABLED | Opcional · Sincronização CnN | Leva 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_KEY | Cadastro CnN · NFS-e | Campo "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_KEY | Cadastro CnN | Campo "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_KEY | Opcional · NFS-e | Campo "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_KEY | Sem efeito | Campo "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_ENABLED | NFS-e | Liga 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_ENABLED | Emissão NFS-e | Liga 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_ESCOPO | Emissão NFS-e | todos = 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_DEALS | Opcional | Ids de deal separados por vírgula, para teste. Só é lida no piloto; com o escopo todos, é ignorada |
NFSE_AMBIENTE | Emissão NFS-e | producao = Emissor Nacional de verdade, nota com valor fiscal. Ausente ou qualquer outro valor = homologação (produção restrita, sem valor fiscal) |
NFSE_ENVIO_ENABLED | Emissão NFS-e | Só o valor exato true envia a nota ao governo; fora isso é o ensaio (monta, valida, assina e grava, sem enviar) |
NFSE_EMISSAO_MODO | Opcional | Ausente = 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_SENHA | Emissão NFS-e · secretas | Certificado 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_SENHA | Emissão NFS-e · secretas | O mesmo, para a Lindomar Delgado (cirurgia e fisioterapia) |
NFSE_SERIE_DPS | Emissão NFS-e | Sé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_PTOTTRIBSN | Emissão NFS-e | Percentual 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_DESTINO | Emissão NFS-e | Quem 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_ID | Opcional | Id 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_KEY | Opcional | Tipo de atividade usado nas duas atividades de nota (padrão task, "Tarefa") |
CNN_CONVENIO_PARTICULAR_ID | Emissão NFS-e | Id 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_FZAP | Agenda | Token da instância FZAP (WhatsApp conectado por QR code) que envia a lista do dia seguinte |
FZAP_BASE_URL | Opcional | Endereço da instância FZAP; tem valor padrão de fábrica, só precisa ser definida se o endereço mudar |
AGENDA_DESTINO | Agenda | Quem 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_MEDICOS | Opcional | Mé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_CRON | Opcional | Horário do envio (cron, fuso Brasília; padrão 0 18 * * * = 18h) |
DISCORD_ERROR_WEBHOOK_URL | Opcional | Alertas operacionais de erro |
PORT | Opcional | Porta HTTP (padrão 3000) |
npx tsx scripts/sonda-cnn-prontidao.ts, que é somente leitura.
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):
| Tabela | O que guarda |
|---|---|
nfse_emissoes | Uma 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_fisio | Quais 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_responsaveis | Quem 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_vez | A 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).
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 criar | Evento | URL da API | Autenticação |
|---|---|---|---|
| SymplesDesk (2 canais) | Mensagem criada | /webhooks/symplesdesk-newmessage | Token de autenticação |
| Pipedrive (Webhooks v2) | deal: create + change | /webhooks/pipedrive | Usuário e senha (Basic Auth) |
| Pipedrive (Webhooks v2) | person: change (sync de nome e nota de dados da NFS-e) | /webhooks/pipedrive | Usuário e senha (Basic Auth) |
| SymplesDesk (2 canais) | Novo atendimento | /webhooks/symplesdesk | — |
| SymplesDesk (2 canais) | Oportunidade (card) | /webhooks/oportunidade | Token de autenticação |
| SymplesDesk (2 canais) | Atendimento finalizado | /webhooks/atendimento-finalizado | Token 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 |
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.
public.integration_channelsTroque 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);
| Campo | O que é / onde encontrar |
|---|---|
doctor_code | Sigla única do médico (1 letra, ex.: 'T'). Aparece no título do deal (telefone - SIGLA) e amarra todas as outras configs. |
doctor_name | Nome de exibição (ex.: 'Dr. Thiago Delgado'). |
symplesdesk_account_id | ID da conta do canal no SymplesDesk (vem no payload dos webhooks do canal). |
symplesdesk_whatsapp_id | ID do canal de WhatsApp no SymplesDesk (ex.: '139'). É por ele que o Fluxo 1 descobre de qual médico é o lead. |
symplesdesk_base_url | Sempre 'https://serv2api.simplesdesk.com.br' (base da API externa). |
symplesdesk_api_id | ID (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_name | Nome 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_id | ID do usuário do Pipedrive que será o dono dos deals criados (Configurações → Usuários). |
pipedrive_pipeline_id / pipedrive_stage_id | ID do funil de Leads do médico e da etapa de entrada (aparecem na URL do Pipedrive ao abrir o funil/etapa). |
pipedrive_label_id | ID da etiqueta aplicada à pessoa (produção usa a etiqueta "WhatsApp"). Pode ser NULL se não houver. |
is_active | true para ligar o canal; false desliga sem apagar a linha. |
public.integration_pipelinesTrê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);
public.integration_pipeline_stepsSem 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.
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>
<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.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');
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.
telefone - SIGLA. Qualquer
erro fica registrado em integration_events.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.
| Endpoint | Autenticação | O 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/pipedrive | Basic Auth | Fluxos 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-newmessage | Token no header | Fluxo 4: ingestão de cada mensagem |
POST /webhooks/oportunidade | Token no header | Cards: movimento, ganho, perda e renome feitos no quadro |
POST /webhooks/atendimento-finalizado | Token no header | Registra que alguém encerrou o atendimento na mão |
POST /webhooks/symplesdesk-chatwoot/<segredo> | Segredo no final da URL | Conta 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.
.env completo → gera a URL pública fixa da API.db/schema.sql + db/seed_prod.sql
(limpo — os dados atuais são de teste).npm run backfill, com --dry-run antes para conferir os números).integration_events e os
alertas do Discord.