# Stripe Revenue Sync

:::tip Disponible
Esta integración está activa y lista para usar en todos los planes Pro.
:::

Importa automáticamente tus cobros de Stripe como facturas registradas en Frihet. Ideal para negocios SaaS que cobran con Stripe y necesitan llevar su facturación en orden.

## ¿Para qué sirve?

Si cobras con Stripe y quieres que esos cobros aparezcan como facturas en Frihet sin crearlas a mano:

- **Importación automática** — Cada factura pagada en Stripe se convierte en una factura en Frihet
- **Sincronización incremental** — Solo importa cobros nuevos desde la última sincronización
- **Deduplicación** — Nunca se duplica una factura aunque ejecutes la importación varias veces
- **VeriFactu compatible** — Las facturas importadas pasan por la cadena de hash y numeración gap-free

## Diferencia con la integración de Stripe

|                 | Stripe (OAuth)                  | Stripe Revenue Sync                  |
| --------------- | ------------------------------- | ------------------------------------ |
| **Conexión**    | OAuth (redirigir a Stripe)      | API Key restringida                  |
| **Dirección**   | Bidireccional                   | Solo Stripe → Frihet                 |
| **Tipo**        | Pagos + suscripciones + Connect | Solo facturas pagadas                |
| **Facturas**    | Automática por webhook          | Importación bajo demanda + auto-sync |
| **Caso de uso** | Cobrar desde Frihet             | Registrar cobros de Stripe en Frihet |

**Usa Revenue Sync si:** cobras directamente desde Stripe (Dashboard, Billing, etc.) y quieres que esos cobros aparezcan en Frihet para tu contabilidad y declaraciones.

## Requisitos

- **Cuenta Stripe activa** — [Crea una en stripe.com](https://stripe.com)
- **API Key restringida** — Con permisos de solo lectura en invoices y customers
- **Frihet Pro o superior** — No disponible en plan Free

## Configurar Stripe Revenue Sync

### Paso 1: Crea una API Key restringida en Stripe

1. Ve a [Stripe Dashboard → Developers → API Keys](https://dashboard.stripe.com/apikeys)
2. Haz clic en **Create restricted key**
3. Nombre: `Frihet Revenue Sync`
4. Permisos necesarios:
   - **Invoices** → Read
   - **Customers** → Read
5. Copia la clave (`rk_live_...`)

### Paso 2: Conecta en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Stripe Revenue Sync**
3. Haz clic en **Conectar**
4. Pega tu API Key restringida
5. Selecciona la fecha desde la que quieres importar
6. Haz clic en **Guardar y conectar**

### Paso 3: Importa facturas

1. Haz clic en **Importar ahora**
2. Frihet consultará las facturas pagadas en Stripe desde la fecha seleccionada
3. Cada factura se crea como borrador y se marca como pagada
4. La numeración gap-free y el hash VeriFactu se aplican automáticamente

### Paso 4: Activa auto-sync (opcional)

1. En la pestaña de configuración, activa **Auto-sync**
2. Frihet importará nuevos cobros automáticamente cada 6 horas
3. Solo se importan facturas nuevas (sincronización incremental)

## Cómo funciona

### Importación manual

1. Pulsas **Importar ahora**
2. Frihet consulta `GET /v1/invoices?status=paid` en Stripe
3. Para cada factura que no exista ya en Frihet (por `stripeInvoiceId`):
   - Crea una factura borrador con los datos del cliente
   - La marca como pagada
   - Se ejecutan los procesos de servidor: numeración y hash VeriFactu
4. Resultado: facturas listas para tu libro registro y declaraciones

### Auto-sync (cada 6 horas)

1. Cada 6 horas se ejecuta una función programada
2. Consulta solo facturas desde `lastSync` (incremental)
3. Importa las nuevas automáticamente
4. Actualiza `lastSync` con la fecha actual
5. Si detecta que tu API Key ha expirado, marca la integración como `requiresReconnect`

### Deduplicación

Cada factura importada guarda el ID de factura de Stripe (`stripeInvoiceId`) en sus metadatos. Si intentas importar la misma factura dos veces, Frihet la ignora automáticamente.

### Mapeo de datos

| Stripe                                     | Frihet                       |
| ------------------------------------------ | ---------------------------- |
| `invoice.customer_name` o `customer_email` | Nombre del cliente           |
| `invoice.number`                           | Referencia (en concepto)     |
| `line_items[].description`                 | Líneas de la factura         |
| `line_items[].amount`                      | Importe por línea            |
| `invoice.tax`                              | Impuestos (si aplica)        |
| `invoice.created`                          | Fecha de factura             |
| `invoice.id`                               | `stripeInvoiceId` (metadato) |

## Seguridad

- **API Key restringida** — Solo lectura de invoices y customers. Sin acceso a dinero.
- **Encriptación AES-256-GCM** — Tu API Key se almacena cifrada en el servidor
- **Desconexión instantánea** — Revoca acceso en Ajustes cuando quieras
- **Sin datos en tránsito** — La comunicación con Stripe es HTTPS, la clave nunca se expone al frontend

## Desconectar

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Stripe Revenue Sync**
3. Haz clic en **Desconectar**
4. Confirma la acción

Las facturas ya importadas permanecen en Frihet. No se borran al desconectar.

## Troubleshooting

### "No se importaron facturas"

- Verifica que tu API Key tiene permisos de lectura en **Invoices** y **Customers**
- Asegúrate de que la fecha de importación es anterior a tus cobros
- Solo se importan facturas con estado `paid` en Stripe
- Revisa que no estés en modo test de Stripe (usa claves live)

### "Reconecta tu cuenta"

- Tu API Key ha expirado o ha sido revocada
- Ve a Stripe Dashboard → API Keys y crea una nueva
- Desconecta y reconecta en Frihet con la nueva clave

### "Factura duplicada"

- No debería pasar. La deduplicación por `stripeInvoiceId` lo previene
- Si ves duplicados, contacta soporte

### "Los importes no coinciden"

- Frihet importa el importe tal como lo reporta Stripe
- Las comisiones de Stripe no se deducen de la factura (son un gasto separado)
- Verifica la divisa: Stripe reporta en centavos, Frihet convierte automáticamente

## Próximos pasos

- [Usa Stripe para cobrar directamente](./stripe)
- [Configura links de pago con Stripe Connect](./stripe-connect)
- [Conecta también WooCommerce si tienes tienda](./woocommerce)

---

**Siguiente:** [Stripe Connect - Links de pago en tus facturas](./stripe-connect)