startAt definido como a data atual, o motor de assinaturas da Malga processa a primeira cobrança imediatamente. Este comportamento especial permite que você inicie a cobrança no mesmo dia da criação da assinatura.
Comportamento especial
Ao definirstartAt como a data atual, o motor de assinaturas:
- Processa a cobrança imediatamente após a criação da assinatura
- Retorna informações detalhadas sobre o processamento na resposta da API
- Envia webhooks específicos para notificar sobre o resultado da cobrança
- Atualiza o status da assinatura baseado no resultado da cobrança
Exemplo de criação com startAt sendo hoje
Sobre o campo
lastCycle: O campo lastCycle sempre está presente nas respostas individuais de assinatura (GET, CREATE, UPDATE), mesmo quando não há cobrança instantânea. Quando não existem faturas, o campo será null. Nos exemplos acima, o campo contém um objeto porque há cobrança instantânea, mas em outros cenários você pode receber "lastCycle": null.Webhooks específicos
Quando você cria uma assinatura com cobrança instantânea, você receberá webhooks específicos:Ordem de eventos
- Quando a assinatura é criada:
subscription.created; - Quando a cobrança é processada:
subscription.activated(em caso de sucesso);subscription.cycle_failed(quando há falha no processamento da cobrança);
subscription.unpaid(após esgotar todas as tentativas de cobrança da fatura).
Novo webhook: subscription.cycle_failed
Este webhook é enviado quando uma fatura de cobrança falha após todas as retentativas:Atualização de startAt, scheduler e validações
Se você alterarrecurrence.startAt com PUT /v1/subscriptions/:id antes do primeiro ciclo, o comportamento segue a mesma ideia da cobrança na criação: quando a nova data de início cai na janela aceita pela plataforma, a primeira cobrança pode ser disparada na própria resposta da atualização, sem depender do próximo ciclo do scheduler.
Datas fora da janela aceita pela plataforma são rejeitadas com HTTP 422.
As mensagens de erro de validação da API são retornadas em inglês (por exemplo, em caso de falha com HTTP 422).
Resumo do comportamento
- Scheduler: para assinaturas em
createdainda sem primeiro ciclo, a data de início da assinatura é validada com base na data atual. - Validação na atualização: não é permitido alterar
startAtapós o primeiro ciclo. Quanto à data emstartAt, não é aceita data anterior a mais de um dia em relação à data atual (mensagem HTTP 422 equivalente astartAt cannot be more than 1 day in the past; vide fluxograma nesta seção). - Mapeamento: antes do primeiro ciclo, ao atualizar
startAt, a próxima data de vencimento acompanha o novo início, para o scheduler e as regras denext_due_datepermanecerem coerentes. - Cobrança imediata no update: com
recurrence.startAtno body e assinatura ainda elegível (created, sem primeiro ciclo, com a data de hoje), a primeira cobrança pode ocorrer no mesmo request. scheduledCancellationAt: na atualização da assinatura, a validação de data é independente destartAt:scheduledCancellationAtdeve estar no mínimo um dia no futuro em relação à data atual (comparação por calendário). Detalhes em Cancelamento agendado — Validações implementadas.
Elegibilidade do agendamento (primeiro ciclo)
Fluxo do PUT com recurrence.startAt
A referência da operação está em Atualizar assinatura.Por que essas regras existem
Em cenários reais, uma assinatura podia permanecer emcreated com o primeiro ciclo nunca gerado quando a data de início era alterada retroativamente enquanto o scheduler considerava a data atual, ou quando a próxima cobrança não acompanhava a nova data de início antes do primeiro ciclo. O alinhamento da próxima data de vencimento e a cobrança imediata no update quando aplicável reduzem esse risco.
Observações importantes
- Campo
lastCycle: Sempre presente nas respostas individuais de subscription (GET, CREATE, UPDATE). Pode sernullse não houver cycles, ou um objeto completo com os detalhes do último cycle. Na cobrança instantânea, o campo conterá informações sobre o cycle processado imediatamente. - Status da assinatura:
- Sucesso:
active - Erro:
created(permanece até retentativas esgotadas)
- Sucesso:
- Status da fatura:
- Sucesso:
authorized - Erro:
retrying
- Sucesso:
- Payment History: Contém detalhes de cada tentativa, incluindo erros
- Next Attempt: Indica quando será a próxima tentativa de cobrança
Próximos passos
Gerenciar assinatura
Aprenda como gerenciar assinaturas após a criação
Configurar webhooks
Configure webhooks para receber notificações em tempo real