Cobranças agendadas

Visão Geral

A partir da v0.5.0, você pode agendar cobranças para um cliente já cadastrado. A Garu cuida do resto:

E-mail para o cliente no dia do vencimento, com um link de pagamento já com PIX ou Boleto pronto.
Alertas para o time financeiro a partir de D+1, D+2 e D+3 se a cobrança ficar em atraso.
Estado da cobrança visível no dashboard (Próximas, Vencidas, Pausadas, Concluídas).
API completa para automatizar o fluxo via SDK ou MCP.

Onde fica: Acesse /cobrancas-agendadas no menu lateral do dashboard. Pela API, use os endpoints abaixo (ou o SDK Node @garuhq/node 0.5+).

O que está suportado nesta versão

Recurso	Status
Cobranças avulsas (`one_time`)	✓
PIX e Boleto	✓
Cobranças recorrentes (`recurring`) com Pix Automático	✓
Cartão	Em uma versão futura (precisa de tokenização do cliente)

Modelo de dados

ScheduledCharge
  id (sch_…)
  customerId  → Customer já cadastrado neste seller
  productId?  → opcional; valor pode ser pré-preenchido a partir do produto
  amount      → BRL decimal (ex: 297.50)
  type        → 'one_time' | 'recurring'
  dueDate     → YYYY-MM-DD em horário de São Paulo
  methods[]   → ['pix'] | ['boleto'] | ['pix', 'boleto'] | ['pix_automatic']
  status      → scheduled | due_today | overdue | paid | paused | canceled
  description?
  externalReference?
  metadata?

ScheduledChargeEvent  (timeline append-only por cobrança)
  created, postponed, paused, resumed,
  manually_marked_paid, paid, overdue_reminder_sent, ...

Ciclo de vida

Você agenda

Cobrança nasce com status scheduled.

Dia do vencimento (D)

A Garu envia e-mail ao cliente com o link de pagamento. Status vira due_today.

Cliente paga (ou não)

Pagou pelo link → paid automaticamente. Não pagou → overdue em D+1.

Cobrança em atraso

A Garu manda lembretes para o time financeiro em D+1, D+2 e D+3, e dispara o webhook scheduled_charge.overdue em cada estágio.

Você intervém quando quiser

Adiar, pausar, retomar ou marcar como paga (caso o cliente tenha pago fora do Garu).

Agendando via dashboard

Acesse Cobranças

No menu lateral, clique em Cobranças.

Clique em Nova cobrança

Botão Vesúvio no canto superior direito.

Preencha o wizard

Cliente → Produto (opcional) → Valor + descrição + vencimento → Métodos (PIX/Boleto) → Revisão.

Pronto

A cobrança aparece na aba Próximas. No dia do vencimento o cliente recebe o e-mail.

Agendando via API

Inclua sua chave de API no header Authorization de todas as requisições:

Authorization: Bearer sk_test_sua_chave_api

Nunca exponha sua chave de API em código frontend ou repositórios públicos.

Criar cobrança

curl -X POST https://garu.com.br/api/scheduled-charges \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 42,
    "amount": 297.50,
    "type": "one_time",
    "dueDate": "2026-06-15",
    "methods": ["pix", "boleto"],
    "description": "Mensalidade Junho"
  }'

Resposta (resumida):

{
  "id": "sch_abc123",
  "customerId": 42,
  "amount": 297.5,
  "type": "one_time",
  "dueDate": "2026-06-15",
  "methods": ["pix", "boleto"],
  "status": "scheduled",
  "createdAt": "2026-05-01T12:00:00Z"
}

Envie o header X-Idempotency-Key: <uuid> para tornar a criação segura contra retries de rede. O SDK Node faz isso automaticamente.

Cobrança recorrente com Pix Automático

Para uma série recorrente debitada automaticamente, use type: "recurring" com methods: ["pix_automatic"]. O cliente autoriza a recorrência uma vez no app do banco e os ciclos seguintes caem sozinhos — veja o guia do Pix Automático.

curl -X POST https://garu.com.br/api/scheduled-charges \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 42,
    "productId": 456,
    "amount": 297.50,
    "type": "recurring",
    "dueDate": "2026-06-15",
    "methods": ["pix_automatic"],
    "recurrence": { "interval": "monthly", "intervalCount": 1, "endsAfter": 12 },
    "description": "Plano Premium - mensal"
  }'

methods com pix_automatic exige type: "recurring" e um productId, e o produto precisa ter pixAutomatic: true. Caso contrário, a criação volta 400. A receita completa está em Como integrar Pix Automático.

Listar cobranças

# Próximas (scheduled + due_today)
curl "https://garu.com.br/api/scheduled-charges?status=scheduled&status=due_today" \
  -H "Authorization: Bearer sk_live_xxx"

# Em atraso de um cliente específico
curl "https://garu.com.br/api/scheduled-charges?status=overdue&customerId=42" \
  -H "Authorization: Bearer sk_live_xxx"

Buscar uma cobrança (com timeline e transações)

curl https://garu.com.br/api/scheduled-charges/sch_abc123 \
  -H "Authorization: Bearer sk_live_xxx"

A resposta é um pacote com a cobrança, eventos do ciclo de vida e transações geradas:

