API EasyJur — Respostas pro Escudeiro

1 Renovar trial de 598931185 sem deixar resquício

Estado atual no banco

Escritório

598931185 — GONCALVES BOSON ARRUDA ADVOGADOS

id_aditivo

35

Tier

enterprise (R$ 700/mês · 600.000 reqs)

Coorte

A (trial 7d)

status_api

ativo (passou de em_periodo_teste em 19/05 17:09)

data_inicio_trial

2026-05-12 16:38:12

data_fim_trial

2026-05-19 16:38:12

data_proxima_cobranca

2026-06-19 17:09:23

id_pagador_vinculado

680529204

Sim, já gerou cobrança

Quando o cron cron_trial_para_ativo.php rodou em 19/05 17:09, ele executou processar_contratacao_plg. O PLG somou o valor da API nas faturas em aberto do pagador e atualizou cada cobrança correspondente no Asaas. Reflexo em tb_receitas (id_pagador=680529204):

Além disso, foram criadas 7 linhas em tb_aditivos_pagamentos (id 592–598) com id_receita = NULL — essa tabela é apenas rastreio do PLG, não é a cobrança em si. A cobrança real vive em tb_receitas + Asaas.

Por que sumiu de junho R$ 293,55? O PLG aplicou pro-rata de 13 dias (19–31/05) na próxima fatura em aberto, que era a de junho (vencimento 10/06). Não criou uma fatura nova de maio.

Passos pra estender +30d sem deixar resquício

// Pseudo-código (deve rodar via script PHP no monolito, em produção, master token)
$reversoes = [
    ['id_receita' => 4477164, 'asaas' => 'pay_ecr891eqggo78ron', 'novo_valor' => 7720.05],  // jun
    ['id_receita' => 4477165, 'asaas' => 'pay_v5b3jk9yfzzfbkkh', 'novo_valor' => 7720.05],  // jul
    ['id_receita' => 4477166, 'asaas' => 'pay_pqisixssgisfk11t', 'novo_valor' => 7720.05],  // ago
    // ... seguir pra 4477167, 4477168, 4477169, 4477170
];
foreach ($reversoes as $r) {
    send_asaas_payment_update_put(['value' => $r['novo_valor']], $r['asaas'], get_master_token());
}

USE advogados_iturn;
START TRANSACTION;

-- 1ª receita (junho): subtrair pro-rata
UPDATE tb_receitas
   SET valor = valor - 293.55,
       valor_total = valor_total - 293.55,
       observacao = CONCAT(observacao, CHAR(10), '[REVERSAO ', NOW(), '] -R$ 293,55 - API EasyJur (extensao de trial)')
 WHERE id = 4477164;

-- Outras 6 (jul–dez): subtrair mensalidade
UPDATE tb_receitas
   SET valor = valor - 700.00,
       valor_total = valor_total - 700.00,
       observacao = CONCAT(observacao, CHAR(10), '[REVERSAO ', NOW(), '] -R$ 700,00 - API EasyJur (extensao de trial)')
 WHERE id IN (4477165, 4477166, 4477167, 4477168, 4477169, 4477170);

-- Confirmar valores voltaram a R$ 7.720,05 nas 7
SELECT id, data_vencimento, valor, valor_total
  FROM tb_receitas
 WHERE id BETWEEN 4477164 AND 4477170
 ORDER BY id;

-- Se ok:
COMMIT;
-- Se errado:
-- ROLLBACK;

USE advogados_iturn;

-- Confirmar que são exatamente as 7 que entraram em 19/05 e ainda não viraram receita
SELECT id, mes_competencia, valor, tipo, id_receita
  FROM tb_aditivos_pagamentos
 WHERE id_aditivo = 35
   AND id_receita IS NULL;
-- Esperado: 7 linhas (ids 592 a 598)

-- Deletar
DELETE FROM tb_aditivos_pagamentos
 WHERE id_aditivo = 35
   AND id_receita IS NULL;

USE advogados_iturn;
START TRANSACTION;

UPDATE tb_aditivos_api_easyjur
   SET status_api            = 'em_periodo_teste',
       data_fim_trial        = DATE_ADD(NOW(), INTERVAL 30 DAY),
       data_proxima_cobranca = DATE_ADD(NOW(), INTERVAL 31 DAY),
       data_cancelamento     = NULL,
       coorte                = 'C',                       -- opcional: marcar como 30d
       updated_at            = NOW()
 WHERE id_empresa = 598931185;

