Trial

​

Como funciona o Trial

​

Configuração do Trial

{
  "name": "Assinatura Premium",
  "trial": {
    "endDate": "2025-02-15"
  },
  "recurrence": {
    "interval": "monthly"
  },
  // ... outros campos
}

​

Características do Sistema de Trial

• Opcional: O trial pode ou não ser configurado na criação da assinatura
• Flexível: Pode ter qualquer duração (dias, semanas, meses)
• Imutável: Uma vez criado, o trial não pode ser editado
• Automático: A transição para cobrança acontece automaticamente

​

Comportamento do Trial

​

Durante o Período de Trial

• Status da assinatura: trialing
• Nenhuma cobrança é realizada
• A assinatura permanece ativa para o cliente
• Webhooks específicos são enviados

​

Transição Automática

1. Status muda de trialing para created
2. Sistema agenda a primeira cobrança
3. Webhook subscription.created é enviado
4. Próxima fatura é gerada automaticamente

​

Fluxo de Trial

​

Exemplos de Uso

​

Criando uma assinatura com trial de 7 dias

curl --location 'https://api.malga.io/v1/subscriptions' \
--header 'Content-Type: application/json' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--data '{
  "name": "Plano Premium - Trial 7 dias",
  "merchantId": "YOUR_MERCHANT_ID",
  "customerId": "YOUR_CUSTOMER_ID",
  "trial": {
    "endDate": "2025-02-07"
  },
  "recurrence": {
    "interval": "monthly"
  },
  "paymentMethod": {
    "type": "credit",
    "card": {
      "cardId": "YOUR_CARD_ID"
    }
  },
  "items": [
    {
      "name": "Plano Premium",
      "amount": 2990,
      "quantity": 1
    }
  ]
}'

​

Webhooks do Sistema de Trial

​

Eventos específicos do trial

​

Regras Importantes

​

Validações do Trial

• Data futura obrigatória: trial.endDate deve ser no futuro (mínimo de 1 dia)
• Alinhamento com startAt: Se startAt não for especificado, usa automaticamente trial.endDate
• Formato UTC: O campo startAt deve ser informado em formato UTC (YYYY-MM-DD)
• Imutabilidade: Trial não pode ser editado após a criação da assinatura

​

Comportamento Especial

• Prioridade de eventos: Se trial definido, emite apenas trial_started, nunca created na criação

​

Limitações

• Apenas na criação: Trial só pode ser configurado durante a criação da assinatura
• Não editável: Impossível modificar ou estender o período de trial
• Sem cobrança parcial: Durante o trial, nenhuma cobrança é realizada

​

Próximos Passos