> ## 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.

# Sincroniza con tu Base de Datos

> Sincroniza automáticamente los datos de Dodo Payments con tu propia base de datos para análisis, informes e integraciones.

Dodo Payments proporciona una función de sincronización de base de datos integrada que sincroniza automáticamente tus datos de pago con tu propia base de datos. Puedes sincronizar **pagos**, **clientes**, **suscripciones** y **licencias** para mantener una copia local de tus datos para análisis, informes o integración con otros sistemas.

<Info>
  **Implementation**: Disponible a través del [paquete npm](https://www.npmjs.com/package/dodo-sync) | **Source Code**: [GitHub](https://github.com/dodopayments/dodo-sync)
</Info>

## ¿Qué Puedes Sincronizar?

Nuestra función de sincronización de base de datos admite la sincronización de las siguientes entidades de Dodo Payments a tu base de datos:

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card">
    Sincroniza todas las transacciones de pago, incluyendo pagos únicos, reembolsos y actualizaciones de estado del pago.
  </Card>

  <Card title="Customers" icon="users">
    Mantén sincronizados los datos de tus clientes, incluyendo perfiles de cliente, información de contacto y metadatos.
  </Card>

  <Card title="Subscriptions" icon="repeat">
    Sincroniza datos de suscripciones, incluyendo suscripciones activas, ciclos de facturación y cambios de estado de suscripción.
  </Card>

  <Card title="Licenses" icon="key">
    Sincroniza la información de licencias, incluyendo claves de licencia, activaciones y actualizaciones de estado de licencia.
  </Card>
</CardGroup>

Puedes sincronizar cualquier combinación de estas entidades especificándolas en el parámetro `scopes`. Todas las operaciones de sincronización son incrementales y solo transfieren registros nuevos o actualizados para un rendimiento óptimo.

## Soporte de Base de Datos

Actualmente soportamos **MongoDB**, **PostgreSQL**, **MySQL** y **ClickHouse**.

Estamos trabajando activamente en expandir el soporte para:

* **Bases de Datos**: Snowflake y otras.
* **Pipelines**: Pipelines ETL, sincronización en tiempo real.

<Tip>
  Estamos ampliando continuamente el soporte de bases de datos. Si deseas contribuir con una nueva integración de base de datos, envía un pull request a nuestro [repositorio de GitHub](https://github.com/dodopayments/dodo-sync).
</Tip>

## Comenzando

Puedes usar nuestra función de sincronización de base de datos a través de la **CLI** o programáticamente en tu **código**. Ambos métodos proporcionan la misma funcionalidad; elige el que mejor se adapte a tu flujo de trabajo.

### Usando la CLI

La herramienta CLI proporciona una forma rápida de configurar y ejecutar la sincronización de base de datos. Instálala globalmente para usarla desde cualquier lugar en tu terminal:

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

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

#### Ejecutando la CLI

La CLI admite dos modos: **Modo Interactivo** para configuración guiada, y **Modo Manual** para configuración directa.

**Modo Interactivo**: Simplemente ejecuta el comando sin argumentos para iniciar el asistente de configuración interactivo.

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

**Modo Manual**: Pasa argumentos directamente para omitir el asistente.

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

**Ejemplos:**

```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 de la CLI

<ParamField path="--interval" type="number" alias="-i">
  Intervalo de sincronización en segundos. Determina con qué frecuencia se ejecuta la operación de sincronización. Si no se proporciona, la sincronización se ejecutará una sola vez y finalizará.
</ParamField>

<ParamField path="--database" type="string" alias="-d" required>
  Tipo de base de datos a usar. Valores compatibles: `"mongodb"`, `"postgres"`, `"mysql"` o `"clickhouse"`.
</ParamField>

<ParamField path="--database-uri" type="string" alias="-u" required>
  URI de conexión para tu base de datos:

  * **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`
</ParamField>

<ParamField path="--scopes" type="string" required>
  Lista separada por comas de entidades de datos para sincronizar. Ámbitos disponibles: `licences`, `payments`, `customers`, `subscriptions`. Ejemplo: `"payments,customers"`.
</ParamField>

<ParamField path="--api-key" type="string" required>
  Tu clave de API de Dodo Payments. Debe comenzar con `dp_live_` para modo en vivo o `dp_test_` para modo de prueba.
</ParamField>

<ParamField path="--env" type="string" required>
  Objetivo del entorno. Debe ser `"live_mode"` o `"test_mode"`. Esto determina de qué entorno de Dodo Payments se sincroniza.
</ParamField>

<ParamField path="--rate-limit" type="number" alias="--rl">
  Límite de solicitudes por segundo. Controla la velocidad a la que el motor de sincronización realiza solicitudes a la API para evitar saturar la API de Dodo Payments.
</ParamField>

### Usando en Tu Código

Para control programático, integra la función de sincronización directamente en tu aplicación. Instálala como una dependencia en tu proyecto:

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

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

#### Sincronización Automática (Basada en Intervalo)

Usa la sincronización automática cuando desees que la sincronización se ejecute continuamente a 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>
  La opción `interval` es obligatoria cuando se utiliza `.start()` para la sincronización automática. La sincronización se ejecutará continuamente en el intervalo especificado hasta que se detenga el proceso.
</Tip>

#### Sincronización Manual

Usa la sincronización manual cuando desees activar operaciones de sincronización bajo demanda (por ejemplo, desde un trabajo cron o un 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>
  Al usar sincronización manual, la opción `interval` no es obligatoria. Puedes llamar a `.run()` siempre que necesites realizar una operación de sincronización.
</Tip>

#### Ejemplo de PostgreSQL

Esta es la forma de usar `dodo-sync` con 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();
```

#### Ejemplo de MySQL

Esta es la forma de usar `dodo-sync` con 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();
```

#### Ejemplo de ClickHouse

Esta es la forma de usar `dodo-sync` con 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();
```

#### Opciones del Constructor

<ParamField body="database" type="string" required>
  Nombre de la base de datos a usar. Valores compatibles: `"mongodb"`, `"postgres"`, `"mysql"` o `"clickhouse"`.
</ParamField>

<ParamField body="databaseURI" type="string" required>
  Cadena de conexión para tu base de datos:

  * **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`
</ParamField>

<ParamField body="scopes" type="string[]" required>
  Arreglo de entidades para sincronizar. Opciones disponibles: `"licences"`, `"payments"`, `"customers"`, `"subscriptions"`. Puedes incluir cualquier combinación de estas.
</ParamField>

<ParamField body="dodoPaymentsOptions" type="object" required>
  Configuración de la API de Dodo Payments para autenticación y selección de entorno. Consulta los [tipos del SDK de TypeScript](https://github.com/dodopayments/dodopayments-typescript/blob/main/src/client.ts) para ver las opciones completas.

  **Propiedades requeridas:**

  * `bearerToken`: Tu clave de API de Dodo Payments
  * `environment`: `"test_mode"` o `"live_mode"`
</ParamField>

<ParamField body="interval" type="number">
  Tiempo en segundos entre sincronizaciones automáticas. Requerido cuando se utiliza `.start()` para sincronización automática. Opcional cuando se usa `.run()` para sincronización manual.
</ParamField>

<ParamField body="rateLimit" type="number">
  Número de solicitudes por segundo. Controla la velocidad a la que el motor de sincronización realiza solicitudes a la API para evitar saturar la API de Dodo Payments.
</ParamField>

## Información Importante

<Warning>
  **MongoDB**: Se creará automáticamente una base de datos llamada `dodopayments_sync` en tu servidor de base de datos. Todos los datos de sincronización se almacenarán allí. Este nombre de base de datos está actualmente fijo y no se puede cambiar.

  **PostgreSQL**: Se crearán tablas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) en la base de datos especificada en tu URI de conexión. Los datos se almacenan como JSONB.

  **MySQL**: Se crearán tablas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) en la base de datos especificada en tu URI de conexión. Los datos se almacenan como JSON.

  **ClickHouse**: Se crearán tablas (`Subscriptions`, `Payments`, `Licenses`, `Customers`) usando el motor ReplacingMergeTree. Al consultar, utiliza la palabra clave `FINAL` para garantizar resultados deduplicados.
</Warning>

<Info>
  El motor de sincronización rastrea los cambios y solo sincroniza registros nuevos o actualizados, lo que hace que las sincronizaciones posteriores sean eficientes incluso con conjuntos de datos grandes.
</Info>

## Recursos Adicionales

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodo-sync">
    Ver código fuente, reportar problemas o contribuir mejoras
  </Card>

  <Card title="npm Package" icon="box-open" href="https://www.npmjs.com/package/dodo-sync">
    Ver detalles del paquete e instrucciones de instalación
  </Card>
</CardGroup>