Entitlements

Um Entitlement é o conceito central do MIDDAG Account. É um registro único que significa: "Alguém tem acesso ao Produto ou Serviço Y." Todo entitlement tem um código, um estado de ciclo de vida e vínculos com todos os recursos derivados que o acesso concede — licenças, contratos, serviços, ambientes, faturas e documentos.

Antes dos entitlements, responder "o Cliente X tem suporte ativo?" significava verificar três ou mais sistemas. Com entitlements, você consulta um código e vê tudo: o que foi comprado, quando expira, quais licenças ou serviços estão vinculados e qual é o status atual.

O código do entitlement

Todo entitlement tem um código único e imutável neste formato:

{CLASS}-{YEAR}{MONTH}{SEQ}

Exemplo: PLG-2026040142 — o 142º Entitlement de Plugin criado em abril de 2026.

O código é:

• Único — gerado atomicamente, sem duplicatas
• Imutável — uma vez atribuído, nunca muda, mesmo que o entitlement seja suspenso ou cancelado
• Legível por humanos — o prefixo da classe indica que tipo de acesso ele representa, e a data indica quando foi criado
• Voltado ao cliente — os clientes veem esse código no portal, em e-mails e o referenciam ao abrir chamados de suporte

Este é seu identificador único para qualquer pergunta sobre o relacionamento com o cliente. "Qual é o status de PLG-2026040142?" dá uma resposta instantânea e completa.

Estados do ciclo de vida

Todo entitlement está em um de quatro estados a qualquer momento:

Estado	O que significa
Active	O entitlement está em dia. Todos os recursos derivados (licenças, serviços, ambientes) estão ativos.
Suspended	Temporariamente pausado — geralmente por falha no pagamento ou bloqueio pelo admin. Pode ser reativado.
Expired	A data de expiração passou. O acesso aos recursos derivados é cortado. Pode ser renovado com novo pagamento.
Cancelled	Revogado. Só pode ser reativado por uma operação deliberada de win-back por um admin.

Como as transições funcionam

De	Para	O que dispara	Quem pode fazer
—	Active	Criação (provisionamento automático ou manual)	Sistema / Admin
Active	Suspended	Pagamento falha ou admin aplica bloqueio	Sistema / Admin
Active	Expired	Data de expiração atingida	Cron (automático)
Active	Cancelled	Cancelamento direto	Admin
Suspended	Active	Pagamento resolvido ou admin libera bloqueio	Sistema / Admin
Suspended	Cancelled	Timeout configurável ou decisão do admin	Sistema / Admin
Expired	Active	Cliente renova (novo pagamento)	Sistema / Admin
Expired	Cancelled	Timeout configurável	Sistema / Admin
Cancelled	Active	Win-back (reativa o mesmo código)	Apenas admin

Nenhuma transição fora desta tabela é permitida. Um entitlement não pode ir de expired diretamente para suspended, por exemplo.

Recuperação de pagamento

Quando um pagamento falha (detectado via webhook do Stripe), o MIDDAG Account consulta a Payment Recovery Policy para decidir o que acontece:

1. O Stripe tenta o pagamento novamente no seu cronograma normal.
2. Se a política diz "suspender na primeira falha", o entitlement é movido para suspended imediatamente. Caso contrário, aguarda até que todas as tentativas se esgotem.
3. Se uma nova tentativa for bem-sucedida, o entitlement é reativado automaticamente.
4. Se todas as tentativas falharem, o entitlement permanece suspended por um período configurável antes do cancelamento automático.

Admins podem cancelar manualmente um entitlement suspenso a qualquer momento, ou aguardar o timeout automático.

Win-back

Um entitlement cancelado pode ser trazido de volta. O win-back reativa o mesmo entitlement com o mesmo código — não cria um novo. Isso preserva o histórico completo: pedidos, faturas, contratos e solicitações de serviço permanecem vinculados. Win-back é uma operação exclusiva de admin (uma decisão humana deliberada).

Criação automática a partir de pedidos

A forma mais comum de criar um entitlement é automaticamente, após o cliente concluir uma compra:

Cada item do pedido tem um campo de metadado do produto (_middag_entitlement_class) que indica ao sistema qual classe de entitlement criar. Se nenhuma classe for especificada, o padrão é ORD (compra geral).

O processo é idempotente: se um webhook dispara duas vezes para o mesmo pedido, o sistema verifica se já existe um entitlement para aquela combinação de pedido + item e pula a criação se existir.

Após a criação do entitlement, os recursos derivados são provisionados automaticamente com base na classe:

