Synchronisez avec votre base de données

Synchronisez vos données Dodo Payments avec votre propre base de données pour l’analytics, les rapports et les intégrations. Le moteur de synchronisation réplique automatiquement les paiements, les clients, les abonnements et les licences vers MongoDB, PostgreSQL, MySQL ou ClickHouse.

Package : dodo-sync sur npm | Source : GitHub

Que pouvez-vous synchroniser ?

Choisissez n’importe quelle combinaison de ces entités :

Payments

Toutes les transactions de paiement, y compris les paiements ponctuels, les remboursements et les mises à jour de statut.

Customers

Profils clients, coordonnées et métadonnées.

Subscriptions

Données d’abonnement, cycles de facturation et changements de statut.

Licenses

Clés de licence, activations et mises à jour de statut.

Spécifiez les entités à synchroniser à l’aide du paramètre scopes. Chaque exécution récupère chaque enregistrement dans les périmètres sélectionnés et l’écrit en utilisant son ID. Les lignes existantes sont ainsi mises à jour sur place au lieu d’être dupliquées. Chaque page d’enregistrements est écrite dans votre base de données en un seul lot.

Bases de données prises en charge

Dodo Sync prend en charge MongoDB, PostgreSQL, MySQL 8.0.20 ou version ultérieure, ainsi que ClickHouse. La prise en charge de Snowflake et d’autres bases de données, des pipelines ETL et de la synchronisation en temps réel est en cours de développement. Pour contribuer à une nouvelle intégration de base de données, envoyez une pull request au dépôt GitHub.

Premiers pas

Utilisez Dodo Sync via la CLI pour une configuration rapide ou directement dans votre code pour l’intégrer à votre application. Les deux méthodes offrent les mêmes fonctionnalités.

Utilisation de la CLI

Installez la CLI globalement pour pouvoir l’exécuter depuis n’importe quel emplacement :

npm install -g dodo-sync

bun add -g dodo-sync

Exécution de la CLI

La CLI prend en charge deux modes : interactif pour une configuration guidée et manuel pour une configuration directe. Mode interactif : exécutez la CLI sans arguments pour démarrer l’assistant de configuration.

dodo-sync

Mode manuel : transmettez directement les arguments pour ignorer l’assistant.

dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]

Exemples :

# MongoDB
dodo-sync -i 600 -d mongodb -u mongodb://mymongodb.url --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# PostgreSQL
dodo-sync -i 600 -d postgres -u postgresql://user:password@localhost:5432/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# MySQL
dodo-sync -i 600 -d mysql -u mysql://user:password@localhost:3306/mydb --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

# ClickHouse
dodo-sync -i 600 -d clickhouse -u http://localhost:8123 --scopes "licences,payments,customers,subscriptions" --api-key YOUR_API_KEY --env test_mode

Arguments de la CLI

number

requis

Intervalle de synchronisation en secondes. La CLI s’exécute en continu selon cet intervalle. Pour une synchronisation ponctuelle, utilisez .run() dans votre code.

string

requis

Type de base de données : "mongodb", "postgres", "mysql" ou "clickhouse".

string

requis

URI de connexion à votre base de données :

MongoDB : mongodb://localhost:27017 ou mongodb+srv://user:pass@cluster.mongodb.net/
PostgreSQL : postgresql://user:password@localhost:5432/mydb
MySQL : mysql://user:password@localhost:3306/mydb
ClickHouse : http://localhost:8123

string

requis

Liste séparée par des virgules des entités à synchroniser : licences, payments, customers, subscriptions. Exemple : "payments,customers".

string

requis

Votre clé API Dodo Payments issue de Developer → API Keys. Utilisez une clé correspondant au même mode que --env.

string

requis

Environnement : "live_mode" ou "test_mode".

number

Limite de débit en requêtes par seconde. Contrôle la vitesse à laquelle le moteur de synchronisation effectue les requêtes API. La valeur par défaut est 10 ; les valeurs supérieures ou égales à 100 désactivent la limitation.

Utilisation dans votre code

Intégrez directement la fonctionnalité de synchronisation à votre application. Installez-la en tant que dépendance :

npm install dodo-sync

bun add dodo-sync

Synchronisation automatique (basée sur un intervalle)

Exécutez la synchronisation en continu à intervalles réguliers :

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60, // Sync every 60 seconds
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI, // e.g., 'mongodb://localhost:27017'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode' // or 'live_mode'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Start the sync loop
syncDodoPayments.start();

L’option interval est obligatoire avec .start(). La synchronisation s’exécute en continu selon l’intervalle indiqué jusqu’à l’arrêt du processus.

Synchronisation manuelle

Déclenchez des opérations de synchronisation à la demande, par exemple depuis une tâche cron, un endpoint API ou une fonction serverless :

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  database: 'mongodb',
  databaseURI: process.env.MONGODB_URI,
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

try {
  // Initialize connection
  await syncDodoPayments.init();

  // Trigger a single sync operation
  await syncDodoPayments.run();
} finally {
  // Close the database connection
  await syncDodoPayments.disconnect();
}

