Partner Program — parceiros, indicações e portal

Objetivo

Transformar agências, consultorias, implementadores, influenciadores e revendedores num canal de aquisição e expansão da Radhr AI, com regras publicadas e verificáveis. Nesta sprint (1) existem o cadastro, a aprovação, a organização do parceiro, os termos, o portal com indicações e clientes vinculados, os links de atribuição e o painel do master. As comissões, os fechamentos e os pagamentos (sprint 2), as metas, o ranking, o Health Score e o forecast (sprint 3), o Coach e a Academy (sprint 4) e a revenda white label (sprint 5) estão desenhados em docs/radar/partner-program.md e, dos itens acima, só os das sprints 3–5 ainda não existem no código. A sprint 2 trouxe o dinheiro: recebimentos, fechamento mensal, demonstrativo, nota fiscal, pagamentos, reserva e dados bancários — tudo sobre as regras puras e testadas de src/parceiros/programa.ts.

Fluxo

Cadastro (/partners): a empresa preenche razão social, CNPJ (validado pelos dígitos), tipo, porte, região, responsável, e-mail e como pretende vender, e aceita os termos. Limite de 10 cadastros por IP por dia e campo armadilha para robôs. O parceiro nasce pendente; o responsável recebe "recebemos" e os admins da Witbiz são avisados com o link da ficha. CNPJ ou e-mail já cadastrados recebem a mesma resposta pública, sem revelar nada.
Aprovação (/radar/plataforma/parceiros/:id, só o master): "Aprovar" cria a organização do parceiro no plano parceiro (slug do nome, único), liga a flag partner_program para ela, gera o código (P + 7 caracteres) e o convite de owner (7 dias) e manda o e-mail de boas-vindas com o link do convite e o link de indicação. "Recusar" exige motivo e avisa o responsável; recadastro só depois de 90 dias.
Termos (/radar/parceiro/termos): no primeiro acesso ao portal o admin da organização do parceiro aceita os termos da versão vigente (versão, quem, quando, IP e navegador registrados; evento parceiro_termos_aceitos). O status aprovado vira ativo. Nova versão exige novo aceite.
Indicação: pelo portal (registro de oportunidade), pelo link (/?ref=<código> ou /planos?ref=<código>: o widget guarda a origem e o lead que conversar ou preencher o formulário fica atribuído) ou por nomeação (o master vincula). O registro cria um lead na organização 1 (origem parceiro) e a indicação registrada com exclusividade de 90 dias, renovável uma vez; a Witbiz é avisada por e-mail. O parceiro acompanha só o status.
Conflito: CNPJ ou domínio já registrados por outro parceiro dentro da exclusividade, empresa já cliente ou em negociação direta há menos de 90 dias → a indicação nasce duplicada, com o motivo, sem lead.
Espelho: o estágio do lead reflete na indicação (qualificado/handoff/reunião/proposta → qualificada; perdido → perdida). Quando o master cria a organização da empresa e a vincula pela ficha do parceiro, a indicação vai a em_teste (ou ativa se o plano já é pagante), a organização ganha parceiro_id e nasce o vínculo em parceiro_clientes. A ativação pelo primeiro recebimento chega na sprint 2.
Expiração: o cron diário marca como expirada a indicação registrada ou qualificada cuja exclusividade venceu sem conversão.
Recebimentos (/radar/plataforma/recebimentos, master): a única fonte de comissão. Registrados à mão, por importação de CSV (prévia linha a linha; referência repetida é pulada) ou pelo webhook do Asaas (POST /api/webhooks/asaas, token no header, idempotente por id do pagamento; referência externa org:<id>[:anual]). Estorno é linha nova negativa apontando a origem. O primeiro recebimento de uma organização indicada marca o vínculo como pagante (ativo_desde) e leva a indicação a ativa.
Fechamento (cron do dia 1 à 1h UTC para a competência anterior, ou "Rodar agora" do master, idempotente): para cada parceiro, o motor puro recebe os recebimentos da competência (anual em 1/12 a partir do mês do recebimento), os clientes ativos (recebimento nos últimos 35 dias; anual 12 meses), o nível (histerese de dois fechamentos; os requisitos de certificação entram com a Academy, sprint 4), o trimestre (clientes novos, meta do nível, comissão do MRR novo, manutenção), a conquista (promovido no fechamento anterior e mantido), a retenção (marcos de 6/12/24/36 meses), o upgrade de plano, a reserva a liberar (competência −2), os ajustes e penalidades pendentes do master, o saldo anterior e o bloqueio. Grava o fechamento (hash, imutável) e o razão (parceiro_lancamentos, imutável); em análise ou suspenso o pagamento fica congelado (saldo transportado); abaixo de R$ 100 o saldo transporta. O parceiro recebe o demonstrativo por e-mail.
Nota fiscal e pagamento: o parceiro informa número e chave da NF no demonstrativo (fechado → nf_recebida); o master marca como pago (PIX/TED, referência) só com a NF; as linhas do razão viram pago (a reserva fica retido). Erro depois do fechamento vira ajuste ou penalidade do master para uma competência ainda aberta, com motivo.
Cancelamento: o master encerra o vínculo com o cliente; até 30 dias do primeiro recebimento a indicação é anulada (sem comissão, não conta para metas); depois, vai a perdida e a comissão para.
Campanhas (/radar/plataforma/parceiros/campanhas, master): sobrescrevem a tabela padrão por período (AAAA-MM) e público (níveis, tipos, parceiros), com orçamento. meta_trimestral troca a meta do nível; bonus_novo paga R$ por cliente novo no mês (limitado ao saldo do orçamento, e a linha avisa); comissao_extra soma pontos à comissão (até 15); desafio registra prêmio e critério para o master decidir. O fechamento aplica as vigentes, grava a campanha na referência do lançamento (bonus_campanha) e soma o gasto.
Partner Health Score e forecast (/radar/parceiro/saude, /radar/parceiro/forecast): calculados do banco (vínculos, recebimentos de 24 meses, indicações, bônus de expansão) pelas regras puras de programa.ts, gravados por dia em parceiro_scores (cron diário, fechamento, "Reler agora") e espelhados em parceiros.health_score. Parceiro com menos de 4 fechamentos tem retenção e churn neutros. O forecast usa churn dos 12 meses (mínimo 2%/mês), expansão 0,5% e o pipeline das indicações abertas (10/30/55% por status, MRR do Profissional como referência).
Ranking (/radar/parceiro/ranking): gravado a cada fechamento mensal por MRR líquido gerado (comissão ÷ percentual), desempate por clientes ativos e Health. O admin do parceiro decide aparecer no ranking público (/partners/ranking: nome e nível dos 10 primeiros, nunca valores); os demais aparecem no portal como "parceiro".
Metas (/radar/parceiro/metas): nível e próximo nível, meta do trimestre corrente (clientes pagantes desde o início do trimestre contra a meta do nível ou da campanha), acelerador atual, degraus, próximos marcos de retenção, histórico de nível e campanhas vigentes. A Home da organização de parceiro ganha o cartão da parceria.

