データベースと同期

Dodo Payments には、payment data を自分のデータベースと自動的に同期する、組み込みの database sync 機能が用意されています。payments、customers、subscriptions、licenses を同期して、分析、レポート、他のシステムとの統合に使用できるデータのローカルコピーを保持できます。

Implementation: npm package で利用可能 | Source Code: GitHub

同期できるデータ

database sync 機能では、次の Dodo Payments entities をデータベースに同期できます。

Payments

one-time payments、refunds、payment status updates を含む、すべての payment transactions を同期します。

Customers

customer profiles、contact information、metadata を含む customer data を同期します。

Subscriptions

active subscriptions、billing cycles、subscription status changes を含む subscription data を同期します。

Licenses

license keys、activations、license status updates を含む license information を同期します。

これらの entities は、scopes parameter に指定することで、任意の組み合わせで同期できます。すべての sync operations は incremental で、パフォーマンスを最適化するため、新規または更新された records のみを転送します。

Database Support

現在、MongoDB、PostgreSQL、MySQL、ClickHouse をサポートしています。現在、次のサポート拡張に取り組んでいます。

Databases: Snowflake など
Pipelines: ETL pipelines、Realtime sync

Database support は継続的に拡張しています。新しい database integration の追加に貢献したい場合は、GitHub repository に Pull Request を送信してください。

はじめに

database sync 機能は CLI または code からプログラムで使用できます。どちらの方法でも同じ機能を利用できます。ワークフローに最適な方法を選択してください。

CLI の使用

CLI tool は database synchronization をすばやく設定して実行する方法を提供します。端末のどこからでも使用できるよう、グローバルにインストールします。

npm install -g dodo-sync

bun add -g dodo-sync

CLI の実行

CLI は 2 つの mode をサポートしています。ガイド付きセットアップを行う Interactive Mode と、直接設定を行う Manual Mode です。 Interactive Mode: 引数なしで command を実行すると、interactive setup wizard が開始します。

dodo-sync

Manual Mode: arguments を直接渡して wizard をスキップします。

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

Examples:

# 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

CLI Arguments

number

seconds 単位の sync interval。sync operation の実行頻度を決定します。指定しない場合、sync は一度だけ実行されて終了します。

string

必須

使用する database type。サポートされる値は "mongodb"、"postgres"、"mysql"、または "clickhouse" です。

string

必須

データベースの Connection URI:

MongoDB: mongodb://localhost:27017 または 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

必須

同期する data entities の comma-separated list。利用可能な scopes は licences、payments、customers、subscriptions です。例: "payments,customers"。

string

必須

あなたの Dodo Payments API key。live mode では dp_live_、test mode では dp_test_ で始まる必要があります。

string

必須

Environment target。"live_mode" または "test_mode" のいずれかである必要があります。これは、どの Dodo Payments environment から同期するかを指定します。

number

requests per second 単位の rate limit。Dodo Payments API への過剰な負荷を避けるため、sync engine が API requests を実行する速度を制御します。

Code での使用

プログラムから制御するには、sync feature をアプリケーションへ直接統合します。project の dependency としてインストールします。

npm install dodo-sync

bun add dodo-sync

Automatic Sync（Interval-based）

sync を一定間隔で継続的に実行する場合は、automatic sync を使用します。

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();

automatic syncing で .start() を使用する場合、interval option が必要です。process が停止されるまで、指定した interval で sync が継続的に実行されます。

Manual Sync

オンデマンド（cron job や API endpoint など）で sync operations をトリガーする場合は、manual sync を使用します。

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'
  }
});

// Initialize connection
await syncDodoPayments.init();

// Trigger a single sync operation
await syncDodoPayments.run();

manual sync では、interval option は不要です。sync operation を実行する必要があるときに、.run() を呼び出せます。

PostgreSQL の例

PostgreSQL で dodo-sync を使用する方法は次のとおりです。

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();

MySQL の例

MySQL で dodo-sync を使用する方法は次のとおりです。

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();

ClickHouse の例

ClickHouse で dodo-sync を使用する方法は次のとおりです。

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();

Constructor Options

string

必須

使用する database の名前。サポートされる値は "mongodb"、"postgres"、"mysql"、または "clickhouse" です。

string

必須

database の connection string:

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

string[]

必須

同期する entities の array。利用可能な options は "licences"、"payments"、"customers"、"subscriptions" です。これらは任意の組み合わせで指定できます。

object

必須

Dodo Payments API configuration。認証と environment selection に使用します。すべての options については、TypeScript SDK types を参照してください。Required properties:

bearerToken: あなたの Dodo Payments API key
environment: "test_mode" または "live_mode"

number

automatic sync 間の seconds 単位の時間。automatic syncing で .start() を使用する場合は必須です。manual syncing で .run() を使用する場合は任意です。

number

1 秒あたりの requests 数。Dodo Payments API への過剰な負荷を避けるため、sync engine が API requests を実行する速度を制御します。

重要な情報

MongoDB: dodopayments_sync という名前の database が、database server 上に自動的に作成されます。すべての sync data はそこに保存されます。この database name は現在固定されており、変更できません。PostgreSQL: Tables（Subscriptions、Payments、Licenses、Customers）は、connection URI で指定された database に作成されます。data は JSONB として保存されます。MySQL: Tables（Subscriptions、Payments、Licenses、Customers）は、connection URI で指定された database に作成されます。data は JSON として保存されます。ClickHouse: Tables（Subscriptions、Payments、Licenses、Customers）は、ReplacingMergeTree engine を使用して作成されます。query 時には、重複排除された results を確実に取得するため、FINAL keyword を使用してください。

sync engine は changes を追跡し、新規または更新された records のみを同期するため、大規模な datasets でも subsequent syncs を効率的に実行できます。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

同期できるデータ

Payments

Customers

Subscriptions

Licenses

Database Support

はじめに

CLI の使用

CLI の実行

CLI Arguments

Code での使用

Automatic Sync（Interval-based）

Manual Sync

PostgreSQL の例

MySQL の例

ClickHouse の例

Constructor Options

重要な情報

追加リソース

GitHub Repository

npm Package

​同期できるデータ

Payments

Customers

Subscriptions

Licenses

​Database Support

​はじめに

​CLI の使用

​CLI の実行

​CLI Arguments

​Code での使用

​Automatic Sync（Interval-based）

​Manual Sync

​PostgreSQL の例

​MySQL の例

​ClickHouse の例

​Constructor Options

​重要な情報

​追加リソース

GitHub Repository

npm Package

同期できるデータ

Database Support

はじめに

CLI の使用

CLI の実行

CLI Arguments

Code での使用

Automatic Sync（Interval-based）

Manual Sync

PostgreSQL の例

MySQL の例

ClickHouse の例

Constructor Options

重要な情報

追加リソース