Sincronizza con il tuo database

Sincronizza i dati di Dodo Payments con il tuo database per analisi, report e integrazioni. Il motore di sincronizzazione replica automaticamente payments, customers, subscriptions e licenses in MongoDB, PostgreSQL, MySQL o ClickHouse.

Package: dodo-sync su npm | Source: GitHub

Cosa puoi sincronizzare?

Scegli una combinazione qualsiasi di queste entità:

Payments

Tutte le transazioni di pagamento, inclusi i pagamenti una tantum, i rimborsi e gli aggiornamenti di stato.

Customers

Profili dei clienti, informazioni di contatto e metadati.

Subscriptions

Dati degli abbonamenti, cicli di fatturazione e modifiche di stato.

Licenses

Chiavi di licenza, attivazioni e aggiornamenti di stato.

Specifica quali entità sincronizzare usando il parametro scopes. Ogni esecuzione recupera ogni record negli ambiti selezionati e lo scrive utilizzando l’ID, quindi le righe esistenti vengono aggiornate sul posto invece di essere duplicate. Ogni pagina di record viene scritta nel database con una singola operazione batch.

Supporto dei database

Dodo Sync supporta MongoDB, PostgreSQL, MySQL 8.0.20 o versioni successive e ClickHouse. Il supporto per Snowflake e altri database, le pipeline ETL e la sincronizzazione in tempo reale sono in fase di sviluppo. Per contribuire a una nuova integrazione con un database, invia una pull request al repository GitHub.

Per iniziare

Usa Dodo Sync tramite la CLI per una configurazione rapida oppure direttamente nel tuo codice per integrarlo nella tua applicazione. Entrambi i metodi offrono le stesse funzionalità.

Utilizzo della CLI

Installa la CLI a livello globale per eseguirla da qualsiasi posizione:

npm install -g dodo-sync

bun add -g dodo-sync

Esecuzione della CLI

La CLI supporta due modalità: interattiva per una configurazione guidata e manuale per una configurazione diretta. Modalità interattiva: esegui il comando senza argomenti per avviare la procedura guidata di configurazione.

dodo-sync

Modalità manuale: passa direttamente gli argomenti per ignorare la procedura guidata.

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

Esempi:

# 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

Argomenti della CLI

number

obbligatorio

Intervallo di sincronizzazione in secondi. La CLI viene eseguita continuamente con questo intervallo. Per una sincronizzazione una tantum, usa .run() nel tuo codice.

string

obbligatorio

Tipo di database: "mongodb", "postgres", "mysql" o "clickhouse".

string

obbligatorio

URI di connessione al database:

MongoDB: mongodb://localhost:27017 o 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

obbligatorio

Elenco separato da virgole delle entità da sincronizzare: licences, payments, customers, subscriptions. Esempio: "payments,customers".

string

obbligatorio

La tua chiave API di Dodo Payments da Developer → API Keys. Usa una chiave della stessa modalità di --env.

string

obbligatorio

Ambiente: "live_mode" o "test_mode".

number

Limite di frequenza in richieste al secondo. Controlla la velocità con cui il motore di sincronizzazione effettua le richieste API. Il valore predefinito è 10; i valori pari o superiori a 100 disattivano il throttling.

Utilizzo nel codice

Integra direttamente la funzionalità di sincronizzazione nella tua applicazione. Installala come dipendenza:

npm install dodo-sync

bun add dodo-sync

Sincronizzazione automatica (basata su intervallo)

Esegui la sincronizzazione continuamente a intervalli regolari:

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’opzione interval è obbligatoria quando si utilizza .start(). La sincronizzazione viene eseguita continuamente all’intervallo specificato finché il processo non si arresta.

Sincronizzazione manuale

Attiva le operazioni di sincronizzazione su richiesta, ad esempio da un cron job, un endpoint API o una funzione 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’opzione interval non è necessaria per la sincronizzazione manuale. Chiama .run() ogni volta che devi eseguire una sincronizzazione. .run() viene risolta solo dopo il completamento di tutte le scritture nel database. .close() è un alias di .disconnect().

Esecuzione su Serverless

Su Vercel, AWS Lambda o piattaforme simili:

Chiama .disconnect() in un blocco finally, come nell’esempio precedente, in modo che le connessioni non rimangano aperte tra un’invocazione e l’altra.
Usa il runtime Node.js. I runtime Edge non possono aprire connessioni al database.
Aumenta il timeout della funzione. Una sincronizzazione di grandi dimensioni può richiedere più tempo del limite predefinito. Su Vercel, imposta export const maxDuration = 60;.
Sincronizza meno ambiti per invocazione, ad esempio scopes: ['payments'], per mantenere breve ogni esecuzione.

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

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

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

