---
id: saas/uso-do-produto-no-crm
industria: SaaS e tecnologia
uso: comum
esforco: médio
grao: Conta (empresa ou workspace) e contato, separados em criar e atualizar
---

# Uso do produto no CRM

Plano, status de pagamento e uso de cada conta escritos no CRM onde vendas e CS trabalham, só quando mudam, sem duplicar contato nem apagar o que o time preencheu.

## Resumo executivo

**Para quem:** Empresas de SaaS cujo time de vendas e CS trabalha no CRM, em especial com trial ou self-service.

**O que resolve**

- Vendedor e CSM veem uso, plano e pagamento sem sair do CRM.
- Listas e automações do CRM passam a disparar por comportamento real no produto.
- A sincronização não duplica contatos nem sobrescreve o que o time preencheu.

**Por que importa:** Sem uso no CRM, o vendedor liga para quem nem entrou no trial e o CS descobre o cancelamento pelo billing. Com o dado lá, lista, tarefa e alerta saem do próprio CRM, sem mais um painel. Mas uma sincronização malfeita destrói a confiança no CRM em uma noite.

**Perguntas de negócio que responde**

- Quais contas em trial estão usando o produto e ainda não falaram com vendas?
- Quais clientes pagantes não acessam há mais de 30 dias?
- Quais contas estão com pagamento atrasado, e quem é o dono delas?
- Quantos usuários ativos tem cada cliente da minha carteira?
- Quais workspaces de self-service têm perfil para upsell?

**O que você precisa**

- Banco do produto ou eventos e billing conectados na Nekt
- O mapa de cliente único com o id de cada registro no CRM
- A lista de propriedades que a rotina pode escrever

**O que você recebe**

- Propriedades de uso, plano e pagamento atualizadas no CRM
- Associações de contato, empresa e deal ao workspace do produto
- Um log de envio por registro, com resultado e erro
- Listas, tarefas e alertas do CRM alimentados por dado do produto

## Detalhado

### O problema

Vendas e CS vivem no CRM, mas uso, plano e status de pagamento estão no banco do produto e no billing. A primeira sincronização costuma criar contato duplicado, sobrescrever campo que o vendedor preencheu e contar uso de usuário interno como uso do cliente. Às vezes derruba a própria fonte do CRM. E o destino escreve propriedades, mas não cria associações entre objetos.

### Regras de negócio

