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