Regras de negócio

Só pessoa jurídica (CNPJ válido) entra; a mesma resposta pública vale para cadastro novo e repetido.
O parceiro é uma Organização no plano parceiro (R$ 0, não público); cliente que também é parceiro usa a mesma organização com a flag ligada. Um login só.
A indicação é um lead da organização 1; o parceiro nunca vê a triagem, as notas nem a proposta — só o status, a ficha que ele mesmo informou e a linha do tempo de status.
Do cliente vinculado o parceiro vê apenas nome, plano, ciclo, status e desde quando.
Atribuição: registro de oportunidade (exclusividade de 90 dias, renovável uma vez) prevalece sobre o link; em conflito vence a atribuição mais antiga e a outra fica duplicada. A Witbiz pode vender direto a qualquer empresa não registrada.
O link do parceiro nunca sobrescreve a origem que o lead já tem (regra herdada da captação ?ref=).
Nível provisório pela contagem de clientes pagantes (plano público, ativa, fora do teste) até os recebimentos existirem; a regra oficial (cliente ativo com recebimento nos últimos 35 dias) entra na sprint 2.
Status do parceiro pela máquina parceiro (pendente → aprovado → ativo; ativo ↔ em análise; suspenso; bloqueado; encerrado; recusado); toda transição registra evento com de/para/por/motivo. Em análise ou suspenso o portal abre em modo de consulta; bloqueado e encerrado não abrem.
Toda ação do master exige motivo (salvo aprovar, liberar e reativar) e vira evento e trilha em acessos.
Base da comissão: valor recebido − taxas do meio − tributos destacados (a alíquota efetiva publicada em programa.ts é 0 até os sócios decidirem). Reserva de 10% por duas competências (20% nos três primeiros fechamentos), liberada integral: a proteção contra estorno é a compensação do saldo negativo.
Fechamento e razão são imutáveis no banco (trigger): só status, NF e pagamento mudam.
Campanha só entra no fechamento se estiver ativa e a competência estiver no período; o orçamento limita o bônus; pontos extras somam no máximo 15; a meta de campanha vale a menor entre as vigentes.
Os requisitos de certificação e Health para Silver+ seguem desligados até a Academy (sprint 4).
Dados bancários cifrados no Worker (AES-GCM, segredo PARCEIRO_CHAVE_DADOS); sem o segredo o portal não grava e pede o envio por e-mail. Toda alteração avisa o responsável e os admins da Witbiz.

