---
id: saas/dados-entregues-aos-clientes
industria: SaaS e tecnologia
uso: muito usado
esforco: médio
grao: Tenant x dia ou mês, e tenant x entidade do cliente (pedido, campanha, item, ligação, dispositivo)
---

# Dados entregues aos clientes do SaaS

Relatório de ROI, portal e extrações para cada cliente do seu SaaS saindo de um modelo só, isolado por cliente e com números que o cliente consegue conferir.

## Resumo executivo

**Para quem:** Empresas de SaaS que precisam provar valor a cada cliente ou entregar a ele os próprios dados.

**O que resolve**

- Cada cliente recebe o mesmo cálculo de valor, sem uma query manual por pedido.
- Nenhum cliente enxerga dado de outro, nem credencial de integração.
- O número entregue diz quando é medido, estimado ou sem dado, e o cliente consegue conferir.

**Por que importa:** O relatório de valor é o que segura a renovação: é nele que o cliente vê receita atribuída, economia ou impacto da funcionalidade. Quando cada cliente vira uma cópia da transformação, os números divergem entre clientes e qualquer correção precisa ser feita centenas de vezes. Um vazamento entre clientes encerra contratos.

**Perguntas de negócio que responde**

- Quanto de receita nossa ferramenta gerou para cada cliente no mês passado?
- Quais clientes tiveram queda de resultado em relação ao mês anterior e precisam de conversa do CS?
- Quanto o cliente economizou desde que começou a usar a automação?
- Os produtos com a nossa funcionalidade vendem mais que os sem ela?
- Quais clientes estão com a integração parada e por isso aparecem sem resultado?
- Quanto tempo leva para colocar um cliente novo no portal?

**O que você precisa**

- Banco do produto conectado na Nekt, com o id do tenant em todas as tabelas ou alcançável por chave
- Uma tabela de configuração por tenant: id, camada de destino, data de início e fontes ativas
- A regra de valor combinada com os clientes: janela de atribuição, linha de base e tarifa

**O que você recebe**

- Tabelas por tenant, isoladas por camada e sem colunas sensíveis
- Relatório mensal de valor com mês fechado, comparação e alertas
- Portal ou extração para o banco do cliente alimentados pelo mesmo modelo
- Um agente de IA que responde por cliente sem misturar dados

## Detalhado

### O problema

Clientes do SaaS pedem os próprios dados e uma prova de valor, e cada pedido vira uma query no banco de produção ou uma cópia da transformação com o id do cliente fixo no código. Há workspaces com centenas de cópias quase iguais, e um ajuste de regra precisa ser repetido em todas. Ao mesmo tempo, a métrica de valor tem detalhes que mudam o número: janela de atribuição, horário truncado pela integração, dia sem medição e tarifa ausente.

### Regras de negócio

