Criando Plano de Assinatura

Um Plano de Assinatura define as regras de cobrança recorrente que serão utilizadas na criação de subscriptions (assinaturas). O plano determina valores, periodicidade, métodos de pagamento aceitos e benefícios exibidos ao cliente.

📌 Um plano não gera cobranças automaticamente. Ele é utilizado posteriormente na criação de assinaturas.

---

Endpoint

POST /v2/plans https://api.barte.com/v2/plans

Headers

X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*

---

Body

{
  "title": "Plano Simples",
  "description": "Descrição do plano",
  "active": false,
  "bullets": [
    {
      "title": "Benefício 1",
      "description": "Descrição do benefício"
    }
  ],
  "values": [
    {
      "type": "MONTHLY",
      "valuePerMonth": 99.9
    }
  ],
  "acceptPaymentMethods": [
    "CREDIT_CARD",
    "PIX",
    "BANK_SLIP"
  ]
}

---

Response

{
  "uuid": "08893f29-d904-4367-93a7-648c33543542",
  "title": "Plano Simples",
  "description": "Descrição do Plano",
  "bullets": [
    {
      "title": "Plano Simples",
      "description": "Descrição do benefício"
    }
  ],
  "active": false,
  "values": [
    {
      "type": "MONTHLY",
      "value": 99.9,
      "valuePerMonth": 99.9
    }
  ],
  "acceptPaymentMethods": [
    "BANK_SLIP",
    "CREDIT_CARD",
    "PIX"
  ]
}

Campos mais importantes da resposta

• uuid - Identificador único do plano. Este campo deve salvo para:

  • Criação de assinaturas
  • Consultas futuras
  • Rastreabilidade e auditoria
• active - Indica se o plano está ativo e disponível para uso
• values - Lista de valores configurados no plano, contém:

  • Contém o tipo de cobrança
  • Valor total do período
  • Valor mensal equivalente
• acceptPaymentMethods - Lista final de métodos de pagamento aceitos no plano

---

Fluxo de uso do plano

1. Criar o plano de assinatura
2. Ativar o plano (active = true)
3. Criar uma assinatura vinculada ao plano
4. Cobranças recorrentes são geradas automaticamente
5. Alterações de status são notificadas via webhook

---

Confirmações e eventos

• A criação do plano não gera cobrança
• Nenhum pagamento é processado nessa etapa
• Webhooks passam a ser disparados apenas após a criação de assinaturas
• Alterações de status das cobranças recorrentes são sempre notificadas via webhook

---

Boas práticas

• Crie planos separados para cada regra de cobrança
• Use descrições claras e objetivas
• Utilize bullets para destacar benefícios importantes
• Ative o plano apenas quando estiver pronto para uso
• Armazene o uuid do plano
• Defina corretamente os métodos de pagamento aceitos

---

O que não fazer

• Alterar planos ativos com assinaturas já vinculadas
• Reutilizar o mesmo plano para regras de cobrança diferentes
• Assumir que criar o plano gera cobrança
• Expor sua chave de API no frontend
• Criar assinaturas com planos inativos