Skip to main content
O motor de recorrência da Malga permite configurar políticas de retentativa personalizadas para cada cliente, oferecendo maior flexibilidade no controle de cobranças recorrentes.

​
Visão Geral

As políticas de retentativa personalizadas permitem que você defina exatamente quando e quantas vezes o sistema deve tentar cobrar um pagamento que falhou, substituindo as regras padrão baseadas no intervalo da assinatura.

​
Benefícios

  • Controle total: Defina exatamente quando tentar novamente
  • Flexibilidade: Até 6 retentativas em até 30 dias
  • Estratégias personalizadas: Adapte às necessidades do seu negócio
  • Fallback automático: Mantém comportamento padrão se não configurado ou removido

​
Como Funciona

​
Estratégias Padrão vs Personalizadas

Estratégias Padrão (quando não há política personalizada):
  • Semanais: D+0, D+1, D+3, D+5
  • Mensais/Trimestrais/Anuais: D+0, D+1, D+4, D+9, D+16
Políticas Personalizadas:
  • Até 6 retentativas configuráveis
  • Janela máxima de 30 dias
  • Aplicadas a todas as assinaturas do cliente

​
Exemplos de Configurações

{
  "retryRules": [
    { "daysAfterLastAttempt": 1 },
    { "daysAfterLastAttempt": 3 },
    { "daysAfterLastAttempt": 5 }
  ]
}

​
Configurando Políticas de Retentativa

​
Obter Configurações Atuais

curl --location 'https://api.malga.io/v1/subscriptions/settings' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY'

​
Atualizar Configurações

curl --location --request PATCH 'https://api.malga.io/v1/subscriptions/settings' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "retryRules": [
    { "daysAfterLastAttempt": 1 },
    { "daysAfterLastAttempt": 3 },
    { "daysAfterLastAttempt": 5 },
    { "daysAfterLastAttempt": 7 },
    { "daysAfterLastAttempt": 14 }
  ]
}'

​
Regras de Validação

​
Limitações Técnicas

  • Quantidade: Entre 1 e 6 regras de retentativa
  • Valores: Cada valor deve ser ≥ 1 dia
  • Janela total: Soma de todos os dias deve ser ≤ 30
  • Duplicatas: Não são permitidas regras duplicadas
  • Ordenação: Regras são automaticamente ordenadas em ordem crescente

​
Exemplos de Validação

{
  "retryRules": [
    { "daysAfterLastAttempt": 1 },
    { "daysAfterLastAttempt": 3 },
    { "daysAfterLastAttempt": 5 }
  ]
}

​
Comportamento em Tempo Real

​
Cálculo de Próxima Tentativa

O sistema calcula a próxima tentativa baseado em:
  1. Data da última tentativa
  2. Número da tentativa atual (1ª falha = 1ª regra, 2ª falha = 2ª regra, etc.)
  3. Política configurada do cliente

​
Interrupção por Novo Ciclo

Quando um novo ciclo de faturamento é gerado:
  • Todos os ciclos anteriores em estado retrying são marcados como failed
  • Webhook cycle_failed é enviado para cada ciclo interrompido

​
Troca de Política

  • Ciclos em andamento: Mantêm o NextAttemptAt já calculado
  • Novas falhas: Usam a política vigente no momento da falha
  • Sem recálculo retroativo: Políticas antigas não afetam ciclos já agendados

​
Removendo Políticas

Para voltar ao comportamento padrão, envie um array vazio: 
curl --location --request PATCH 'https://api.malga.io/v1/subscriptions/settings' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "retryRules": []
}'

​
Próximos Passos

Gerenciar Assinaturas

Aprenda a gerenciar o ciclo de vida das suas assinaturas.

Configurar Webhooks

Configure notificações em tempo real sobre mudanças de status.

API de Subscriptions

Revise a documentação completa da API de Subscriptions.

Getting Started

Comece a integrar o motor de recorrência.