Sincronize com seu banco de dados

Sincronize seus dados do Dodo Payments com seu próprio banco de dados para analytics, relatórios e integrações. O mecanismo de sincronização replica automaticamente pagamentos, clientes, assinaturas e licenças para MongoDB, PostgreSQL, MySQL ou ClickHouse.

Pacote: dodo-sync no npm | Código-fonte: GitHub

O que você pode sincronizar?

Escolha qualquer combinação destas entidades:

Payments

Todas as transações de pagamento, incluindo pagamentos únicos, reembolsos e atualizações de status.

Customers

Perfis de clientes, informações de contato e metadados.

Subscriptions

Dados de assinatura, ciclos de cobrança e alterações de status.

Licenses

Chaves de licença, ativações e atualizações de status.

Especifique quais entidades sincronizar usando o parâmetro scopes. Cada execução busca todos os registros nos escopos selecionados e os grava pelo ID, portanto as linhas existentes são atualizadas no local em vez de duplicadas. Cada página de registros é gravada no seu banco de dados em um único lote.

Suporte a Banco de Dados

Dodo Sync é compatível com MongoDB, PostgreSQL, MySQL 8.0.20 ou posterior e ClickHouse. O suporte para Snowflake e outros bancos de dados, pipelines de ETL e sincronização em tempo real está em desenvolvimento. Para contribuir com uma nova integração de banco de dados, envie um pull request para o repositório no GitHub.

Primeiros passos

Use o Dodo Sync por meio do CLI para uma configuração rápida ou de forma programática no seu código para integrá-lo ao seu aplicativo. Ambos os métodos oferecem a mesma funcionalidade.

Usando o CLI

Instale o CLI globalmente para executá-lo de qualquer lugar:

npm install -g dodo-sync

bun add -g dodo-sync

Executando o CLI

O CLI oferece dois modos: interativo, para uma configuração guiada, e manual, para configuração direta. Modo interativo: execute sem argumentos para iniciar o assistente de configuração.

dodo-sync

Modo manual: passe os argumentos diretamente para ignorar o assistente.

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

Exemplos:

# 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

Argumentos do CLI

number

obrigatório

Intervalo de sincronização em segundos. O CLI é executado continuamente nesse intervalo. Para uma sincronização única, use .run() no seu código.

string

obrigatório

Tipo de banco de dados: "mongodb", "postgres", "mysql" ou "clickhouse".

string

obrigatório

URI de conexão do seu banco de dados:

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

obrigatório

Lista de entidades separadas por vírgulas para sincronizar: licences, payments, customers, subscriptions. Exemplo: "payments,customers".

string

obrigatório

Sua chave de API do Dodo Payments em Developer → API Keys. Use uma chave do mesmo modo que --env.

string

obrigatório

Ambiente: "live_mode" ou "test_mode".

number

Limite de taxa em solicitações por segundo. Controla a velocidade com que o mecanismo de sincronização faz solicitações de API. O padrão é 10; valores de 100 ou superiores desativam a limitação.

Usando no seu código

Integre o recurso de sincronização diretamente ao seu aplicativo. Instale-o como uma dependência:

npm install dodo-sync

bun add dodo-sync

Sincronização automática (baseada em intervalo)

Execute a sincronização continuamente em intervalos regulares:

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

A opção interval é obrigatória ao usar .start(). A sincronização é executada continuamente no intervalo especificado até que o processo seja interrompido.

Sincronização manual

Acione operações de sincronização sob demanda, por exemplo, a partir de um cron job, um endpoint de API ou uma função 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();
}

A opção interval não é obrigatória para a sincronização manual. Chame .run() sempre que precisar sincronizar. .run() só é resolvida depois que todas as gravações no banco de dados forem concluídas. .close() é um alias para .disconnect().

Executando em Serverless

No Vercel, AWS Lambda ou plataformas semelhantes:

Chame .disconnect() em um bloco finally, como no exemplo acima, para que as conexões não permaneçam abertas entre as invocações.
Use o runtime do Node.js. Runtimes Edge não podem abrir conexões com o banco de dados.
Aumente o timeout da função. Uma sincronização grande pode levar mais tempo do que o limite padrão. No Vercel, defina export const maxDuration = 60;.
Sincronize menos escopos por invocação, como scopes: ['payments'], para manter cada execução curta.

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

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

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

