Node.js SDK

npm install @garuhq/node

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

const garu = new Garu({
  apiKey: process.env.GARU_API_KEY,
});

const product = await garu.products.create({
  name: "Curso de Marketing Digital",
  image: "https://meusite.com/imagens/curso-marketing.jpg",
  value: 297.0, // R$ 297,00 em Reais, NÃO centavos
  pix: true,
  creditCard: true,
});

console.log(`https://garu.com.br/pay/${product.uuid}`);

await garu.products.update("a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  value: 347.0, // R$ 347,00 em Reais
});

const offer = await garu.offers.create("a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  name: "Black Friday",
  value: 97.0, // R$ 97,00 em Reais, NÃO centavos
  slug: "black-friday",
});
// Link: https://garu.com.br/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890?offer=black-friday

// Encerrar a promoção sem apagar a oferta
await garu.offers.update(offer.id, { isActive: false });

const charge = await garu.charges.create({
  productId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  paymentMethod: "pix",
  customer: {
    name: "João Silva",
    email: "joao@email.com",
    document: "12345678909", // CPF, só números
    phone: "11987654321",
  },
});

console.log(charge.uuid); // identificador da cobrança
console.log(charge.pix?.code); // código PIX copia-e-cola
console.log(charge.amount); // preço do produto, em Reais

const charge = await garu.charges.create({
  productId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  paymentMethod: "creditCard",
  card: {
    number: "4111111111111111",
    holderName: "MARIA SILVA",
    expirationDate: "2030-12",
    cvv: "123",
    installments: 3,
  },
  customer: {
    name: "Maria Silva",
    email: "maria@email.com",
    document: "98765432100",
    phone: "11987654321",
  },
});

// chargedTotal inclui o acréscimo do parcelamento; use-o para conciliar
console.log(charge.amount, charge.chargedTotal);

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

for (const charge of charges.data) {
  console.log(`${charge.uuid}: R$ ${charge.chargedTotal} — ${charge.status}`);
}

const charge = await garu.charges.retrieve("6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f");
console.log(charge.status); // "paid", "pending", "refunded", etc.

// Total
await garu.charges.refund("6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f");

// Parcial: R$ 10,00, em Reais
await garu.charges.refund("6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f", { amount: 10.0 });

await garu.charges.cancel("6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f");

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

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

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

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

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

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

const charge = await garu.scheduledCharges.create({
  customerId: 42,
  amount: 297.5, // BRL decimal, NÃO centavos; mínimo R$ 5,00
  type: "one_time",
  dueDate: "2026-06-15", // YYYY-MM-DD, fuso de São Paulo
  methods: ["pix", "boleto"],
  description: "Mensalidade Junho",
  idempotencyKey: "mensalidade-42-2026-06",
});
console.log(charge.id); // sch_abc123

// 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",
});

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

// charge.amount e transactions[].value são ambos BRL decimal — nunca centavos.

// 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

// Trocar o cartão salvo de uma série recorrente
await garu.scheduledCharges.changePaymentMethod("sch_abc123", {
  paymentMethodId: 42,
});

const charge = await garu.charges.create({
  productId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  paymentMethod: "pix",
  customer: {
    name: "João Silva",
    email: "joao@email.com",
    document: "12345678909",
    phone: "11987654321",
  },
  idempotencyKey: "order_12345",
});

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

try {
  await garu.products.create({
    name: "Adesivo",
    image: "https://meusite.com/imagens/adesivo.jpg",
    value: 4.99, // abaixo do mínimo de R$ 5,00
  });
} catch (error) {
  if (error instanceof GaruAPIError) {
    console.error(`Erro ${error.status}: ${error.message}`);
    // Erro 400: O preço mínimo de um produto é R$ 5,00. Use R$ 0,00 para um produto sem preço.
  } else {
    throw error;
  }
}