Plugin de Assinaturas do Discourse

Plugin
, , ,
712

[Guia] Como Configurar Assinaturas do Discourse com Tabelas de Preços do Stripe (e Armadilhas Comuns)

Olá a todos,

Após um longo processo de solução de problemas, queria compartilhar um guia definitivo para configurar o plugin oficial discourse-subscriptions usando o método moderno de Tabela de Preços do Stripe. Essa abordagem é poderosa, mas tem algumas etapas críticas que não são imediatamente óbvias e podem levar a erros como webhooks falhando (404 Not Found) ou usuários não sendo adicionados a grupos após um pagamento bem-sucedido.

Aqui está o processo passo a passo que está confirmado que funciona.

Parte 1: Configuração do Stripe

Este processo usa o Stripe como a “fonte da verdade” para todos os produtos e preços.

1. Crie Seus Produtos e Preços

  • No seu Painel do Stripe, certifique-se de estar no Modo Ativo.
  • Vá para Produtos > Catálogo de produtos.
  • Crie seus produtos principais primeiro (por exemplo, “Assinatura Premium”, “Acesso VIP”).
  • Sob cada produto, crie todos os preços associados (por exemplo, XX / mês, XXX / ano).

2. O Passo CRUCIAL de Metadados Para que o plugin adicione automaticamente os usuários a um grupo, você deve adicionar metadados específicos a cada objeto de Preço que criar. A interface do painel do Stripe pode dificultar a localização.

  • Ao criar um novo preço (ou se puder encontrar a opção “Editar preço”), você deve adicionar metadados. Pode ser necessário clicar em “Opções adicionais” durante a criação do preço para revelar os campos de metadados.
  • Clique em + Adicionar metadados e insira o seguinte:
    • CHAVE: group_name
    • VALOR: O slug/identificador único e seguro para URL do grupo no Discourse, não seu nome completo.

Exemplo:

  • Se o nome completo do seu grupo no Discourse for “Enclave Plus”, seu slug provavelmente será EnclavePlus.
  • Você deve usar EnclavePlus como valor. Usar "Enclave Plus" com um espaço falhará.
  • Você deve repetir isso para cada plano de preço que deseja vincular a um grupo.

Screenshot 2025-07-01 at 11.58.13 PM
Screenshot 2025-07-01 at 11.58.13 PM1912×708 132 KB

3. Crie Sua Tabela de Preços do Stripe

  • Vá para Produtos > Tabelas de preços.
  • Crie uma nova tabela e adicione os Preços que você acabou de configurar.
  • Após publicar a tabela, clique no botão “Copiar código” para obter seu ID da Tabela de Preços (começa com prctbl_...).

4. Configure o Endpoint do Webhook (A Correção do Erro 404) Este é o ponto de falha mais comum.

  • Vá para Desenvolvedores > Webhooks e clique em + Adicionar endpoint.
  • A URL do Endpoint deve estar no seguinte formato: https://seusite-discourse.com/s/hooks
  • Nota: O caminho correto é /s/hooks, não /s/stripe/webhook.
  • Para Eventos a serem enviados, adicione no mínimo:
    • checkout.session.completed
    • customer.subscription.deleted
  • Crie o endpoint e copie o Segredo de assinatura (começa com whsec_...).

Parte 2: Configuração do Discourse

Agora, vamos configurar o plugin para usar tudo o que você configurou no Stripe.

1. Insira as Chaves de API e o ID da Tabela de Preços

  • Vá para Admin > Configurações e procure por discourse subscriptions.
  • Preencha suas chaves do Stripe em modo ativo:
    • discourse subscriptions public key (pk_live_...)
    • discourse subscriptions secret key (sk_live_...)
    • discourse subscriptions webhook secret (whsec_...)
  • Habilite o modo de tabela de preços:
    • Marque a caixa para discourse subscriptions pricing table enabled.
    • Cole seu ID prctbl_... no campo discourse subscriptions pricing table id.

2. Vincule Produtos do Stripe a Grupos do Discourse Mesmo com uma tabela de preços, você precisa dizer ao Discourse qual grupo pertence a qual produto.

  • Vá para Admin > Plugins > Subscriptions e clique na aba Produtos.
  • Clique em Criar Novo Produto.
  • Insira um Nome do Produto que corresponda exatamente ao Nome do Produto no Stripe (por exemplo, Enclave Plus).
  • Salve o produto. Na página do produto, role para baixo e clique em Adicionar Novo Plano.
  • Este plano é apenas uma “ponte”. O único campo crítico é Grupo de Usuários.
    • Apelido do Plano: Enlace de Grupo Enclave Plus (ou qualquer coisa para sua referência).
    • Grupo de Usuários: Selecione o grupo correto do Discourse no menu suspenso.
    • Os outros campos (Valor, Intervalo) podem ser deixados como padrão, pois serão ignorados.
  • Salve o plano. Repita isso para todos os seus diferentes produtos.

Resumo de Solução de Problemas

  • Problema: Webhooks falhando com um erro 404 Not Found.
    • Solução: Sua URL do Endpoint no Stripe está incorreta. Deve ser https://seusite-discourse.com/s/hooks.
  • Problema: O webhook é bem-sucedido (200 OK) e o pagamento aparece no perfil de faturamento do usuário, mas ele não é adicionado ao grupo.
    • Solução: Seus metadados estão incorretos. Verifique três coisas:
      1. Os metadados devem estar no objeto Preço do Stripe, não no objeto Produto.
      2. A CHAVE dos metadados deve ser exatamente group_name.
      3. O VALOR dos metadados deve ser o slug/identificador único do grupo (por exemplo, EnclavePlus), não seu nome completo com espaços.

Espero que este guia poupe tempo e frustração de outras pessoas com esta configuração complexa, mas muito poderosa.

5 curtidas