Classificações e Segmentação

Guia completo e aprofundado de como configurar o catálogo, associar categorias e valores em assinaturas, gerenciar ciclos e auditar cobranças no Agnozys.

As Classificações são o pilar de governança e inteligência de dados do Agnozys, permitindo segmentar, agrupar e auditar suas entidades de negócio (Assinaturas, Ciclos e Cobranças) por múltiplos eixos analíticos customizados.

1. Visão Geral e Arquitetura

Em modelos de cobrança recorrente, a gestão financeira exige relatórios sob diversas perspectivas de negócio (por exemplo: faturamento por filial, inadimplência por segmento de mercado ou volume de contratos por canal comercial).

As Classificações atuam como tags e metadados estruturados que acompanham todo o ciclo de vida do cliente e de suas faturas.

Pilares Fundamentais:

Catálogo Centralizado: Configurado por organização, garantindo padronização e evitando duplicidade de termos.
Flexibilidade de Modos: Suporte a categorias de escolha exclusiva (Uma opção) e categorias cumulativas (Múltiplas opções).
Imutabilidade em Cobranças: Congelamento de classificationSnapshot (JSONB) em cada cobrança emitida.
Isolamento Multi-tenant: Proteção total de dados entre organizações com locks transacionais contra concorrência.

2. Classificações vs. Splits de Pagamento

É fundamental diferenciar a finalidade das Classificações da finalidade dos Splits financeiros:

Dimensão	Classificações de Assinatura	Splits de Pagamento
Finalidade Primária	Analítica, governança e segmentação contábil/gerencial	Divisão financeira e repasse entre contas bancárias
Entidades Afetadas	`Subscription`, `Charge`, `SubscriptionCycle`	`Provider`, `ProviderSplit`, `Withdrawal`
Modo de Operação	Escolha única (Uma opção) ou cumulativa (Múltiplas opções)	Porcentagem (%) ou valor fixo (R$) por recebedor
Persistência de Dados	`classificationSnapshot` (JSONB imutável)	`splitRuleSnapshot` e regras de liquidação
Impacto no Repasse	Zero impacto no fluxo de caixa ou saldo de terceiros	Define quem recebe os fundos no payout

3. Tipos de Categoria e Modos de Seleção

Ao modelar seu catálogo, cada categoria deve ser configurada com um dos dois modos de seleção:

A. Seleção Única

Comportamento: A assinatura pode possuir no máximo 1 valor vinculado desta categoria.
Apresentação na UI: Renderizado como um combobox de seleção exclusiva com pesquisa.
Casos de Uso Comuns:
- Unidade Regional / Filial (ex: São Paulo, Rio de Janeiro, Belo Horizonte).
- Segmento Principal (ex: Pessoa Física, Pessoa Jurídica, Governo).
- Centro de Custo (ex: Operações, Comercial, TI).

B. Múltiplas Opções

Comportamento: A assinatura pode possuir 1 ou mais valores simultâneos.
Apresentação na UI: Renderizado como botões/chips selecionáveis.
Casos de Uso Comuns:
- Tags de Negócio (ex: VIP, Piloto, Renovação 2026).
- Canais de Aquisição (ex: Google Ads, Indicação, Evento).
- Serviços Agregados (ex: Suporte 24/7, SLA Dedicado).

4. Configuração e Gestão do Catálogo

Acesse o menu Configurações → Classificações (/settings/classifications). A tela organiza as categorias ativas e arquivadas em uma grade de 2 colunas com toolbar sticky.

Visão Geral do Catálogo de Classificações

A. Barra de Ferramentas e Popovers de Filtro

A barra de ferramentas superior permanece fixa durante a rolagem e oferece controles rápidos:

Barra de Ferramentas com Filtros e Busca

Clique no botão Status (CircleFadingPlus) para alternar entre categorias Ativas e Arquivadas:

Popover de Filtro por Status

Clique no botão Tipo (Shapes) para filtrar pelo modo de seleção (Uma opção ou Múltiplas opções):

Popover de Filtro por Tipo

O campo de busca filtra instantaneamente qualquer categoria ou valor cadastrado conforme você digita.

Clique no botão de recarregar (RefreshCw) para revalidar os dados em tempo real sem precisar recarregar o navegador.

B. Criando uma Nova Categoria

Na barra superior, clique no botão primário Criar (ou Criar Categoria).

No modal Nova Categoria de Classificação, preencha o Nome da Categoria e selecione o Modo de Seleção:

Permite escolher 1 valor exclusivo por assinatura.

Modal de Criação de Categoria com Modo de Seleção Única

Permite escolher múltiplos valores por assinatura.

Modal de Criação de Categoria com Modo de Múltiplas Opções

Clique em Criar Categoria para salvar. A categoria é inserida imediatamente no banco e disponibilizada na grade.

C. Gerenciando Categorias e Valores

Cada card de categoria exibe avatar de iniciais, total de valores, modo e menu de ações (Settings2):

Menu de Ações Rápidas no Card

Clique diretamente no card da categoria desejada:

Modal de Gestão de Categoria e Valores

O modal organiza as opções em ordem lógica:

Dados da Categoria (Bloco Superior): Renomear e alterar modo com botão Salvar Alterações.
Valores Cadastrados (Bloco Inferior): Listagem de itens e campo de adição.

Adicionar Novos Valores

No campo Adicionar novo valor, digite o rótulo do item e pressione Enter ou clique no botão Adicionar:

Adicionando Novo Valor no Modal de Gestão

Editar o Nome de um Valor

Passe o mouse sobre o chip do valor e clique no ícone de lápis (✏️) para abrir o diálogo de edição:

Modal de Edição de Valor

Altere o rótulo e clique em Salvar Alterações.

Arquivar e Reativar Valores

