SDK de Facturación

Billing SDK es un conjunto de componentes de facturación de React de código abierto, con una CLI que conecta tu proyecto con Dodo Payments. La CLI genera las rutas de API, el hook de React y el cliente de Dodo Payments para tu framework, y añade componentes como tablas de precios y medidores de uso.

Descripción General

Billing SDK incluye:

Componentes de React: Componentes de facturación prediseñados y personalizables para aplicaciones de React.
Herramientas de CLI: Una interfaz de línea de comandos que inicializa proyectos y añade componentes.
Compatibilidad con frameworks: Plantillas para Next.js, Express.js, Hono, Fastify, NestJS y React.
Proveedor de pagos: Integración completa con Dodo Payments.

Inicio Rápido

Para configurar Billing SDK en un proyecto existente, ejecuta la CLI desde la raíz del proyecto:

Install the CLI

Ejecuta la CLI con npx, sin instalarla:

npx @billingsdk/cli --help

También puedes instalarla globalmente si la utilizas con frecuencia. La instalación global añade el comando billingsdk, por ejemplo billingsdk init:

npm install -g @billingsdk/cli

Initialize a Project

Ejecuta la configuración interactiva para añadir la facturación a tu proyecto:

npx @billingsdk/cli init

La CLI te solicita seleccionar:

Tu framework: Next.js, Express.js, React, Hono, Fastify o NestJS. La CLI detecta tu framework y lo marca como detectado.
Tu proveedor de pagos: selecciona Dodo Payments.

Add Components

Añade componentes de facturación individuales a tu proyecto:

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

Frameworks Soportados

Billing SDK tiene una plantilla de Dodo Payments para cada uno de estos frameworks:

Framework	Dodo Payments
Next.js	Sí
Express.js	Sí
Hono	Sí
React	Sí
Fastify	Sí
NestJS	Sí

Comandos de CLI

`@billingsdk/cli init`

init configura la facturación en tu proyecto: instala la plantilla del framework con la integración de Dodo Payments y las dependencias que necesita la plantilla. Qué hace:

Selección del framework: Eliges tu framework y proveedor de pagos.
Instalación de la plantilla: La CLI descarga la plantilla para tu framework y proveedor desde el registro de Billing SDK e instala sus archivos.
Gestión de dependencias: La CLI instala las dependencias de la plantilla, como dodopayments, standardwebhooks y zod, con npm, pnpm, Yarn o Bun.
Generación de archivos: La CLI escribe los archivos de configuración y el código base. Para Express.js, Fastify, Hono y NestJS, los escribe en src/.

Ejemplo:

npx @billingsdk/cli init

Para ejecutar init sin indicaciones, pasa --framework, --provider y --yes, por ejemplo npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes. Añade --dry-run para mostrar los archivos sin escribirlos, --no-install para omitir la instalación de dependencias o --package-manager para elegir npm, pnpm, yarn o bun.

`@billingsdk/cli add`

add instala un componente de facturación en tu proyecto mediante el sistema de registro de shadcn/ui. Ejecuta shadcn@latest add @billingsdk/<component> con el runner de tu gestor de paquetes. Ejemplos:

# 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

Qué sucede:

La CLI de shadcn descarga la configuración del componente desde el registro.
Instala los archivos del componente en tu directorio components/billingsdk/.
Actualiza la configuración de tu proyecto si es necesario.
Instala las dependencias adicionales.

Estructura de los archivos generados

Después de ejecutar init, tu proyecto contiene:

Rutas de API: Endpoints para checkout, clientes, pagos de clientes, productos, suscripciones y webhooks. La plantilla de React no tiene rutas de API.
Hooks: Un hook de React useBilling para operaciones de facturación, disponible para React y Next.js.
Archivos de biblioteca: La configuración del cliente de Dodo Payments y funciones auxiliares, en lib/dodopayments.ts.
Configuración del entorno: Un archivo de entorno de ejemplo, .env.example.

Estructura de ejemplo de Next.js

Para Next.js, init escribe estos archivos:

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

Configuración del entorno

Después de la inicialización, configura tus variables de entorno. Obtén la clave de API desde Developer → API Keys y la clave del webhook desde Developer → Webhooks en el 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

Establece DODO_PAYMENTS_ENVIRONMENT en test_mode o live_mode. El cliente de Dodo Payments generado genera un error para cualquier otro valor.

Guarda tus claves de API en variables de entorno. Nunca las confirmes en el control de versiones.

Componentes disponibles

Billing SDK proporciona componentes de React en estos grupos:

Tablas de precios: Ocho variantes, desde pricing-table-one hasta pricing-table-eight, para mostrar los precios de los productos.
Gestión de suscripciones: subscription-management, además de tarjetas y diálogos para cancelar una suscripción o actualizar un plan.
Supervisión del uso: Medidores de uso circulares y lineales, y tablas de uso para la facturación basada en el uso.
Componentes de checkout: Un selector de método de pago, formularios de datos de pago y una tarjeta de error de pago.
Customer Portal: Configuración de facturación, una pantalla de facturación, historial de facturas y cargos próximos, para la autogestión de los clientes.

Para explorar todos los componentes con una vista previa en directo, consulta la biblioteca de componentes.

Código abierto

Billing SDK es de código abierto:

Transparencia: Puedes consultar cómo funciona cada componente.
Comunidad: Los desarrolladores lo crean para otros desarrolladores.
Seguridad: Cualquiera puede revisar el código para detectar problemas de seguridad.
Innovación: Las contribuciones de la comunidad aceleran el desarrollo.

Billing SDK se distribuye bajo la Licencia Pública General de GNU v3.0 (GPL-3.0), que mantiene el proyecto abierto y gratuito.

Obtener ayuda

Para obtener ayuda con Billing SDK, utiliza estos recursos:

Problemas de GitHub: Abrir un problema
Documentación: Visita billingsdk.com/docs
Documentación completa para LLM: billingsdk.com/llms-full.txt

Contribuir

Billing SDK acepta contribuciones. La guía de contribuciones explica cómo:

Informar de errores
Solicitar funcionalidades
Enviar pull requests
Añadir nuevos componentes
Mejorar la documentación

Más información

Full Documentation

Guía completa de Billing SDK con ejemplos y prácticas recomendadas

CLI Reference

Documentación detallada de la CLI para todos los comandos y opciones

Component Library

Explora todos los componentes disponibles con ejemplos en directo

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Descripción General

Inicio Rápido

Frameworks Soportados

Comandos de CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Estructura de los archivos generados

Estructura de ejemplo de Next.js

Configuración del entorno

Componentes disponibles

Código abierto

Obtener ayuda

Contribuir

Más información

Full Documentation

CLI Reference

Component Library

​Descripción General

​Inicio Rápido

​Frameworks Soportados

​Comandos de CLI

​@billingsdk/cli init

​@billingsdk/cli add

​Estructura de los archivos generados

​Estructura de ejemplo de Next.js

​Configuración del entorno

​Componentes disponibles

​Código abierto

​Obtener ayuda

​Contribuir

​Más información

Full Documentation

CLI Reference

Component Library

Descripción General

Inicio Rápido

Frameworks Soportados

Comandos de CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Estructura de los archivos generados

Estructura de ejemplo de Next.js

Configuración del entorno

Componentes disponibles

Código abierto

Obtener ayuda

Contribuir

Más información