1. **Um modelo parametrizado, não uma cópia por cliente.** Escreva a transformação uma vez com o id do tenant como coluna e leia a lista de tenants de uma tabela de configuração (id, nome de exibição, camada de destino, data de início, fontes ativas, parâmetros como janela e tarifa). Cliente novo é uma linha nessa tabela. Cópias só se justificam quando o cliente tem fonte própria que não existe para os outros, e mesmo assim chamando o mesmo cálculo. (Evite: Duplicar a transformação e trocar o id literal do cliente em cada cópia.)
2. **A camada é a fronteira de permissão.** Na Nekt, permissão se dá por camada. Entregue cada cliente numa camada própria (ou num destino próprio) e nunca numa tabela compartilhada filtrada só na leitura. A tabela consolidada com todos os tenants fica numa camada interna, visível só para o time do SaaS. (Evite: Uma tabela única com todos os clientes e um filtro no painel.)
3. **Filtre pelo tenant e propague pelas chaves.** Tabelas que têm o id do tenant são filtradas direto. Tabelas filhas sem essa coluna (itens, mensagens, insights) entram pela chave estrangeira da tabela dona; tabelas de referência entram só com as linhas que os registros do tenant usam. Confira que toda tabela copiada tem caminho até o tenant. (Evite: Copiar tabelas filhas inteiras porque não têm a coluna do tenant.)
4. **Remova colunas sensíveis antes de entregar.** Mantenha uma lista fechada de colunas que nunca saem: client_secret, access_token, refresh_token, senhas, chaves de API e credenciais de integração. Exclua-as em toda tabela entregue, inclusive nas que vêm de conector padrão, como o client_secret do payment intent do Stripe. (Evite: Copiar a tabela inteira do banco do produto para a camada do cliente.)
5. **Atribuição com janela declarada.** Receita atribuída a uma mensagem, campanha ou automação conta só pedidos do mesmo cliente final feitos depois do envio e dentro da janela combinada (um caso real usa 3 dias). Cada pedido é atribuído a um único disparo, o mais recente antes dele. Valores em centavos são divididos por 100 uma vez. (Evite: Somar todo pedido do contato no mês como receita da ferramenta.)
6. **Detecte horário truncado por tenant.** Algumas integrações de pedido mandam só a data, com hora 00:00:00. Para cada tenant, olhe os últimos três pedidos: se todos têm hora, minuto e segundo zerados, trate o campo como data e compare a janela em dias; senão, como timestamp. Guarde a decisão na configuração do tenant. (Evite: Comparar pedido à meia-noite com mensagem enviada às 15h e perder a atribuição do mesmo dia.)
7. **Sem dado é nulo, com o motivo.** Se falta um insumo (tarifa não cadastrada, medidor offline, integração parada), o resultado é nulo com uma coluna de motivo, nunca zero. Distinga erro de dado de decisão deliberada: um cliente que contratou só a medição em kWh tem economia em reais nula e sem alerta, não um alerta de tarifa incompleta. (Evite: Gravar economia zero quando não há tarifa.)
8. **Estimado aparece como estimado.** Dias sem leitura podem ser preenchidos pela média do mesmo dia da semana no período real mais próximo, mas a linha leva uma marca (medido ou projetado). Nunca use um valor fixo de preenchimento. A linha de base de economia é a média por dia da semana na janela de monitoramento antes da automação; se a operação muda (por exemplo, o número de equipamentos), abra um novo regime de linha de base com data de corte. (Evite: Preencher lacunas com um valor fixo e entregar como dado real.)
9. **Com e sem a funcionalidade, pelo mesmo catálogo.** Para provar impacto de uma funcionalidade, divida os itens do cliente em com e sem ela a partir da lista que o próprio cliente mantém, e compare visualizações, carrinho, compra e receita no mesmo período. O cruzamento é pelo id do item; sem id, pelo nome que começa com o nome cadastrado, ficando com um único casamento, o mais específico (nome mais longo). (Evite: Casar por nome com contém e contar o mesmo item em dois grupos.)
10. **Leia as tabelas brutas da aplicação e documente as que enganam.** Quando o produto grava tabelas derivadas próprias (prefixos como dw_ ou dwt_) ao lado das tabelas de aplicação, use as de aplicação, que são a fonte da verdade. Registre no context document as tabelas cujo nome engana (por exemplo, uma tabela chamada crédito que guarda cobranças), filtre soft delete (deletedAt nulo) e tire do relatório métricas cujo status nunca é preenchido na origem. (Evite: Montar o relatório a partir das tabelas derivadas e confiar no nome da tabela.)

### Como cada número entregue é marcado

Toda linha entregue ao cliente leva o tipo do valor, para o portal e o agente explicarem o número.

- **Leitura ou registro real no período** → Medido (`tipo_valor = medido`)
- **Lacuna preenchida pela média do mesmo dia da semana** → Projetado (`tipo_valor = projetado`)
- **Insumo ausente por erro: tarifa, medidor, integração** → Sem dado, com alerta (`valor nulo, motivo preenchido`)
- **Insumo ausente por escolha do contrato** → Não se aplica (`valor nulo, sem alerta`)
- **Pedido fora da janela de atribuição** → Não atribuído (`fora da receita atribuída`)
- **Integração sem pedido novo há N dias** → Integração parada (`resultado não comparável`)

### Definições

| Métrica | Definição |
|---|---|
| Tenant | cliente do SaaS e unidade de isolamento; uma linha na tabela de configuração com id, camada de destino, data de início, fontes e parâmetros |
| Receita atribuída | soma do valor dos pedidos do tenant feitos depois de um disparo e dentro da janela (ex.: 3 dias), cada pedido atribuído ao disparo mais recente, em reais, por tenant e mês |
| Taxa de entrega | mensagens com status enviado, entregue ou lido / mensagens disparadas, por campanha e canal |
| Taxa de conexão | ligações com status conectado / ligações finalizadas (exclui em preparação e em andamento), por tenant e período |
| Taxa de influência | pedidos entregues influenciados / base alcançável (contatos com pedido anterior ou conversa, sem opt-out de campanha), por tenant e mês |
| Economia | (linha de base por dia da semana menos consumo real) x tarifa da faixa horária, por tenant e dia; nula quando falta tarifa |
| Relatório mensal de valor | mês fechado anterior contra o mês antes dele, com delta percentual e alertas, uma linha por tenant |
| Impacto da funcionalidade | visualizações, carrinho, compras e receita dos itens com a funcionalidade contra os sem, no mesmo período e tenant |