1. **Uma tabela por objeto, com o id do CRM.** Monte uma tabela de saída por objeto do CRM (empresa, contato, workspace como objeto customizado), com o id do registro do CRM em cada linha. O id vem do mapa de cliente único, nunca de um cruzamento por nome feito na hora. Contato casa por e-mail em minúsculas e sem espaços. (Evite: Casar empresa do produto com empresa do CRM pelo nome, dentro da rotina de envio.)
2. **Criar e atualizar são rotinas diferentes.** Separe quem ainda não existe no CRM (criar) de quem já existe (atualizar). A rotina de atualizar nunca cria. A de criar confere antes se o e-mail ou o domínio já existe. Comece a criação com um piloto pequeno (por exemplo, 15 registros) e confira se o registro continua lá alguns segundos depois: automações anti duplicado do CRM já apagaram contatos recém-criados. (Evite: Uma rotina só, que cria quando não acha.)
3. **Envie só o que mudou.** Compare o valor calculado com o valor atual no CRM e mande só a diferença. Exemplo: marcar usuário ativo como Não só para quem está Sim no CRM e ficou inativo no produto. Mandar tudo todo dia gasta limite de API, dispara automações à toa e polui o histórico da propriedade. (Evite: Reenviar todas as propriedades de todos os registros a cada execução.)
4. **Campo do time é protegido.** Declare quais propriedades a rotina pode escrever. Telefone, e-mail e documento só são preenchidos quando estão vazios. Dono, etapa e campos editados pelo time nunca são sobrescritos. Propriedades escritas pela rotina ganham um prefixo próprio (por exemplo, lake_ ou produto_), para ninguém editar à mão. (Evite: Sobrescrever telefone e dono com o que veio do produto.)
5. **Uso é do cliente, não do seu time.** Tire do cálculo usuários internos, de suporte e de serviço (por papel, domínio de e-mail ou lista), contas de teste e de demonstração. Usuário habilitado numa empresa sem pacote ou assinatura vigente não é usuário ativo. (Evite: Contar o login do suporte dentro da conta do cliente.)
6. **Pagamento vem do billing, no grão do cliente.** Plano, status da assinatura (active, past_due, canceled, trialing), MRR e data do primeiro pagamento vêm do billing, consolidados por cliente e não por assinatura. Com várias assinaturas, uma regra de prioridade declarada escolhe o status. A data do primeiro pagamento é a da primeira cobrança paga, não a do ciclo. Envie junto a data de referência do dado. (Evite: Mandar o status da última assinatura criada.)
7. **Poucas propriedades, prontas para ação.** Escreva indicadores que o time usa (usuários ativos em 7 e 30 dias, dias desde o último acesso, módulos em uso, faixa do cliente), não um campo por evento ou funcionalidade. Valores de lista vão traduzidos e numa lista fechada. O HubSpot limita o tamanho de uma propriedade a 512.000 bytes, e a fonte de contatos falha acima de 10.000 campos aninhados; depois de 3 falhas seguidas, ela se desativa. (Evite: Criar uma propriedade para cada evento do produto.)
8. **Associação é uma rotina à parte.** O destino da Nekt escreve propriedades pelo id do objeto, mas não associa contato a workspace, empresa a workspace ou deal a workspace. Faça isso num notebook que compara as associações esperadas com as existentes e cria só as que faltam, com o rótulo da associação. Rode em simulação antes: num caso real, duas semanas de simulação mostraram centenas de associações a criar e mais de cem contatos que ainda nem existiam. (Evite: Esperar que o destino crie as associações.)
9. **Trava antes de escrever.** A rotina confere o portal ou a conta de destino antes de escrever (sandbox no teste, o id esperado em produção) e para se não bater. Confere também o volume: catálogo menor que o mínimo esperado ou número de alterações fora do normal indica dado quebrado na origem, e a rotina para em vez de apagar opções ou zerar campos. Cada envio fica num log com registro, valor, resultado e erro. Chave de API fica no cofre de segredos, nunca no código. (Evite: Rodar direto em produção, sem conferir a conta nem o volume.)
10. **Conta que saiu também é enviada.** Inclua contas inativas e excluídas no envio, para atualizar status e data de saída no CRM e na ferramenta de atendimento. Senão o CS continua vendo como ativo quem já cancelou. (Evite: Filtrar só contas ativas antes de enviar.)

### O que vai para o CRM, e de onde vem

Propriedades escritas pela rotina, com prefixo próprio e data de referência.

- **Billing, consolidado por cliente** → Plano e status da assinatura (`subscription.status`)
- **Tabela de MRR** → MRR atual do cliente
- **Primeira cobrança paga** → Data do primeiro pagamento (`charge.status = succeeded`)
- **Eventos do produto, sem internos** → Usuários ativos em 7 e 30 dias
- **Último login de qualquer usuário** → Dias desde o último acesso
- **Lista fechada de módulos** → Módulos em uso
- **Volume acumulado em faixas** → Faixa do cliente
- **Objeto customizado com o id do produto** → Workspace associado

### Definições

| Métrica | Definição |
|---|---|
| Usuário ativo 30d | usuário do cliente, fora internos, de suporte e de serviço, com ao menos um login ou evento nos últimos 30 dias até o dia anterior |
| Usuário ativo no CRM | Sim se o usuário está ativo no produto e a empresa tem pacote ou assinatura vigente; Não nos demais casos |
| Dias desde o último acesso | dias entre o último login de qualquer usuário do cliente e a data de referência |
| Status de pagamento | status da assinatura principal do cliente no billing na data de referência, escolhida por regra de prioridade declarada |
| Data do primeiro pagamento | data da primeira cobrança paga com valor maior que zero do cliente |
| Data de referência | dia do dado que gerou o valor, enviada junto com a propriedade |
| Lote de envio | registros cujo valor calculado difere do valor atual no CRM, com o resultado gravado no log |