Casos de uso

Agência quer vender a Radhr AI: cadastra em /partners, é aprovada, cria o acesso pelo convite, aceita os termos e registra a primeira oportunidade; a Witbiz faz a triagem e, quando cria a organização do cliente, vincula.
Lead chegou pelo link: o visitante abriu novo.witbiz.com.br/?ref=PABCD234, conversou com o agente e virou lead; o lead aparece com origem parceiro e a indicação aparece no portal com origem link.
Dois parceiros, a mesma empresa: o segundo registro vira duplicada com o motivo; o master arbitra se preciso.
Parceiro suspeito: o master põe em análise (portal avisa, pagamentos congelados na sprint 2), decide com motivo.
Witbiz confere o programa: /radar/plataforma/parceiros lista todos por status, com as indicações abertas.

Telas

/partners (pública): hero, benefícios, como funciona, comissões e níveis, planos com a comissão por nível, bonificações, depoimentos (vazios até existirem), certificações, FAQ e cadastro. /partners/termos: texto vigente.
/partner-portal → /radar/parceiro: visão geral (indicações por status, clientes vinculados, nível e próximo nível, link, o que vem nas próximas sprints); /radar/parceiro/indicacoes (lista com filtros e registro de oportunidade); /radar/parceiro/indicacao/:id (ficha e linha do tempo de status, renovação); /radar/parceiro/ clientes; /radar/parceiro/links; /radar/parceiro/termos; /radar/parceiro/dados.json.
/radar/plataforma/parceiros e /radar/plataforma/parceiros/:id (master): lista, ficha, indicações com o vínculo à organização, ações com motivo.
/radar/parceiro/comissoes (extrato por competência), /radar/parceiro/comissoes/:competencia (razão, totais, hash, nota fiscal) e /pdf; /radar/parceiro/pagamentos (histórico, reserva, dados bancários).
/radar/plataforma/recebimentos (registrar, CSV com prévia, estornar) e /radar/plataforma/parceiros/fechamentos (fechamentos da competência, rodar agora, marcar pago, ajuste/penalidade, encerrar vínculo, CSV), master.
/radar/parceiro/metas, /radar/parceiro/ranking (com opt-in), /radar/parceiro/forecast (+ .json), /radar/parceiro/saude (com "Reler agora"); /radar/plataforma/parceiros/campanhas (master); /partners/ranking (público). O relatório semanal da Witbiz ganha o bloco "Parceiros" (ativos, pendentes, pagantes, MRR via parceiros, comissões e a pagar da última competência).
O trilho ganha o grupo "Parceria" nas organizações de parceiro e o item "Parceiros" no grupo Plataforma do master.

Permissões

Portal: parceria.ler (todo papel da organização do parceiro), parceria.indicar (owner, admin, manager, sales), parceria.configurar (owner e admin: termos, membros do portal). Nos papéis legados, leitura e financeiro só consultam; o aceite dos termos é do admin.
Master: plataforma.parceiros (aprovar, recusar, analisar, liberar, suspender, reativar, bloquear, encerrar, vincular) e plataforma.parceiros_financeiro (recebimentos, fechamentos, pagamentos, ajustes). Os demais admins da Witbiz não veem o painel.
Portal financeiro: parceria.financeiro (owner, admin, financial): nota fiscal e dados bancários; no papel legado, financeiro e admin/consultor; leitura não.
Ranking público: parceria.configurar (admin da organização); "Reler" o Health Score: quem opera (parceria.indicar); campanhas: plataforma.parceiros_campanhas (master).
Flag partner_program: desligada por padrão; ligada na organização do parceiro na aprovação e no plano interno.
Público: POST /partners/cadastro limitado por IP (LIMITES_PUBLICOS.parceiro_cadastro).

Perguntas frequentes

Sem a migração 0041, o que acontece? /partners continua no ar com o cadastro (que falha com aviso); o portal e o painel explicam que a migração falta. Nada mais muda.
O parceiro vê os leads da Witbiz? Não. Vê só o status da própria indicação.
Como testar o link? Abra /?ref=<código> e preencha o formulário do site: o lead nasce com origem parceiro e a indicação aparece no portal com origem link.
Quando a comissão aparece? No dia 1 do mês seguinte ao primeiro recebimento registrado de um cliente do parceiro, no extrato em /radar/parceiro/comissoes.
Posso corrigir um fechamento? Não: lance um ajuste ou uma penalidade para a competência seguinte, com motivo.
Sem a migração 0042? As telas financeiras explicam; o restante do programa segue. Sem a 0044, campanhas, ranking e scores não gravam (o cálculo ainda aparece na tela).
O Health Score muda o nível? Ainda não: o requisito de Gold+ passa a valer com a Academy (sprint 4).