-- Validar
SELECT id, id_empresa, tier, coorte, status_api,
       data_inicio_trial, data_fim_trial, data_proxima_cobranca, data_cancelamento
  FROM tb_aditivos_api_easyjur
 WHERE id_empresa = 598931185;

-- Se ok:
COMMIT;

-- Confirmar estado do aditivo
SELECT id, status_api, data_fim_trial, data_proxima_cobranca
  FROM tb_aditivos_api_easyjur
 WHERE id_empresa = 598931185;
-- Esperado: status_api='em_periodo_teste', data_fim_trial = hoje+30d

-- Confirmar receitas restauradas
SELECT id, data_vencimento, valor, valor_total
  FROM tb_receitas
 WHERE id BETWEEN 4477164 AND 4477170
 ORDER BY id;
-- Esperado: todas com valor=7720.05 e valor_total=7720.05

-- Confirmar tb_aditivos_pagamentos limpa
SELECT COUNT(*) FROM tb_aditivos_pagamentos WHERE id_aditivo = 35;
-- Esperado: 0

Queries de apoio

Query 1 — Diagnóstico de qualquer escritório (estado completo do aditivo):

SELECT a.id, a.id_empresa, ea.nome, a.tier, a.coorte, a.status_api,
       p.preco_centavos/100 AS preco_mes,
       a.data_inicio_trial, a.data_fim_trial,
       a.data_proxima_cobranca, a.data_cancelamento,
       a.updated_at,
       (SELECT COUNT(*) FROM tb_aditivos_pagamentos
         WHERE id_aditivo = a.id) AS rastreios_pagamento,
       ea.id_pagador_vinculado
  FROM tb_aditivos_api_easyjur a
  LEFT JOIN tb_api_pacotes p ON p.id = a.id_pacote
  LEFT JOIN tb_escritorio_advogados ea ON ea.id = a.id_empresa
 WHERE a.id_empresa = 598931185;   -- trocar pelo id alvo

Query 2 — Receitas afetadas pelo PLG (todas as 7 do exemplo):

SELECT id, id_pagador, valor, valor_total, status,
       data_cadastro, data_vencimento, id_pagamento_asaas,
       LEFT(observacao, 300) AS observacao
  FROM tb_receitas
 WHERE id_pagador = 680529204
   AND observacao LIKE '%API EasyJur%'
   AND status = 'A'                -- aberta (não pode reverter receita paga sem chargeback)
 ORDER BY data_vencimento;

Query 3 — Rastreio em tb_aditivos_pagamentos (espelho do PLG):

SELECT id, id_aditivo, produto, id_empresa, mes_competencia, valor, tipo, id_receita, created_at
  FROM tb_aditivos_pagamentos
 WHERE id_empresa = 598931185
 ORDER BY mes_competencia;

2 Rollout 30d pra base toda — mapeamento dos não-elegíveis

Universo bruto hoje

Sim, precisa de uma planilha

33 mil escritórios é o universo bruto, mas nem todos têm plano ativo, alguns são contas trial vazias, outros são clientes históricos sem atividade. O piloto original (359) já passou por um filtro externo pelo time do JV/Hideo (planilha c350.xlsx) usando critérios que o banco não tem em coluna única:

• Cliente ativo com plano pago (≠ Trial, ≠ juris_ai, ≠ legal_crm)
• Login ≥ 20 nos últimos 30d (proxy de "usa o sistema")
• Health ≠ Crítico (puxado do CustomerX)
• Pagamento mensal (cartão e à vista anual ficaram de fora em 28/04 e voltaram como Grupo D)

Pro rollout 30d, recomendação prática:

1. Pedir ao Hideo/JV uma planilha equivalente à c350.xlsx com os critérios desta nova fase. Mesma estrutura: id_empresa, nome, tier_sugerido.
2. Aplicar o seed usando o mesmo padrão do D-day original: cria registros em tb_aditivos_api_easyjur_elegiveis com status_aceite='pending' e coorte='C' (30d). O modal aparece pro admin do escritório no próximo login.
3. Não usar caminho B direto (ativação sem modal) pro rollout em massa — isso bypassa o aceite formal e pode gerar dor de cabeça com financeiro/jurídico se cliente reclamar.

