Cobrar Agora
Cobranças Agendadas
Cobrar Agora
Dispare a cobrança e o e-mail ao cliente na hora, sem esperar o vencimento
POST
Cobrar Agora
Visão Geral
Dispara a cobrança e a notificação ao cliente imediatamente — o mesmo fluxo que o cron diário rodaria no dia do vencimento, só que antecipado. Use quando você quer cobrar antes dodueDate: o cliente já confirmou, você fechou o mês mais cedo, ou está recuperando manualmente uma série que ficou para trás.
Não tem corpo de requisição. A cobrança é identificada pelo id no path.
Permitido a partir de: scheduled / due_today.
Exige chave de API (sk_test_… / sk_live_…) e só enxerga cobranças do próprio seller.
Exemplo de Requisição
Um SDK Flutter com
chargeNow será documentado aqui assim que essa biblioteca
for publicada.Parâmetros de Path
string
required
ID da cobrança (
sch_…). Deve pertencer ao seller autenticado.Resposta
Sempre201 quando a cobrança é válida e cobrável (padrão do NestJS para POST sem override). O resultado real fica no campo outcome — ele indica se a Garu disparou, ignorou (já enviado) ou falhou. Trate outcome, não o status HTTP, para saber o que aconteceu.
O texto de
message neste e nos demais exemplos é ilustrativo — o valor
exato é gerado pelo servidor e pode mudar. Faça sua lógica em cima de outcome
e reason; use message apenas para exibir ao usuário.Campos
Valores de outcome
Valores de reason
Para not_sent:
Para
failed:
O campo
message já vem com o texto pt-BR correspondente a cada combinação de
outcome + reason, pronto para exibir direto na sua interface.Erros
Como se relaciona com o cron diário
charge-now roda a mesma rotina de cobrança que o cron dispara no dueDate, compartilhando o lock por ciclo. Por isso o disparo manual e o automático não se atropelam:
- Se o cron já disparou o ciclo hoje,
charge-nowdevolvealready_sent. - Se você disparar com
charge-now, o cron não dispara de novo aquele ciclo.
maxRecoveryDays (definido na criação) é um mecanismo separado: ele controla por quantos dias o cron tenta recuperar automaticamente um ciclo cujo disparo tenha falhado. charge-now não altera essa janela — é o gatilho manual para disparar o ciclo na hora.
Próximos passos
Criar cobrança agendada
Inclui o campo
maxRecoveryDays para recuperação automática de ciclos perdidosTentativas de cobrança
Audite cada tentativa por ciclo, com o
failureCode canônico de cada recusa