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 SDK Node.js da Garu permite integrar pagamentos PIX, Cartão de Crédito e Boleto no seu projeto com poucas linhas de código. A SDK abstrai a API REST, usando valores em centavos e status simplificados para facilitar a integração.
Pré-requisito: Você precisa de uma chave de API. Veja como obter em Autenticação.

​
Instalação

npm install @garuhq/node

​
Inicialização

import { Garu } from "@garuhq/node";

const garu = new Garu({
  apiKey: process.env.GARU_API_KEY,
});
Nunca coloque sua chave de API diretamente no código. Use variáveis de ambiente.

​
Cobranças

​
Criar uma cobrança PIX

const charge = await garu.charges.create({
  amount: 4990, // R$ 49,90 em centavos
  method: "pix",
  customer: {
    name: "João Silva",
    email: "joao@email.com",
    document: "12345678900",
  },
});

console.log(charge.id); // ID da cobrança
console.log(charge.pixCode); // Código PIX copia-e-cola
console.log(charge.qrCodeUrl); // URL do QR Code

​
Criar uma cobrança com cartão de crédito

const charge = await garu.charges.create({
  amount: 29700, // R$ 297,00 em centavos
  method: "credit_card",
  installments: 3,
  customer: {
    name: "Maria Silva",
    email: "maria@email.com",
    document: "98765432100",
  },
});

​
Listar cobranças

const charges = await garu.charges.list({
  status: "paid",
  limit: 10,
});

for (const charge of charges.data) {
  console.log(`${charge.id}: R$ ${charge.amount / 100} — ${charge.status}`);
}

​
Consultar uma cobrança

const charge = await garu.charges.get("charge_12345");
console.log(charge.status); // "paid", "pending", "refunded", etc.

​
Reembolsar uma cobrança

const refund = await garu.charges.refund("charge_12345");
console.log(refund.status); // "refunded"

​
Clientes

​
Criar um cliente

const customer = await garu.customers.create({
  name: "João Silva",
  email: "joao@email.com",
  document: "12345678900",
  phone: "11999999999",
});

​
Listar clientes

const customers = await garu.customers.list({ limit: 20 });

​
Consultar um cliente

const customer = await garu.customers.get("cust_abc123");

​
Atualizar um cliente

const customer = await garu.customers.update("cust_abc123", {
  phone: "11988888888",
});

​
Remover um cliente

await garu.customers.delete("cust_abc123");

​
Filtrar clientes em atraso

const overdue = await garu.customers.list({ status: "overdue" });
// retorna apenas clientes com pelo menos uma cobrança agendada em atraso

​
Cobranças agendadas

PIX e Boleto agendados para uma data futura. A Garu envia o e-mail no vencimento e alerta o time se atrasar. Disponível a partir do @garuhq/node 0.5.

​
Criar uma cobrança agendada

const charge = await garu.scheduledCharges.create({
  customerId: 42,
  amount: 297.5, // BRL decimal, NÃO centavos
  type: "one_time",
  dueDate: "2026-06-15", // YYYY-MM-DD, fuso de São Paulo
  methods: ["pix", "boleto"],
  description: "Mensalidade Junho",
});
console.log(charge.id); // sch_abc123
O SDK anexa X-Idempotency-Key automaticamente em cada create, então retries de rede não duplicam a cobrança.

​
Listar e filtrar

// Múltiplos status como array
const upcoming = await garu.scheduledCharges.list({
  status: ["scheduled", "due_today"],
  limit: 50,
});

// Em atraso de um cliente específico
const overdueForCustomer = await garu.scheduledCharges.list({
  status: "overdue",
  customerId: 42,
});

// Janela de vencimento + busca pelo cliente
const this_month = await garu.scheduledCharges.list({
  dueFrom: "2026-06-01",
  dueTo: "2026-06-30",
  search: "maria",
});

​
Detalhes (cobrança + linha do tempo + transações)

const { charge, events, transactions } =
  await garu.scheduledCharges.get("sch_abc123");

// charge.amount é BRL decimal; transactions[].value é centavos.

​
Ações no ciclo de vida

// Adiar
await garu.scheduledCharges.postpone("sch_abc123", {
  newDueDate: "2026-07-01",
  reason: "cliente pediu mais prazo",
});

// Pausar (sem lembretes até retomar)
await garu.scheduledCharges.pause("sch_abc123", { reason: "em negociação" });

// Retomar
await garu.scheduledCharges.resume("sch_abc123");

// Marcar como paga (pagamento off-Garu)
await garu.scheduledCharges.markPaid("sch_abc123", {
  paymentDate: "2026-06-20",
  externalReference: "TED 4472881",
});

// Cobrar agora (dispara na hora, sem esperar o vencimento; idempotente por ciclo)
const result = await garu.scheduledCharges.chargeNow("sch_abc123");
result.outcome; // 'dispatched' | 'already_sent' | 'not_sent' | 'failed'
result.message; // texto pt-BR pronto para exibir
Veja Cobranças agendadas para o ciclo de vida completo e a tabela de status permitidos por ação.

​
Chaves de Idempotência

Use chaves de idempotência para garantir que uma operação não seja executada duas vezes, mesmo em caso de retry: 
const charge = await garu.charges.create(
  {
    amount: 4990,
    method: "pix",
    customer: { email: "joao@email.com" },
  },
  {
    idempotencyKey: "order_12345",
  },
);
Use o ID do pedido no seu sistema como chave de idempotência. Assim, mesmo que a requisição seja enviada duas vezes, apenas uma cobrança será criada.

​
Tratamento de Erros

import { Garu, GaruError } from "@garuhq/node";

try {
  const charge = await garu.charges.create({
    amount: 100, // valor muito baixo
    method: "pix",
    customer: { email: "joao@email.com" },
  });
} catch (error) {
  if (error instanceof GaruError) {
    console.error(`Erro ${error.status}: ${error.message}`);
    console.error("Detalhes:", error.errors);
  } else {
    throw error;
  }
}
Códigos de erro comuns:
Verifique os campos enviados. A resposta inclui detalhes sobre quais campos estão incorretos.
Confira se a variável GARU_API_KEY está definida e se a chave é válida.
O ID informado não corresponde a nenhum recurso existente.
A chave de idempotência já foi usada com dados diferentes. Use uma chave única por operação.
A requisição é válida mas viola uma regra de negócio (ex: valor mínimo, status incompatível).
Aguarde alguns segundos e tente novamente. Implemente backoff exponencial em automações.

​
Recursos

Repositório GitHub

Código-fonte e documentação técnica

Pacote npm

@garuhq/node no npm

​
Próximos Passos

MCP Server

Conecte agentes de IA à API

Webhooks

Receba notificações de pagamento