Saltar al contenido principal

Stripe Revenue Sync

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ónOAuth (redirigir a Stripe)API Key restringida
DirecciónBidireccionalSolo Stripe → Frihet
TipoPagos + suscripciones + ConnectSolo facturas pagadas
FacturasAutomática por webhookImportación bajo demanda + auto-sync
Caso de usoCobrar desde FrihetRegistrar 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
  • 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
  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 triggers de Firestore: 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​

StripeFrihet
invoice.customer_name o customer_emailNombre del cliente
invoice.numberReferencia (en concepto)
line_items[].descriptionLíneas de la factura
line_items[].amountImporte por línea
invoice.taxImpuestos (si aplica)
invoice.createdFecha de factura
invoice.idstripeInvoiceId (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​

Siguiente: Stripe Connect - Links de pago en tus facturas