Billing SDK

O Billing SDK é um conjunto de componentes de billing para React de código aberto, com uma CLI que conecta seu projeto ao Dodo Payments. A CLI gera as rotas da API, o hook do React e o cliente do Dodo Payments para seu framework, além de adicionar componentes como tabelas de preços e medidores de uso.

Visão Geral

O Billing SDK inclui:

Componentes React: Componentes de billing pré-construídos e personalizáveis para aplicações React.
Ferramentas de CLI: Uma interface de linha de comando que inicializa projetos e adiciona componentes.
Suporte a frameworks: Templates para Next.js, Express.js, Hono, Fastify, NestJS e React.
Provedor de pagamentos: Integração completa com Dodo Payments.

Começo Rápido

Para configurar o Billing SDK em um projeto existente, execute a CLI a partir da raiz do projeto:

Install the CLI

Execute a CLI com npx, sem instalá-la:

npx @billingsdk/cli --help

Ou instale-a globalmente para uso frequente. A instalação global adiciona o comando billingsdk, por exemplo billingsdk init:

npm install -g @billingsdk/cli

Initialize a Project

Execute a configuração interativa para adicionar billing ao seu projeto:

npx @billingsdk/cli init

A CLI solicita que você selecione:

Seu framework: Next.js, Express.js, React, Hono, Fastify ou NestJS. A CLI detecta seu framework e o marca como detectado.
Seu provedor de pagamentos: selecione Dodo Payments.

Add Components

Adicione componentes individuais de cobrança ao seu projeto:

npx @billingsdk/cli add pricing-table-one
npx @billingsdk/cli add subscription-management

Frameworks Suportados

O Billing SDK tem um template do Dodo Payments para cada um destes frameworks:

Framework	Dodo Payments
Next.js	Sim
Express.js	Sim
Hono	Sim
React	Sim
Fastify	Sim
NestJS	Sim

Comandos da CLI

`@billingsdk/cli init`

init configura o billing no seu projeto: ele instala o template do framework com a integração do Dodo Payments e as dependências necessárias para o template. O que faz:

Seleção do framework: Você escolhe seu framework e provedor de pagamentos.
Instalação do template: A CLI baixa o template do seu framework e provedor do registro do Billing SDK e instala seus arquivos.
Gerenciamento de dependências: A CLI instala as dependências do template, como dodopayments, standardwebhooks e zod, usando npm, pnpm, Yarn ou Bun.
Geração de arquivos: A CLI grava os arquivos de configuração e o código boilerplate. Para Express.js, Fastify, Hono e NestJS, ela os grava em src/.

Exemplo:

npx @billingsdk/cli init

Para executar init sem prompts, passe --framework, --provider e --yes, por exemplo npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes. Adicione --dry-run para listar os arquivos sem gravá-los, --no-install para ignorar a instalação das dependências ou --package-manager para escolher npm, pnpm, yarn ou bun.

`@billingsdk/cli add`

add instala um componente de billing no seu projeto por meio do sistema de registro do shadcn/ui. Ele executa shadcn@latest add @billingsdk/<component> com o runner do seu gerenciador de pacotes. Exemplos:

# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle

O que acontece:

A CLI do shadcn baixa a configuração do componente do registro.
Ela instala os arquivos do componente no diretório components/billingsdk/.
Ela atualiza a configuração do seu projeto, se necessário.
Ela instala todas as dependências adicionais.

Estrutura dos arquivos gerados

Depois de executar init, seu projeto contém:

Rotas da API: Endpoints para checkout, clientes, pagamentos de clientes, produtos, assinaturas e webhooks. O template do React não tem rotas da API.
Hooks: Um hook do React useBilling para operações de billing, para React e Next.js.
Arquivos de biblioteca: A configuração do cliente do Dodo Payments e funções auxiliares, em lib/dodopayments.ts.
Configuração do ambiente: Um arquivo de ambiente de exemplo, .env.example.

Estrutura de exemplo do Next.js