Query — universo candidato (com nome e plano)

SELECT
    e.id AS id_empresa,
    e.nome,
    e.cnpj,
    e.tipo_perfil,
    e.juris_ai,
    e.tamanho_escritorio,
    e.data_cadastro,
    e.data_expiracao
  FROM tb_escritorio_advogados e
 WHERE COALESCE(e.bloqueado, 0) = 0
   AND e.id NOT IN (SELECT id_empresa FROM tb_aditivos_api_easyjur_elegiveis)
   AND e.id NOT IN (SELECT id_empresa FROM tb_aditivos_api_easyjur)
   AND (e.data_expiracao IS NULL OR e.data_expiracao > NOW())   -- sem plano vencido
 ORDER BY e.data_cadastro DESC;

Quando a planilha chegar — template de seed

Assumindo que o Hideo/JV mande um CSV com colunas id_empresa, tier_sugerido, o seed segue o padrão do D-day:

-- Pra cada linha da planilha, rodar (com cuidado: validar nº de linhas afetadas)
INSERT INTO tb_aditivos_api_easyjur_elegiveis
    (id_empresa, id_pacote_sugerido, tier_sugerido, coorte,
     status_aceite, created_at, updated_at)
SELECT
    @id_empresa,
    (SELECT id FROM tb_api_pacotes WHERE slug = @tier_sugerido AND ativo = 1),
    @tier_sugerido,
    'C',                                                              -- 30 dias
    'pending',
    NOW(), NOW()
ON DUPLICATE KEY UPDATE
    id_pacote_sugerido = VALUES(id_pacote_sugerido),
    tier_sugerido      = VALUES(tier_sugerido),
    coorte             = VALUES(coorte),
    status_aceite      = 'pending',
    updated_at         = NOW();

Quando o admin do escritório fizer login no SGR, o modal de aceite aparece (mesmo fluxo do piloto). Aceitou → cria tb_aditivos_api_easyjur com status_api='em_periodo_teste', trial de 30 dias, cobrança automática após vencer. Igual coorte C do piloto.

Script Python pra gerar o seed (opcional)

O piloto usou ~/claude/api-launch-v1/scripts/gen_d_day_seed_sql.py (lê XLSX e cospe SQL idempotente). Pra reutilizar, basta trocar o input pelo CSV/XLSX novo e ajustar a coorte default pra 'C'.

3 Documentação da API EasyJur

Existe sim — está distribuída, mapa abaixo

1. Confluence — visão de produto e modelo de cobrança

2. Runbooks operacionais

3. Schema do banco (3 tabelas centrais)

4. Código no monolito

5. Código no Turin (API que valida e contabiliza chamadas)

6. Logs e métricas

• Elasticsearch índice api_easyjur_requests — toda chamada autenticada à API (track_request)
• Elasticsearch índice easyjur-logs-plg — eventos PLG (contratação, atualização Asaas, etc)
• Kibana dashboard exportado em ~/claude/api-launch-v1/kibana-dashboard-api-easyjur.ndjson
• Receita estipulada: relatorios.easyjur.ygarasab.com/receita-estipulada.html · atualizado periodicamente · todas as queries SQL prontas

Resumo do fluxo end-to-end (mapa mental)

D-day (seed)            → tb_aditivos_api_easyjur_elegiveis (status_aceite='pending')
                          │
Admin clica "Aceitar"     │
no modal SGR              │
                          ▼
aceitar_api.php         → tb_aditivos_api_easyjur (status_api='em_periodo_teste')
                          │
Trial roda N dias         │
(coorte A=7d, B=14d, C=30d, D=7d sem cobrança)
                          ▼
cron_trial_para_ativo   → Coorte D: status_api='cancelado' (fim)
                        → Coorte A/B/C: processar_contratacao_plg
                                        │
                                        ├─ Soma valor na tb_receitas (fatura aberta) → Asaas PUT
                                        ├─ INSERT em tb_aditivos_pagamentos (rastreio)
                                        └─ UPDATE tb_aditivos_api_easyjur SET status_api='ativo'

Cliente faz chamada     → Turin valida aditivo em tb_aditivos_api_easyjur
                        → quota_service.track_request() indexa no ES
                        → 429 se estourou quota