Pular para o conteúdo

Para equipe ilarika

Assinatura: o que é plano, add-on, crédito e fatura

  • Super AdminAssinaturasCobrança automática

Como o iLarika cobra uma loja e o que cada estado da assinatura permite. É a base das outras docs: assinar, minha assinatura, atraso e bloqueio, fatura e pagamento e Super Admin › Assinaturas.

Os quatro nomes

  • Plano: o pacote de recursos da loja (Starter, Essencial, Pro, Rede). Por dentro, um produto do tipo plan que aponta para o catálogo de capacidades que a loja recebe. Tem preço mensal e, se quiser, anual.
  • Add-on: um recurso vendido à parte. Um produto do tipo addon que liga ou eleva chaves do catálogo enquanto está na assinatura. Hoje nenhum está à venda: a atendente com IA vem no plano (Essencial e Pro), e o único add-on do catálogo é o interno de excedente de IA, que só dá nome à linha da fatura.
  • Crédito de IA: um pacote de atendimentos comprado à parte, que não vence. Um produto do tipo credit_pack; não entra como item da assinatura, é compra avulsa.
  • Fatura: o documento que a loja paga. Cada fatura tem linhas (plano, add-on, excedente de IA, ajuste), um número legível por ano (2026-000123) e um vencimento. Depois de aberta, não muda: corrigiu algo, emite um ajuste ou anula e abre outra.

Os estados da assinatura

Estado A loja consegue O que o painel mostra
Em teste (trialing) tudo do plano escolhido “X dias de teste”
Ativa (active) tudo nada de especial
Atrasada (past_due) tudo, durante a carência (7 dias por padrão) faixa vermelha persistente
Suspensa (suspended) só a tela de Assinatura, Conta e Suporte “sua loja foi pausada; pague para voltar na hora”
Cancelada (canceled) o mesmo que suspensa; volta só pelo Reativar do Super Admin os dados ficam 90 dias para reativação (Termos do lojista, item 14); apagar é a limpeza manual do Super Admin (Estabelecimentos › Zona de perigo)

Pagar em qualquer ponto volta a assinatura para ativa na hora. Ninguém volta para “em teste”. Só suspensa e cancelada travam a loja: é o que o cardápio público, o marketplace, o bot e o acesso por IA leem para responder “indisponível”.

O que a assinatura faz na loja

Os recursos que a loja tem são derivados do que está na assinatura: o plano vira o plano da loja, e cada add-on vira uma exceção automática no catálogo (marcada addon:<produto>). Trocar de plano é trocar o item e recalcular; nenhuma tela de recurso muda. As exceções manuais do Super Admin continuam valendo e ganham das automáticas.

  • Subir de plano ou adicionar add-on aplica na hora e cobra o proporcional dos dias que faltam no período (crédito do antigo menos custo do novo).
  • Descer de plano ou trocar entre mensal e anual agenda para o fim do período: a fatura desse vencimento já sai no plano novo e, na data, o plano entra. Em teste, qualquer troca vale na hora, sem cobrança.
  • Mês comercial: quem assinou dia 31 vence no último dia de cada mês e volta ao 31 quando o mês tem.

De onde vieram as assinaturas

  • Toda loja que existia antes da cobrança ganhou uma assinatura cortesia ativa no plano atual, sem fatura e sem cobrança. A chave billing.enabled em PlatformSetting nasce desligada.
  • As faturas antigas de excedente de IA viraram faturas legacy, com o número gerado e o excedente como linha, sem perder nada.
  • GET /platform/billing/status mostra se a cobrança está ligada, quantas assinaturas há por estado, a carência e a suspensão em dias e o provedor padrão; é o que o painel Cobrança automática lê.

Ligar a cobrança

O interruptor Cobrança automática ligada fica em Super Admin › Assinaturas › Cobrança automática (só superadmin; PUT /platform/billing/cobranca, auditado). O painel mostra também o provedor padrão, o link para o Asaas e a carência / suspensão em dias. Ligada, a régua passa a emitir a fatura do ciclo seguinte, avisar, marcar atraso e suspender, só para assinaturas com preço: as lojas migradas como cortesia continuam sem fatura até ganharem um plano com preço. O roteiro completo, com a loja de teste, o Asaas em sandbox e a virada das lojas reais, está em docs/runbooks/ligar-cobranca-em-producao.md.

O que depende de billing.enabled

Ligada ou desligada, funciona: a vitrine, o checkout (cadastro, código, cobrança da primeira fatura no cartão, Pix à vista no anual ou Pix Automático quando liberado), o webhook do Asaas que libera a loja paga, a compra de pacotes de IA e o “Já paguei”.

Só com ela ligada (é a régua, de hora em hora):

  • o teste de 7 dias com cartão: sem a régua ninguém cobraria o cartão no fim do teste, então com ela desligada a vitrine não oferece teste e o cartão é cobrado na contratação;
  • a fatura do ciclo seguinte (renovação mensal ou anual) e a cobrança automática no cartão salvo;
  • o aviso de 2 dias antes do fim do teste;
  • atraso, pausa e cancelamento por falta de pagamento;
  • trocas de plano agendadas e cancelamentos agendados;
  • o excedente de IA (ele entra na fatura de ciclo).

Com ela desligada, uma loja paga renova sem fatura (fica ativa) e uma loja de Pix (ou Pix Automático) que não pagou fica esperando o primeiro pagamento sem prazo.

Perguntas comuns

Uma loja pode ter duas assinaturas? Não: uma assinatura viva por loja. Rede com várias unidades ganha depois uma conta que agrupa lojas, sem mudar isto.

O Super Admin ainda consegue dar um recurso de graça? Sim, como hoje, pela exceção manual no catálogo. Ela ganha do que a assinatura diz.

Onde ficam os valores? Sempre em centavos, em UTC, nas tabelas subscriptions, subscription_items, invoices, invoice_lines, payment_attempts, billing_payments, subscription_events.