> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronize com seu Banco de Dados

> Sincronize automaticamente seus dados de Dodo Payments com seu próprio banco de dados para análises, relatórios e integrações.

Dodo Payments fornece um recurso de sincronização de banco de dados embutido que sincroniza automaticamente seus dados de pagamento com seu próprio banco de dados. Você pode sincronizar **pagamentos**, **clientes**, **assinaturas** e **licenças** para manter uma cópia local de seus dados para análises, relatórios ou integração com outros sistemas.

<Info>
  **Implementação**: Disponível via [pacote npm](https://www.npmjs.com/package/dodo-sync) | **Código-fonte**: [GitHub](https://github.com/dodopayments/dodo-sync)
</Info>

## O que você pode sincronizar?

Nosso recurso de sincronização de banco de dados suporta a sincronização das seguintes entidades do Dodo Payments para seu banco de dados:

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card">
    Sincronize todas as transações de pagamento, incluindo pagamentos únicos, reembolsos e atualizações de status de pagamento.
  </Card>

  <Card title="Customers" icon="users">
    Mantenha os dados dos clientes sincronizados, incluindo perfis, informações de contato e metadados.
  </Card>

  <Card title="Subscriptions" icon="repeat">
    Sincronize os dados de assinaturas, incluindo assinaturas ativas, ciclos de cobrança e alterações de status das assinaturas.
  </Card>

  <Card title="Licenses" icon="key">
    Sincronize informações de licença, incluindo chaves de licença, ativações e atualizações de status da licença.
  </Card>
</CardGroup>

Você pode sincronizar qualquer combinação dessas entidades especificando-as no parâmetro `scopes`. Todas as operações de sincronização são incrementais e transferem apenas registros novos ou atualizados para desempenho ideal.

## Suporte a Banco de Dados

Atualmente, suportamos **MongoDB**, **PostgreSQL**, **MySQL** e **ClickHouse**.

Estamos trabalhando ativamente para expandir o suporte para:

* **Bancos de Dados**: Snowflake e outros.
* **Pipelines**: Pipelines ETL, sincronização em tempo real.

<Tip>
  Estamos expandindo continuamente o suporte a bancos de dados. Se quiser contribuir com uma nova integração de banco de dados, envie um Pull Request para o nosso [repositório no GitHub](https://github.com/dodopayments/dodo-sync).
</Tip>

## Começando

Você pode usar nosso recurso de sincronização de banco de dados via **CLI** ou programaticamente em seu **código**. Ambos os métodos fornecem a mesma funcionalidade—escolha o que melhor se adapta ao seu fluxo de trabalho.

### Usando a CLI

A ferramenta CLI fornece uma maneira rápida de configurar e executar a sincronização de banco de dados. Instale-a globalmente para usá-la de qualquer lugar em seu terminal:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g dodo-sync
  ```

  ```bash bun theme={null}
  bun add -g dodo-sync
  ```
</CodeGroup>

#### Executando a CLI

A CLI suporta dois modos: **Modo Interativo** para configuração guiada, e **Modo Manual** para configuração direta.

**Modo Interativo**: Basta executar o comando sem argumentos para iniciar o assistente de configuração interativa.

```bash theme={null}
dodo-sync
```

**Modo Manual**: Passe argumentos diretamente para pular o assistente.

```bash theme={null}
dodo-sync -i [interval] -d [database] -u [database_uri] --scopes [scopes] --api-key [api_key] --env [environment]
```

**Exemplos:**

```bash theme={null}
# 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 da CLI

<ParamField path="--interval" type="number" alias="-i">
  Intervalo de sincronização em segundos. Determina com que frequência a operação de sincronização é executada. Se não for fornecido, a sincronização será executada apenas uma vez e encerrada.
</ParamField>

<ParamField path="--database" type="string" alias="-d" required>
  Tipo de banco de dados a ser usado. Valores suportados: `"mongodb"`, `"postgres"`, `"mysql"` ou `"clickhouse"`.
</ParamField>

<ParamField path="--database-uri" type="string" alias="-u" required>
  URI de conexão para o 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`
</ParamField>

<ParamField path="--scopes" type="string" required>
  Lista separada por vírgulas das entidades de dados a sincronizar. Escopos disponíveis: `licences`, `payments`, `customers`, `subscriptions`. Exemplo: `"payments,customers"`.
</ParamField>

<ParamField path="--api-key" type="string" required>
  Sua chave de API da Dodo Payments. Deve começar com `dp_live_` para modo ao vivo ou `dp_test_` para modo de teste.
</ParamField>

<ParamField path="--env" type="string" required>
  Destino do ambiente. Deve ser `"live_mode"` ou `"test_mode"`. Isso determina de qual ambiente da Dodo Payments será feita a sincronização.
</ParamField>

<ParamField path="--rate-limit" type="number" alias="--rl">
  Limite de taxa em requisições por segundo. Controla a velocidade com que o mecanismo de sincronização faz chamadas à API da Dodo Payments para evitar sobrecarregá-la.
</ParamField>

### Usando em Seu Código

Para controle programático, integre o recurso de sincronização diretamente em sua aplicação. Instale-o como uma dependência em seu projeto:

<CodeGroup>
  ```bash npm theme={null}
  npm install dodo-sync
  ```

  ```bash bun theme={null}
  bun add dodo-sync
  ```
</CodeGroup>

#### Sincronização Automática (Baseada em Intervalo)

Use a sincronização automática quando quiser que a sincronização ocorra continuamente em intervalos regulares:

```typescript theme={null}
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();
```

<Tip>
  A opção `interval` é obrigatória ao usar `.start()` para sincronização automática. A sincronização será executada continuamente no intervalo especificado até que o processo seja interrompido.
</Tip>

#### Sincronização Manual

Use a sincronização manual quando quiser acionar operações de sincronização sob demanda (por exemplo, a partir de um cron job ou endpoint de API):

```typescript theme={null}
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();
```

<Tip>
  Ao usar sincronização manual, a opção `interval` não é obrigatória. Você pode chamar `.run()` sempre que precisar executar uma operação de sincronização.
</Tip>

#### Exemplo de PostgreSQL

Veja como usar `dodo-sync` com PostgreSQL:

```typescript theme={null}
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

Veja como usar `dodo-sync` com MySQL:

```typescript theme={null}
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

Veja como usar `dodo-sync` com ClickHouse:

```typescript theme={null}
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

<ParamField body="database" type="string" required>
  Nome do banco de dados a ser usado. Valores suportados: `"mongodb"`, `"postgres"`, `"mysql"` ou `"clickhouse"`.
</ParamField>

<ParamField body="databaseURI" type="string" required>
  String de conexão para o 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`
</ParamField>

<ParamField body="scopes" type="string[]" required>
  Array de entidades a sincronizar. Opções disponíveis: `"licences"`, `"payments"`, `"customers"`, `"subscriptions"`. Você pode incluir qualquer combinação delas.
</ParamField>

<ParamField body="dodoPaymentsOptions" type="object" required>
  Configuração da API da Dodo Payments para autenticação e seleção de ambiente. Consulte os [tipos do SDK TypeScript](https://github.com/dodopayments/dodopayments-typescript/blob/main/src/client.ts) para obter as opções completas.

  **Propriedades obrigatórias:**

  * `bearerToken`: Sua chave de API da Dodo Payments
  * `environment`: `"test_mode"` ou `"live_mode"`
</ParamField>

<ParamField body="interval" type="number">
  Tempo em segundos entre sincronizações automáticas. Obrigatório ao usar `.start()` para sincronização automática. Opcional ao usar `.run()` para sincronização manual.
</ParamField>

<ParamField body="rateLimit" type="number">
  Número de requisições por segundo. Controla a rapidez com que o mecanismo de sincronização faz chamadas à API da Dodo Payments para evitar sobrecarregá-la.
</ParamField>

## Informações Importantes

<Warning>
  **MongoDB**: Um banco de dados chamado `dodopayments_sync` será criado automaticamente no seu servidor de banco de dados. Todos os dados de sincronização serão armazenados lá. Esse nome de banco de dados é fixo e não pode ser alterado.

  **PostgreSQL**: Tabelas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) serão criadas no banco de dados especificado na sua URI de conexão. Os dados são armazenados como JSONB.

  **MySQL**: Tabelas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) serão criadas no banco de dados especificado na sua URI de conexão. Os dados são armazenados como JSON.

  **ClickHouse**: Tabelas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) serão criadas usando o mecanismo ReplacingMergeTree. Ao consultar, use a palavra-chave `FINAL` para garantir resultados deduplicados.
</Warning>

<Info>
  O mecanismo de sincronização rastreia mudanças e sincroniza apenas registros novos ou atualizados, tornando sincronizações subsequentes eficientes mesmo com grandes conjuntos de dados.
</Info>

## Recursos Adicionais

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-sync">
    Veja o código-fonte, reporte problemas ou contribua com melhorias
  </Card>

  <Card title="npm Package" icon="box-open" href="https://www.npmjs.com/package/dodo-sync">
    Veja os detalhes do pacote e as instruções de instalação
  </Card>
</CardGroup>