Para Next.js, init grava estes arquivos:

your-project/
├── app/api/
│   ├── checkout/route.ts
│   ├── customer/route.ts
│   ├── customer/payments/route.ts
│   ├── customer/subscriptions/route.ts
│   ├── product/route.ts
│   ├── products/route.ts
│   └── webhook/route.ts
├── hooks/
│   └── useBilling.ts
├── lib/
│   └── dodopayments.ts
└── .env.example

Configuração do ambiente

Após a inicialização, defina suas variáveis de ambiente. Obtenha a chave da API em Developer → API Keys e a chave do webhook em Developer → Webhooks, no dashboard:

# DodoPayments
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

Defina DODO_PAYMENTS_ENVIRONMENT como test_mode ou live_mode. O cliente gerado do Dodo Payments lança um erro para qualquer outro valor.

Armazene suas chaves da API em variáveis de ambiente. Nunca faça commit delas no controle de versão.

Componentes disponíveis

O Billing SDK fornece componentes React nestes grupos:

Tabelas de preços: Oito variantes, de pricing-table-one a pricing-table-eight, para exibir preços de produtos.
Gerenciamento de assinaturas: subscription-management, além de cards e diálogos para cancelar uma assinatura ou atualizar um plano.
Monitoramento de uso: Medidores de uso circulares e lineares, além de tabelas de uso para billing baseado em uso.
Componentes de checkout: Um seletor de método de pagamento, formulários de detalhes de pagamento e um card de falha no pagamento.
Customer Portal: Configurações de billing, uma tela de billing, histórico de faturas e cobranças futuras, para autoatendimento do cliente.

Para navegar por todos os componentes com uma prévia ao vivo, consulte a biblioteca de componentes.

Código aberto

O Billing SDK é de código aberto:

Transparência: Você pode ler como cada componente funciona.
Comunidade: Desenvolvedores criam a solução para outros desenvolvedores.
Segurança: Qualquer pessoa pode revisar o código em busca de problemas de segurança.
Inovação: As contribuições da comunidade aceleram o desenvolvimento.

O Billing SDK é distribuído sob a GNU General Public License v3.0 (GPL-3.0), que mantém o projeto aberto e gratuito.

Como obter ajuda

Para obter ajuda com o Billing SDK, use estes recursos:

Issues no GitHub: Abra uma issue
Documentação: Acesse billingsdk.com/docs
Documentação completa para LLMs: billingsdk.com/llms-full.txt

Contribuição

O Billing SDK aceita contribuições. O guia de contribuição explica como:

Relatar bugs
Solicitar funcionalidades
Enviar pull requests
Adicionar novos componentes
Melhorar a documentação

Saiba mais

Full Documentation

Guia completo do Billing SDK com exemplos e práticas recomendadas

CLI Reference

Documentação detalhada da CLI para todos os comandos e opções

Component Library

Navegue por todos os componentes disponíveis com exemplos ao vivo

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Visão Geral

Começo Rápido

Frameworks Suportados

Comandos da CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Estrutura dos arquivos gerados

Estrutura de exemplo do Next.js

Configuração do ambiente

Componentes disponíveis

Código aberto

Como obter ajuda

Contribuição

Saiba mais

Full Documentation

CLI Reference

Component Library

​Visão Geral

​Começo Rápido

​Frameworks Suportados

​Comandos da CLI

​@billingsdk/cli init

​@billingsdk/cli add

​Estrutura dos arquivos gerados

​Estrutura de exemplo do Next.js

​Configuração do ambiente

​Componentes disponíveis

​Código aberto

​Como obter ajuda

​Contribuição

​Saiba mais

Full Documentation

CLI Reference

Component Library

Visão Geral

Começo Rápido

Frameworks Suportados

Comandos da CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Estrutura dos arquivos gerados

Estrutura de exemplo do Next.js

Configuração do ambiente

Componentes disponíveis

Código aberto

Como obter ajuda

Contribuição

Saiba mais