Piloto API EasyJur — Relatório de Validação

Resumo

Projeção financeira

Piloto = soma do preço calculado dos 350 escritórios selecionados. Base completa = extrapolação linear pra 943 pagantes ativos do iturn (Gabriel, 2026-04-27 — pagadores com fatura operacional em aberto, excluindo Legal Ops e Mentoria Black). Snapshot é fixo após ativação · ARR assume retenção 100% sem reajuste contratual. JV apresentou R$ 1.788.907,00 anualizados na planilha (assumindo 1.400 clientes — base maior que a real); número calculado correspondente nessa metodologia é R$ 862,654.24.

Como o cálculo é feito

Para cada escritório da planilha, o script consulta o banco de produção (read-only) seguindo exatamente os 4 passos abaixo, e compara o resultado com o "Preço Sugerido" do JV.

1. Localizar o escritório nos 3 bancos (advogados_iturn → advogados_oabes → advogados_oabmg, primeiro match ganha):

   SELECT id, id_pagador_vinculado, nome
   FROM <banco>.tb_escritorio_advogados
   WHERE id IN (...);

2. Calcular o valor mensal real usando o método MRR via contrato vigente:

   SELECT c.id_cliente AS id_pagador,
          c.valor / TIMESTAMPDIFF(MONTH, c.data_inicio, c.data_final) AS mrr
   FROM tb_contrato c
   INNER JOIN (
       SELECT id_cliente, MAX(id) AS max_id
       FROM tb_contrato
       WHERE id_empresa = 1
         AND id_cliente IN (...)            -- pagadores do passo 1
         AND status = 'VIGENTE'
         AND data_final > data_inicio
         AND data_final != '0000-00-00'
       GROUP BY id_cliente
   ) v ON v.max_id = c.id;

   Espelha o valor mensal real do contrato. Para o cliente que paga R$ 16.734 em 2 parcelas semestrais (contrato anual de R$ 33.469), retorna R$ 2.789/mês. É a base mais fiel pro snapshot da cobrança da API, mas requer contrato vigente no banco — clientes sem contrato VIGENTE caem no piso.
3. Aplicar a regra de cobrança (definida pelo Hideo, 2026-04-27):

   preço_sugerido = MAX(0.10 × fatura_mensal, R$ 30,00)

   O valor é congelado nesse momento (snapshot) — não recalcula depois mesmo se o escritório adicionar/cancelar aditivos.
4. Comparar com a planilha do JV e marcar como divergente quando |Δ| > R$ 1.

Por que 3 métodos?

O JV original calculou via "última fatura paga" — bate com a planilha mas infla quem paga parcelado. Ex.: cliente CARDOSO E MEDEIROS paga R$ 16.734 em 2 parcelas semestrais (contrato anual de R$ 33.469). Pelo método "última paga", o MRR vira R$ 16.734 e a cobrança da API bate em R$ 1.673/mês (10%) — mas o MRR real é apenas R$ 2.789, e a cobrança correta seria R$ 279/mês. Quase 6× de diferença.

Os 166 escritórios divergentes entre os métodos "MRR via contrato" e "Última paga" são exatamente esses casos — clientes que pagam semestral, anual à vista, em 2×, 3×, 6× ou 36× (contratos trianuais). Pra eles a cobrança da API precisa ser tratada com cuidado: ou o piloto exclui esse universo, ou a regra de cobrança é derivada do contrato (não da fatura paga).

Cartão de crédito também é caso especial — Gabriel apontou que o Asaas não permite alterar o valor de cobrança recorrente em CC. O pipeline PLG existente já faz fallback pra boleto nos aditivos novos (tipo_pg='CC' → 'BO' em functions.php:816), mas isso significa que o cliente recebe um boleto separado pra API — vale comunicar.

Casos limite

• Sem id_pagador_vinculado: escritório sem pagador (cobrança não chega) — vai pro piso, mas o pipeline PLG não consegue criar receita. Atenção pra esses antes de ativar.
• Sem fatura/contrato calculável: cliente recém-cadastrado, sem contrato VIGENTE no banco, ou mensalidade isolada sem recorrência clara. Cai no piso R$ 30.
• Casamento exato (Δ = R$ 0): o cálculo bate com o que o JV usou — confiança máxima no número.
• Δ > R$ 1 grande: divergência por modal de pagamento (parcelado ≠ mensal). Filtre na tabela "Com divergência" pra ver os casos.

