Pedidos e Entitlements
Quando um pedido WooCommerce atinge o status Completed, o MIDDAG Account processa cada item de linha e cria os entitlements apropriados. Esta página explica esse pipeline em detalhes.
O pipeline pedido-para-entitlement
Passo a passo
1. Pagamento é confirmado
Um webhook de pagamento chega do Stripe (cartão de crédito) ou Banco Inter (Pix, Boleto), ou o admin marca manualmente o pedido como pago. O WooCommerce transiciona o pedido para o status Completed.
2. O serviço de provisionamento processa o pedido
O EntitlementProvisioningService escuta o hook woocommerce_order_status_completed. Quando disparado, ele carrega o pedido e itera por cada item de linha.
3. Cada item de linha é verificado quanto ao mapeamento de classe
Para cada item de linha, o serviço lê o meta _middag_entitlement_class do produto WooCommerce vinculado. Se o meta estiver ausente, o item é ignorado — é um produto padrão que não cria entitlement.
4. Um entitlement é criado
Para cada item mapeado, o serviço cria um entitlement:
| Campo | Valor |
|---|---|
| Código | Gerado automaticamente: {CLASS}-{ANO}{MÊS}{SEQ:4d} (ex.: PLG-2026050042) |
| Classe | Do mapeamento do produto |
| Status | active |
| Organização | Resolvida a partir da conta WordPress do cliente |
| Referência do pedido | ID do pedido WooCommerce |
| Data de início | Timestamp da confirmação de pagamento |
| Data de término | Calculada a partir do período de cobrança (assinaturas) ou definida pela configuração do produto |
5. Recursos downstream são provisionados
Com base na Entitlement Class, recursos adicionais são criados:
| Classe | Recursos downstream criados |
|---|---|
| PLG | Chave de licença (com limite de ativação), acesso a download |
| ENV | Instância de ambiente (hospedagem gerenciada) |
| SVC | Registro de serviço, Contrato, Saldo de Créditos inicial |
| ORD | Apenas vínculo com o pedido (entitlement de uso geral) |
| AFL | Registro de afiliado no SolidAffiliate |
| EDU | Registro de acesso a curso/treinamento |
6. O cliente é notificado
Uma notificação é enviada ao e-mail da organização confirmando o(s) novo(s) entitlement(s), incluindo o código do entitlement e instruções de acesso.
Pedidos com múltiplos itens
Um pedido pode conter múltiplos itens de linha, cada um potencialmente mapeando para uma Entitlement Class diferente. O serviço de provisionamento processa cada item de forma independente:
- Um pedido com licença de plugin + plano de hospedagem cria um entitlement PLG e um entitlement ENV
- Um pedido com três produtos de plugin cria três entitlements PLG separados
- Itens de linha sem mapeamento de classe (ex.: uma taxa de setup codificada como fee do WC) são ignorados
Cada entitlement recebe seu próprio código único e seus próprios recursos downstream.
Idempotência
Webhooks de pagamento podem disparar mais de uma vez (isso é comum com o Stripe). O serviço de provisionamento verifica se já existe um entitlement para a mesma combinação de pedido + item de linha + classe antes de criar um novo. Webhooks duplicados são ignorados com segurança.
De onde vêm os pedidos
Pedidos nem sempre são criados pelo cliente através de uma vitrine:
| Origem | Como funciona |
|---|---|
| Cotação aceita | Cliente aceita uma cotação no portal; um pedido WC é criado automaticamente |
| Criado pelo admin | Admin cria um pedido diretamente no WooCommerce |
| Renovação de assinatura | WooCommerce Subscriptions cria um pedido de renovação automaticamente |
| Deal no HubSpot | Um deal no CRM sincroniza com uma cotação, que converte em pedido ao ser aceita |
Independente da origem, o pipeline de criação de entitlements funciona da mesma forma. Todo pedido concluído dispara o serviço de provisionamento.
Solução de problemas: entitlement não criado
Se um pedido foi concluído mas nenhum entitlement apareceu, verifique estes pontos:
| Verificação | O que procurar |
|---|---|
| Status do pedido | Deve ser Completed, não Processing ou On Hold |
| Mapeamento do produto | O produto deve ter o meta _middag_entitlement_class definido |
| Vínculo com organização | A conta WordPress do cliente deve estar vinculada a uma organização |
| Log de provisionamento | Verifique MIDDAG Account > Logs para erros durante o provisionamento |
| Verificação de duplicata | Se um webhook disparou duas vezes, o entitlement pode já existir -- verifique pelo ID do pedido |
| Modo de provisionamento manual | Se o modo de provisionamento do produto é manual, um admin deve aprová-lo |
O que o admin vê
Após o provisionamento ser concluído:
- Página do pedido WooCommerce -- Exibe um meta box do MIDDAG Account com o(s) código(s) de entitlement criado(s)
- Dashboard da organização -- O novo entitlement aparece com seu código, classe e status ativo
- Página de detalhe do entitlement -- Vincula de volta ao pedido de origem para auditoria
Páginas relacionadas
- Produtos e Entitlement Classes -- como o mapeamento de produto é configurado
- Renovações -- o que acontece na renovação de assinatura
- Reembolsos e Cancelamentos -- impacto de reembolsos nos entitlements
- Mapeamento de Status de Pagamento -- mapeamento de status entre WooCommerce, Stripe e MIDDAG Account
- Pedidos -- referência do conceito de pedido
- Fluxo de Compra e Renovação -- walkthrough completo do pipeline