SDK de Facturation

Billing SDK est un ensemble open source de composants de facturation React, doté d’une interface CLI qui connecte votre projet à Dodo Payments. L’interface CLI génère les routes API, le hook React et le client Dodo Payments pour votre framework, et ajoute des composants tels que des tableaux tarifaires et des compteurs d’utilisation.

Aperçu

Billing SDK comprend :

Composants React : composants de facturation prédéfinis et personnalisables pour les applications React.
Outils CLI : une interface en ligne de commande qui initialise les projets et ajoute des composants.
Prise en charge des frameworks : modèles pour Next.js, Express.js, Hono, Fastify, NestJS et React.
Fournisseur de paiement : intégration complète avec Dodo Payments.

Démarrage Rapide

Pour configurer Billing SDK dans un projet existant, exécutez l’interface CLI depuis la racine du projet :

Install the CLI

Exécutez l’interface CLI avec npx, sans l’installer :

npx @billingsdk/cli --help

Vous pouvez aussi l’installer globalement pour une utilisation fréquente. L’installation globale ajoute la commande billingsdk, par exemple billingsdk init :

npm install -g @billingsdk/cli

Initialize a Project

Exécutez la configuration interactive pour ajouter la facturation à votre projet :

npx @billingsdk/cli init

L’interface CLI vous invite à sélectionner :

Votre framework : Next.js, Express.js, React, Hono, Fastify ou NestJS. L’interface CLI détecte votre framework et le marque comme détecté.
Votre fournisseur de paiement : sélectionnez Dodo Payments.

Add Components

Ajoutez des composants de facturation individuels à votre projet :

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

Frameworks Supportés

Billing SDK propose un modèle Dodo Payments pour chacun de ces frameworks :

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

Commandes CLI

`@billingsdk/cli init`

init configure la facturation dans votre projet : il installe le modèle du framework avec l’intégration Dodo Payments, ainsi que les dépendances nécessaires au modèle. Ce que cela fait :

Sélection du framework : vous choisissez votre framework et votre fournisseur de paiement.
Installation du modèle : l’interface CLI télécharge le modèle correspondant à votre framework et à votre fournisseur depuis le registre Billing SDK, puis installe ses fichiers.
Gestion des dépendances : l’interface CLI installe les dépendances du modèle, telles que dodopayments, standardwebhooks et zod, avec npm, pnpm, Yarn ou Bun.
Génération des fichiers : l’interface CLI écrit les fichiers de configuration et le code standard. Pour Express.js, Fastify, Hono et NestJS, elle les écrit sous src/.

Exemple :

npx @billingsdk/cli init

Pour exécuter init sans invites, transmettez --framework, --provider et --yes, par exemple npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes. Ajoutez --dry-run pour lister les fichiers sans les écrire, --no-install pour ignorer l’installation des dépendances ou --package-manager pour choisir npm, pnpm, yarn ou bun.

`@billingsdk/cli add`

add installe un composant de facturation dans votre projet via le système de registre shadcn/ui. Il exécute shadcn@latest add @billingsdk/<component> avec le runner de votre gestionnaire de paquets. Exemples :

# 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

Fonctionnement :

L’interface CLI shadcn télécharge la configuration du composant depuis le registre.
Elle installe les fichiers du composant dans votre répertoire components/billingsdk/.
Elle met à jour la configuration de votre projet si nécessaire.
Elle installe les dépendances supplémentaires éventuelles.

Structure des fichiers générés

Après avoir exécuté init, votre projet contient :

Routes API : endpoints pour le checkout, les clients, les paiements des clients, les produits, les abonnements et les webhooks. Le modèle React ne comporte aucune route API.
Hooks : un hook React useBilling pour les opérations de facturation, destiné à React et Next.js.
Fichiers de bibliothèque : la configuration du client Dodo Payments et les fonctions d’assistance, dans lib/dodopayments.ts.
Configuration de l’environnement : un fichier d’environnement d’exemple, .env.example.

Exemple de structure Next.js

Pour Next.js, init écrit ces fichiers :

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

Configuration de l’environnement

Après l’initialisation, définissez vos variables d’environnement. Récupérez la clé API dans Developer → API Keys et la clé webhook dans Developer → Webhooks du 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

Définissez DODO_PAYMENTS_ENVIRONMENT sur test_mode ou live_mode. Le client Dodo Payments généré renvoie une erreur pour toute autre valeur.

Stockez vos clés API dans des variables d’environnement. Ne les validez jamais dans le contrôle de version.

Composants disponibles

Billing SDK fournit des composants React dans les groupes suivants :

Tableaux tarifaires : huit variantes, de pricing-table-one à pricing-table-eight, pour afficher les tarifs des produits.
Gestion des abonnements : subscription-management, ainsi que des cartes et des boîtes de dialogue pour annuler un abonnement ou mettre à jour un forfait.
Suivi de l’utilisation : compteurs d’utilisation circulaires et linéaires, ainsi que des tableaux d’utilisation pour la facturation basée sur l’utilisation.
Composants de checkout : un sélecteur de moyen de paiement, des formulaires de détails de paiement et une carte d’échec de paiement.
Customer Portal : paramètres de facturation, écran de facturation, historique des factures et frais à venir, pour permettre aux clients d’effectuer leurs opérations en self-service.

Pour parcourir tous les composants avec un aperçu en direct, consultez la bibliothèque de composants.

Open source

Billing SDK est open source :

Transparence : vous pouvez consulter le fonctionnement de chaque composant.
Communauté : des développeurs le conçoivent pour d’autres développeurs.
Sécurité : chacun peut examiner le code pour détecter d’éventuels problèmes de sécurité.
Innovation : les contributions de la communauté accélèrent le développement.

Billing SDK est distribué sous la GNU General Public License v3.0 (GPL-3.0), ce qui permet au projet de rester ouvert et gratuit.

Obtenir de l’aide

Pour obtenir de l’aide concernant Billing SDK, utilisez les ressources suivantes :

Problèmes GitHub : ouvrir un problème
Documentation : consultez billingsdk.com/docs
Documentation complète pour les LLM : billingsdk.com/llms-full.txt

Contribuer

Billing SDK accueille les contributions. Le guide de contribution explique comment :

Signaler des bugs
Demander des fonctionnalités
Soumettre des pull requests
Ajouter de nouveaux composants
Améliorer la documentation

En savoir plus

Full Documentation

Guide complet de Billing SDK avec des exemples et des bonnes pratiques

CLI Reference

Documentation détaillée de l’interface CLI pour toutes les commandes et options

Component Library

Parcourez tous les composants disponibles avec des exemples en direct

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Aperçu

Démarrage Rapide

Frameworks Supportés

Commandes CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Structure des fichiers générés

Exemple de structure Next.js

Configuration de l’environnement

Composants disponibles

Open source

Obtenir de l’aide

Contribuer

En savoir plus

Full Documentation

CLI Reference

Component Library

​Aperçu

​Démarrage Rapide

​Frameworks Supportés

​Commandes CLI

​@billingsdk/cli init

​@billingsdk/cli add

​Structure des fichiers générés

​Exemple de structure Next.js

​Configuration de l’environnement

​Composants disponibles

​Open source

​Obtenir de l’aide

​Contribuer

​En savoir plus

Full Documentation

CLI Reference

Component Library

Aperçu

Démarrage Rapide

Frameworks Supportés

Commandes CLI

`@billingsdk/cli init`

`@billingsdk/cli add`

Structure des fichiers générés

Exemple de structure Next.js

Configuration de l’environnement

Composants disponibles

Open source

Obtenir de l’aide

Contribuer

En savoir plus