Resumo por coorte

Desenvolvimento concluído (2026-04-27)

• OAuth 2.1 no Turin MCP com DCR + PKCE + JWT (HS256) carregando user_id+banco — pronto pra Claude se conectar via custom connector. Bearer atual coexiste via MultiAuth, sem quebrar curl/Cursor/Claude Code.
• SSO bridge no monolito (sgr/sso/start.php) com handshake HMAC pro Turin. Hook em checklogin.php retoma fluxo após login (incl. 2FA).
• 3 tabelas OAuth em advogados_iturn (clients, authorization_codes, refresh_tokens) via migration Laravel no Fenix.
• Bases do trial (subpasta api_easyjur/): tabela tb_assinaturas_api_easyjur (1:1 com escritório), funções de DB e negócio (obter_status, calcular_valor_mensal, ativar_escritorio, cancelar_trial, processar_trial_para_assinatura), endpoints (get_status, cancelar_trial), script CLI de ativação em massa, cron diário de transição.
• Logs no Elastic em índice próprio easyjur-logs-api-easyjur em todos os pontos críticos (ativação, cancelamento, trial→assinado, falhas).
• Envs novas no Turin: TURIN_OAUTH_JWT_SECRET, TURIN_SGR_SSO_SECRET, TURIN_SGR_SSO_URL. Env TURIN_PUBLIC_BASE_URL aponta pra turin.easyjur.ygarasab.com em dev.

Próximos passos

• Validar valores divergentes da tabela abaixo (filtre por "Divergência") — entender se o número da planilha é base diferente do que estamos calculando ou se é dado defasado.
• Criar escritorios_elegiveis.php a partir do snapshot validado, com array id_empresa => coorte.
• Frontend: gate de visibilidade da aba (id_empresa==1 OR escritório elegível) + entrada api-easyjur no catálogo do JS + card com contador de dias / botão Cancelar / aviso de cobrança.
• Doc OAuth/claude.ai na aba Integrações apontando pro conector custom.
• Smoke test E2E num escritório de homologação antes de rodar o script de ativação em massa.
• Agendar cron diário (sgr/rotinas/api_easyjur/cron_trial_para_assinatura.php) — 1x ao dia, idealmente antes do horário de cobrança no Asaas.
• Banner pré-lançamento + popup de ativação (Marcelo Hideo).

Pontos fracos / atenções pro teste

• Snapshot é fixo — escritório que adicionar aditivos depois do trial seguirá pagando o valor do snapshot. Comunicar isso explicitamente no popup pra evitar reclamação ("paguei mais aditivos e o preço da API não subiu" pode virar "subiu sem avisar").
• 14 escritórios sem fatura real caem no piso R$ 30 — cliente em trial gratuito recém-cadastrado pode estranhar a cobrança fixa.
• Cancelamento síncrono não revoga tokens — só muda flag. Token Bearer/JWT existente continua aceito até o gate de status ser checado em runtime. Garantir que o verify_token do Turin OAuth + Bearer cheque api_easyjur_status (ou que o JWT tenha TTL curto).
• 3 coortes (7/14/30) são teste A/B/C. Se uma coorte tiver perfil de cliente sistematicamente diferente (ex: A concentrou só Premium e C só Start), os números de retenção/cancelamento ficam viesados — vale checar a estratificação por plano antes de tirar conclusões do teste.
• Health "Saudável/Ideal" — clientes "Em risco" ou "Crítico" no piloto podem cancelar mais por motivos não relacionados ao produto; tratar como variável de controle, não conclusão.
• HubSpot deal silencioso — pipeline atual cria deal no HubSpot mas falha não bloqueia. Pra 350 escritórios de uma vez, vale monitorar o índice easyjur-logs-plg pra detectar massivos falsos negativos.
• Cron pode acumular — se o cron quebrar 1 dia, todos que deveriam ter virado assinatura naquela rodada ficam em trial. Idempotente, mas vale alertar se o número de transições num dia explodir.
• Asaas NFE/cobrança — os 350 vão gerar receitas novas em prod ao mesmo tempo se o cron rodar todos juntos. Considerar escalonar por horário (cota da API Asaas).

Tabela completa