Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt

Use this file to discover all available pages before exploring further.

​
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

RecursoStatus
Cobranças avulsas (one_time)✓
PIX e Boleto✓
CartãoEm uma versão futura (precisa de tokenização do cliente)
Cobranças recorrentesEm uma versão futura

​
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' nesta versão
  dueDate     → YYYY-MM-DD em horário de São Paulo
  methods[]   → ['pix'] | ['boleto'] | ['pix', 'boleto']
  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

1

Você agenda

Cobrança nasce com status scheduled.
2

Dia do vencimento (D)

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

Cliente paga (ou não)

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

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.
5

Você intervém quando quiser

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

​
Agendando via dashboard

1

Acesse Cobranças

No menu lateral, clique em Cobranças.
2

Clique em Nova cobrança

Botão Vesúvio no canto superior direito.
3

Preencha o wizard

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

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.

​
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çãoEndpointStatus permitidos
AdiarPOST /api/scheduled-charges/{id}/postponescheduled / due_today / overdue / paused
PausarPOST /api/scheduled-charges/{id}/pausescheduled / due_today / overdue
RetomarPOST /api/scheduled-charges/{id}/resumepaused
Marcar como pagaPOST /api/scheduled-charges/{id}/mark-paiddue_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" }'

​
Webhooks emitidos

Configure um endpoint em Configurações → Desenvolvedores → Webhooks para receber:
EventoQuando
scheduled_charge.createdCobrança agendada com sucesso
scheduled_charge.postponedData alterada
scheduled_charge.pausedCobrança pausada
scheduled_charge.resumedCobrança retomada
scheduled_charge.chargedE-mail D-day enviado ao cliente
scheduled_charge.overdueAtrasou; emitido em D+1, D+2 e D+3
scheduled_charge.paidPagamento confirmado
scheduled_charge.failedPagamento 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çãoPermissão
Listar / ver cobrançasscheduled_charge:view
Criar cobrançascheduled_charge:create
Adiar / pausar / retomar / marcar como pagascheduled_charge:edit
Cancelar cobrançascheduled_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

​
Próximos passos

  • Cobranças recorrentes (mensal, anual, com período de trial).
  • 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.