@geekapps/billing-fastify

Cliente/plugin Fastify para a Geekapps Billing API — cria cobranças, gerencia clientes/itens/pedidos parcelados a partir de outros serviços Node.

Uso como plugin Fastify

import Fastify from "fastify";
import { billingPlugin } from "@geekapps/billing-fastify";

const app = Fastify();

app.register(billingPlugin, {
  baseUrl: "https://billing-api.seudominio.com",
  serviceAccount: {
    issuerUrl: process.env.GEEKAPPS_AUTH_ISSUER!,
    clientId: process.env.GEEKAPPS_SERVICE_ACCOUNT_CLIENT_ID!,
    clientSecret: process.env.GEEKAPPS_SERVICE_ACCOUNT_CLIENT_SECRET!,
  },
  mode: "prod", // definido uma vez — todas as chamadas via app.billingClient já usam esse valor
});

app.get("/exemplo", async (req) => {
  return app.billingClient.charges.create({
    customer_id: "...",
    item_id: "...",
    method: "PIX",
  });
});

Uso standalone (sem Fastify)

import { BillingClient, createServiceAccountToken } from "@geekapps/billing-fastify";

const client = new BillingClient({
  baseUrl: "https://billing-api.seudominio.com",
  token: createServiceAccountToken({
    issuerUrl: "...",
    clientId: "...",
    clientSecret: "...",
  }),
  mode: "dev",
});

await client.customers.create({ name: "...", email: "..." });

O mode (dev/prod) é configurado uma única vez ao instanciar o cliente — nenhum método individual precisa recebê-lo novamente.

Cobrança avulsa simples (sempre cartão)

charges.charge cobra direto no cartão padrão já salvo do cliente; se ele ainda não tiver um, retorna uma URL de checkout para cadastrar o cartão e pagar.

const result = await client.charges.charge(customerId, 5000); // R$ 50,00

if (!result.charged_off_session) {
  // abra result.checkout_url em uma nova aba para o cliente cadastrar o cartão
}

Assinatura de plano (checkout + confirmação + status)

Fluxo público (cliente final anônimo, ainda sem Customer cadastrado — coleta nome/e-mail no checkout):

const { checkout_url, checkout_token, management_token } = await client.plans.checkout(planId, {
  customer: { name, email },
});

// redirecione o cliente para checkout_url, depois confirme o pagamento:
const status = await client.checkout.waitUntilPaid(checkout_token);

// guarde management_token — a qualquer momento depois, verifique se a assinatura
// segue ativa e qual item ela cobre (rota pública, sem autenticação):
const subStatus = await client.subscriptions.checkByToken(management_token);
if (subStatus.subscription.active) {
  console.log("cobrando", subStatus.item.name);
}

Fluxo simplificado (autenticado, o Customer já existe na sua org — sem formulário de nome/e-mail):

const { checkout_url } = await client.plans.checkoutPlan(planId, customerId, {
  return_url: "https://meuapp.com/conta?upgraded=1",
});
// redirecione o cliente para checkout_url; ele paga e volta para sua URL de retorno

// depois que o cliente volta:
const { active, item } = await client.plans.confirmPlanSubscription(planId, customerId);
if (active) {
  // ativa o plano real no seu sistema
}

Plano avulso (sem página pública)

Planos normalmente nascem junto com uma BillingPlanPage (POST /billing-plan-pages), mas também podem ser criados sozinhos — útil para o fluxo simplificado acima, onde você não precisa de uma página de preços hospedada:

const plan = await client.plans.create({
  item_id: itemId,
  interval: "MONTHLY",
  // plan_page_id omitido — plano fica avulso
});

// depois, se quiser, vincule a uma página existente:
await client.plans.attachToPage(plan.id, pageId);
// ou desvincule de novo:
await client.plans.detachFromPage(plan.id);