Opzioni del costruttore

string

obbligatorio

Tipo di database: "mongodb", "postgres", "mysql" o "clickhouse".

string

obbligatorio

Stringa di connessione al database:

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

string[]

obbligatorio

Array di entità da sincronizzare: "licences", "payments", "customers", "subscriptions". Includi qualsiasi combinazione.

object

obbligatorio

Configurazione dell’API Dodo Payments. Consulta i tipi dell’SDK TypeScript per tutte le opzioni.Proprietà obbligatorie:

bearerToken: la tua chiave API Dodo Payments
environment: "test_mode" o "live_mode"

number

Tempo in secondi tra le sincronizzazioni automatiche. Obbligatorio per .start(), facoltativo per .run().

number

Limite di frequenza in richieste al secondo. Il valore predefinito è 10; i valori pari o superiori a 100 disattivano il throttling.

Informazioni importanti

MongoDB: le collection (subscriptions, payments, licences, customers) vengono create nel database indicato nell’URI di connessione, ad esempio mongodb://localhost:27017/my_database. Se l’URI non indica alcun database, Dodo Sync usa dodopayments_sync.PostgreSQL: le tabelle (Subscriptions, Payments, Licenses, Customers) vengono create nel database specificato nell’URI di connessione. I dati vengono archiviati come JSONB.MySQL: richiede MySQL 8.0.20 o versioni successive. Le tabelle (Subscriptions, Payments, Licenses, Customers) vengono create nel database specificato nell’URI di connessione. I dati vengono archiviati come JSON.ClickHouse: le tabelle (Subscriptions, Payments, Licenses, Customers) vengono create usando il motore ReplacingMergeTree. Quando esegui query, usa la parola chiave FINAL per assicurarti di ottenere risultati deduplicati.

Aggiornamento dalla versione 0.x

La versione 1.0 modifica il modo in cui vengono archiviati i dati MongoDB e aumenta il requisito per MySQL. Prima dell’aggiornamento:

MongoDB: elimina la collection licences esistente. I documenti delle licenze vengono ora archiviati in base a id invece che in base a subscription_id, e la sincronizzazione successiva ripopola la collection.
MongoDB: controlla l’URI di connessione. Ora i dati vengono scritti nel database indicato dall’URI, non sempre in dodopayments_sync. Per continuare a utilizzare i dati esistenti, inserisci dodopayments_sync nell’URI oppure ometti il database.
MySQL: esegui l’aggiornamento a MySQL 8.0.20 o versioni successive.

Risorse aggiuntive

GitHub Repository

Visualizza il codice sorgente, segnala problemi o contribuisci con miglioramenti

npm Package

Visualizza i dettagli del pacchetto e le istruzioni per l’installazione

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Cosa puoi sincronizzare?

Payments

Customers

Subscriptions

Licenses

Supporto dei database

Per iniziare

Utilizzo della CLI

Esecuzione della CLI

Argomenti della CLI

Utilizzo nel codice

Sincronizzazione automatica (basata su intervallo)

Sincronizzazione manuale

Esecuzione su Serverless

Esempio PostgreSQL

Esempio MySQL

Esempio ClickHouse

Opzioni del costruttore

Informazioni importanti

Aggiornamento dalla versione 0.x

Risorse aggiuntive

GitHub Repository

npm Package

​Cosa puoi sincronizzare?

Payments

Customers

Subscriptions

Licenses

​Supporto dei database

​Per iniziare

​Utilizzo della CLI

​Esecuzione della CLI

​Argomenti della CLI

​Utilizzo nel codice

​Sincronizzazione automatica (basata su intervallo)

​Sincronizzazione manuale

​Esecuzione su Serverless

​Esempio PostgreSQL

​Esempio MySQL

​Esempio ClickHouse

​Opzioni del costruttore

​Informazioni importanti

​Aggiornamento dalla versione 0.x

​Risorse aggiuntive

GitHub Repository

npm Package

Cosa puoi sincronizzare?

Supporto dei database

Per iniziare

Utilizzo della CLI

Esecuzione della CLI

Argomenti della CLI

Utilizzo nel codice

Sincronizzazione automatica (basata su intervallo)

Sincronizzazione manuale

Esecuzione su Serverless

Esempio PostgreSQL

Esempio MySQL

Esempio ClickHouse

Opzioni del costruttore

Informazioni importanti

Aggiornamento dalla versione 0.x

Risorse aggiuntive