Skip to main content
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 do dueDate: 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.
Esta ação é idempotente por ciclo. Se o ciclo atual da cobrança já foi disparado (pelo cron ou por uma chamada anterior a charge-now), a Garu não cobra de novo — retorna 201 com outcome: "already_sent". Pode chamar à vontade sem risco de cobrança dupla.

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.
Sem corpo de requisição.

Resposta

Sempre 201 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

400 e 404 são erros de requisição — a cobrança não pôde sequer ser avaliada. Já um disparo que roda mas não cobra (cartão recusado, sem e-mail) volta como 201 com outcome: "failed" ou "not_sent". Não confunda os dois: trate o HTTP para erros de chamada e o outcome para o resultado do disparo.

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-now devolve already_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 perdidos

Tentativas de cobrança

Audite cada tentativa por ciclo, com o failureCode canônico de cada recusa