Opções do Construtor

string

obrigatório

Tipo de banco de dados: "mongodb", "postgres", "mysql" ou "clickhouse".

string

obrigatório

String de conexão do seu banco de dados:

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[]

obrigatório

Array de entidades a sincronizar: "licences", "payments", "customers", "subscriptions". Inclua qualquer combinação.

object

obrigatório

Configuração da API do Dodo Payments. Consulte os tipos do SDK do TypeScript para ver todas as opções.Propriedades obrigatórias:

bearerToken: sua chave de API do Dodo Payments
environment: "test_mode" ou "live_mode"

number

Tempo, em segundos, entre sincronizações automáticas. Obrigatório para .start(), opcional para .run().

number

Limite de taxa em solicitações por segundo. O padrão é 10; valores de 100 ou superiores desativam o controle de taxa.

Informações importantes

MongoDB: As collections (subscriptions, payments, licences, customers) são criadas no banco de dados indicado na sua URI de conexão, como mongodb://localhost:27017/my_database. Se a URI não indicar um banco de dados, o Dodo Sync usará dodopayments_sync.PostgreSQL: As tabelas (Subscriptions, Payments, Licenses, Customers) são criadas no banco de dados especificado na sua URI de conexão. Os dados são armazenados como JSONB.MySQL: Requer MySQL 8.0.20 ou posterior. As tabelas (Subscriptions, Payments, Licenses, Customers) são criadas no banco de dados especificado na sua URI de conexão. Os dados são armazenados como JSON.ClickHouse: As tabelas (Subscriptions, Payments, Licenses, Customers) são criadas usando o mecanismo ReplacingMergeTree. Ao consultar, use a palavra-chave FINAL para garantir resultados sem duplicidades.

Atualização da versão 0.x

A versão 1.0 altera a forma como os dados do MongoDB são armazenados e aumenta o requisito do MySQL. Antes de fazer a atualização:

MongoDB: Exclua sua collection licences existente. Os documentos de licença agora são armazenados pelo id da licença em vez de subscription_id, e a próxima sincronização repopulará a collection.
MongoDB: Verifique sua URI de conexão. Os dados agora são gravados no banco de dados indicado pela URI, e não sempre em dodopayments_sync. Para continuar usando seus dados existentes, inclua dodopayments_sync na URI ou não informe o banco de dados.
MySQL: Atualize para MySQL 8.0.20 ou posterior.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

O que você pode sincronizar?

Payments

Customers

Subscriptions

Licenses

Suporte a Banco de Dados

Primeiros passos

Usando o CLI

Executando o CLI

Argumentos do CLI

Usando no seu código

Sincronização automática (baseada em intervalo)

Sincronização manual

Executando em Serverless

Exemplo de PostgreSQL

Exemplo de MySQL

Exemplo de ClickHouse

Opções do Construtor

Informações importantes

Atualização da versão 0.x

Recursos adicionais

GitHub Repository

npm Package

​O que você pode sincronizar?

Payments

Customers

Subscriptions

Licenses

​Suporte a Banco de Dados

​Primeiros passos

​Usando o CLI

​Executando o CLI

​Argumentos do CLI

​Usando no seu código

​Sincronização automática (baseada em intervalo)

​Sincronização manual

​Executando em Serverless

​Exemplo de PostgreSQL

​Exemplo de MySQL

​Exemplo de ClickHouse

​Opções do Construtor

​Informações importantes

​Atualização da versão 0.x

​Recursos adicionais

GitHub Repository

npm Package

O que você pode sincronizar?

Suporte a Banco de Dados

Primeiros passos

Usando o CLI

Executando o CLI

Argumentos do CLI

Usando no seu código

Sincronização automática (baseada em intervalo)

Sincronização manual

Executando em Serverless

Exemplo de PostgreSQL

Exemplo de MySQL

Exemplo de ClickHouse

Opções do Construtor

Informações importantes

Atualização da versão 0.x

Recursos adicionais