{
  "charge": { "id": "sch_abc123", "status": "paid", "amount": 297.5, "...": "..." },
  "events": [
    { "eventType": "created", "actor": { "type": "user", "id": 1 }, "createdAt": "..." },
    { "eventType": "paid", "actor": { "type": "system" }, "createdAt": "..." }
  ],
  "transactions": [
    { "id": 4472, "value": 29750, "paymentMethod": "pix", "status": "payedPix", "...": "..." }
  ]
}

Cuidado com unidades: charge.amount está em BRL decimal (297.50), mas transactions[].value está em centavos (29750). Converta antes de comparar.

Ações no ciclo de vida

Ação	Endpoint	Status permitidos
Cobrar agora	`POST /api/scheduled-charges/{id}/charge-now`	`scheduled` / `due_today`
Adiar	`POST /api/scheduled-charges/{id}/postpone`	`scheduled` / `due_today` / `overdue` / `paused`
Pausar	`POST /api/scheduled-charges/{id}/pause`	`scheduled` / `due_today` / `overdue`
Retomar	`POST /api/scheduled-charges/{id}/resume`	`paused`
Marcar como paga	`POST /api/scheduled-charges/{id}/mark-paid`	`due_today` / `overdue`

# Adiar para uma nova data
curl -X POST https://garu.com.br/api/scheduled-charges/sch_abc123/postpone \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "newDueDate": "2026-07-01", "reason": "cliente pediu mais prazo" }'

# Marcar como paga (cliente pagou via TED, fora do Garu)
curl -X POST https://garu.com.br/api/scheduled-charges/sch_abc123/mark-paid \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "paymentDate": "2026-06-20", "externalReference": "TED 4472881" }'

Cobrar agora (sem esperar o vencimento)

Quer disparar a cobrança e o e-mail ao cliente na hora, antes do dueDate? Use charge-now. Roda o mesmo fluxo do cron diário, só que antecipado, e é idempotente por ciclo — se o ciclo já foi disparado, volta already_sent e não cobra de novo.

curl -X POST https://garu.com.br/api/scheduled-charges/sch_abc123/charge-now \
  -H "Authorization: Bearer sk_live_xxx"

A resposta traz o outcome (dispatched / already_sent / not_sent / failed) e uma message em pt-BR pronta para exibir. Veja Cobrar agora para todos os resultados e motivos.

Na criação, o campo opcional maxRecoveryDays (1–365, padrão 14) define por quantos dias a Garu tenta recuperar automaticamente uma cobrança cujo disparo o cron tenha perdido. charge-now é o atalho manual para o mesmo efeito.

Webhooks emitidos

Configure um endpoint em Configurações → Desenvolvedores → Webhooks para receber:

Evento	Quando
`scheduled_charge.created`	Cobrança agendada com sucesso
`scheduled_charge.postponed`	Data alterada
`scheduled_charge.paused`	Cobrança pausada
`scheduled_charge.resumed`	Cobrança retomada
`scheduled_charge.charged`	E-mail D-day enviado ao cliente
`scheduled_charge.overdue`	Atrasou; emitido em D+1, D+2 e D+3
`scheduled_charge.paid`	Pagamento confirmado
`scheduled_charge.failed`	Pagamento recusado

Verifique a assinatura HMAC do webhook como em qualquer outro evento Garu — veja Webhooks.

Notificações para o time

Quando uma cobrança fica em atraso, a Garu notifica os membros do time que tenham pelo menos uma das permissões:

transaction:view
billing:view
admin:view

Cada membro pode silenciar o alerta em Configurações → Notificações → Cobranças agendadas.

Permissões

Ação	Permissão
Listar / ver cobranças	`scheduled_charge:view`
Criar cobrança	`scheduled_charge:create`
Cobrar agora / adiar / pausar / retomar / marcar como paga	`scheduled_charge:edit`
Cancelar cobrança	`scheduled_charge:delete`

Por papel (padrão da Garu):

Owner / Administrator: tudo.
Support: ver, editar, cancelar (não cria).
Developer / Analyst / View Only: apenas ver.

Ajuste em Configurações → Equipe se precisar de papéis personalizados.

SDK e MCP

Node SDK: Cobranças agendadas no @garuhq/node.
MCP server: Tools de cobranças no Garu MCP.

Próximos passos

Pix Automático em cobranças recorrentes (já disponível com type: "recurring").
Cartão de crédito como método agendável (após tokenização do cliente).
Portal do cliente em /minha-area para o próprio cliente acompanhar e pagar cobranças sem login.

​Visão Geral

​O que está suportado nesta versão

​Modelo de dados

​Ciclo de vida

​Agendando via dashboard

​Agendando via API

​Criar cobrança

​Cobrança recorrente com Pix Automático

​Listar cobranças

​Buscar uma cobrança (com timeline e transações)

​Ações no ciclo de vida

​Cobrar agora (sem esperar o vencimento)

​Webhooks emitidos

​Notificações para o time

​Permissões

​SDK e MCP

​Próximos passos

Visão Geral

O que está suportado nesta versão

Modelo de dados

Ciclo de vida

Agendando via dashboard

Agendando via API

Criar cobrança

Cobrança recorrente com Pix Automático

Listar cobranças

Buscar uma cobrança (com timeline e transações)

Ações no ciclo de vida

Cobrar agora (sem esperar o vencimento)

Webhooks emitidos

Notificações para o time

Permissões

SDK e MCP

Próximos passos