• PLG cria uma Licença (com chave de ativação e acesso a downloads)
• ENV cria um Ambiente (status: provisioning)
• SVC cria um Serviço, um Contrato (se contínuo) e um Saldo de Créditos
• ORD vincula ao Pedido e à Fatura
• AFL vincula a um registro de Afiliado
• EDU vincula ao Pedido e habilita downloads educacionais

Criação manual

Admins também podem criar entitlements manualmente pelo WordPress admin. Isso é útil para:

• Migrar clientes existentes de um sistema legado
• Conceder acesso cortesia
• Configurar entitlements para negócios que não passaram pelo fluxo padrão de pedidos

Entitlements criados manualmente se comportam de forma idêntica aos criados automaticamente. A única diferença é o campo auto_created, que é false para criação manual.

Entitlements soberanos

Um entitlement não requer uma Organização. Todos os relacionamentos são opcionais — um entitlement pode existir completamente independente, sem nenhum registro de cliente vinculado. É isso que "soberano" significa no MIDDAG Account.

Essa flexibilidade suporta cenários além do B2B tradicional:

• Cartões-presente e acesso promocional — entitlements emitidos sem compra ou cliente
• Clientes individuais (B2C) — uma pessoa, não uma empresa, pode deter entitlements diretamente
• Importações de migração — entitlements importados de sistemas externos onde o mapeamento de organização ainda não existe
• Licenças compartilhadas — entitlements que não estão vinculados a uma única organização

O entitlement é a entidade soberana do sistema. Todo o resto se conecta a ele opcionalmente.

Entitlements pai-filho

Entitlements podem ser organizados em hierarquia. Um exemplo comum: um Entitlement de Serviço (SVC) atua como contrato-mestre, com Entitlements de Ambiente (ENV) e Plugin (PLG) como filhos abaixo dele.

Regras:

• A profundidade máxima padrão é de 3 níveis (configurável através da Policy Engine)
• Detecção de ciclos impede que entitlements sejam vinculados em loops
• Entitlements filhos podem compartilhar o saldo de créditos do pai (configurável por filho)
• Cada entitlement tem sua própria data de expiração — um filho pode sobreviver ao pai
• Quando um pai é cancelado ou expira, os filhos são desvinculados (não cancelados). Eles se tornam independentes e continuam com seu próprio ciclo de vida.

Recursos derivados

Cada entitlement se conecta aos recursos que o acesso concede. Quais recursos dependem da Entitlement Class:

Recurso	Descrição
Licença	Licença de software com chaves de ativação e sites
Contrato	Acordo de serviço com termos e SLA
Serviço	Trabalho contínuo ou baseado em projetos
Ambiente	Instalação de hospedagem gerenciada
Fatura	Registro financeiro vinculado através do pedido
Documento	Arquivos compartilhados, certificados, relatórios
Download	Arquivos para download (software, materiais)
Saldo de Créditos	Créditos consumíveis para entitlements baseados em serviço
Solicitação de Serviço	Chamados de suporte rastreados contra o entitlement

Quando um entitlement é suspenso, seus recursos derivados acompanham: licenças ficam inativas, ambientes são pausados, solicitações de serviço são congeladas. Quando é reativado, os recursos derivados voltam a funcionar.

O que os admins veem

No WordPress admin, a listagem de entitlements mostra:

• Código do entitlement (com prefixo da classe)
• Nome do produto
• Nome da organização (ou "independente" para entitlements soberanos)
• Status (com indicadores de cor: verde para ativo, amarelo para suspenso, cinza para expirado, vermelho para cancelado)
• Data de expiração
• Método de criação (automático ou manual)

Clicar em um entitlement abre sua visão detalhada com abas para pedidos vinculados, licenças, contratos, serviços, ambientes e o histórico completo de status.

Admins podem filtrar por classe, status, organização ou intervalo de datas. A busca suporta consulta de entitlements diretamente pelo código — digite PLG-2026040142 e obtenha um resultado instantâneo.

Automação de expiração

Um cron job diário cuida da expiração automaticamente:

1. Busca entitlements ativos cuja data expires_at já passou e os transiciona para expired.
2. Busca entitlements expirados que ultrapassaram o timeout configurado na Cancellation Policy e os transiciona para cancelled.

Nenhuma intervenção manual é necessária para expiração rotineira. Admins são notificados sobre entitlements prestes a expirar através do dashboard e podem agir (renovar, estender) antes que a transição aconteça.

Páginas relacionadas

• Entitlement Classes — os tipos de entitlements e o que cada um provisiona
• Políticas — as regras que governam o comportamento dos entitlements
• Pedidos — como compras criam entitlements
• Organizações — a entidade cliente que (opcionalmente) detém entitlements
• Como os Conceitos se Conectam — o diagrama completo de relacionamentos