L’option interval n’est pas requise pour une synchronisation manuelle. Appelez .run() chaque fois que vous devez effectuer une synchronisation. .run() ne se résout qu’une fois toutes les écritures dans la base de données terminées. .close() est un alias de .disconnect().

Exécution sur une plateforme serverless

Sur Vercel, AWS Lambda ou des plateformes similaires :

Appelez .disconnect() dans un bloc finally, comme dans l’exemple ci-dessus, afin que les connexions ne restent pas ouvertes entre les invocations.
Utilisez le runtime Node.js. Les runtimes Edge ne peuvent pas ouvrir de connexions à la base de données.
Augmentez le délai d’expiration de la fonction. Une synchronisation volumineuse peut prendre plus de temps que la limite par défaut. Sur Vercel, définissez export const maxDuration = 60;.
Synchronisez moins de périmètres par invocation, par exemple scopes: ['payments'], afin de garder chaque exécution courte.

Exemple PostgreSQL

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'postgres',
  databaseURI: process.env.POSTGRES_URI, // e.g., 'postgresql://user:password@localhost:5432/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

Exemple MySQL

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'mysql',
  databaseURI: process.env.MYSQL_URI, // e.g., 'mysql://user:password@localhost:3306/mydb'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

Exemple ClickHouse

import { DodoSync } from 'dodo-sync';

const syncDodoPayments = new DodoSync({
  interval: 60,
  database: 'clickhouse',
  databaseURI: process.env.CLICKHOUSE_URI, // e.g., 'http://localhost:8123'
  scopes: ['licences', 'payments', 'customers', 'subscriptions'],
  dodoPaymentsOptions: {
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: 'test_mode'
  }
});

await syncDodoPayments.init();
syncDodoPayments.start();

Options du constructeur

string

requis

Type de base de données : "mongodb", "postgres", "mysql" ou "clickhouse".

string

requis

Chaîne de connexion à votre base de données :

MongoDB : mongodb://localhost:27017 ou mongodb+srv://...
PostgreSQL : postgresql://user:password@localhost:5432/mydb
MySQL : mysql://user:password@localhost:3306/mydb
ClickHouse : http://localhost:8123

string[]

requis

Tableau d’entités à synchroniser : "licences", "payments", "customers", "subscriptions". Vous pouvez inclure n’importe quelle combinaison.

object

requis

Configuration de l’API Dodo Payments. Consultez les types du SDK TypeScript pour connaître toutes les options.Propriétés requises :

bearerToken : votre clé API Dodo Payments
environment : "test_mode" ou "live_mode"

number

Durée, en secondes, entre les synchronisations automatiques. Requise pour .start(), facultative pour .run().

number

Limite de débit en requêtes par seconde. La valeur par défaut est 10 ; les valeurs égales ou supérieures à 100 désactivent la limitation de débit.

Informations importantes

MongoDB : les collections (subscriptions, payments, licences, customers) sont créées dans la base de données indiquée dans votre URI de connexion, par exemple mongodb://localhost:27017/my_database. Si l’URI n’indique aucune base de données, Dodo Sync utilise dodopayments_sync.PostgreSQL : les tables (Subscriptions, Payments, Licenses, Customers) sont créées dans la base de données spécifiée dans votre URI de connexion. Les données sont stockées au format JSONB.MySQL : nécessite MySQL 8.0.20 ou version ultérieure. Les tables (Subscriptions, Payments, Licenses, Customers) sont créées dans la base de données spécifiée dans votre URI de connexion. Les données sont stockées au format JSON.ClickHouse : les tables (Subscriptions, Payments, Licenses, Customers) sont créées à l’aide du moteur ReplacingMergeTree. Lors des requêtes, utilisez le mot-clé FINAL pour garantir des résultats dédupliqués.

Mise à niveau depuis la version 0.x

La version 1.0 modifie la manière dont les données MongoDB sont stockées et augmente la version minimale requise de MySQL. Avant la mise à niveau :

MongoDB : supprimez votre collection licences existante. Les documents de licence sont désormais stockés selon id de la licence au lieu de subscription_id, et la prochaine synchronisation repeuplera la collection.
MongoDB : vérifiez votre URI de connexion. Les données sont désormais écrites dans la base de données indiquée par l’URI, et plus systématiquement dans dodopayments_sync. Pour continuer à utiliser vos données existantes, ajoutez dodopayments_sync dans l’URI ou omettez la base de données.
MySQL : effectuez la mise à niveau vers MySQL 8.0.20 ou version ultérieure.

Ressources supplémentaires

GitHub Repository

Afficher le code source, signaler des problèmes ou contribuer à des améliorations

npm Package

Consulter les détails du package et les instructions d’installation

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Que pouvez-vous synchroniser ?

Payments

Customers

Subscriptions

Licenses

Bases de données prises en charge

Premiers pas

Utilisation de la CLI

Exécution de la CLI

Arguments de la CLI

Utilisation dans votre code

Synchronisation automatique (basée sur un intervalle)

Synchronisation manuelle

Exécution sur une plateforme serverless

Exemple PostgreSQL

Exemple MySQL

Exemple ClickHouse

Options du constructeur

Informations importantes

Mise à niveau depuis la version 0.x

Ressources supplémentaires

GitHub Repository

npm Package