### Armadilhas

- **Centenas de cópias.** Uma transformação por cliente cresceu para centenas de versões; uma correção de regra deixou clientes com números diferentes para o mesmo cálculo. Como evitar: Parametrize por tenant e migre as cópias para o modelo único.
- **Prefixo de conector fixo no código.** Quando cada fonte conectada gera tabelas com o id do conector no nome, o id muda entre workspaces e se a fonte for reconectada; queries com o id fixo quebram. Como evitar: Resolva o prefixo atual listando as tabelas antes de consultar e nunca grave o id no context document.
- **Apagão do histórico por sincronização completa.** Uma sincronização completa da origem apagou meses de dados brutos que não existiam mais na API, e o relatório de valor perdeu o histórico. Como evitar: Guarde um backup congelado do histórico já entregue e reprocesse por cima dele.
- **Planilha do cliente com texto no número.** Planilhas de cadastro trouxeram vírgula decimal, ponto de milhar, símbolo de moeda, células vazias e erros como #DIV/0!. Como evitar: Converta com tentativa segura e transforme erro e vazio em nulo, nunca em zero.
- **Datas em quatro formatos.** O mesmo campo de data veio como ano-mês-dia, mês/dia/ano, dia/mês/ano e mês por extenso, conforme o tenant. Como evitar: Tente os formatos em ordem fixa, registre o formato por tenant e marque o que não converteu.
- **Calendário diferente entre motores.** Dia da semana numerado de forma diferente entre Spark e Athena trocou a linha de base de dia, e feriados móveis como a Páscoa ficaram de fora. Como evitar: Use um calendário único com dia útil e feriados nacionais e móveis, gerado uma vez.

### Teste de aceitação

- [ ] Para um tenant e um mês fechado, a receita atribuída bate com o painel do próprio produto (diferença abaixo de 1%) e nenhum pedido aparece atribuído a dois disparos.
- [ ] Em cada camada de cliente existe exatamente um id de tenant distinto em todas as tabelas.
- [ ] Nenhuma tabela entregue contém colunas da lista de proibidas (client_secret, access_token e afins).
- [ ] O número de linhas marcadas como projetado é igual ao de dias sem leitura, e não existe economia zero em linha sem tarifa.
- [ ] Adicionar um tenant de teste exige só uma linha na configuração e gera o relatório dele na próxima execução.

### Context document

```text
Dados entregues aos clientes do SaaS
- Tenant = cliente do SaaS. A lista de tenants e seus parâmetros (camada de destino, data de início, janela de atribuição, tarifa, formato de data) está na tabela de configuração de tenants.
- Toda pergunta sobre um cliente filtra um único tenant. Nunca misture tenants numa resposta para um cliente.
- A camada de cada cliente é a fronteira de permissão. A tabela consolidada é interna.
- Nunca exponha client_secret, access_token, refresh_token, senhas ou chaves de API.
- Receita atribuída: pedidos depois do disparo e dentro da janela do tenant (padrão de 3 dias), cada pedido no disparo mais recente. Valores em centavos divididos por 100.
- Tenant com horário de pedido truncado (00:00:00) compara a janela por data.
- Valor nulo significa sem dado; leia a coluna de motivo. Nulo não é zero.
- Linhas com tipo_valor = projetado são estimadas pela média do mesmo dia da semana. Diga que são estimadas.
- Relatório mensal: mês fechado anterior contra o mês antes dele.
- Use as tabelas de aplicação, não as derivadas com prefixo dw_ ou dwt_. Filtre registros com deletedAt preenchido.
- Se o conector gera tabelas com prefixo de id, descubra o prefixo listando as tabelas antes de consultar.
Exceções por cliente:
- <cliente>: janela de atribuição de <n> dias em vez de 3.
- <cliente>: contratou só a medição; economia em reais fica nula e não gera alerta.
- <cliente>: linha de base trocada em <data> por mudança na operação; antes e depois são regimes separados.
```

### Variações

- **Mídia e site por cliente:** Quando o conector é de uma conta por fonte, cada cliente entra como mais uma fonte no mesmo modelo, com a conversão canônica combinada (ex.: um evento de cadastro no GA4).
- **Extração bruta para o cliente:** Em vez de métricas, a cópia filtrada das tabelas do tenant para o banco dele, com a mesma propagação por chave e a lista de colunas proibidas.
- **Indicadores por área interna:** O mesmo desenho serve para painéis por setor: uma camada por área, com o cálculo de atingimento no pipeline e não no agente.