Arquivar: Clique no ícone de arquivo (📦). O valor passa para estado desativado e não é mais oferecido em novos cadastros.
Reativar: Clique no ícone de reload (🔄) no chip arquivado para reativá-lo.

Arquivar a Categoria

No rodapé do modal, clique em Arquivar Categoria. Ela será ocultada dos formulários de nova assinatura e movida para a seção Categorias Arquivadas.

5. Associação na Entidade Assinatura (`Subscription`)

A. Cadastro de Nova Assinatura

Acesse Assinaturas (/subscriptions) e clique em Nova Assinatura.

No primeiro passo do assistente (Cliente e Segmentação), a seção Classificações exibe automaticamente todas as categorias ativas da sua empresa:

Associação de Classificações no Cadastro de Nova Assinatura

Selecione os valores desejados (combobox para categorias de seleção única e chips para categorias de múltiplas opções).

Avance pelos passos de Plano, Itens e Pagamento para concluir o cadastro.

B. Reclassificação de Assinatura Existente

Na tabela de assinaturas (/subscriptions), localize o registro, clique no botão de ações da linha (...) e selecione Editar assinatura:

No modal de edição, role até a seção Classificações:

Modal de Edição de Assinatura com Seção de Classificações

Atualize as categorias conforme a nova realidade contratual e clique em Salvar assinatura.

6. Propagação e Snapshots em Cobranças (`Charge`)

Toda vez que a Agnozys emite um ciclo recorrente (SubscriptionCycle) ou gera uma cobrança avulsa (Charge):

O backend captura o estado das classificações vinculadas à assinatura no segundo da emissão.
É gravado um snapshot JSONB imutável no campo classificationSnapshot da cobrança.

O snapshot congela as seguintes informações:

[
  {
    "categoryId": "cat_123",
    "categoryName": "Unidade Regional",
    "categorySlug": "unidade-regional",
    "categoryMode": "SINGLE",
    "values": [
      {
        "valueId": "val_456",
        "name": "São Paulo",
        "slug": "sao-paulo"
      }
    ]
  }
]

Auditoria e Integridade Contábil

Se uma assinatura for reclassificada ou uma categoria for arquivada posteriormente, as faturas passadas já liquidadas não são modificadas. Isso assegura relatórios de conciliação fiscal e DREs perpétuos e à prova de inconsistências.

7. Filtragem e Análise de Relatórios

A. Listagem de Assinaturas (`/subscriptions`)

Na listagem de assinaturas, as tags são exibidas diretamente na coluna de classificações:

Tabela de Assinaturas com Coluna de Classificações

Abra os popovers de filtro na toolbar para segmentar contratos por qualquer categoria:

Toolbar de Assinaturas com Filtros de Classificação

B. Listagem de Cobranças e Pagamentos (`/payments`)

Na tela de cobranças, utilize os snapshots analíticos para conciliação financeira:

Listagem de Cobranças com Snapshots Analíticos

A toolbar de cobranças permite isolar faturamento e inadimplência por filial ou segmento:

Filtros na Toolbar de Cobranças

8. Matriz de Permissões e Segurança (RBAC)

Ação no Sistema	Proprietário (`owner`)	Administrador (`admin`)	Membro (`member`)	Visualizador (`viewer`)
Visualizar Catálogo	✅ Sim	✅ Sim	✅ Sim	✅ Sim
Criar / Editar Categorias	✅ Sim	✅ Sim	❌ Não	❌ Não
Cadastrar / Editar Valores	✅ Sim	✅ Sim	❌ Não	❌ Não
Arquivar / Reativar Itens	✅ Sim	✅ Sim	❌ Não	❌ Não
Vincular em Assinaturas	✅ Sim	✅ Sim	✅ Sim	❌ Não
Filtrar Relatórios	✅ Sim	✅ Sim	✅ Sim	✅ Sim

9. Exemplos Práticos de Aplicação

Categoria 1 (Uma opção): Unidade (Matriz Paulista, Filial Campinas, Centro RJ).
Categoria 2 (Uma opção): Especialidade (Dermatologia, Ortopedia, Odontologia).
Categoria 3 (Múltiplas opções): Benefícios (Retorno Grátis, Desconto Exames, Plano Família).

Categoria 1 (Uma opção): Região (Sul, Sudeste, Centro-Oeste, Nordeste).
Categoria 2 (Uma opção): Porte do Franqueado (Quiosque, Loja Shopping, Flagship).
Categoria 3 (Múltiplas opções): Campanhas Comerciais (Black Friday, Expansão Q1, Clube Fidelidade).

Categoria 1 (Uma opção): Tier de Cliente (Enterprise, Mid-Market, SMB).
Categoria 2 (Uma opção): Canal de Aquisição (Inbound, Outbound, Parceiros).
Categoria 3 (Múltiplas opções): Add-ons Contratados (API Avançada, SSO / SAML, Gerente Dedicado).

10. Perguntas Frequentes (FAQ)

O que acontece com cobranças passadas ao renomear uma categoria ou valor?

Nada. Toda cobrança possui um snapshot imutável (classificationSnapshot) registrado no segundo de sua emissão. Renomear um item afeta apenas novos ciclos e novas faturas geradas a partir daquele momento.

Posso alterar o modo de Uma opção para Múltiplas opções em uma categoria já em uso?

Sim! No modal de gestão da categoria, selecione Múltiplas opções e clique em Salvar Alterações. Todas as assinaturas existentes preservarão o valor já escolhido e passarão a permitir a seleção de valores adicionais.

O que acontece ao arquivar uma categoria inteira?

A categoria continua existindo no banco de dados e os contratos atuais continuam operando normalmente. Apenas não será possível selecionar essa categoria para novas assinaturas até que ela seja reativada no catálogo.

On this page