### Armadilhas

- **Contato criado e apagado em seguida.** Uma automação anti duplicado do CRM apagava contatos recém-criados pela rotina, e o lote parecia ter dado certo. Como evitar: Crie um piloto e confira se o registro ainda existe alguns segundos depois.
- **Fonte do CRM desativada.** Propriedades demais em contatos passaram do limite de 10.000 campos aninhados; a extração falhou três vezes e a fonte se desativou sem aviso. Como evitar: Poucas propriedades, revisão das que não são usadas e alerta de falha da fonte.
- **Contato em dobro na primeira carga.** Sem separar criar de atualizar, cada execução recriava quem tinha o e-mail com maiúscula diferente. Como evitar: E-mail em minúsculas e rotina de criar que confere existência.
- **Cancelado aparecendo como ativo.** Empresas excluídas ficavam fora do envio e seguiam ativas na ferramenta de atendimento. Como evitar: Envie inativas e excluídas com a data de saída.
- **O time inflou o uso do cliente.** Usuários de um serviço operado pelo próprio time trabalhavam dentro das contas dos clientes e contavam como usuários ativos deles. Como evitar: Exclua por papel do usuário, além de domínio de e-mail e contas de teste.
- **Chave de API no código.** Tokens do CRM e de outras ferramentas estavam escritos dentro de notebooks, visíveis a quem abrisse ou versionasse o código. Como evitar: Guarde no cofre de segredos da Nekt e leia com nekt.load_secret.

### Teste de aceitação

- [ ] Para uma amostra de 20 contas, plano, status e usuários ativos no CRM batem com o billing e o produto na data de referência.
- [ ] Uma segunda execução sem mudança na origem envia zero registros.
- [ ] A rotina de atualizar não cria nenhum contato, e os contatos criados batem com o plano do lote de criar.
- [ ] Nenhum usuário interno, de suporte ou de teste entra na contagem de usuários ativos.
- [ ] Toda associação esperada existe no CRM, e o log não tem erro sem tratamento.

### Context document

```text
Uso do produto no CRM
- Propriedades escritas pela rotina têm o prefixo <prefixo> e trazem a data de referência do dado. Valor no CRM pode estar até 1 dia atrás do produto.
- Usuário ativo = usuário do cliente com login ou evento nos últimos 30 dias, fora internos, suporte, serviço e contas de teste, em empresa com plano vigente.
- Status de pagamento vem do billing, consolidado por cliente: active, past_due, canceled, trialing. Past_due não é cancelado.
- Data do primeiro pagamento = primeira cobrança paga com valor maior que zero, não a data do ciclo.
- A rotina nunca sobrescreve dono, etapa nem campos editados pelo time. Telefone, e-mail e documento só são preenchidos quando vazios.
- Associação contato, empresa e deal ao workspace é feita por rotina própria; registro sem associação não é cliente sem uso.
- Se o valor do CRM divergir do produto, a fonte de verdade é o produto ou o billing, não o CRM.
Exceções por cliente:
- <cliente>: usuários com papel <papel> são internos e não contam como ativos.
- <cliente>: faixa do cliente por volume acumulado: <faixas>.
```

### Variações

- **Planilha como ponte:** Uma planilha alimentada pela Nekt é a fonte única lida por uma automação (por exemplo, n8n) que distribui para várias ferramentas.
- **Faixa por volume:** Faixa do cliente por volume acumulado (por exemplo, por TPV) enviada ao CRM e à ferramenta de tarefas do time.
- **Valor por pessoa:** No self-service, uma linha por e-mail com total pago e status da última assinatura, escrita no contato.