# Frihet Documentation — Complete Reference
# Generated: 2026-07-07
# Source: https://docs.frihet.io
# Files: 231

---

## Frihet Apps — apps verticales modulares
> Path: /apps

# Frihet Apps

Frihet Apps es el sistema de apps verticales modulares sobre Frihet ERP. Cada app añade un dominio de negocio completo (propiedades, reservas, limpieza, terminales, inventario, etc.) sobre la misma base fiscal, contable y de facturación del core.

## Qué son

Piensa en el ERP como el núcleo — facturación, gastos, impuestos, clientes, banca — y las Apps como extensiones verticales que añaden un flujo completo para un sector concreto. Si tienes alojamientos turísticos, activas **Stay** y tu ERP empieza a hablar de propiedades, reservas, partes de viajeros y check-ins. Si tienes un bar o una tienda, activas **POS** y aparecen terminales, ventas y cierres de caja.

Todas las apps comparten el mismo motor fiscal del ERP: VeriFactu, factura electrónica, IVA/IGIC, modelos fiscales, plan contable, contabilidad automática. No duplicamos nada — Stay factura a través del mismo sistema que ya conoces.

## Apps disponibles

### Frihet Stay — PMS para alojamientos turísticos

Sistema completo de gestión para alquileres vacacionales, casas rurales y hoteles boutique.

- **Estado:** próximamente (beta cerrada en preparación)
- **Precio:** 19 €/mes base + 2 €/propiedad adicional (5 incluidas), 14 días de prueba, 0 % de comisión sobre reservas
- **Cumplimiento:** VeriFactu, IGIC, SES.HOSPEDAJES, Impuesto Turístico Canario, Modelo 179

[Ver documentación de Stay →](/stay/)

### Frihet POS — punto de venta para restauración y retail

TPV de tarifa plana sin comisiones por transacción.

- **Estado:** próximamente
- **Precio:** 25 €/mes por terminal, 30 días de prueba, 0 % transaccional, hardware-agnóstico

### Hospitality Suite — paquete de hospitalidad

Pack que combina Frihet ERP Pro + Stay + POS con un 19 % de descuento sobre el precio à la carte.

- **Estado:** planificado
- **Precio:** 59 €/mes (nivel hero para hoteles boutique y casas de huéspedes)

## Cómo se activan

Todas las apps se gestionan desde **Ajustes → Apps** en tu cuenta de Frihet ERP. Cada app muestra su estado (inactiva, prueba, activa, gracia), el plan incluido, el trial disponible y los controles de suscripción.

La facturación de las apps viaja por la misma suscripción Stripe que tu plan ERP: un único recibo mensual con las unidades medidas (propiedades en Stay, terminales en POS) y las tarifas aplicadas.

## Seguridad y aislamiento

- Cada app corre aislada dentro de tu cuenta: sus datos quedan separados del resto y solo tu workspace puede leerlos.
- El acceso se verifica en el servidor: ninguna app es accesible si no está activa o en periodo de prueba.
- Toda la infraestructura está alojada en la UE.
- La activación, el periodo de prueba y la facturación de cada app se gestionan de forma centralizada desde **Ajustes → Apps**.

## Preguntas frecuentes

**¿Tengo que pagar Pro del ERP para usar una App?**
Sí. Las apps son add-ons sobre el plan Pro o superior. El plan Premium incluye descuento en apps.

**¿Puedo probar una app sin tarjeta?**
Las apps tienen periodo de prueba gratuito (14 días Stay, 30 días POS). Al finalizar, o pasas a suscripción activa o el acceso entra en periodo de gracia de 90 días antes del archivado definitivo.

**¿Qué pasa con mis datos si desactivo una app?**
Entras en periodo de gracia de 90 días durante los cuales puedes reactivar sin perder nada. Tras el grace, los datos pasan por un proceso GDPR de archivado cifrado (6 años de retención fiscal) y borrado definitivo. Siempre puedes exportar todo tu contenido antes — derecho de acceso garantizado.

**¿Dónde viven mis datos?**
Tus datos se almacenan de forma segura en la UE, aislados dentro del workspace de tu cuenta y accesibles solo por ti y los miembros que invites.

---

## Frihet Kitchen
> Path: /apps/kitchen

# Frihet Kitchen

Frihet Kitchen es la app vertical de hostelería sobre Frihet ERP. Combina un KDS (Kitchen Display System) con un backend de restauración que orquesta pedidos, estaciones de cocina, impresión cloud, ingesta de pedidos de agregadores (Glovo, Uber Eats, Deliveroo) y notificaciones a clientes vía WhatsApp.

## Cómo funciona

Cada local de hostelería conecta su flujo de pedidos a Kitchen a través del POS, de la integración con agregadores o de la introducción manual desde la propia app. Los pedidos se reparten automáticamente entre estaciones de cocina (parrilla, fría, bebidas, postres) según las reglas que definas. El KDS muestra a cada estación únicamente los items que le corresponden, con un flujo claro de preparación: pendiente → en preparación → listo.

La facturación de cada pedido viaja por el motor fiscal del ERP. Las ventas generan tickets simplificados (B2C) o facturas completas (B2B), aplican IVA o IGIC según la zona, y se reportan a VeriFactu de forma transparente. No hay duplicidad de datos: el cierre de caja del local entra directo al libro registro del ERP.

La impresión de tickets en cocina y barra usa una capa cloud que envía los documentos a impresoras térmicas conectadas al local. Si un cliente ha dejado su número de teléfono al pedir, el sistema le manda una notificación WhatsApp cuando el pedido está listo para recoger o cuando se actualiza el estado.

Los agregadores como Glovo o Uber Eats sincronizan pedidos hacia Kitchen mediante webhooks o conectores nativos. Esto evita tener que reescribir cada pedido en el TPV manualmente y centraliza el control de stock y precios.

## Configuración

Activa la app desde **Configuración → Apps → Kitchen** en tu cuenta de Frihet ERP. La app está integrada con [Frihet POS](./pos) — si gestionas restauración, normalmente activarás ambas. La activación incluye un periodo de prueba antes de pasar al plan suscrito.

Las estaciones de cocina, impresoras y reglas de enrutado de items se configuran desde el panel propio de Kitchen tras la activación. Las integraciones con agregadores y la conexión Stripe Terminal (cuando se use para cobro en mesa) se gestionan desde el catálogo de integraciones del ERP.

<!-- TODO: confirm with Viktor — disponibilidad pública (gated trial, beta cerrada o GA) y precio exacto Kitchen -->

## Ver también

- [Frihet POS](./pos)
- [Apps Frihet](/apps)
- [Cumplimiento fiscal](../cumplimiento/verifactu)

---

## Frihet POS
> Path: /apps/pos

# Frihet POS

Frihet POS es la app vertical de punto de venta de Frihet ERP. Está pensada para restauración y retail, con tarifa plana mensual por terminal, sin comisiones sobre transacciones y cumplimiento fiscal nativo VeriFactu (Península) e IGIC (Canarias) desde el primer ticket.

## Cómo funciona

Cada terminal POS es un dispositivo activo en tu cuenta — tablet, ordenador o lector Stripe Terminal — desde el que vendes a clientes presenciales. El flujo es directo: el cajero selecciona productos del catálogo, aplica descuentos o cupones si procede, cobra al cliente (efectivo, tarjeta, transferencia) y emite el ticket o factura simplificada en el acto.

La facturación viaja por el motor fiscal del ERP. Cada venta genera un documento conforme a la normativa aplicable: ticket simplificado con NIF opcional, factura completa si el cliente lo pide, reporte automático a VeriFactu o emisión IGIC en Canarias. El tratamiento del IVA/IGIC se aplica según la zona fiscal de tu negocio sin configuración extra.

Las sesiones de caja agrupan ventas, devoluciones y movimientos en efectivo por turno. Al cierre, la caja se concilia con el efectivo contado y los pagos digitales, generando un asiento contable automático. Las devoluciones quedan trazadas con el ticket original para auditoría.

Si conectas un lector Stripe Terminal compatible, el POS lo usa para cobros con tarjeta presencial sin necesidad de hardware propietario. El catálogo de productos es el mismo del ERP — añades, editas o quitas referencias desde el módulo Productos y se reflejan al instante en el TPV.

## Configuración

Activa la app desde **Configuración → Apps → POS** en tu cuenta Frihet ERP. La activación incluye un periodo de prueba antes de pasar al plan suscrito. La tarifa es plana por terminal activa al mes, sin comisión adicional sobre transacciones.

Cada terminal se vincula desde el dispositivo final iniciando sesión con la cuenta del cajero correspondiente. Los cajeros se gestionan como miembros del equipo desde [Invitar miembros](../equipo/invitar-miembros) con el rol adecuado para POS.

Para hostelería, normalmente activarás [Frihet Kitchen](./kitchen) junto al POS para orquestar pedidos y estaciones de cocina.

## Ver también

- [Apps Frihet](/apps)
- [Frihet Kitchen](./kitchen)
- [Catálogo de productos](../productos/catalogo)
- [Cumplimiento VeriFactu](../cumplimiento/verifactu)
- [IGIC en Canarias](../cumplimiento/igic-canarias)

---

## Personas de contacto
> Path: /clientes/contactos-persona

# Personas de contacto

Cuando trabajas con una empresa, sueles tratar con varias personas: contabilidad, dirección, técnico. Frihet permite registrar cada persona de contacto por separado dentro de la ficha del cliente.

## Añadir persona

Abre el detalle de un cliente y ve al tab **Personas** → haz clic en **Añadir persona**.

## Campos disponibles

| Campo | Obligatorio | Ejemplo |
|-------|:-----------:|---------|
| Nombre | Sí | María García |
| Email | No | maria@acme.com |
| Teléfono | No | +34 922 123 456 |
| Cargo | No | Directora financiera |

## Editar y eliminar

Pasa el cursor sobre la persona → aparecen los iconos de **editar** y **eliminar**.

## Uso práctico

- Identifica quién es el interlocutor principal de cada cliente.
- Registra datos de contacto que no van en la ficha fiscal del cliente.
- Útil cuando la persona de facturación es diferente a la persona de decisión.

---

## Detalle de cliente
> Path: /clientes/detalle-cliente

# Detalle de cliente

Al hacer clic en cualquier cliente desde la lista, se abre su ficha completa en `/contacts/:id`. Desde aquí gestionas toda la relación comercial con ese cliente.

## Cabecera

La parte superior muestra los datos principales del cliente:

- **Nombre** (empresa o persona)
- **NIF/CIF**
- **Email**, **teléfono**, **web**
- **Dirección completa**

Junto a los datos, cuatro tarjetas de resumen:

| Tarjeta | Qué muestra |
|---------|-------------|
| **Facturado** | Importe total facturado al cliente |
| **Pendiente** | Saldo pendiente de cobro |
| **Facturas** | Número total de facturas emitidas |
| **Desde** | Fecha de la primera factura (antigüedad) |

Haz clic en **Editar** para modificar los datos del cliente.

## Pipeline (estado del cliente)

Cada cliente tiene un estado dentro de tu pipeline comercial. Haz clic en el estado para cambiarlo.

| Estado | Descripción |
|--------|-------------|
| **Lead** | Contacto nuevo, aún no cualificado |
| **Contactado** | Has iniciado conversación |
| **Propuesta** | Has enviado presupuesto o propuesta |
| **Activo** | Cliente con relación comercial activa |
| **Inactivo** | Cliente sin actividad reciente |
| **Perdido** | Oportunidad cerrada sin éxito |

El pipeline te permite visualizar en qué fase se encuentra cada relación comercial y priorizar seguimiento.

## Pestaña Actividad

Muestra un timeline cronológico con todo lo que ha ocurrido con el cliente:

- **Actividad automática**: facturas creadas, enviadas y cobradas; presupuestos enviados; gastos vinculados.
- **Actividad manual**: llamadas, reuniones y otros eventos que registres tú.

Las entradas se agrupan por fecha. Para registrar actividad manualmente, haz clic en **+ Actividad** y selecciona el tipo (llamada, reunión, email, otro).

## Pestaña Notas

Notas internas sobre el cliente. Solo visibles para ti y tu equipo, nunca para el cliente.

- Haz clic en **+ Nota** para crear una nueva.
- Cada nota muestra autor y fecha de creación.
- Puedes editar o eliminar notas existentes.
- **Cmd+Enter** (Mac) o **Ctrl+Enter** (Windows) para guardar rápidamente.

Útiles para registrar acuerdos verbales, contexto de negociación o recordatorios.

## Pestaña Personas

Contactos individuales asociados a la empresa. Cada persona incluye:

- **Nombre**
- **Email**
- **Teléfono**
- **Cargo**

Ideal para empresas con varios interlocutores (director comercial, administración, técnico). Haz clic en **+ Persona** para añadir un contacto.

## Pestaña Documentos

Lista de facturas y presupuestos vinculados al cliente, filtrados automáticamente. Desde aquí puedes:

- Ver el estado de cada documento (borrador, enviada, cobrada, vencida).
- Abrir cualquier factura o presupuesto directamente.
- Crear una nueva factura o presupuesto para este cliente (datos pre-rellenados).

## Atajos de teclado

Navega por la ficha del cliente sin tocar el ratón:

| Atajo | Acción |
|-------|--------|
| **Esc** | Volver a la lista de clientes |
| **a** | Ir a pestaña Actividad |
| **n** | Ir a pestaña Notas |
| **p** | Ir a pestaña Personas |
| **d** | Ir a pestaña Documentos |
| **e** | Editar datos del cliente |

---

## Gestion de clientes
> Path: /clientes/gestion-clientes

# Gestión de clientes

Mantén un registro centralizado de todos tus clientes con sus datos fiscales y contacto. Frihet vincula automáticamente cada cliente a sus facturas, presupuestos y cobros.

## Crear cliente

### Paso 1: Accede al registro de clientes

Ve a **Clientes > Nuevo cliente** o desde dashboard haz clic en el botón **+ Cliente**.

### Paso 2: Datos generales

Llena la información básica:

- **Nombre**: Nombre del cliente (empresa o persona)
- **Tipo**: Elige **Empresa** o **Persona física**

### Paso 3: Identificación fiscal

Según el tipo de cliente:

**Para empresas:**
- **CIF**: Código de Identificación Fiscal (ej: A12345678)
- **Razón social**: Nombre oficial registrado

Frihet valida el formato del CIF automáticamente.

**Para personas físicas:**
- **NIF**: Número de Identificación Fiscal (ej: 12345678A)
- **Nombre completo**: Apellidos y nombre

Frihet valida que sea NIF válido (algoritmo DNI/NIE).

### Paso 4: Ubicación

- **País**: España por defecto (configurable)
- **Región**: Comunidad autónoma (afecta a IGIC en Canarias)
- **Ciudad**
- **Código postal**
- **Dirección**: Domicilio completo

Opcional si el cliente te vende servicios digitales sin dirección requerida.

### Paso 5: Contacto

- **Email**: Principal para envío de facturas y recibos
- **Teléfono**: Número de contacto
- **Sitio web**: URL si aplicable (ej: www.micliente.com)

El email es obligatorio para enviar documentos electrónicamente.

### Paso 6: Condiciones comerciales

Personaliza según acuerdo:

- **Plazo de pago**: 30, 60, 90 días o personalizado
- **Descuento por defecto**: % de descuento automático en nuevas facturas (ej: 5%)
- **Forma de pago preferida**: Transferencia, efectivo, tarjeta, etc.

## Editar cliente

Para cambiar datos de un cliente:

1. Abre **Clientes** y selecciona el cliente
2. Haz clic en **Editar**
3. Modifica los campos necesarios
4. Haz clic en **Guardar**

**Nota**: Los datos fiscales (CIF/NIF) se bloquean tras la primera factura para evitar errores en auditoría. Si necesitas cambiar, contacta con soporte.

## Estadísticas por cliente

En la ficha de cada cliente ves un resumen:

- **Total facturado**: Suma total de todas sus facturas (sin contar devoluciones)
- **Número de facturas**: Cantidad de documentos emitidos
- **Saldo pendiente**: Dinero que aún debe
- **Última transacción**: Cuándo fue la última factura/pago
- **Tasa de pago**: % de facturas pagadas a tiempo

Ejemplo:

```
Cliente: Acme Corp
CIF: A12345678
Total facturado: 15.450 EUR
Facturas: 12
Pendiente: 2.890 EUR
Última factura: 5 feb 2026
Pago a tiempo: 83% (10 de 12)
```

## Vista rápida

Desde la lista de clientes puedes:

- **Filtrar** por tipo (empresas / personas)
- **Buscar** por nombre, CIF o email
- **Ordenar** por total facturado, último contacto, etc.
- **Exportar** lista a CSV

Haz clic en cualquier cliente para ver detalle completo.

## Cliente reciente

Los últimos 5 clientes con los que facturaste aparecen en **Dashboard > Clientes recientes** para acceso rápido.

## Acciones por cliente

Desde la ficha de cliente:

- **Nueva factura**: Crea factura para este cliente (pre-rellena datos)
- **Nuevo presupuesto**: Propuesta de venta
- **Historial de facturas**: Lista de todos los documentos
- **Historial de pagos**: Qué ha pagado y cuándo
- **Contacto directo**: Abre email / llama (si teléfono guardado)
- **Mensaje**: Envía factura o estado de cuenta por email

## Clientes frecuentes vs puntuales

Frihet identifica automáticamente:

- **Cliente recurrente**: 3+ facturas en últimos 6 meses
- **Cliente puntual**: Una sola factura histórica

Los recurrentes aparecen destacados en formularios de factura (aparecen primero en autocompletado).

## Datos sensibles y privacidad

- **Contraseña**: Los clientes pueden acceder a su portal sin contraseña (autenticación por enlace)
- **Datos fiscales**: Almacenados encriptados, accesibles solo a ti y autoridades si auditan
- **Historial**: Disponible para ti indefinidamente (auditoría)

Frihet cumple RGPD. Si un cliente solicita borrado (derecho al olvido), contacta soporte.

## Duplication de clientes

Si accidentalmente creas dos fichas del mismo cliente:

1. Abre el cliente "principal"
2. Ve a **Más acciones > Unir con otro cliente**
3. Selecciona el cliente duplicado
4. Frihet **une todas las facturas** bajo un solo registro
5. Se elimina el registro duplicado

## Integración con portal cliente

Cada cliente tiene acceso a un **Portal de cliente** donde puede ver:

- Sus facturas (emitidas)
- Sus presupuestos (pendientes)
- Estado de pagos
- Descargar documentos

El portal es seguro y accesible vía enlace personalizado (sin crear usuario).

## Detalle del cliente

Al hacer clic en cualquier cliente de la lista, se abre su ficha completa con información financiera, historial de actividad, notas y personas de contacto.

- [Detalle de cliente](./detalle-cliente) — Ficha completa con stats, pipeline y pestañas
- [Notas y actividades](./notas-actividades) — Historial de interacciones y notas internas
- [Personas de contacto](./contactos-persona) — Contactos individuales dentro de la empresa

---

## Importar y exportar
> Path: /clientes/importar-exportar

# Importar y exportar clientes

Transfiere clientes entre sistemas, realiza backup o integra datos desde tus registros anteriores.

## Exportar clientes a CSV

### Descarga simple

1. Ve a **Clientes**
2. Haz clic en **Exportar > CSV**
3. Se descarga archivo `clientes-{fecha}.csv`

El archivo contiene todas las columnas:

```csv
nombre,tipo,cif_nif,email,telefono,ciudad,pais,fecha_creacion
Acme Corp,empresa,A12345678,contacto@acme.com,+34 91 123 45 67,Madrid,ES,2025-11-15
Juan García,persona,12345678A,juan@email.com,+34 666 123 456,Barcelona,ES,2026-01-10
```

### Exportación con filtros

Antes de exportar, aplica filtros:

1. Filtra por **tipo** (empresas / personas)
2. Filtra por **región** o **país**
3. Filtra por **rango de fecha** (clientes nuevos)
4. Luego exporta

Se exportan solo los clientes filtrados.

### Casos de uso

- **Cambio de sistema contable**: Exporta clientes para importar en nuevo software
- **Backup**: Guarda CSV seguro regularmente
- **Facturación manual**: Exporta para hacer correspondencia en Word/Excel
- **Integración**: Envía clientes a herramienta de marketing o CRM

## Importar clientes desde CSV

### Preparar archivo

Crea un CSV con columnas mínimas:

```csv
nombre,tipo,cif_nif,email
Beers Ltd,empresa,B87654321,info@beers.com
María López,persona,87654321B,maria@example.com
Servicios TI SL,empresa,C11223344,contacto@servicios-ti.es
```

Columnas reconocidas automáticamente:

| Columna | Obligatoria | Ejemplo |
|---------|-----------|---------|
| nombre | Sí | "Acme Corp" |
| tipo | Sí | empresa / persona |
| cif_nif | Sí | A12345678 / 12345678A |
| email | No | contacto@empresa.com |
| telefono | No | +34 91 123 45 67 |
| ciudad | No | Madrid |
| pais | No | ES |
| region | No | Madrid |
| codigo_postal | No | 28001 |
| web | No | www.empresa.com |

### Detección inteligente de columnas

Frihet usa **IA para detectar automáticamente** columnas incluso si tienen nombres ligeramente diferentes:

- "Empresa" = "nombre"
- "Tipo cliente" = "tipo"
- "NIF" / "CIF" = "cif_nif"
- "Email" / "Correo" / "E-mail" = "email"
- "Teléfono" / "Tlf" = "telefono"
- "Ciudad" / "Municipio" = "ciudad"
- "Web" / "Sitio web" = "web"

Esto permite importar archivos de otros sistemas sin reformat manual.

### Proceso de importación

1. Ve a **Clientes > Importar > Desde CSV**
2. Arrastra archivo o selecciona desde disco
3. Frihet **valida formato** y muestra preview:
   - Filas a importar
   - Columnas detectadas
   - Problemas encontrados
4. Resuelve conflictos (ver abajo)
5. Haz clic **Importar**

### Validación y conflictos

Durante importación, Frihet verifica:

#### Duplicados

Si el CIF/NIF ya existe en tu cuenta:

- **Opción 1**: Saltar (no importar ese cliente)
- **Opción 2**: Actualizar datos del cliente existente
- **Opción 3**: Crear nuevo con datos de la importación

#### CIF/NIF inválido

Si el formato no es válido:

```
Fila 5: "Acme Corp" — CIF "123" no válido
Sugerencia: ¿Quisiste decir "A12345678"?
```

Puedes:
- Corregir antes de importar
- Dejar en blanco (requiere edición manual después)
- Saltar esa fila

#### Email duplicado

Si el mismo email está registrado en 2 clientes:

```
Fila 3: "García & Asociados" usa email "contacto@empresas.com"
También en: "García Servicios Legales" (existente)
```

Elige cuál mantener o crea nuevo con email diferente.

### Ejemplo: Importar desde Excel

Si tus clientes están en Excel:

1. Abre archivo en Numbers / Excel
2. Selecciona rango de datos
3. Copia (Cmd+C)
4. En Frihet, ve a **Clientes > Importar**
5. Pega (Cmd+V) en el área de importación
6. Frihet detecta formato automáticamente

## Operaciones en lote

Tras importar, puedes aplicar cambios a múltiples clientes:

### Asignar plazo de pago

1. Ve a **Clientes**
2. Selecciona varios (checkbox en lista)
3. Haz clic **Acciones > Establecer plazo pago**
4. Elige plazo (30, 60, 90 días)
5. Aplica a todos seleccionados

### Cambiar región

Útil si importaste clientes de otra sucursal:

1. Selecciona clientes
2. **Acciones > Editar región**
3. Nueva región: Cataluña
4. Aplica

### Agregar etiqueta

Categoriza clientes importados:

1. Selecciona clientes
2. **Acciones > Agregar etiqueta**
3. Crea etiqueta (ej: "Importados 2026")
4. Aplica

Las etiquetas permiten filtrar después.

## Exportar a otras herramientas

### A Stripe (para pagos)

Frihet exporta clientes a formato compatible con Stripe:

1. Ve a **Clientes > Exportar**
2. Selecciona **Formato Stripe**
3. Se descarga JSON con estructura correcta
4. Importa en Stripe dashboard

### A HubSpot (CRM)

1. **Clientes > Exportar > HubSpot**
2. Frihet genera token de integración
3. Sincroniza automáticamente bidireccional (plan Premium)

### A Google Sheets

Para colaboración:

1. **Clientes > Exportar > Google Sheets**
2. Se abre nueva hoja compartible
3. Cambios en Sheets se sincronizan a Frihet (delay 1 hora)

## Sincronización continua

En plan **Premium**, habilita sincronización:

1. Ve a **Integraciones > CRM**
2. Selecciona herramienta (HubSpot, Pipedrive, Salesforce)
3. Autoriza acceso (OAuth)
4. Elige qué sincronizar:
   - Datos del cliente (bidireccional)
   - Histórico de facturas (unidireccional: Frihet → CRM)
   - Pagos (unidireccional)

Cambios se sincronizan automáticamente cada hora.

## Problemas comunes

### "CIF no válido en fila 3"

El CIF debe seguir formato: 1 letra + 7 números + 1 letra/número.
- ✅ A12345678
- ❌ 12345678 (falta letra)
- ❌ A1234567 (solo 7 dígitos)

Corrije antes de importar.

### "Email duplicado en mi cuenta"

Un cliente tiene 2 registros con el mismo email. Usa **Clientes > Unir clientes** para consolidar antes de importar.

### "Archivo CSV corrupto"

Si Frihet no puede leer el archivo:

- Guarda como UTF-8 (no Latin-1)
- Verifica delimitador (coma, punto y coma)
- Abre en Excel y resguarda como CSV nuevo
- Intenta import nuevamente

### "Importación lenta"

Si importas 10.000+ clientes:

- Procesa en lotes de 5.000 máximo
- En plan Premium, contacta soporte para import optimizado
- La primera importación es más lenta (índices); posteriores son rápidas

---

## Vista Kanban del CRM
> Path: /clientes/kanban-crm

<!-- AUTO-STUB 2026-05-05 -->

# Vista Kanban del CRM

> Visualiza todos tus clientes en un tablero Kanban de 6 etapas (lead, contactado, propuesta, activo, inactivo, perdido) y muévelos con arrastrar y soltar.

## Overview

Además de la vista de lista, el CRM de Frihet ofrece una vista Kanban para gestionar tu pipeline comercial visualmente. Cada cliente aparece como una tarjeta con su nombre, importe facturado acumulado e indicador de salud. Arrastra las tarjetas entre columnas para actualizar su etapa de pipeline instantáneamente.

La vista Kanban sincroniza con la vista de lista: los cambios de etapa se reflejan en el perfil del cliente y se registran en el historial de actividad.

## Quick start

1. Ve a **Clientes** y pulsa el icono de tablero (Kanban) en la esquina superior derecha.
2. Arrastra la tarjeta de un cliente a la columna que represente su etapa actual.
3. Pulsa sobre la tarjeta para abrir el detalle completo del cliente sin salir del Kanban.

## Reference

- API: `PATCH /v1/clients/:id` (campo `stage`) — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `update_client` — ver [MCP reference](/desarrolladores/mcp-server)

## Related

- [Gestión de clientes](./gestion-clientes)
- [Detalle del cliente](./detalle-cliente)
- [Salud del cliente y churn](./gestion-clientes)

---

## Notas y actividades
> Path: /clientes/notas-actividades

# Notas y actividades

Cada ficha de cliente incluye un historial completo de interacciones y un sistema de notas internas. Todo queda registrado cronológicamente para que nunca pierdas contexto.

## Timeline de actividad

Frihet registra automáticamente cada evento relevante del cliente:

- **Factura creada**, enviada, cobrada o vencida
- **Presupuesto creado**, aceptado o rechazado
- **Gasto registrado** vinculado al cliente
- **Cambio de estado** en el pipeline de ventas
- **Cliente creado**

El timeline agrupa las entradas por fecha: **hoy**, **esta semana** y **este mes**. No necesitas hacer nada — cada acción sobre el cliente genera una entrada automática.

## Actividades manuales

Además del registro automático, puedes registrar interacciones manualmente desde la pestaña **Actividad** del cliente:

- **Llamada**: Registra una llamada telefónica con descripción opcional
- **Reunión**: Registra una reunión con descripción opcional

Usa los botones en la parte inferior de la pestaña Actividad para añadir una entrada.

## Notas

Las notas son comentarios internos vinculados al cliente. No son visibles para el cliente en ningún momento.

### Crear nota

1. Abre la ficha del cliente y ve a la pestaña **Notas**
2. Escribe en el área de texto
3. Haz clic en **Guardar** o pulsa **Cmd+Enter**

Cada nota genera automáticamente una entrada en el timeline de actividad.

### Editar nota

Pasa el cursor sobre la nota y haz clic en el **icono de lápiz**.

### Eliminar nota

Pasa el cursor sobre la nota y haz clic en el **icono de papelera**.

## Tips

- Usa notas para contexto interno: "Interesado en plan anual", "Prefiere email a teléfono", "Contactar después del 15 de marzo".
- El timeline de actividad responde a la pregunta clave: **¿cuándo fue la última vez que interactuamos con este cliente?**
- Combina notas + actividades manuales para tener un mini-CRM dentro de cada ficha de cliente.

---

## Portal de cliente
> Path: /clientes/portal-cliente

# Portal de cliente

Frihet ofrece tres formas de compartir documentos con tus clientes, cada una para un caso de uso diferente:

| Canal | URL | Uso |
|-------|-----|-----|
| **Portal completo** | `app.frihet.io/portal/:token` | Acceso self-service a todo: facturas, presupuestos, pagos, estado de cuenta |
| **Factura publica** | `app.frihet.io/p/:hash` | Enlace de solo lectura para compartir una factura individual |
| **Pagina de pago** | `app.frihet.io/pay/:userId/:invoiceId/:token` | Checkout directo con Stripe para cobrar una factura |

---

## Portal completo

El portal es una experiencia self-service donde tu cliente accede a toda su informacion sin necesidad de crear cuenta ni contraseña.

### Acceso

1. Abre la ficha de un cliente en Frihet
2. Pulsa **Generar enlace del portal**
3. Frihet genera un token unico para ese cliente
4. Comparte el enlace por email, WhatsApp o donde prefieras

```
https://app.frihet.io/portal/eyJhbGciOiJIUzI1NiJ9...
```

El enlace da acceso a **todo el historial del cliente**, no a una sola factura. Puedes revocarlo en cualquier momento desde la ficha del cliente.

### Pestanas del portal

El portal tiene 5 pestanas:

#### Dashboard

Vista general del cliente con:
- Saldo pendiente total
- Facturas vencidas (numero e importe)
- Actividad reciente (ultimas facturas, pagos, presupuestos)

#### Facturas

Lista completa de facturas del cliente con:
- Filtrado por estado (pendiente, pagada, vencida)
- Descarga de PDF individual
- Boton de pago (si Stripe Connect esta configurado)

#### Presupuestos

Lista de presupuestos enviados al cliente con:
- Estado actual (enviado, aceptado, rechazado, expirado)
- Aceptar o rechazar presupuesto directamente desde el portal

#### Pagos

Historial completo de pagos realizados:
- Fecha, importe y factura asociada
- Metodo de pago utilizado
- Estado del pago

#### Estado de cuenta

Resumen consolidado del historial financiero:
- Exportable como PDF
- Total facturado, total pagado, saldo pendiente

### Personalizacion

El portal muestra tu branding automaticamente:
- **Logo** de tu empresa (configurado en Ajustes > Datos de empresa)
- **Color de marca** principal
- **Nombre** de tu negocio

---

## Factura publica

Para compartir una factura individual de forma rapida, sin dar acceso al portal completo.

```
https://app.frihet.io/p/a1b2c3d4e5f6
```

### Como funciona

1. Abre una factura en Frihet
2. Pulsa **Compartir** > **Enlace publico**
3. Frihet genera un hash unico para esa factura
4. Cualquier persona con el enlace puede ver la factura

### Que ve el cliente

- Vista de solo lectura de la factura con tu branding
- Boton para descargar PDF
- Boton de pago (si Stripe Connect esta configurado)
- Sin acceso a otras facturas ni datos del portal

### Seguridad

- Hash aleatorio no adivinable (no contiene IDs secuenciales)
- Solo lectura — no se puede modificar nada
- Se puede revocar eliminando la factura o desde el detalle de la factura

---

## Pagina de pago

Enlace especifico para cobrar una factura via Stripe.

```
https://app.frihet.io/pay/{userId}/{invoiceId}/{token}
```

### Como funciona

1. **Requisito:** Tener Stripe Connect configurado en Ajustes > Pagos
2. El enlace se incluye automaticamente en los emails de factura con el boton "Ver y pagar factura"
3. El cliente ve los datos de la factura y pulsa **Pagar**
4. Se abre una sesion de Stripe Checkout (tarjeta, Apple Pay, Google Pay)
5. Al completar el pago, la factura se marca como pagada automaticamente

### Seguridad

- Token HMAC-SHA256 unico por combinacion usuario+factura
- Determinístico: no almacena tokens en base de datos
- Comparacion timing-safe para prevenir ataques de temporización
- HTTPS obligatorio

---

## Seguridad general

Todos los canales comparten las siguientes medidas:

- **Sin autenticacion tradicional:** No se requiere cuenta ni contraseña. Acceso por token o hash
- **HTTPS obligatorio** en todos los enlaces
- **Cabeceras de seguridad:** `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`
- **Aislamiento:** Un cliente solo ve sus propios datos. No puede acceder a facturas de otros clientes
- **Revocacion:** Al eliminar un cliente, todos sus enlaces se invalidan inmediatamente
- **Sin expiracion:** Los tokens son validos indefinidamente mientras el cliente exista en tu base de datos

---

## Notificaciones automaticas

Frihet puede enviar emails automaticos al cliente:

- **Factura emitida:** Email cuando creas nueva factura (con enlace de pago y PDF adjunto)
- **Recordatorio de pago:** Email antes del vencimiento (configurable en Ajustes > Recordatorios)
- **Pago recibido:** Confirmacion cuando se registra un pago
- **Presupuesto expirado:** Aviso si un presupuesto caduca sin aceptar

Configura los automatismos en **Ajustes > Notificaciones**.

---

## Facturación electrónica en Francia
> Path: /compliance/france

:::warning Estado actual (mayo 2026) — envío Chorus Pro/PDP en sandbox/mock

- Generación + descarga de Factur-X (PDF/A-3 + XML CII) / UBL: producción. El archivo se puede **subir manualmente a Chorus Pro**.
- **Transmisión automática a Chorus Pro vía API** e integración con la futura **Plateforme de Dématérialisation Partenaire (PDP)**: en desarrollo (Q3 2026) — requieren credenciales OAuth **PISTE.gouv.fr** y, para PDP, certificación oficial que **aún no están provisionadas en producción**. El envío automatizado y el ciclo PDP están en roadmap.
  :::

# Facturación electrónica en Francia

## ¿Qué estándar aplica?

En Francia, el estándar principal para la facturación electrónica es **Factur-X**, que combina un PDF/A-3 con un archivo XML en formato CII (Cross Industry Invoice) incrustado. Este estándar está disponible en varios perfiles: MINIMUM, BASIC WL, BASIC, EN16931 (también conocido como COMFORT) y EXTENDED. Cada perfil incluye un nivel creciente de datos estructurados. Para transacciones **Business-to-Government (B2G)**, es obligatorio utilizar la plataforma **Chorus Pro**, desde 2017. Para relaciones **Business-to-Business (B2B)**, entrará en vigor una nueva obligación a partir de 2026, basada en la reforma de la Ley de Finanzas 2024.

## ¿Desde cuándo y quién está afectado?

La obligación de facturación electrónica en B2G se implementó por fases: desde 2017 para grandes empresas, 2018 para medianas empresas y 2019-2020 para pequeñas empresas. En el ámbito B2B, la nueva regulación establece que la **emisión** de facturas electrónicas será obligatoria a partir de **septiembre de 2026 para grandes empresas**, y en **2027 para pymes**. En cuanto a la **recepción**, todas las empresas sujetas deberán aceptar y procesar facturas electrónicas a partir de **2025**, independientemente de su tamaño. Estas fechas pueden ajustarse según la publicación de textos reglamentarios definitivos.

## Cómo te ayuda Frihet

Frihet genera facturas en formato **Factur-X versión EN16931** con PDF/A-3 incrustado, compatibles con los perfiles requeridos.

### Capacidad actual

- Generación y descarga de XML Factur-X/UBL completamente soportada
- Detección automática del cliente francés con routing a Factur-X por defecto
- Exportación desde el invoice actions menu, lista para **subida manual a Chorus Pro** (B2G)

### Roadmap (Q3 2026)

- Envío automatizado a **Chorus Pro** (B2G) mediante API PISTE — pendiente provisión de credencial OAuth PISTE.gouv.fr
- Integración con **PPF** (Plateforme Publique de Facturation) y **PDP** (operadores privados certificados) que gestionará la facturación B2B desde 2026 — requiere acreditación oficial como operador certificado, pendiente
- e-Reporting automatizado (B2C y operaciones transfronterizas)

[Ver facturación en Frihet](/facturacion/facturas)

## Detalles del formato

Factur-X es un estándar híbrido: el documento visible es un PDF/A-3, mientras que los datos estructurados se almacenan en un XML CII incrustado, legible por máquinas. Esto garantiza tanto la usabilidad humana como la automatización del procesamiento. Los perfiles varían en nivel de detalle: MINIMUM (solo 6 campos obligatorios), BASIC WL (sin IVA desglosado), BASIC, EN16931 (alineado con estándares europeos) y EXTENDED (datos adicionales específicos del negocio). También se acepta la interfaz **PEPPOL** como canal de intercambio.

## Portal gubernamental

La plataforma oficial para el intercambio de facturas en relaciones B2G es **Chorus Pro** ([https://chorus-pro.gouv.fr](https://chorus-pro.gouv.fr)). A partir de 2026, se implementará la **Plateforme de Dématérialisation Partenaire (PDP)** para gestionar la facturación B2B, actuando como intermediario certificado entre emisores y receptores.

## Referencias oficiales

- FNFE-MPE Factur-X: https://www.factur-x.org
- Plataforma Chorus Pro: https://chorus-pro.gouv.fr
- Dirección General de Finanzas Públicas (DGFiP) - Reforma e-factura: https://www.impots.gouv.fr/e-facture

---

## Germany XRechnung B2G e-invoicing with Frihet
> Path: /compliance/germany-xrechnung-b2g

# Germany XRechnung B2G e-invoicing with Frihet

Germany requires structured e-invoices for all public sector transactions and is rolling out mandatory B2B e-invoicing under the Wachstumschancengesetz. Frihet generates XRechnung-CII and XRechnung-UBL invoices, validates them against the KoSIT schema, and routes them to government recipients.

## Legal framework

German e-invoicing rules stem from two legislative sources:

**EU Directive 2014/55/EU** — mandated that all EU member states accept structured e-invoices for B2G transactions from national, regional, and local authorities. Germany implemented this through federal law in 2020.

**Wachstumschancengesetz (Growth Opportunities Act)** — enacted March 2024, extends the obligation to B2B transactions:

| Date               | Obligation                                                              |
| ------------------ | ----------------------------------------------------------------------- |
| **1 January 2025** | All businesses must be able to **receive** EN16931-compliant e-invoices |
| **1 January 2027** | Businesses with annual revenue > €800,000 must **issue** e-invoices     |
| **1 January 2028** | All remaining businesses must **issue** e-invoices                      |

The B2B receive obligation started on 1 January 2025. If your German customer sends you a structured e-invoice, you are legally required to process it. Frihet handles incoming structured formats as attachments and flags them for reconciliation.

## XRechnung — the mandatory standard

**XRechnung** is the German national profile of EN16931. It defines strict implementation rules on top of the European semantic standard. Two technical syntaxes are accepted:

| Syntax            | File extension | Notes                                                                  |
| ----------------- | -------------- | ---------------------------------------------------------------------- |
| **XRechnung-CII** | `.xml`         | UN/CEFACT Cross Industry Invoice. Recommended by KoSIT for German B2G. |
| **XRechnung-UBL** | `.xml`         | OASIS UBL 2.1. Also valid; more common in multinational ERP systems.   |

Both syntaxes express the same semantic data model. The current version is **XRechnung 3.0.2**, governed by KoSIT (Koordinierungsstelle für IT-Standards).

**Factur-X / ZUGFeRD 2.3** is also compliant with EN16931 and accepted in B2B contexts. It embeds an EN16931-CII XML inside a PDF/A-3 file, making it human-readable while remaining machine-processable. Frihet generates Factur-X hybrid PDFs for B2B invoices where requested.

## Leitweg-ID — mandatory routing identifier for B2G

Every XRechnung invoice sent to a German public authority must include a **Leitweg-ID** in the `BuyerReference` field (`BT-10`). This identifier routes the invoice to the correct administrative unit within the receiving authority.

The Leitweg-ID follows the format `{section}-{subsection}-{check}`, for example:

```
04011000-1234-06
```

Where:

- `04011000` — administrative unit code (Behördenkennzahl)
- `1234` — sub-unit or cost center
- `06` — check digit

:::caution
A missing or malformed Leitweg-ID causes automatic rejection at OZG-RE or the receiving authority's portal. Confirm the correct Leitweg-ID with your government customer's procurement office before invoicing.
:::

### Setting the Leitweg-ID in Frihet

1. Open the client record in **Clients**.
2. In the **Tax data** section, enable **Public authority (B2G)**.
3. Enter the Leitweg-ID in the **Leitweg-ID** field.
4. Save the client.

Frihet populates `BT-10` with this value in every XRechnung generated for that client.

## Generating XRechnung invoices in Frihet

Once the client is configured:

1. Create the invoice as usual.
2. Open the completed invoice and click **More options** → **Export e-invoice**.
3. In the export dialog (`EInvoiceExportDialog`), select **XRechnung 3.0 (Germany)**.
4. Choose the syntax: **CII (recommended for B2G)** or **UBL**.
5. Download the `.xml` file.

Frihet validates the generated XML against the KoSIT schema rules before making it available for download. If the invoice data is incomplete (missing Leitweg-ID, missing VAT number, unsupported currency), the export dialog shows the specific error before generating the file.

## KoSIT validator — pre-submission check

The KoSIT validator is the official tool for verifying XRechnung conformance. Frihet runs the validation rules internally, but you can also verify the exported XML manually:

- **Online validator**: [https://ecosio.com/en/peppol-and-xml-document-validator/](https://ecosio.com/en/peppol-and-xml-document-validator/) (community tool using KoSIT rules)
- **CLI validator**: [https://github.com/itplr-kosit/validator](https://github.com/itplr-kosit/validator) — run `java -jar validationtool-x.y.z-standalone.jar -r scenarios.xml -t report invoice.xml`

A compliant invoice produces a validation report with `valid: true` and zero `errors`.

## Submitting to OZG-RE (federal authorities)

The **OZG-RE (Onlinezugangsgesetz — Rechnungseingang)** is the federal government's central e-invoice receiving platform. It connects to the **PEPPOL network** for automated routing.

### Via PEPPOL (recommended for recurring B2G suppliers)

If your government customer uses PEPPOL routing:

1. Your company needs a **PEPPOL ID** (e.g., `0088:DE123456789` or issued by a certified Access Point Provider).
2. The receiving authority's PEPPOL ID appears in their procurement documents.
3. Frihet routes the invoice via the PEPPOL network to OZG-RE.

PEPPOL AS4 transport for DE B2G is available in Frihet on Premium+ plans. Contact support to activate your PEPPOL endpoint.

### Via email transport (current default for ad-hoc B2G)

For authorities not yet on PEPPOL, or for initial submissions:

1. Export the XRechnung XML from Frihet.
2. Email the `.xml` file to the authority's designated invoicing address (usually specified in the contract or purchase order).
3. Some authorities use the **ZRE (Zentrale Rechnungseingangsplattform)** with a dedicated submission address.

:::note PEPPOL AS4 deferred
Full automated PEPPOL AS4 transport for German B2G is in the Frihet Day 4 roadmap. Until activated for your account, email delivery is the supported path. The XRechnung XML generated by Frihet is technically correct for either transport method.
:::

## B2B obligations — what changes from 2025

From **1 January 2025**, every German VAT-registered business must be able to **receive** EN16931-compliant structured e-invoices. This means:

- You cannot refuse a structured XML invoice from a German supplier.
- Your accounting software must be able to parse XRechnung or Factur-X.
- Frihet automatically handles incoming structured formats when connected via integration or API.

The **emit** obligation follows in 2027 (large companies) and 2028 (all others). Until those dates, you may continue issuing PDF invoices to German B2B customers, but you must be ready to transition.

**Practical impact for Frihet users:**

- German customers will increasingly send you XRechnung or Factur-X XML files.
- Use Frihet's expense import to attach and process these files against supplier records.
- From 2027/2028, Frihet generates the mandatory structured format automatically for German B2B invoices.

## Factur-X for B2B — hybrid PDF/A-3

For German B2B invoices where the recipient prefers a human-readable document:

1. In the export dialog, select **Factur-X (Germany/France B2B)**.
2. Frihet generates a PDF/A-3 file with the EN16931-CII XML embedded.
3. The recipient's software can read the embedded XML automatically; humans can read the PDF.

Factur-X complies with both EN16931 and the Wachstumschancengesetz B2B requirements.

## VAT and tax handling

German e-invoices must include:

- Supplier and buyer VAT numbers (`BT-31`, `BT-48`)
- VAT breakdown per rate (`BG-23`)
- Standard rates: **19%** (general), **7%** (reduced)
- Zero-rated and exempt supplies require the applicable reason code

Frihet applies German VAT rates automatically when the invoice recipient has a German address. If your German customer is VAT-exempt (e.g., a public authority not subject to VAT), set the exemption in the tax configuration.

## Frequently asked questions

**Does XRechnung replace the PDF invoice entirely?**
For B2G, yes — the PDF is no longer the primary document. The structured XML is the legally binding invoice. For B2B, PDFs remain acceptable until the emit mandate dates (2027/2028), but Factur-X allows you to send both simultaneously in one file.

**What if my German customer sends a Factur-X file and I can not process it?**
From 1 January 2025, you are legally required to be able to receive it. Frihet's expense and supplier invoice management handles Factur-X ingestion. If you receive a file outside Frihet, you can upload it via the document import function.

**Is my German VAT number sufficient as a PEPPOL identifier?**
No. Your PEPPOL ID is a separate identifier issued by a certified Access Point Provider (e.g., Pagero, Basware, Comarch). Your German VAT number (`DE123456789`) can form part of the ID under scheme `0088`, but you need an Access Point to participate in the network.

**Can I send XRechnung invoices to Austrian or Swiss public authorities?**
Austria uses a similar B2G mandate (ebInterface or PEPPOL UBL). Switzerland is not in the EU mandate scope. For cross-border B2G in other EU countries, Frihet generates the appropriate national profile.

## Official references

- XRechnung specification: [https://xeinkauf.de/xrechnung/](https://xeinkauf.de/xrechnung/)
- KoSIT validator: [https://www.kosit.org](https://www.kosit.org)
- OZG-RE federal portal: [https://www.e-rechnung-bund.de](https://www.e-rechnung-bund.de)
- EN16931 standard: [https://www.en16931.eu](https://www.en16931.eu)
- Wachstumschancengesetz: [https://www.bundesfinanzministerium.de/Content/DE/Standardartikel/Themen/Steuern/2023-07-24-massnahmenpaket-steuerpolitik.html](https://www.bundesfinanzministerium.de/Content/DE/Standardartikel/Themen/Steuern/2023-07-24-massnahmenpaket-steuerpolitik.html)
- PEPPOL DE: [https://www.peppol.eu/resources/peppol-in-germany/](https://www.peppol.eu/resources/peppol-in-germany/)

## Related

- [E-Invoicing in Germany](/compliance/germany)
- [Electronic invoicing formats](/facturacion/factura-electronica)
- [France Factur-X](/compliance/france)
- [REST API](/desarrolladores/api-rest)

---

## Facturación electrónica en Alemania
> Path: /compliance/germany

# Facturación electrónica en Alemania

## ¿Qué estándar aplica?

En Alemania, el estándar obligatorio para facturas electrónicas en transacciones B2G (empresa a administración) es **XRechnung 3.0**, basado en el marco europeo EN16931. Este estándar garantiza la interoperabilidad y el tratamiento automático de facturas electrónicas en el sector público. Además de XRechnung, también se acepta **Factur-X** (basado en EN16931), especialmente en sectores privados, aunque no es obligatorio. El estándar europeo **EN16931** define los requisitos mínimos para la facturación electrónica y es el fundamento técnico de ambos formatos. XRechnung puede implementarse en dos formatos técnicos: **CII (UN/CEFACT)** y **UBL 2.1**. Ambos son válidos, pero UBL es más común en sistemas empresariales internacionales. Es crucial que las facturas cumplan con la versión exacta del esquema y contengan todos los campos obligatorios para evitar rechazos.

## ¿Desde cuándo y quién está afectado?

La obligatoriedad de la facturación electrónica en Alemania comenzó en **2020 para contratos con el sector público a nivel federal**, exigiendo el uso de XRechnung 3.0. Desde entonces, todas las empresas que facturan a entidades gubernamentales deben enviar sus facturas en formato electrónico conforme a este estándar. A partir del **1 de enero de 2025**, la obligación se amplía a todas las relaciones **B2B** (empresa a empresa) en Alemania. Todos los contribuyentes deberán **recibir** facturas electrónicas en formatos conformes EN16931 (como XRechnung o Factur-X). Las pequeñas y medianas empresas tendrán un periodo de transición: deberán **emitir** facturas electrónicas a partir de **2027**. Para garantizar la conformidad, se recomienda utilizar el **validador oficial de KoSIT**, herramienta gratuita que verifica si una factura cumple con los requisitos técnicos y de formato.

## Cómo te ayuda Frihet

Frihet simplifica el cumplimiento de las normativas alemanas de facturación electrónica. Nuestra plataforma genera **facturas en formato XRechnung 3.0** completamente conformes, en variantes CII y UBL. Antes del envío, cada factura se valida automáticamente mediante reglas técnicas actualizadas, incluyendo verificación con el estándar EN16931. Frihet también permite la **entrega directa a la plataforma gubernamental OZG-RE** (Rechnungseingangsplattform), asegurando un flujo eficiente y sin errores. Con integraciones sencillas y soporte continuo, facilitamos la transición hacia la facturación electrónica obligatoria en Alemania. [ver facturación en Frihet](/facturacion/facturas)

## Detalles del formato

El formato **XRechnung 3.0** requiere el uso específico de la versión del esquema definida por KoSIT. Admite tanto el formato **CII (Cross Industry Invoice)** como **UBL 2.1** (Universal Business Language), permitiendo flexibilidad técnica según el sistema del emisor. Un campo obligatorio clave es el **BuyerReference**, conocido en Alemania como **Leitweg-ID**, que identifica de forma única al destinatario en la red de recepción gubernamental. Este identificador es esencial para el enrutamiento correcto de la factura. Todas las facturas deben validarse contra el esquema oficial utilizando el **KoSIT Validator**, herramienta de referencia para comprobar la conformidad técnica antes del envío.

## Portal gubernamental

El punto de entrada oficial para las facturas electrónicas al sector público alemán es la **OZG-RE (Onlinezugangsgesetz - Rechnungseingangsplattform)**. Esta plataforma central recibe, valida y distribuye las facturas electrónicas a las entidades públicas. OZG-RE está integrada con la red **Peppol**, lo que permite el intercambio transfronterizo de facturas dentro de Europa. Las empresas pueden conectarse directamente o a través de proveedores de acceso certificados (Access Point Providers) en la red Peppol. Más información y acceso disponible en: https://www.e-rechnung-bund.de

## Referencias oficiales

- XRechnung spec: https://xeinkauf.de/xrechnung/
- KoSIT validator: https://www.kosit.org
- EN16931: https://www.en16931.eu

---

## Facturación electrónica en Italia
> Path: /compliance/italy

:::warning Estado actual (mayo 2026) — envío SDI en sandbox/mock

- Generación + firma XML FatturaPA 1.2.2 + descarga: producción. El XML se puede **subir manualmente al SDI**.
- **Transmisión automática al SDI**: en desarrollo (Q3 2026) — requiere alta como intermediario acreditado ante la Agenzia delle Entrate y provisión de certificado con intermediario PEC oficial (Aruba o Namirial), aún **no provisionados en producción**. El envío automatizado y el seguimiento de notifiche SDI están en roadmap.
  :::

# Facturación electrónica en Italia

## ¿Qué estándar aplica?

FatturaPA 1.2.2 — el único formato oficial italiano, obligatorio para todas las transacciones (B2G, B2B, B2C). XML con schema del Agenzia delle Entrate. Transmisión exclusivamente por SDI (Sistema di Interscambio).

## ¿Desde cuándo y quién está afectado?

B2G: obligatorio desde 2015. B2B y B2C: obligatorio desde enero 2019 (Italia fue pionera en Europa). Todas las empresas con sede o establecimiento en Italia, incluyendo régimen forfettario (con excepciones hasta 2024 ya eliminadas).

## Cómo te ayuda Frihet

Frihet genera el XML FatturaPA 1.2.2 listo para SDI (naturalezas IVA, regímenes, tipos de documento) y firma XAdES-BES con certificado del emisor.

### Capacidad actual

- Generación y descarga de XML FatturaPA 1.2.2 firmado completamente soportada
- Firma XAdES-BES en infraestructura europea
- Detección automática de cliente italiano + Codice Destinatario
- Subida manual al SDI mediante el intermediario de tu elección (gestor, software de envío acreditado, o portal Fatture e Corrispettivi)

### Roadmap (Q3 2026)

- Envío automatizado al **SDI** (Sistema di Interscambio) — requiere alta de Frihet como soggetto intermediario ante la Agenzia delle Entrate y provisión de certificado PEC con Aruba o Namirial, pendiente
- Seguimiento de estados SDI (consegnata, non consegnata, accettata)
- Conservazione sostitutiva (10 años) con proveedor certificado — aún no activa; los XML se almacenan en infraestructura europea

Hasta Q3 2026: descarga el XML firmado desde Frihet y envíalo vía tu intermediario PEC o el portal web de la Agenzia delle Entrate.

Link: [ver facturación en Frihet](/facturacion/facturas)

## Detalles del formato

FatturaPA: XML con namespace http://ivaservizi.agenziaentrate.gov.it. Versiones: FPR12 (privados B2B/B2C), FPA12 (PA). Tipos de documento: TD01 (factura), TD04 (nota crédito), TD24 (diferida). Regímenes: RF01 (ordinario), RF19 (forfettario). Naturalezas IVA: N1-N7.

## Portal gubernamental

SDI (Sistema di Interscambio): https://www.agenziaentrate.gov.it/portale/web/guest/fatturazione-elettronica. Fatture e Corrispettivi para consulta y conservación.

## Referencias oficiales

- Agenzia delle Entrate: https://www.agenziaentrate.gov.it
- Schema FatturaPA: https://www.fatturapa.gov.it
- Assosoftware: https://www.assosoftware.it

---

## Poland KSeF mandatory B2B e-invoicing — get ready
> Path: /compliance/poland-ksef

# Poland KSeF mandatory B2B e-invoicing — get ready

Poland's **KSeF (Krajowy System e-Faktur)** is the national e-invoicing platform operated by the Ministry of Finance (`mf.gov.pl`). It centralizes all B2B invoice exchange: invoices are submitted to KSeF, which assigns an official identifier (KSeF number) and makes the invoice available to the recipient. KSeF is already operational as a voluntary system. Mandatory enrollment follows in phases starting February 2026.

## Mandatory dates

| Taxpayer category                             | Mandatory from                       |
| --------------------------------------------- | ------------------------------------ |
| Large taxpayers (VAT revenue > PLN 200M/year) | **1 February 2026**                  |
| SMEs                                          | **1 April 2026**                     |
| Micro-enterprises (turnover < PLN 9M/year)    | **1 January 2027**                   |
| Foreign entities with Polish VAT registration | Subject to separate regulation (TBC) |

These dates were confirmed by the Ministry of Finance in 2025 after an earlier postponement from July 2024. If you invoice Polish businesses or operate a Polish VAT-registered entity, you need a KSeF-ready workflow before these deadlines.

## What KSeF changes operationally

Under KSeF:

1. You submit structured XML (FA_VAT format) to the KSeF API.
2. KSeF assigns an official **KSeF number** (KSEFNR) to the invoice.
3. The invoice is legally valid from the moment KSeF assigns the number.
4. Your buyer retrieves the invoice from KSeF using the KSEFNR — email attachments no longer serve as the primary invoice delivery mechanism.
5. **30-day payment deadline** is calculated from the KSeF assignment date, not from the invoice date.

This is a significant operational shift: an invoice that fails KSeF submission (due to schema errors, authentication failure, or API downtime) is not legally issued until KSeF accepts it. Frihet validates locally before submission to minimize rejections.

## FA_VAT(3) schema

The current KSeF invoice format is **FA_VAT version 3**, published in the official Polish Government Legislation Journal:

- **Namespace**: `http://crd.gov.pl/wzor/2025/06/25/13775/`
- **Schema file**: `FA_VAT(3).xsd` — available from the Ministry of Finance developer portal
- **Effective**: aligned with the 2026 mandatory rollout

FA_VAT(3) introduces changes from FA_VAT(2):

| Element               | Change in v3                                  |
| --------------------- | --------------------------------------------- |
| Seller identification | Extended taxpayer type codes                  |
| VAT rate enumeration  | Added new zero-rate reason codes              |
| Pre-paid invoices     | New field `ZaliczkaCzesciowa`                 |
| KSeF reference        | Mandatory field for corrective invoices       |
| Annotation field      | Structured annotation codes replace free text |

Frihet generates FA_VAT(3) XML directly from your invoice data. You do not need to manage the schema manually.

## XAdES authentication — how KSeF works

KSeF uses a challenge-response authentication flow before accepting invoice submissions. The flow is asynchronous:

1. **Request a challenge token** — your system calls `POST /api/online/Session/AuthorisationChallenge` with your NIP (Polish VAT number).
2. **Sign the challenge** — KSeF returns a `challenge` string. You sign it with XAdES using your qualified electronic signature certificate.
3. **Initialize session** — send the signed challenge to `POST /api/online/Session/Authorise`. KSeF returns a session token valid for a limited window.
4. **Submit invoices** — use the session token in the `SessionToken` header for each `POST /api/online/Invoice/Send` call.
5. **Retrieve KSeF number** — poll `GET /api/online/Invoice/Send/{referenceNumber}` until `processingCode: 200` and extract the `ksefReferenceNumber`.

Frihet automates this entire flow in its backend. The session token is cached for the valid window to minimize authentication round-trips.

### Authentication certificate requirements

The certificate used to sign the KSeF challenge must be a **qualified electronic signature** issued by a Polish Trusted List (PTL) authority. Accepted issuers include:

- **Certum** (Asseco Data Systems)
- **EuroCert**
- **KIR** (Krajowa Izba Rozliczeniowa)
- **PWPW** (Polska Wytwórnia Papierów Wartościowych)

Certificates issued outside Poland's Trusted List are not accepted by KSeF, even if they are eIDAS-qualified certificates from other EU states. If you operate a Polish entity, you need a Polish qualified certificate.

## Sandbox testing

KSeF provides a test environment at:

```
https://ksef-test.mf.gov.pl
```

The sandbox accepts the same API schema as production but does not create legally binding invoices. Frihet points to the sandbox URL when the workspace KSeF configuration is in test mode.

To test in sandbox:

1. Go to **Settings → Integrations → KSeF**.
2. Enter your NIP and upload your qualified certificate (`.p12` format).
3. Enable **Sandbox mode**.
4. Issue a test invoice to a Polish company. Frihet submits it to `ksef-test.mf.gov.pl` and returns the test KSEFNR.

The sandbox environment accepts test NIP numbers. If you do not yet have a Polish qualified certificate, contact KSeF support at the Ministry of Finance to obtain test credentials.

## Corrective invoices

Under KSeF, a corrective invoice (Polish: _faktura korygująca_) must reference the KSEFNR of the original invoice. Frihet automatically populates the `KSeF` reference field in the corrective invoice XML when you create a credit note against a KSeF-submitted invoice.

If you need to correct an invoice submitted before KSeF was mandatory (no KSEFNR), Frihet includes the original invoice number in the `NrFaKorygowanej` field instead.

## Generating a KSeF invoice in Frihet

1. Set the client's country to **Poland** and enter their **NIP** (Polish VAT number) in the client record.
2. Create the invoice as usual.
3. In the invoice export dialog, select **KSeF FA_VAT(3)** as the format.
4. Click **Submit to KSeF** to initiate the authenticated submission flow.
5. Frihet returns the **KSeF reference number (KSEFNR)** once KSeF accepts the invoice.
6. The KSEFNR is stored in the invoice record and printed on the PDF invoice for your buyer's reference.

If KSeF is unavailable (planned maintenance or outage), Polish regulations include a fallback mode: invoices may be issued offline and submitted retrospectively within a defined window. Frihet manages the offline queue and submits automatically when KSeF recovers.

## VAT rates in Poland

Polish VAT rates as of 2025:

| Rate    | Category                                        |
| ------- | ----------------------------------------------- |
| **23%** | Standard rate                                   |
| **8%**  | Reduced (food, medical equipment, construction) |
| **5%**  | Super-reduced (basic food, books, periodicals)  |
| **0%**  | Exports, intra-EU supplies                      |
| **ZW**  | VAT-exempt                                      |

Frihet applies the correct rate based on your product configuration and the invoice recipient's status. B2G invoices to Polish public authorities typically use the same rates as B2B; the difference is in the buyer identification fields within FA_VAT(3).

## Impact on payment terms

A critical operational change under KSeF: the statutory **30-day payment period** for commercial transactions is measured from the **KSeF assignment date**, not from the invoice date or delivery date. This aligns with Polish commercial law (Ustawa o terminach zapłaty w transakcjach handlowych).

Frihet sets the due date on KSeF invoices based on the KSeF assignment timestamp received from the API, not the invoice creation date. Check your payment terms configuration if you rely on specific due date calculations.

## What about B2G in Poland?

Poland's B2G e-invoicing (invoices to the public sector) uses a separate platform: **PEF (Platforma Elektronicznego Fakturowania)**, operated by PEPPOL. This is independent of KSeF and has been mandatory for central government procurement since April 2019. Frihet generates PEPPOL BIS 3.0 UBL for Polish B2G invoices. KSeF and PEF are parallel systems; some invoices may need to be submitted to both.

## Frequently asked questions

**Is KSeF mandatory for foreign companies with Polish VAT registration?**
The Ministry of Finance has indicated that foreign entities with Polish VAT registration will be subject to separate regulation. The current mandatory dates apply primarily to Polish-resident taxpayers. Monitor `podatki.gov.pl` for updates on foreign entity obligations.

**What happens if KSeF is down when I need to invoice?**
Polish regulations include an offline fallback: you can issue an invoice locally and submit it to KSeF within a grace period (expected 1 business day, subject to final regulation text). Frihet queues unsubmitted invoices and submits them automatically when KSeF becomes available.

**Can I still send PDF invoices to Polish customers after the mandate?**
The KSeF number (KSEFNR) must appear on any PDF or printed copy. The structured XML in KSeF is the primary legal document. You may include a PDF as a courtesy copy, but the KSEFNR must be printed on it.

**Does KSeF apply to B2C (consumer) invoices?**
No. KSeF is a B2B and B2G system. Consumer invoices (paragon fiskalny) remain outside KSeF scope and are regulated separately through fiscal printers.

**What is the penalty for non-compliance?**
The penalty regime is still being finalized in implementing regulations. Initial proposals specify fines up to 100% of the VAT amount on non-compliant invoices, capped at certain thresholds. Monitor the Ministry of Finance guidance at `podatki.gov.pl`.

## Official references

- KSeF Ministry of Finance: [https://www.podatki.gov.pl/ksef/](https://www.podatki.gov.pl/ksef/)
- KSeF API documentation: [https://www.podatki.gov.pl/ksef/dokumentacja-api/](https://www.podatki.gov.pl/ksef/dokumentacja-api/)
- FA_VAT(3) schema: [https://crd.gov.pl/wzor/2025/06/25/13775/](https://crd.gov.pl/wzor/2025/06/25/13775/)
- KSeF sandbox: [https://ksef-test.mf.gov.pl](https://ksef-test.mf.gov.pl)
- PEF B2G platform: [https://www.pef.gov.pl](https://www.pef.gov.pl)

## Related

- [Electronic invoicing formats](/facturacion/factura-electronica)
- [Germany XRechnung B2G](/compliance/germany-xrechnung-b2g)
- [PEPPOL and EU e-invoicing](/compliance/spain)
- [REST API](/desarrolladores/api-rest)

---

## Facturación electrónica en España
> Path: /compliance/spain

# Facturación electrónica en España

## ¿Qué estándar aplica?

En España coexisten dos marcos principales para la facturación electrónica: el estándar **Facturae 3.2.2** y el nuevo sistema **VeriFactu/TicketBAI**, impulsado por la **Ley Crea y Crece (Ley 18/2022)**. Para transacciones **Business-to-Government (B2G)**, el formato obligatorio es **Facturae en XML** con firma electrónica avanzada **XAdES-EPES**. Este estándar se emplea a través del portal **FACe**, utilizado por la Administración Pública. Para operaciones **Business-to-Business (B2B)**, el sistema cambia: desde 2025, las empresas deberán emitir y recibir facturas electrónicas estructuradas (como UBL, Facturae o Factur-X) a través de **operadores de servicios de facturación homologados**, comunicándolas en tiempo real a la **Agencia Estatal de la Administración Tributaria (AEAT)** mediante **VeriFactu**.

## ¿Desde cuándo y quién está afectado?

La obligatoriedad de facturación electrónica en relaciones con el sector público está vigente desde **2015**, conforme a la **Ley 25/2013**, que estableció el uso del formato Facturae para todas las facturas enviadas a entidades del Estado. Sin embargo, la **Ley 18/2022, conocida como Ley Crea y Crece**, introduce una nueva obligación para el ámbito B2B. Esta ley establece que todas las empresas deberán emitir y recibir facturas electrónicas, con un calendario escalonado: empresas con facturación superior a **8 millones de euros anuales** deberán cumplir desde **julio de 2025**, y el resto de empresas a partir de **enero de 2026**. El sistema **VeriFactu**, gestionado por la AEAT, permitirá la **trazabilidad en tiempo real** de las facturas, aunque el reglamento definitivo aún está en desarrollo.

## Cómo te ayuda Frihet

Frihet ofrece una solución integral para cumplir con todos los requisitos de facturación electrónica en España. Soportamos el formato **Facturae 3.2.2** para envíos al portal **FACe**, garantizando la correcta firma XAdES y el cumplimiento de los requisitos administrativos. Además, estamos preparados para integrar con el nuevo sistema **VeriFactu**, permitiendo la comunicación directa con la AEAT. También ofrecemos compatibilidad con **TicketBAI** en las regiones del País Vasco y Navarra. Nuestra plataforma permite la conexión nativa con operadores homologados y asegura el cumplimiento de la **Ley Crea y Crece**. [Ver cómo funciona la facturación en Frihet](/facturacion/facturas)

## Detalles del formato

El formato **Facturae 3.2.2** requiere un archivo XML firmado con firma electrónica **XAdES-EPES enveloped**. Para su aceptación en FACe, es obligatorio incluir tres identificadores administrativos: órgano gestor, unidad tramitadora y oficina contable. En cuanto al IVA, los tipos aplicables son: **21% (general), 10% (reducido), 4% (superreducido) y 0%**. Por otro lado, **VeriFactu** introduce un sistema de **registro encadenado mediante hash criptográfico**, lo que permite a la AEAT verificar la integridad y cronología de todas las facturas emitidas.

## Portal gubernamental

- **FACe (B2G)**: https://face.gob.es
- **AEAT VeriFactu**: https://www.agenciatributaria.es
- **TicketBAI (Euskadi)**: https://www.ticketbai.eus

## Referencias oficiales

- Facturae: https://www.facturae.gob.es
- FACe: https://face.gob.es
- Ley Crea y Crece: https://www.boe.es/buscar/act.php?id=BOE-A-2022-14680
- VeriFactu reglamento: https://www.agenciatributaria.es/AEAT.internet/Inicio/La_Agencia_Tributaria/Normativa_y_doctrina/Normativa/Normativa_Mercantil_y_Contable/Verifactu.shtml

---

## Claves de API
> Path: /configuracion/api-keys

# Claves de API

> Conecta cualquier herramienta a Frihet en segundos: genera una clave de API con permisos granulares.

## Overview

Las claves de API de Frihet permiten que aplicaciones externas, scripts y integraciones accedan a los datos de tu cuenta mediante autenticacion Bearer. Cada clave tiene un nombre descriptivo, alcance configurable (lectura, escritura o ambos) y fecha de expiracion opcional. Puedes revocar cualquier clave individualmente sin afectar a las demas. La especificacion OpenAPI 3.1 esta disponible en `/openapi.yaml` para generar clientes automaticamente.

## Quick start

1. Ve a Configuracion → **API** → **Nueva clave de API**
2. Asigna un nombre descriptivo y la fecha de expiracion (opcional)
3. Copia la clave — solo se muestra una vez; guardala en tu gestor de secretos

## Uso con Zapier

Las claves de API son el metodo de autenticacion de la **app nativa de Frihet en Zapier**. Cuando conectes Frihet en Zapier, necesitaras una clave generada aqui. Consulta la [guia de integracion con Zapier](/integraciones/zapier) para el proceso completo.

## Reference

- API: `GET /v1/api-keys` (listar), `POST /v1/api-keys` (crear), `DELETE /v1/api-keys/:id` (revocar)
- MCP tool: `manage_api_keys` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Configuracion → Desarrolladores → API

---

## Cancelar suscripción
> Path: /configuracion/cancelar-suscripcion

# Cancelar suscripción

Frihet incluye un flujo de cancelación multi-paso desde **Configuración → Plan y facturación → Cancelar**. Antes de confirmar la baja, el sistema te presenta opciones de retención por si alguna encaja mejor con tu situación que cancelar completamente.

## Cómo funciona

Cuando inicias el proceso de cancelación, Frihet te pregunta el motivo principal — precio, falta de uso, funcionalidad concreta, cambio de proveedor — y a partir de ahí adapta las opciones que te ofrece.

Las opciones de retención típicas son cuatro. **Descuento del 30%** sobre el plan actual durante un periodo definido. **Descuento del 50%** si la respuesta al motivo apunta a precio o presupuesto ajustado. **Pausa temporal** de la suscripción si el motivo es estacional o cierre puntual del negocio — los datos se conservan y reactivar es un clic cuando vuelves. **Downgrade** a un plan inferior si las funcionalidades del plan actual no son necesarias.

Si ninguna oferta encaja, puedes continuar con la cancelación. Frihet te muestra entonces el resumen de lo que pasa: hasta cuándo conservas acceso (normalmente fin del periodo facturado), qué sucede con tus datos durante el periodo de gracia GDPR y cómo exportar todo tu contenido antes de la baja definitiva.

La cancelación queda registrada con fecha de efecto y motivo. Si cambias de idea, puedes reactivar la suscripción antes de que termine el periodo facturado sin perder configuración ni datos. Tras el grace, los datos pasan al proceso de archivado y borrado conforme a la política GDPR de Frihet.

## Configuración

El flujo está activo por defecto en todas las cuentas Pro y Premium. No requiere configuración explícita. Si gestionas una cuenta multi-empresa o de gestoría, el flujo de cancelación aplica al workspace completo — habla con soporte si necesitas dar de baja un cliente específico dentro de un panel de gestoría.

Para exportar tus datos antes de cancelar, ve a **Configuración → Exportación** o usa las opciones de exportación desde cada módulo (facturas, gastos, clientes).

## Ver también

- [Planes y facturación](./planes-facturacion)
- [Política de privacidad](../legal/privacidad)
- [Notificaciones](./notificaciones)

---

## Datos de empresa
> Path: /configuracion/datos-empresa

# Datos de empresa

Tu perfil de empresa es la base de todos tus documentos. Desde aquí configuras los datos que aparecen en facturas, presupuestos y otros documentos fiscales.

## Información básica

### Nombre legal y comercial

El **nombre legal** es el nombre registrado en el registro mercantil o la administración tributaria. Es el que debe aparecer en todos tus documentos fiscales.

El **nombre comercial** (opcional) es cómo te conocen clientes y proveedores. Si usas ambos, el nombre legal aparece en facturas y el comercial puede usarse en comunicaciones de marketing.

```
Ejemplo:
Nombre legal: Acme Spain, S.L.
Nombre comercial: Acme
```

### Identificador fiscal

Ingresa tu **NIF** (Número de Identificación Fiscal), **CIF** (Código de Identificación Fiscal) o **NIE** (Número de Identidad de Extranjero) según tu tipo de entidad.

Frihet valida automáticamente el formato:
- **NIF**: 8 dígitos + 1 letra (ej: 12345678X)
- **CIF**: 1 letra + 7 dígitos + 1 dígito/letra (ej: A12345674)
- **NIE**: X, Y o Z + 7 dígitos + 1 letra (ej: X1234567L)

Este identificador aparece en todas tus facturas y es obligatorio para operaciones fiscales en España.

## Contacto

### Email de facturación

Tu email de contacto principal. Se usa para:
- Notificaciones de pagos recibidos
- Alertas de documentos pendientes
- Comunicaciones de Frihet sobre tu cuenta

### Teléfono

Número de contacto que puede aparecer en tus documentos comerciales. El formato se normaliza automáticamente.

### Sitio web (opcional)

Tu URL de empresa. Aparece en documentos si la incluyes en la plantilla de facturación.

## Dirección

### Configuración y autocompletado

Frihet integra autocompletado de direcciones para acelerar la entrada. Escribe la calle y la aplicación sugiere opciones.

Los campos necesarios son:
- **Calle y número**: Dirección completa del domicilio fiscal
- **Código postal**: Obligatorio para validar la provincia
- **Municipio**: Se autocompleta basándose en el código postal
- **Provincia**: Se determina automáticamente

La dirección completa es obligatoria y debe ser tu domicilio fiscal o la dirección donde ejerces tu actividad económica.

## Presentación en documentos

Los datos que configures aquí se insertan automáticamente en:

- **Facturas**: Encabezado y pie del documento
- **Presupuestos**: Datos del vendedor
- **Recibos**: Información de facturación
- **Notas de crédito**: Detalles de la empresa

Puedes revisar cómo se veen en la **vista previa** antes de guardar cambios.

## Declaración responsable VeriFactu

En la parte inferior del perfil fiscal se muestra la **declaración responsable del software**, obligatoria para sistemas de facturación en España (Art. 20 RD 1007/2023).

Esta sección muestra:

| Campo | Valor |
|-------|-------|
| Software | Frihet ERP v1.0 |
| Fabricante | (Se configura en **Ajustes** > **Cumplimiento** > **VeriFactu**) |
| NIF fabricante | (Se configura en **Ajustes** > **Cumplimiento** > **VeriFactu**) |
| Cadena de hash | SHA-256 |
| Normativa | RD 1007/2023, Orden HAC/1177/2024 |

Esta información es de solo lectura y se incluye automáticamente. Para más detalles sobre el cumplimiento de Frihet, consulta la [documentación de VeriFactu](/cumplimiento/verifactu).

## Cambios futuros

Modificar tus datos de empresa afecta a nuevos documentos automáticamente. Los documentos ya emitidos conservan los datos que tenían en el momento de emisión, cumpliendo así con requisitos fiscales de [inmutabilidad](/cumplimiento/inmutabilidad).

Si cambias de dirección o identificador fiscal, actualiza estos datos lo antes posible para mantener la consistencia con tus registros oficiales.

---

## Emails del ciclo de vida
> Path: /configuracion/emails-ciclo-vida

# Emails del ciclo de vida

Frihet envía emails automatizados según el estado de tu cuenta y los hitos que vas alcanzando. Son los mensajes que te ayudan a sacar partido al producto sin tener que descubrir todo por tu cuenta: bienvenida, próximos pasos, recordatorios, resúmenes y reactivación.

## Cómo funciona

El sistema cuenta con un conjunto de 11 plantillas en español e inglés, cada una asociada a un evento de ciclo de vida. Un dispatcher automático se activa cuando ocurre un evento relevante en tu cuenta — registro, primera factura, primer mes facturado, inactividad, vencimientos próximos, hitos fiscales — y selecciona la plantilla correcta para enviarla a través del [sistema de emails](./sistema-emails) integrado.

Las plantillas siguen una cadencia diseñada para acompañarte sin saturar. Tras crear la cuenta, recibes una bienvenida con los primeros pasos. Tras tu primera factura, una guía sobre cobros y conciliación. Si llevas días sin entrar, un mensaje de reactivación con sugerencias basadas en lo que tenías a medio configurar. Antes de cierres trimestrales, un recordatorio con tu situación fiscal del periodo.

Cada email incluye un enlace para revisar y modificar tus preferencias de notificación. Si decides que prefieres no recibir emails de ciclo de vida (por ejemplo, ya conoces el producto a fondo), puedes desactivarlos desde [Notificaciones](./notificaciones) y mantener únicamente los transaccionales — los que llevan información concreta sobre tu cuenta o tus clientes.

El dispatcher está controlado por un flag de rollout. Esto permite al equipo de Frihet activar nuevas plantillas progresivamente y medir su impacto sin afectar a usuarios que ya tienen sus flujos consolidados.

## Configuración

Activos por defecto en todas las cuentas. Puedes desactivar categorías concretas o todos los emails de ciclo de vida desde **Configuración → Notificaciones**. Los emails transaccionales (facturas a clientes, recordatorios de pago activados por ti, confirmaciones de acciones) no se ven afectados — siguen su flujo independiente.

<!-- TODO: confirm with Viktor — listado público de las 11 plantillas concretas y sus disparadores -->

## Ver también

- [Sistema de emails](./sistema-emails)
- [Notificaciones](./notificaciones)
- [Datos de empresa](./datos-empresa)

---

## Multi-Divisa: 71 Paises, 40 Monedas
> Path: /configuracion/multi-divisa

# Multi-Divisa

Frihet soporta facturacion en 40 monedas con precision conforme al estandar ISO 4217. Si facturas a clientes internacionales o trabajas desde fuera de la zona euro, puedes emitir facturas en la moneda local de tu cliente sin configuracion adicional.

## Monedas soportadas

Frihet incluye 40 monedas que cubren 71 paises. Las principales:

| Codigo ISO | Moneda | Simbolo | Decimales |
|------------|--------|---------|-----------|
| EUR | Euro | € | 2 |
| USD | Dolar estadounidense | $ | 2 |
| GBP | Libra esterlina | £ | 2 |
| CHF | Franco suizo | CHF | 2 |
| CAD | Dolar canadiense | CA$ | 2 |
| AUD | Dolar australiano | A$ | 2 |
| JPY | Yen japones | ¥ | 0 |
| KRW | Won surcoreano | ₩ | 0 |
| CNY | Yuan chino | ¥ | 2 |
| INR | Rupia india | ₹ | 2 |
| MXN | Peso mexicano | MX$ | 2 |
| BRL | Real brasileno | R$ | 2 |
| CLP | Peso chileno | $ | 0 |
| COP | Peso colombiano | $ | 2 |
| PEN | Sol peruano | S/ | 2 |
| ARS | Peso argentino | $ | 2 |
| UYU | Peso uruguayo | $U | 2 |
| DOP | Peso dominicano | RD$ | 2 |
| CRC | Colon costarricense | ₡ | 2 |
| SEK | Corona sueca | kr | 2 |
| NOK | Corona noruega | kr | 2 |
| DKK | Corona danesa | kr | 2 |
| PLN | Zloty polaco | zł | 2 |
| CZK | Corona checa | Kč | 2 |
| HUF | Florín hungaro | Ft | 2 |
| RON | Leu rumano | lei | 2 |
| BGN | Lev bulgaro | лв | 2 |
| TRY | Lira turca | ₺ | 2 |
| ZAR | Rand sudafricano | R | 2 |
| AED | Dirham de EAU | د.إ | 2 |
| SAR | Riyal saudi | ﷼ | 2 |
| ILS | Shekel israeli | ₪ | 2 |
| THB | Baht tailandes | ฿ | 2 |
| SGD | Dolar de Singapur | S$ | 2 |
| HKD | Dolar de Hong Kong | HK$ | 2 |
| NZD | Dolar neozelandes | NZ$ | 2 |
| MAD | Dirham marroqui | MAD | 2 |
| NGN | Naira nigeriana | ₦ | 2 |
| EGP | Libra egipcia | E£ | 2 |
| GHS | Cedi ganes | GH₵ | 2 |

## Configuracion

### Moneda por defecto

La moneda por defecto se establece segun el pais configurado en tu perfil fiscal:

1. Ve a **Ajustes** > **Perfil Fiscal**
2. Selecciona tu **pais**
3. La moneda se asigna automaticamente (Espana = EUR, Mexico = MXN, etc.)

### Cambiar moneda por factura

Puedes cambiar la moneda en cada factura individual:

1. Al crear o editar una factura, busca el selector de **Moneda**
2. Selecciona la moneda deseada de la lista
3. Todos los importes de esa factura se calculan en la moneda seleccionada

La moneda de una factura se fija en el momento de emision y no cambia posteriormente.

## Precision y redondeo

Frihet aplica la precision de decimales definida por el estandar ISO 4217 para cada moneda:

- **2 decimales** (mayoria de monedas): EUR, USD, GBP, MXN, BRL, etc.
- **0 decimales** (monedas sin centimos): JPY, KRW, CLP

### Funcionamiento interno

Los importes se almacenan internamente en la unidad menor de cada moneda (minor units):

- Para EUR: `12,50 EUR` se almacena como `1250` (centimos)
- Para JPY: `1500 JPY` se almacena como `1500` (sin subdivision)

Este sistema (`toMinorUnits` / `fromMinorUnits`) evita errores de redondeo en operaciones aritmeticas con decimales flotantes.

### Redondeo en calculos

Al calcular impuestos, subtotales y totales, Frihet:

1. Opera en minor units (enteros)
2. Aplica el porcentaje de impuesto
3. Redondea al entero mas cercano (half-up)
4. Convierte de vuelta a la unidad de presentacion

:::info
Este metodo de calculo con enteros internos es el mismo que usan Stripe, PayPal y otros procesadores de pagos para garantizar precision monetaria.
:::

## Factura PDF

El PDF de cada factura refleja la moneda seleccionada:

- **Simbolo local**: se muestra el simbolo de la moneda (€, $, £, ¥, etc.)
- **Formato numerico**: se adapta segun la convencion del locale (coma decimal en EUR, punto decimal en USD)
- **Codigo ISO**: aparece junto al total para evitar ambiguedad entre monedas que comparten simbolo (USD, CAD, AUD usan `$`)

## Modelos fiscales

Los modelos fiscales espanoles (Modelo 303, Modelo 130, Modelo 420) se presentan siempre en euros, independientemente de la moneda de cada factura.

Cuando una factura esta en moneda distinta al euro:

- Frihet utiliza el importe original en la moneda de la factura para el registro contable
- Los modelos fiscales trimestrales agregan los importes convertidos a EUR
- El libro registro refleja tanto la moneda original como el equivalente en euros

:::warning
Frihet no incluye un servicio de tipos de cambio en tiempo real. Si necesitas conversion a EUR para modelos fiscales, verifica que los importes equivalentes son correctos antes de presentar la declaracion.
:::

## Compatibilidad con integraciones

La funcionalidad multi-divisa es compatible con las integraciones de pago:

| Integracion | Monedas soportadas |
|-------------|-------------------|
| [Stripe](/integraciones/stripe) | 135+ monedas |
| [PayPal](/integraciones/paypal) | 25+ monedas |
| [Revolut](/integraciones/revolut) | 30+ monedas |
| [Wise](/integraciones/wise) | 50+ monedas |
| [Stripe Connect](/integraciones/stripe-connect) | Misma moneda que la cuenta conectada |

Al recibir un pago en una moneda diferente a la de la factura, la integracion registra el pago en la moneda recibida y Frihet lo concilia con la factura correspondiente.

## Preguntas frecuentes

### Puedo tener facturas en distintas monedas en el mismo periodo?

Si. Cada factura es independiente. Puedes emitir una factura en EUR, la siguiente en USD y la siguiente en GBP dentro del mismo trimestre.

### Afecta la moneda al calculo de impuestos?

No. El porcentaje de impuesto se aplica sobre la base imponible en la moneda de la factura. El tipo impositivo (IVA, IGIC) no depende de la moneda.

### Como se exportan las facturas multi-divisa?

La [exportacion contable](/integraciones/exportacion-contable) incluye el codigo de moneda en cada registro. Los formatos Xero y QuickBooks soportan multi-divisa de forma nativa. ContaPlus y DATEV requieren conversion manual a EUR.

---

**Anterior:** [Planes y facturacion](/configuracion/planes-facturacion) | **Relacionado:** [Exportacion Contable](/integraciones/exportacion-contable)

---

## Notificaciones
> Path: /configuracion/notificaciones

# Notificaciones

Mantente al tanto de eventos importantes en tu negocio. Configura qué notificaciones quieres recibir, por qué canales y cuándo.

## Canales disponibles

### Email

El canal principal. Las notificaciones se envían a tu email de facturación configurado en **Datos de empresa**.

Puedes cambiar el email desde **Configuración > Cuenta** sin afectar tu dirección fiscal.

### En la aplicación

Notificaciones dentro de Frihet. Aparecen en el **Centro de notificaciones** (icono de campana) en el navegador principal.

No requieren configuración adicional. Se muestran en tiempo real mientras usas la aplicación.

### Push (próximamente)

Notificaciones push en el navegador y mobile. Disponible en versiones futuras.

## Tipos de notificaciones

### Facturas y pagos

#### Factura emitida
Se envía automáticamente cuando creas una factura. Incluye un resumen del documento.

#### Recordatorio de pago
Se envía a tus clientes (si cuentas con su email) recordándoles pagar dentro del plazo configurado.

- Primer recordatorio: 3 días antes del vencimiento
- Segundo recordatorio: día del vencimiento
- Tercer recordatorio: 5 días después del vencimiento

*Nota: Los recordatorios se envían solo si la factura está marcada como "Pendiente de pago".*

#### Factura pagada
Se notifica cuando un cliente marca un pago en Frihet o cuando se registra manualmente.

#### Pago recibido (integracion bancaria)
Cuando conectas tu banco via [Open Banking](/finanzas/conexiones-bancarias), Frihet detecta pagos automaticamente y concilia con tus facturas.

### Facturas vencidas

#### Alerta de factura vencida
Se envía 1 día después de la fecha de vencimiento si el pago no se ha registrado.

Frecuencia: Una alerta por factura, no repetidas.

#### Resumen de facturas vencidas
Un resumen diario de todas las facturas pendientes de pago con más de 5 días de retraso.

Disponible solo en canales email e in-app.

### Objetivos y metas

#### Alerta de meta alcanzada
Se dispara cuando alcanzas un objetivo configurado (ej: ingresos mensuales, número de clientes).

Puedes recibir alertas por cada meta o una sola por período.

### Digests (resúmenes periódicos)

#### Resumen semanal
Todos los lunes a las 9:00 AM:
- Ingresos y gastos de la semana
- Facturas pendientes de cobro
- Cambios importantes en tu actividad

#### Resumen mensual
Primer día del mes a las 9:00 AM:
- Resumen fiscal del mes anterior
- Ingresos, gastos, beneficio neto
- Impuestos estimados (IVA, IRPF si aplica)
- Tendencias respecto a meses anteriores

### Fechas fiscales

#### Recordatorios de impuestos
- Declaración trimestral de IVA (últimos días del trimestre)
- Estimación de declaración de la renta (si corresponde)
- Vencimiento de pagos fiscales

Estos recordatorios se basan en tu régimen fiscal configurado.

## Horario de tranquilidad

### Configuración

Define un rango horario en el que no deseas recibir notificaciones:

```
Ejemplo:
Desde las 22:00 hasta las 08:00
```

**Excepción**: Las alertas críticas (factura vencida, cambios de seguridad) se envían igualmente durante este período.

Las notificaciones que habrían llegado en horario de tranquilidad se entregan en la siguiente ventana activa.

## Preferencias por tipo

### Activa/desactiva por canal

Para cada tipo de notificación, puedes elegir:
- Recibir por email
- Recibir en la app
- No recibir

```
Ejemplo de configuración:
Factura emitida          → Email + App
Recordatorio de pago     → Email
Alerta de vencimiento    → Email + App
Resumen mensual          → Email
Push (en el futuro)      → App
```

### Configuración global por canal

Puedes desactivar completamente un canal (ej: no recibir emails de ningún tipo) desde **Canales**.

Esto sobrescribe las preferencias individuales.

## Frecuencia de notificaciones

Para evitar sobrecarga:

- **Máximo 1 notificación por evento**: No recibirás duplicados
- **Agrupación automática**: Múltiples eventos en el mismo período se agrupan en un digest
- **Deduplicación**: Si hay varias condiciones que disparan la misma alerta, recibirás una sola

## Historial y centro de notificaciones

Accede al **Centro de notificaciones** para:
- Ver todas las notificaciones recibidas
- Marcar como leídas
- Archivar o eliminar
- Acceder a acciones rápidas (ej: ver factura pendiente)

El historial se mantiene durante 30 días.

## Integración futura

Estamos trabajando en:
- Integración con Slack
- [Webhooks personalizados](/desarrolladores/webhooks)
- Notificaciones SMS
- Alertas basadas en umbrales personalizados

---

## Personalización
> Path: /configuracion/personalizacion

# Personalización

Personaliza la apariencia de tus documentos para reflejar tu marca. Logo, colores y formatos de numeración son elementos clave en tu identidad fiscal y comercial.

## Logo

### Carga tu logo

Sube un logo en formato **PNG** o **SVG** con transparencia. El tamaño recomendado es **1000x400 px** o superior para mantener calidad en impresiones.

El logo aparece en la esquina superior izquierda de:
- Facturas
- Presupuestos
- Notas de crédito
- Recibos

### Requisitos técnicos

- **Formatos**: PNG, SVG (sin estilos CSS externos)
- **Tamaño máximo**: 5 MB
- **Resolución mínima**: 150 DPI para impresión
- **Transparencia**: Recomendada para flexibilidad

### Consejos de diseño

El logo debe ser legible en blanco y negro, ya que los PDFs pueden imprimirse en escala de grises. Evita degradientes o efectos que no se rendericen correctamente en impresoras antiguas.

## Color de marca

### Configuración del color de acento

Elige un color hexadecimal que se aplicará a:
- Encabezados en facturas y presupuestos
- Bordes y líneas divisorias
- Botones en PDFs interactivos (si aplica)

El color por defecto es **#1F2937** (gris oscuro). Puedes usar cualquier hexadecimal válido.

```
Ejemplo:
#2563EB (azul)
#DC2626 (rojo)
#059669 (verde)
```

La aplicación te muestra una vista previa en tiempo real de cómo lucirá tu documento con el color seleccionado.

## Pie de página

### Texto personalizado en documentos

Añade un texto en el pie de página que aparecerá en todas tus facturas, presupuestos y notas de crédito.

Casos de uso comunes:
- Datos bancarios (IBAN, BIC)
- Términos de pago
- Información legal o de contacto
- Números de registro o licencia

**Límite**: 500 caracteres. El texto se ajusta automáticamente al ancho del documento.

```
Ejemplo:
Banco: BBVA | IBAN: ES91 0182 0981 2300 0123 4567
Plazo de pago: 30 días desde emisión
CIF: A12345678 | Inscrita en el Registro Mercantil
```

## Numeración de documentos

### Patrones personalizados

Frihet genera automáticamente números secuenciales para facturas, presupuestos y otros documentos. Puedes personalizar el formato.

#### Variables disponibles

- `{YEAR}`: Año actual (ej: 2024)
- `{MONTH}`: Mes (01-12)
- `{SEQ}`: Número secuencial (reinicia anualmente)
- `{CUSTOM}`: Prefijo personalizado

#### Ejemplos

```
FAC-2024-{SEQ}        → FAC-2024-0001, FAC-2024-0002
{YEAR}{MONTH}-{SEQ}   → 202401-0001, 202401-0002
INV-{CUSTOM}-{SEQ}    → INV-ACME-0001, INV-ACME-0002
{SEQ}/{YEAR}          → 0001/2024, 0002/2024
```

### Configuración por tipo de documento

Puedes usar patrones diferentes para:
- **Facturas**: `FAC-{YEAR}-{SEQ}`
- **Presupuestos**: `PRES-{YEAR}-{SEQ}`
- **Notas de crédito**: `NC-{YEAR}-{SEQ}`
- **Recibos**: `REC-{YEAR}-{SEQ}`

Frihet mantiene un contador independiente para cada tipo, asegurando que no haya duplicados.

## Vista previa

Antes de aplicar cambios, la aplicación genera una vista previa interactiva mostrando cómo se vería un documento con tu configuración.

Si no estás satisfecho, realiza ajustes y vuelve a generar la vista previa. Los cambios no se aplican hasta que hagas clic en **Guardar**.

## Aplicación a documentos existentes

Los cambios de personalización afectan **solo a documentos nuevos**. Los ya emitidos conservan su formato original, manteniendo la inmutabilidad requerida por ley.

Si necesitas regenerar documentos antiguos, descárgalos con la nueva configuración desde el detalle del documento (opción **Regenerar PDF**).

---

## Planes y facturación
> Path: /configuracion/planes-facturacion

# Planes y facturación

Frihet ofrece planes flexibles según tus necesidades. Empieza gratis y sube de plan cuando quieras. Consulta la [página de precios](https://www.frihet.io/es/pricing) para ver los detalles actualizados y comparar planes.

En ningún plan de pago el número de facturas es un muro: **facturas ilimitadas** en Free, Pro y Premium. Lo que separa los planes son las funcionalidades avanzadas, no cuántas facturas emites.

## Planes disponibles

### Plan Gratuito

**Costo**: Gratis para siempre

Perfecto para negocios que están comenzando.

**Incluye**:
- Facturas y presupuestos: Ilimitados
- Documentos escaneados: 5 por mes
- Mensajes de IA: 30 por mes
- Clientes: Ilimitados
- Dashboard financiero y multi-moneda (170+)
- VeriFactu incluido
- Soporte: Email (respuesta en 24-48h)

**Perfectamente válido para**:
- Autónomos y negocios que empiezan
- Pequeños negocios en fase de prueba
- Usuarios que quieren declarar y operar sin drama

No requiere tarjeta de crédito.

### Plan Pro

**Costo**: 9 €/mes (equivalente ~$10 USD · ~£8 GBP). Anual: 90 €/año.

El plan lean para autónomos y profesionales independientes: "declaro y opero sin drama".

**Incluye**:
- Facturas y presupuestos: Ilimitados
- Documentos escaneados: 50 por mes
- Mensajes de IA: 100 por mes
- Clientes: Ilimitados
- Descuentos: ~16,7% en facturación anual

**Funcionalidades incluidas**:
- Todo del plan Gratuito
- Modelos fiscales exportables (Modelo 303/130/390 · TXT + PDF para tu gestor o la Sede Electrónica)
- CRM, banco y fiscalidad
- Facturas recurrentes
- Notas de crédito y pagos parciales
- Portal de cliente
- Series y branding personalizados
- Importación CSV y roles de equipo

**Qué usuarios típicos usan**:
- Consultor técnico con 5-10 clientes
- Pequeña agencia (1-3 personas)
- Profesional liberal activo

Puedes cambiar a este plan en cualquier momento. Se facturará prorrateado.

### Plan Premium

**Costo**: 29 €/mes (equivalente ~$33 USD · ~£26 GBP). Anual: 290 €/año.

El plan con el moat: la plataforma avanzada, la IA agéntica y la contabilidad profesional.

**Incluye**:
- Facturas y presupuestos: Ilimitados
- Documentos escaneados: 200 por mes
- Mensajes de IA: 500 por mes
- Clientes: Ilimitados
- Descuentos: ~16,7% en facturación anual

**Funcionalidades incluidas**:
- Todo del plan Pro
- e-invoicing / Facturae (B2B/B2G)
- [Acceso a API](/desarrolladores/api-rest), [webhooks](/desarrolladores/webhooks) y automatizaciones
- Conciliación bancaria avanzada
- Contabilidad de partida doble y exportación contable avanzada
- Panel de gestoría (multi-cliente)
- People / RRHH
- Cofundador IA (Beta) · 100 ejecuciones/mes

**Qué usuarios típicos usan**:
- Gestoría o asesoría multi-cliente
- Agencia o pequeña empresa (5-50 personas)
- Consultoría multidisciplinar

Ideal si necesitas plataforma avanzada, contabilidad profesional y automatización con IA.

### Plan Enterprise

**Costo**: Personalizado

Para grandes organizaciones con requisitos específicos.

**Incluye**:
- Todo del plan Premium
- API dedicada
- Roles y permisos granulares
- SLA garantizado
- Integración personalizada
- Soporte 24/7 con account manager
- Auditoría y compliance específicos (SOC2, etc.)

**Cómo contratar**: Contacta a sales@frihet.io

## Cómo cambiar de plan

### Upgrade (cambio a plan superior)

1. Ve a **Configuración > Facturación > Tu plan**
2. Selecciona el nuevo plan
3. Revisa el resumen de cambios (te muestran el prorrateo)
4. Haz clic en **Actualizar a [Plan]**
5. Confirma el pago con Stripe

**Prorrateo**: Si cambias a mitad de mes, se te acredita el tiempo no usado del plan anterior en la nueva factura.

Ejemplo:
```
Usabas Pro (9 €/mes) desde el 1º de febrero
El 15 de febrero cambias a Premium (29 €/mes)
Crédito de 14 días de Pro: -4,20 €
Cobro: 29 € (nuevo plan) - 4,20 € = 24,80 €
```

### Downgrade (cambio a plan inferior)

1. Ve a **Configuración > Facturación > Tu plan**
2. Selecciona el plan más barato
3. Se te informará sobre los límites que aplicarán (escaneos, mensajes de IA)
4. Confirma el cambio

**Cuándo se aplica**: El cambio entra en vigencia el próximo ciclo de facturación. No hay prorrateo en downgrades.

Tus facturas nunca se ven afectadas por un downgrade: la facturación es ilimitada en todos los planes.

### Cancelar suscripción

Si cancelas tu plan de pago, tu cuenta volverá al **Plan Gratuito** automáticamente.

1. Ve a **Configuración > Facturación**
2. Haz clic en **Cancelar suscripción**
3. Selecciona un motivo (opcional, nos ayuda a mejorar)
4. Confirma

Tu acceso a Frihet no se pierde, solo se aplicarán los límites del Plan Gratuito a partir del próximo período.

**Nota**: No se ofrecen reembolsos por tiempo no usado si cancelas antes de fin de mes.

## Métodos de pago

### Stripe Billing

Frihet usa **Stripe Billing** para gestionar todas las suscripciones. Esto garantiza:

- **Seguridad PCI**: Tu tarjeta nunca se almacena en nuestros servidores
- **Múltiples métodos**: Tarjeta débito, crédito, Apple Pay, Google Pay
- **Facturas automáticas**: Cada mes recibirás tu recibo
- **Gestión segura**: Dashboard en Stripe para cambiar tarjeta, descargar facturas, ver historial

### Cambiar método de pago

En **Configuración > Facturación > Método de pago**:

1. Haz clic en **Editar método de pago**
2. Serás redirigido a Stripe
3. Añade una nueva tarjeta
4. Confirma

La nueva tarjeta se usará en el próximo cargo automático.

### Facturas y recibos

Recibirás automáticamente una factura por email el día de cada cobro.

También puedes descargar todas tus facturas desde **Configuración > Facturación > Historial de pagos**.

Las facturas están en PDF e incluyen:
- Detalles de tu suscripción
- Período de facturación
- Cantidad cobrada
- Método de pago

## Exceso de límites (overage)

En Frihet nunca hay cargos sorpresa por exceso. Si alcanzas un límite mensual, recibirás una sugerencia de upgrade, no un cobro automático.

### Facturas

No hay límite de facturas en ningún plan (Free, Pro y Premium): factura sin muros.

### Documentos escaneados (Free: 5/mes · Pro: 50/mes · Premium: 200/mes)

El escaneo se detiene cuando alcanzas el límite. Espera al mes siguiente o sube a un plan superior.

### Mensajes de IA (Free: 30/mes · Pro: 100/mes · Premium: 500/mes)

Funciona igual que documentos escaneados. Se bloquea al alcanzar el límite.

**No hay sorpresas**: Nunca se cobra automáticamente por exceso. Solo recibirás sugerencias de upgrade.

## Ciclo de facturación

Los ciclos son **mensuales** y se calculan desde tu fecha de contratación.

Ejemplo:
```
Contrataste el 15 de febrero
Ciclos: 15 Feb - 15 Mar, 15 Mar - 15 Abr, etc.
Cada 15 se cobra automáticamente
```

## Retención de datos tras cancelación

Si cancelas tu plan de pago y vuelves a Gratuito:

- Mantienes acceso a tus datos
- Se aplican los límites del plan Gratuito
- Puedes exportar tus datos en cualquier momento (ver [Seguridad](/configuracion/seguridad))
- Después de 90 días sin actividad, tu cuenta se marcará como inactiva

Si no te conectas durante 180 días con plan Gratuito, tu cuenta puede ser eliminada (con notificación previa de 30 días).

## Preguntas frecuentes

**¿Puedo cambiar de plan a mitad de mes?**

Sí. Se prorratea automáticamente.

**¿Hay descuentos anuales?**

Sí. Paga 12 meses por adelantado y ahorra ~16,7% (unos dos meses gratis) en Pro y Premium.

**¿Cuántas facturas puedo emitir?**

Ilimitadas, en cualquier plan (incluido el Gratuito). El número de facturas nunca es el límite.

**¿Qué pasa si me olvido de actualizar mi tarjeta?**

Intentaremos cobrar 3 veces (días 1, 5 y 10). Si falla, tu plan se suspenderá hasta que actualices el método de pago. Tus datos no se pierden.

**¿Puedo recuperar mi cuenta después de cancelar?**

Sí, en cualquier momento. Tus datos se mantienen en el Plan Gratuito durante 180 días.

**¿Necesito contrato o compromiso?**

No. Puedes cancelar cuando quieras sin penalización.

---

## Programa de referidos
> Path: /configuracion/programa-referidos

<!-- AUTO-STUB 2026-05-05 -->

# Programa de referidos

> Gana una comisión recurrente del 30% por cada cliente que refieras a Frihet mientras mantenga su suscripción activa.

## Overview

El programa de referidos de Frihet te permite generar ingresos pasivos compartiendo la herramienta con otros autónomos, pymes o gestorías. Cada cuenta tiene un código de referido único. Cuando alguien se registra usando tu enlace y activa una suscripción de pago, empiezas a recibir comisiones mensuales.

Desde el panel de referidos puedes ver en tiempo real cuántos contactos has invitado, cuántos se han registrado, cuántos han activado una suscripción y cuánto has ganado hasta la fecha.

## Quick start

1. Ve a **Configuración → Programa de referidos** o busca "referidos" en el buscador de ajustes.
2. Copia tu enlace único o comparte directamente por email.
3. Sigue el estado de cada referido en el panel (invitado → registrado → activado → pagando).

## Reference

- Panel: Configuración → Programa de referidos
- Para gestorías: el panel de gestoría incluye una tarjeta de estadísticas de referidos con métricas en vivo.

## Related

- [Gestiona tu plan](./planes-facturacion)
- [Panel de gestoría](/equipo/gestoria)

---

## App móvil (PWA)
> Path: /configuracion/pwa-app-movil

<!-- AUTO-STUB 2026-05-05 -->

# App móvil (PWA)

> Frihet es una Progressive Web App (PWA): instálala en tu móvil, tablet o escritorio para acceder sin browser, recibir notificaciones y usar funciones offline — sin tiendas de apps, sin actualizaciones manuales.

## Overview

Frihet funciona como una app nativa gracias a la tecnología PWA. Una vez instalada:

- Se abre como app independiente (sin barra de navegación del browser).
- Funciona offline para consulta de facturas, clientes y datos ya cargados.
- Actualiza automáticamente en segundo plano.
- Incluye accesos directos en pantalla de inicio: Nueva factura, Nuevo gasto, Dashboard, Contactos.
- Recibe fotos y PDFs compartidos desde otras apps directamente en el flujo de escaneo OCR de gastos.

El caché de la app ocupa menos de 750 KB (optimizado desde 20 MB originales) para respetar el almacenamiento de tu dispositivo.

## Quick start

1. **Android (Chrome)**: Abre [app.frihet.io](https://app.frihet.io) en Chrome → menú (⋮) → **Añadir a pantalla de inicio**.
2. **iOS (Safari)**: Abre [app.frihet.io](https://app.frihet.io) en Safari → botón compartir → **Añadir a pantalla de inicio**.
3. **Escritorio (Chrome/Edge)**: Busca el icono de instalación (⊕) en la barra de direcciones.

## Reference

- No requiere configuración adicional. La PWA se activa automáticamente.

## Related

- [Primeros pasos](/primeros-pasos/crear-cuenta)
- [Escaneo OCR de gastos](/gastos/escaneo-ocr)
- [Atajos de teclado](/primeros-pasos/atajos-teclado)

---

## Autenticación en dos pasos (2FA / MFA)
> Path: /configuracion/seguridad-mfa

<!-- AUTO-STUB 2026-05-05 -->

# Autenticación en dos pasos (2FA / MFA)

> Protege tu cuenta con autenticación TOTP de dos factores compatible con Google Authenticator, Authy, 1Password y cualquier app de autenticación estándar.

## Overview

Frihet implementa autenticación multifactor (MFA) mediante TOTP (Time-based One-Time Password) a través de su plataforma de identidad gestionada. Una vez activado, cada inicio de sesión requiere el código de 6 dígitos generado por tu app de autenticación — además de tu contraseña.

Si activas MFA, también recibirás un conjunto de códigos de recuperación de un solo uso para casos de emergencia en los que no tengas acceso a tu dispositivo.

## Quick start

1. Ve a **Configuración → Seguridad → Autenticación en dos pasos**.
2. Pulsa **Activar 2FA** y escanea el código QR con tu app de autenticación (Google Authenticator, Authy, 1Password…).
3. Introduce el código de 6 dígitos para verificar la configuración y guarda los códigos de recuperación en un lugar seguro.

## Reference

- Settings: Configuración → Seguridad → Autenticación en dos pasos
- Recurso: [Google Authenticator](https://support.google.com/accounts/answer/1066447)

## Related

- [Seguridad de la cuenta](./seguridad)
- [Sesiones activas](./seguridad)
- [Gestión del plan y facturación](./planes-facturacion)

---

## Seguridad
> Path: /configuracion/seguridad

# Seguridad

Tu cuenta y datos son tu responsabilidad compartida con nosotros. Frihet implementa estándares de seguridad industria en cloud, pero tú controlas el acceso a tu cuenta.

## Autenticación

### Login con Cloudflare Turnstile

Al iniciar sesión, Frihet valida tu identidad usando **Cloudflare Turnstile**, un sistema de prueba de humanidad sin CAPTCHA tradicional.

Este proceso:

- Ocurre una sola vez por sesión
- No requiere acciones adicionales en la mayoría de casos
- Previene acceso automatizado a tu cuenta

Si experimentas problemas, asegúrate de que el JavaScript está habilitado en tu navegador.

### Código de verificación por email

Después de autenticarte, recibirás un email con un código de 6 dígitos válido por 15 minutos.

Este paso adicional garantiza que realmente eres tú quien intenta acceder.

**Nota**: Si no recibiste el código, revisa tu carpeta de spam.

### Autenticación

Frihet gestiona las sesiones mediante autenticación gestionada de grado empresarial. Tu contraseña se almacena encriptada y nunca es accesible directamente.

## Gestión de contraseña

### Requisitos

Una contraseña válida debe tener:

- Mínimo 12 caracteres
- Al menos 1 mayúscula, 1 minúscula, 1 número y 1 carácter especial

Ejemplos válidos:

```
Fr1het!2024Secure
P@ssw0rd#Frihet
Banca$2024*Segura
```

### Cambiar contraseña

En **Configuración > Seguridad > Contraseña**:

1. Confirma tu contraseña actual
2. Introduce la nueva contraseña (respetando requisitos)
3. Confirma la nueva contraseña
4. Haz clic en **Actualizar**

Se cerrará sesión en todos tus dispositivos. Deberás iniciar sesión nuevamente con la nueva contraseña.

### Recuperación de contraseña olvidada

Si olvidas tu contraseña:

1. En la pantalla de login, haz clic en **¿Olvidaste tu contraseña?**
2. Ingresa tu email
3. Recibirás un email con un enlace de recuperación
4. El enlace es válido por 1 hora
5. Crea una nueva contraseña

## Dispositivos y sesiones

### Sesiones activas

Desde **Configuración > Seguridad > Dispositivos**, puedes:

- Ver todos los dispositivos donde tienes sesión iniciada
- Información: navegador, sistema operativo, IP, última actividad
- Cerrar sesión en dispositivos específicos

```
Ejemplo:
Chrome en macOS, IP: 192.168.1.100, Última actividad: 2 min
Safari en iOS, IP: 192.168.1.101, Última actividad: 1 hora
```

### Cierre de sesión automático

Las sesiones inactivas se cierran automáticamente después de **30 días**.

Si intentas acceder desde un dispositivo no reconocido, se te pedirá verificación adicional.

## Autorización y permisos

En versiones futuras, Frihet soportará **roles y permisos** para gestionar acceso en equipos:

- Owner (control total)
- Admin (casi todos los permisos)
- Accountant (solo acceso a facturas y gastos)
- Viewer (lectura)

Por ahora, tu cuenta tiene acceso total.

## Privacidad de datos

### Datos que recopilamos

- Datos de tu empresa (nombre, NIF, dirección)
- Facturas, gastos, clientes, proveedores
- Analítica de uso (alojada en la UE)
- Logs de acceso y cambios

**No recopilamos**:

- Contraseñas en texto plano
- Datos de tarjeta de crédito (gestionados por Stripe)
- Cookies de seguimiento

### Cumplimiento GDPR

Tienes derecho a:

- **Acceso**: Descargar una copia de todos tus datos
- **Rectificación**: Corregir información inexacta
- **Portabilidad**: Exportar datos en formato estándar
- **Olvido**: Eliminar tu cuenta y datos

## Exportación de datos (GDPR)

### Descarga tus datos

En **Configuración > Privacidad > Exportar datos**:

1. Haz clic en **Solicitar exportación**
2. Recibirás un email con un enlace
3. El archivo contiene:
   - Todos tus clientes, facturas, gastos
   - Configuración de cuenta
   - Historial de cambios

El archivo es un `.zip` con datos en JSON y CSV, compatible con cualquier software.

La exportación se genera en máximo 48 horas.

### Formato de exportación

```
frihet-export-2024-02-09.zip
├── clientes.json
├── facturas.csv
├── gastos.csv
├── configuracion.json
└── historial_cambios.json
```

## Eliminación de cuenta (derecho al olvido)

### Proceso

En **Configuración > Privacidad > Eliminar cuenta**:

1. Lee la advertencia (es irreversible)
2. Confirma tu contraseña
3. Haz clic en **Eliminar cuenta permanentemente**

Se iniciará un proceso de 30 días:

- **Días 1-30**: Tu cuenta estará inactiva, datos ocultos
- **Día 30**: Eliminación permanente de bases de datos
- **No reversible**: No podrás recuperar tu cuenta

Antes de eliminar, puedes exportar tus datos (ver sección anterior).

## Incidentes de seguridad

Si sospechas que tu cuenta ha sido comprometida:

1. **Cambia tu contraseña inmediatamente**
2. **Cierra todas las sesiones** en Configuración > Seguridad
3. **Contacta a soporte**: security@frihet.io

Frihet investigará y te notificará de cualquier acceso no autorizado detectado.

## Claves de API

Si utilizas la [API REST](/desarrolladores/api-rest) o el [servidor MCP](/desarrolladores/mcp-server) de Frihet, puedes gestionar tus claves de API desde **Configuracion > API**. Cada clave empieza por `fri_` y tiene permisos de lectura y escritura sobre los recursos de tu cuenta.

Recomendaciones:

- Genera claves independientes para cada integracion o entorno
- Revoca claves que ya no utilices
- No compartas claves en repositorios publicos ni en texto plano

Para mas detalles, consulta la [seccion de autenticacion de la API](/desarrolladores/api-rest#autenticacion).

## Auditoria y cumplimiento

Frihet mantiene:

- Registro inmutable de cambios (Audit Trail)
- Cumplimiento TicketBAI en Euskadi
- Trazabilidad de todas las operaciones
- Backups cifrados diarios

Para detalles técnicos, consulta nuestra documentación sobre [TicketBAI y facturación electrónica](/legal/ticketbai).

---

## Sistema de emails
> Path: /configuracion/sistema-emails

# Sistema de emails

Frihet envía todos los emails transaccionales y de ciclo de vida a través de Resend, el proveedor de entregabilidad integrado en la plataforma. Esto incluye facturas, recordatorios de pago, confirmaciones de acción, mensajes de bienvenida y notificaciones de eventos relevantes para tu cuenta y tus clientes.

## Cómo funciona

Cuando emites una factura, registras un cobro o ejecutas una acción que dispara una comunicación, Frihet genera el email con la plantilla correspondiente y lo entrega a Resend para envío inmediato. El sistema sigue las mejores prácticas de entregabilidad — DKIM, SPF, DMARC alineados con `frihet.io` por defecto — lo que reduce el riesgo de que tus emails caigan en spam.

Los emails transaccionales se envían en el momento del evento (factura emitida, pago confirmado, recordatorio manual). Los emails de ciclo de vida siguen reglas automatizadas y se programan según el estado de tu cuenta: bienvenida tras crear cuenta, sugerencias tras la primera factura, mensajes de reactivación si llevas tiempo sin entrar, resúmenes semanales o mensuales según tus preferencias.

Cada email incluye una cabecera con el logo y la marca de tu negocio cuando va dirigido a un cliente (por ejemplo, una factura). Los emails internos del producto usan la marca Frihet. Los enlaces transaccionales (ver factura, pagar, confirmar) son firmados y caducan según la política de seguridad de cada flujo.

Si un email no se entrega (bounce permanente, dirección inexistente, dominio rechazado), Frihet registra el evento y lo refleja en la actividad del documento o de la cuenta. Los bounces temporales se reintentan automáticamente según la política de Resend.

## Configuración

La configuración de remitente, replyTo y dominio personalizado vive en **Configuración → Datos de empresa** y **Configuración → Personalización**. Si quieres enviar emails desde tu propio dominio (`facturas@tu-negocio.com` en lugar del default Frihet), abre soporte para activar el dominio personalizado tras verificar registros DNS.

Para gestionar qué emails de ciclo de vida quieres recibir y por qué canales, ve a [Notificaciones](./notificaciones).

## Ver también

- [Notificaciones](./notificaciones)
- [Datos de empresa](./datos-empresa)
- [Personalización](./personalizacion)
- [Emails del ciclo de vida](./emails-ciclo-vida)

---

## Webhooks
> Path: /configuracion/webhooks-config

# Webhooks

> Conecta Frihet a tu stack en tiempo real: 94 tipos de eventos, firma HMAC y reintentos automaticos.

## Overview

Los webhooks de Frihet envian notificaciones HTTP a tu servidor cuando ocurren eventos en la cuenta: facturas creadas o pagadas, gastos nuevos, clientes actualizados, modelos fiscales generados, etc. Cada entrega incluye una firma HMAC-SHA256 en la cabecera `X-Frihet-Signature` para verificar la autenticidad. Si tu servidor devuelve un error, Frihet reintenta automaticamente con backoff exponencial hasta 5 veces. El log de entregas muestra el historial de intentos por endpoint.

## Quick start

1. Ve a Configuracion → **Webhooks** → **Nuevo endpoint**
2. Pega la URL de tu servidor y selecciona los tipos de evento que quieres recibir
3. Copia el secreto de firma y verifica la firma en tu servidor antes de procesar eventos

## Reference

- API: `GET /v1/webhooks` (listar endpoints), `POST /v1/webhooks` (crear), `DELETE /v1/webhooks/:id`
- MCP tool: `manage_webhooks` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Configuracion → Desarrolladores → Webhooks

---

## Widget de feedback
> Path: /configuracion/widget-feedback

# Widget de feedback

Frihet integra Canny como widget de feedback in-app para que los usuarios envíen sugerencias, voten ideas existentes y vean el estado de las peticiones de funcionalidad sin salir de la aplicación.

## Cómo funciona

El widget aparece como un punto de entrada accesible desde la barra lateral o el menú de ayuda de Frihet. Al abrirlo, se muestra el panel de Canny embebido con el feed de ideas: lo que está pedido por la comunidad, lo que está en consideración, en desarrollo y lo que ya está enviado a producción.

Puedes hacer tres cosas desde el widget. **Crear una nueva idea** describiendo qué necesitas y por qué. **Votar** ideas existentes para ayudar al equipo de producto a priorizar lo que más impacto tiene. **Suscribirte** a una idea concreta para recibir actualizaciones por email cuando cambie de estado.

Cuando una sugerencia tuya cambia de estado — por ejemplo, pasa a "en desarrollo" o "enviado" — recibes una notificación. Las ideas enviadas a producción quedan enlazadas con la entrada de changelog correspondiente, de forma que puedas leer exactamente qué se ha cambiado.

El feedback es público dentro del board de Frihet: otras personas usuarias verán tu sugerencia y podrán votar. No se comparten datos sensibles de tu cuenta — solo el texto que tú decides escribir.

## Configuración

El widget está activo por defecto en todas las cuentas y no requiere configuración explícita por parte del usuario. Si prefieres no usarlo, puedes ignorarlo: ningún flujo lo requiere para operar Frihet.

Para soporte directo en lugar de feedback público, usa el correo [ayuda@frihet.io](mailto:ayuda@frihet.io) o el chat de soporte si está disponible en tu plan.

## Ver también

- [Notificaciones](./notificaciones)
- [Centro de ayuda](https://www.frihet.io/es/contact)

---

## Asientos manuales y cierre de ejercicio
> Path: /contabilidad/asientos-manuales

<!-- AUTO-STUB 2026-05-05 -->

# Asientos manuales y cierre de ejercicio

> Registra ajustes contables manuales con selección de cuentas PGC y ejecuta el proceso de cierre de ejercicio con transferencia automática de resultados a reservas.

## Overview

Frihet genera asientos automáticamente para el ciclo completo de facturas, pagos y gastos. Para ajustes específicos (periodificaciones, correcciones, amortizaciones manuales) puedes crear asientos de diario directamente desde `Contabilidad → Asientos Contables`. Cada asiento requiere que la suma de débitos iguale a la de créditos.

El cierre de ejercicio transfiere el saldo de la cuenta de Pérdidas y Ganancias a Reservas (cuenta 129), bloquea el periodo cerrado contra nuevas escrituras y genera los asientos de apertura del ejercicio siguiente.

## Quick start

1. Ve a **Contabilidad → Asientos Contables** y pulsa **Nuevo asiento**.
2. Añade las líneas de débito y crédito seleccionando cuentas del Plan General Contable. El sistema te avisará si el asiento no cuadra.
3. Para cerrar el ejercicio, ve a **Configuración → Perfil fiscal → Cierre de ejercicio** y sigue el asistente de 3 pasos.

## Reference

- API: `POST /v1/accounting/journal-entries` — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `create_journal_entry` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Configuración → Perfil fiscal → Cierre de ejercicio

## Related

- [Informes contables](./informes-contables)
- [Plan de cuentas](./plan-cuentas)
- [Bloqueo de periodo fiscal](./bloqueo-periodo)

---

## Audit trail de asientos contables
> Path: /contabilidad/audit-trail-asientos

# Audit trail de asientos contables

El audit trail de asientos garantiza que cada modificacion en el libro mayor (GL) quede registrada con quien la hizo, cuando y por que. Es un requisito de cumplimiento para empresas sujetas a normativas GoBD (Alemania), SIBA (Islas Baleares) y buenas practicas contables en general.

Frihet implementa un flujo de aprobacion de dos niveles: el contable propone el asiento y el responsable financiero lo aprueba o rechaza antes de que quede firme.

## Roles y permisos

| Rol en Frihet              | Puede crear | Puede aprobar | Puede rechazar | Puede ver historial |
| -------------------------- | ----------- | ------------- | -------------- | ------------------- |
| **Contable**               | Si          | No            | No             | Si (propios)        |
| **Responsable financiero** | Si          | Si            | Si             | Si (todos)          |
| **Administrador**          | Si          | Si            | Si             | Si (todos)          |
| **Solo lectura**           | No          | No            | No             | Si (todos)          |

Configura los roles en **Configuracion** → **Equipo** → **Permisos contabilidad**.

## Flujo de aprobacion

### 1. Creacion del asiento (estado: Borrador)

El contable crea el asiento en **Contabilidad** → **Asientos manuales** → **Nuevo asiento**. Mientras esta en borrador, puede editarlo libremente. Los borradores no aparecen en los informes contables oficiales.

### 2. Envio a aprobacion (estado: Pendiente)

Al hacer clic en **Enviar para aprobacion**, el asiento pasa a estado **Pendiente** y:

- El responsable financiero recibe una notificacion (email + Telegram si configurado).
- El asiento queda bloqueado — el contable ya no puede editarlo.
- Aparece en la cola **Contabilidad** → **Pendientes de aprobacion**.

### 3a. Aprobacion (estado: Aprobado)

El responsable financiero revisa el asiento y hace clic en **Aprobar**. Frihet:

- Fija el asiento en el libro mayor con marca de tiempo inmutable.
- Registra en el historial: aprobado por, fecha y hora (UTC).
- Notifica al contable que creo el asiento.

Un asiento aprobado **no puede modificarse**. Si hay un error, debe crearse un asiento de correccion (contraasiento o ajuste).

### 3b. Rechazo (estado: Rechazado)

Si el asiento tiene errores, el responsable lo rechaza indicando el motivo. El contable recibe la notificacion con el motivo de rechazo y puede corregir el borrador y reenviarlo.

```
Ejemplo de motivo de rechazo:
"La cuenta 629 no corresponde — usar 627 (Publicidad) segun PGC."
```

## Historial de auditoria

Cada asiento tiene una pestana **Historial** que muestra el log inmutable de todos los estados:

```
2026-05-10 09:14 UTC  [CREADO]    Maria Lopez (contable@empresa.com)
2026-05-10 09:20 UTC  [ENVIADO]   Maria Lopez → pendiente aprobacion
2026-05-10 11:03 UTC  [RECHAZADO] Carlos Ruiz — "Cuenta incorrecta: usar 627"
2026-05-10 11:45 UTC  [EDITADO]   Maria Lopez — correccion cuenta 629 → 627
2026-05-10 11:46 UTC  [ENVIADO]   Maria Lopez → pendiente aprobacion
2026-05-10 12:01 UTC  [APROBADO]  Carlos Ruiz
```

El historial no puede borrarse ni modificarse. Es el registro oficial para auditorias externas.

## Exportacion para auditoria externa

Exporta el audit trail completo en **Contabilidad** → **Audit trail** → **Exportar**:

- **PDF**: informe legible para auditores.
- **CSV**: datos estructurados para analisis.
- **JSON**: integracion con herramientas de GRC (Governance, Risk, Compliance).

El export incluye: asiento, cuentas, importes, usuario creador, usuario aprobador, timestamps completos y motivos de rechazo si aplica.

## Cumplimiento GoBD y SIBA

### GoBD (Alemania)

El estandar GoBD exige que los registros contables sean **inmutables, trazables y recuperables** durante 10 anos. El audit trail de Frihet cumple los principios GoBD:

- **Unveranderbarkeit** (inmutabilidad): asientos aprobados no pueden modificarse.
- **Nachvollziehbarkeit** (trazabilidad): cada cambio tiene usuario, fecha y motivo.
- **Maschinelle Auswertbarkeit** (exportabilidad): export JSON/CSV disponible.

### SIBA (Islas Baleares)

El Seminar fur Interne Buchfuhrung y Aufsicht (SIBA) aplica para empresas con sede en Baleares con actividad en Alemania. Frihet mantiene el mismo nivel de audit trail independientemente de la sede.

:::info
Para empresas que operan solo en Espana, el audit trail cumple igualmente con el **Plan General de Contabilidad** y los requisitos de la AEAT para libros contables informatizados (art. 29 LGT).
:::

## Configurar aprobacion obligatoria

Puedes establecer que todos los asientos requieran aprobacion o solo los que superen un umbral de importe:

1. Ve a **Configuracion** → **Contabilidad** → **Flujo de aprobacion**.
2. Activa **Aprobacion obligatoria**.
3. Opcional: define un **umbral de importe** (ej: asientos > 1.000 € requieren aprobacion).
4. Asigna los **aprobadores** por defecto.

## Gotchas

- **Asientos automaticos** (generados por facturacion, conciliacion bancaria): no pasan por el flujo de aprobacion manual — se aprueban automaticamente con marca `[AUTO]` en el historial.
- **Periodo bloqueado**: si el periodo contable esta bloqueado, no pueden crearse ni aprobarse asientos con fecha en ese periodo, aunque tengas rol de administrador.
- **Timezone**: los timestamps del historial siempre se almacenan en UTC. La interfaz los muestra en la zona horaria del usuario.
- **Delegacion temporal**: si el aprobador habitual esta de vacaciones, un administrador puede asignar un aprobador sustituto temporal en **Configuracion** → **Equipo** → **Delegaciones**.

## Relacionado

- [Asientos manuales](./asientos-manuales)
- [Bloqueo de periodo contable](./bloqueo-periodo)
- [Cierre de ejercicio](./cierre-ejercicio)
- [Roles y permisos de equipo](../equipo/invitar-miembros)

---

## Balance de situacion
> Path: /contabilidad/balance-situacion

# Balance de situacion

> El estado financiero mas importante de tu empresa, actualizado en tiempo real tras cada apunte contable.

## Overview

El Balance de Situacion de Frihet refleja en todo momento los activos, pasivos y patrimonio neto de la empresa, calculado directamente desde el motor de doble entrada. Incluye comparativa con el periodo anterior y el mismo periodo del ano anterior, columnas mensuales o trimestrales desplegables, y arbol jerarquico expandible por subcuenta. Conforme al PGC espanol y adaptable a otros planes de cuentas (IFRS, UK, etc.).

## Quick start

1. Ve a Contabilidad → **Informes** → **Balance de situacion**
2. Selecciona el periodo de corte (fin de trimestre, fin de ejercicio, etc.)
3. Expande las categorias que necesites revisar → **Exportar CSV**

## Reference

- API: `GET /v1/accounting/balance-sheet` — parametros: `asOf`, `compareTo`, `groupBy`
- MCP tool: `get_balance_sheet` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Contabilidad → Informes

---

## Bloqueo de periodo fiscal
> Path: /contabilidad/bloqueo-periodo

<!-- AUTO-STUB 2026-05-05 -->

# Bloqueo de periodo fiscal

> Frihet protege la integridad contable bloqueando automáticamente cualquier modificación de facturas, gastos y asientos en ejercicios fiscales ya cerrados.

## Overview

Una vez que ejecutas el cierre de ejercicio, Frihet activa el bloqueo de periodo para ese año fiscal. Cualquier intento de crear, editar o eliminar una factura, gasto o asiento con fecha dentro del periodo cerrado genera un error `PeriodClosedError` — nunca silencioso.

El bloqueo respeta el inicio de ejercicio configurado por usuario (01-01 estándar, 04-01 Reino Unido, 07-01 Australia), lo que garantiza compatibilidad con ciclos fiscales no-calendario.

## Quick start

1. Completa el proceso de cierre en **Configuración → Perfil fiscal → Cierre de ejercicio**.
2. El sistema bloquea automáticamente el periodo. No hay acción adicional.
3. Si necesitas una corrección retroactiva, contacta con soporte para una apertura controlada — no se puede desbloquear desde la interfaz.

## Reference

- Settings: Configuración → Perfil fiscal → Cierre de ejercicio
- Ver también: [Asientos manuales y cierre de ejercicio](./asientos-manuales)

## Related

- [Asientos manuales](./asientos-manuales)
- [Informes contables](./informes-contables)
- [VeriFactu e inmutabilidad](/cumplimiento/inmutabilidad)

---

## Cierre de ejercicio
> Path: /contabilidad/cierre-ejercicio

# Cierre de ejercicio

> Cierra el ano contable en minutos: Frihet genera los asientos automaticamente y bloquea el periodo.

## Overview

El cierre de ejercicio en Frihet automatiza el proceso contable de fin de ano: genera los asientos de regularizacion, transfiere el resultado del ejercicio a la cuenta de patrimonio neto, y bloquea el periodo cerrado para prevenir modificaciones retroactivas. El proceso es reversible si se detectan errores antes de la firma con el auditor. Compatible con ejercicios fiscales no calendario (UK abr-mar, AU jul-jun, etc.).

## Quick start

1. Ve a Contabilidad → **Cierre de ejercicio**
2. Revisa el borrador de asientos de cierre generados por Frihet
3. Confirma el cierre → el periodo queda bloqueado y el resultado se transfiere a patrimonio

## Reference

- API: `POST /v1/accounting/year-end-close` — parametros: `fiscalYear`, `dryRun` (preview sin confirmar)
- MCP tool: `close_fiscal_year` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Contabilidad → Cierre de ejercicio

---

## Informes contables
> Path: /contabilidad/informes-contables

<!-- AUTO-STUB 2026-05-05 -->

# Informes contables

> Motor de contabilidad de doble entrada con 9 informes financieros: Pérdidas y Ganancias, Balance, Balance de Comprobación, Mayor General, Antigüedad, Asientos, Comparativo, Activos Fijos y Exposición FX.

## Overview

Frihet incluye un motor contable completo basado en el Plan General Contable (PGC) y estándares internacionales. Todos los asientos se generan automáticamente al crear facturas, registrar pagos o añadir gastos — sin trabajo manual. Desde `Contabilidad` accedes a 9 pestañas con informes listos para exportar o compartir con tu asesor.

Los informes soportan comparación entre periodos (mensual/trimestral/semestral/anual), columnas de periodo anterior y año anterior con variación porcentual, y vista jerárquica con desglose por subcuenta.

## Quick start

1. Ve a **Contabilidad** en el menú lateral.
2. Selecciona el informe que necesitas en las pestañas superiores (P&L, Balance, Trial Balance, Mayor…).
3. Ajusta el rango de fechas y el nivel de detalle, luego exporta en PDF o CSV.

## Informes disponibles

| Informe                     | Descripción                                             |
| --------------------------- | ------------------------------------------------------- |
| **Pérdidas y Ganancias**    | Ingresos, gastos y resultado neto por periodo           |
| **Balance de Situación**    | Activo, pasivo y patrimonio neto                        |
| **Balance de Comprobación** | Saldos deudor/acreedor por cuenta                       |
| **Mayor General**           | Historial completo de movimientos por cuenta            |
| **Flujo de Caja**           | Actividades operativas, inversión y financiación        |
| **Antigüedad**              | Cobros y pagos pendientes por tramos 30/60/90/120+ días |
| **Asientos Contables**      | Asientos manuales y automáticos del periodo             |
| **Comparativo**             | Dos periodos en paralelo para P&L y Balance             |
| **Activos Fijos**           | Seguimiento de amortizaciones                           |
| **Exposición FX**           | Partidas en divisa extranjera con P&L latente           |

## Reference

- API: `GET /v1/accounting/reports` — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `generate_report` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Contabilidad → Plan de Cuentas

## Related

- [Plan de cuentas](./plan-cuentas)
- [Asientos manuales y cierre de ejercicio](./asientos-manuales)
- [Modelos fiscales](/cumplimiento/modelos-fiscales)

---

## Libro Mayor
> Path: /contabilidad/libro-mayor

# Libro Mayor

> Toda la actividad contable de tu empresa, cuenta por cuenta, con saldo acumulado y filtros avanzados.

## Overview

El Libro Mayor de Frihet muestra el historial completo de movimientos del plan de cuentas con saldo acumulado por apunte. Es la referencia definitiva para auditores y gestores: filtra por cuenta, periodo, tercero o referencia, agrupa los asientos segun tu necesidad, y exporta en CSV con los 19 campos requeridos por la AEAT. Los movimientos son inmutables — no puedes editar ni eliminar apuntes pasados un periodo cerrado.

## Quick start

1. Ve a Contabilidad → **Libro Mayor**
2. Selecciona la cuenta o el rango de cuentas del PGC
3. Ajusta el periodo → revisa los asientos y el saldo acumulado por columna

## Reference

- API: `GET /v1/accounting/general-ledger` — parametros: `accountCode`, `from`, `to`, `groupBy`
- MCP tool: `get_general_ledger` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Contabilidad → Informes → Libro Mayor

---

## Cuenta de resultados
> Path: /contabilidad/perdidas-ganancias

# Cuenta de resultados (P&L)

> Cuanto ingresaste, cuanto gastaste y cual es tu resultado: visible en tiempo real, filtrable por periodo.

## Overview

La Cuenta de Resultados (P&L) de Frihet muestra ingresos, gastos y resultado neto del ejercicio calculado desde el motor contable de doble entrada. Soporta columnas por mes o trimestre para analizar tendencias, comparativa con periodo anterior y ano anterior con variacion porcentual, y arbol jerarquico expandible. Ideal para presentar a socios, inversores o gestores fiscales sin exportar a Excel.

## Quick start

1. Ve a Contabilidad → **Informes** → **Cuenta de resultados**
2. Elige el periodo (mes actual, trimestre, ejercicio completo)
3. Activa **Columnas mensuales** para ver la evolucion → **Exportar CSV**

## Reference

- API: `GET /v1/accounting/profit-and-loss` — parametros: `from`, `to`, `periodColumns`, `compareTo`
- MCP tool: `get_profit_and_loss` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Contabilidad → Informes

---

## Contabilidad
> Path: /contabilidad/plan-cuentas

# Contabilidad

El modulo de contabilidad de Frihet implementa partida doble completa. Cada factura, gasto y pago genera asientos contables automaticamente en el libro mayor. Puedes consultar el plan de cuentas, revisar el diario, y obtener los estados financieros oficiales sin tocar nada manualmente.

Accede desde el menu lateral: **Contabilidad**.

---

## Plan de cuentas

El plan de cuentas es la estructura jerarquica de todas las cuentas de tu empresa. Frihet incluye un plan preconfigurado basado en el Plan General Contable espanol (PGC 2007), adaptado al tipo de empresa y pais durante el proceso de alta.

### Ver el plan de cuentas

1. Ve a **Contabilidad** → **Plan de cuentas** (ruta: `/accounting/chart`)
2. Se muestra la vista jerarquica con los 9 grupos del PGC:

| Grupo | Nombre |
|-------|--------|
| 1 | Financiacion basica |
| 2 | Activo no corriente |
| 3 | Existencias |
| 4 | Acreedores y deudores por operaciones comerciales |
| 5 | Cuentas financieras |
| 6 | Compras y gastos |
| 7 | Ventas e ingresos |
| 8 | Gastos imputados al patrimonio neto |
| 9 | Ingresos imputados al patrimonio neto |

Cada grupo se expande en subgrupos (2 digitos), cuentas (3 digitos) y subcuentas (6-8 digitos).

### Cuentas usadas por Frihet de forma automatica

Las siguientes cuentas se asignan automaticamente segun el tipo de operacion:

| Cuenta | Nombre | Cuando se usa |
|--------|--------|---------------|
| 700 | Ventas de mercancias | Ingresos por ventas de productos |
| 705 | Prestaciones de servicios | Ingresos por servicios |
| 477 | H.P. IVA repercutido | IVA de facturas emitidas |
| 430 | Clientes | Credito con clientes (facturas enviadas) |
| 572 | Bancos e instituciones de credito | Cobros en cuenta bancaria |
| 600 | Compras de mercancias | Gastos de compra de productos |
| 472 | H.P. IVA soportado | IVA de gastos y facturas recibidas |
| 400 | Proveedores | Deuda con proveedores |
| 621 | Arrendamientos y canones | Gastos de alquiler |
| 629 | Otros servicios | Gastos generales de servicios |

### Personalizar cuentas

Puedes anadir subcuentas propias o modificar las cuentas existentes:

1. Ve a **Contabilidad** → **Plan de cuentas**
2. Haz clic en **+ Nueva cuenta**
3. Completa:
   - **Codigo** — Sigue la nomenclatura del PGC (ej: 7050001)
   - **Nombre** — Descripcion de la cuenta
   - **Tipo** — Activo, Pasivo, Ingresos, Gastos, Patrimonio neto
   - **Cuenta padre** — Para mantener la jerarquia
4. Haz clic en **Guardar**

**Nota:** No modifiques los codigos de las cuentas usadas por Frihet de forma automatica, ya que podria afectar la generacion de asientos.

---

## Asientos contables

Frihet genera asientos automaticamente al:

- Guardar una factura como enviada (debe → 430 Clientes / haber → 70x Ventas + 477 IVA)
- Registrar el cobro de una factura (debe → 572 Bancos / haber → 430 Clientes)
- Registrar un gasto (debe → 6xx Gastos + 472 IVA / haber → 400 Proveedores o 572 Bancos)
- Procesar una factura rectificativa (asiento inverso)
- Cerrar el ejercicio

### Asientos manuales

Para asientos que no se generan automaticamente (ajustes, amortizaciones, periodificaciones):

1. Ve a **Contabilidad** → **Diario**
2. Haz clic en **+ Nuevo asiento**
3. Rellena la cabecera:
   - **Fecha** — Fecha del asiento
   - **Descripcion** — Concepto del asiento
   - **Referencia** — Documento relacionado (opcional)
4. Anade las lineas (debe y haber):
   - Selecciona la cuenta contable
   - Introduce el importe en la columna correspondiente
5. Verifica que **Debe = Haber** (Frihet avisa si no cuadra)
6. Haz clic en **Guardar**

Los asientos manuales quedan registrados en el diario junto con los automaticos.

---

## Informes contables

Accede a todos los informes desde **Contabilidad** (ruta: `/accounting`).

### Balance de comprobacion

Muestra todas las cuentas con sus saldos deudor, acreedor y saldo final en un periodo determinado. Util para verificar que el libro mayor esta equilibrado.

- **Filtros:** Periodo, grupo de cuentas, nivel de detalle (3, 6 u 8 digitos)
- **Exportar:** CSV, PDF

### Libro mayor

Detalle de todos los movimientos por cuenta: fecha, concepto, importe debe/haber y saldo acumulado.

1. Ve a **Contabilidad** → **Libro mayor**
2. Selecciona la cuenta (o deja en blanco para ver todas)
3. Filtra por periodo
4. Cada linea muestra el asiento que origino el movimiento

Puedes hacer clic en cualquier linea para ir directamente al asiento o al documento fuente (factura, gasto, cobro).

### Cuenta de perdidas y ganancias

Estado de resultados jerarquico basado en el PGC. Muestra ingresos, gastos y resultado del ejercicio.

| Seccion | Cuentas |
|---------|---------|
| Importe neto de la cifra de negocios | 700-705 |
| Aprovisionamientos | 600-602 |
| Gastos de personal | 640-649 |
| Otros gastos de explotacion | 620-629 |
| Amortizacion del inmovilizado | 681-682 |
| Resultado de explotacion | Calculado |
| Ingresos financieros | 760-769 |
| Gastos financieros | 660-669 |
| Resultado antes de impuestos | Calculado |
| Impuesto sobre beneficios | 630 |
| Resultado del ejercicio | Calculado |

Selecciona el periodo (mensual, trimestral, anual) y compara con periodo anterior.

### Balance de situacion

Balance general jerarquico segun el PGC. Muestra activo, pasivo y patrimonio neto a fecha de corte.

| Seccion | Descripcion |
|---------|-------------|
| Activo no corriente | Inmovilizado, inversiones a largo plazo |
| Activo corriente | Existencias, deudores, tesoreria |
| Patrimonio neto | Capital, reservas, resultado del ejercicio |
| Pasivo no corriente | Deudas a largo plazo |
| Pasivo corriente | Proveedores, deudas a corto plazo |

Verifica que **Activo = Pasivo + Patrimonio neto** en todo momento.

### Informe de antiguedad de deudores (AR Aging)

Muestra las facturas pendientes de cobro agrupadas por antiguedad:

| Tramo | Descripcion |
|-------|-------------|
| Corriente | No vencidas todavia |
| 1-30 dias | Vencidas hace menos de un mes |
| 31-60 dias | Vencidas entre 1 y 2 meses |
| 61-90 dias | Vencidas entre 2 y 3 meses |
| +90 dias | Vencidas hace mas de tres meses |

Util para gestionar el riesgo de impago y priorizar cobros.

### Informes comparativos

Compara dos periodos (mes, trimestre o ano) en la misma vista. Muestra variacion absoluta y porcentual.

Disponible en:
- Cuenta de perdidas y ganancias comparativa
- Balance de situacion comparativo
- Balance de comprobacion comparativo

### Registro de activos fijos

Seguimiento del inmovilizado de la empresa: coste de adquisicion, amortizacion acumulada y valor neto contable.

| Campo | Descripcion |
|-------|-------------|
| Descripcion | Nombre del activo |
| Fecha adquisicion | Cuando se compro o puso en uso |
| Coste | Importe de adquisicion |
| Vida util | Anos de amortizacion |
| Metodo | Lineal, degresivo |
| Amortizacion anual | Calculada automaticamente |
| Valor neto | Coste menos amortizacion acumulada |

### Informe de exposicion en divisas (FX Exposure)

Para empresas con facturacion en multiples monedas. Muestra el saldo de cuentas a cobrar y a pagar por divisa, con el contravalor en la moneda funcional y la ganancia o perdida latente por tipo de cambio.

Requiere activar **Multidivisa** en **Configuracion** → **Divisas**.

---

## Cierre del ejercicio

Al final de cada ejercicio contable:

1. Ve a **Contabilidad** → **Cierre de ejercicio**
2. Frihet ejecuta las siguientes operaciones automaticamente:
   - Calcula el resultado del ejercicio (cuenta 129)
   - Propone el asiento de regularizacion (cierre de cuentas 6 y 7)
   - Propone el asiento de cierre (cierre de cuentas de balance)
   - Abre el nuevo ejercicio con los saldos de apertura
3. Revisa los asientos propuestos antes de confirmar
4. Haz clic en **Confirmar cierre**

Una vez cerrado el ejercicio, los periodos anteriores quedan bloqueados para edicion.

---

## Estado del modulo

El motor contable de Frihet esta en produccion. Los asientos automaticos, el libro mayor, la cuenta de perdidas y ganancias y el balance de situacion son totalmente funcionales. Algunas vistas de detalle avanzadas (desglose por centro de coste, presupuestos vs. real) se encuentran en refinamiento y se publicaran en proximas versiones.

---

**Siguiente:** [Factura electronica](../facturacion/factura-electronica) | [VeriFactu](../cumplimiento/verifactu)

---

## Declaración responsable VeriFactu
> Path: /cumplimiento/declaracion-responsable-verifactu

# Declaración responsable del sistema informático de facturación

**Última actualización**: 11 de junio de 2026 · [Descargar en PDF](/pdf/declaracion-responsable-verifactu-frihet-v1.0-20260611.pdf)

Esta declaración responsable se emite conforme al artículo 13 del Real Decreto 1007/2023, de 5 de diciembre, y al artículo 15 de la Orden HAC/1177/2024, de 17 de octubre. Está disponible dentro del propio sistema (Impuestos → Cumplimiento → VeriFactu) y en esta página, en formato electrónico de uso ampliamente extendido y gratuito.

---

## DECLARACIÓN RESPONSABLE DEL SISTEMA INFORMÁTICO DE FACTURACIÓN

**a) Nombre del sistema informático:** Frihet

**b) Código identificador del sistema informático:** 01

**c) Versión del sistema informático a que se refiere esta declaración:** 1.0

**d) Componentes del sistema informático y descripción:** Frihet es un sistema informático de facturación compuesto por un único componente de software, sin componentes de hardware específicos: una aplicación web en modalidad de software como servicio (SaaS), accesible en https://app.frihet.io, integrada por una interfaz web de usuario y por servicios de proceso y almacenamiento en la nube gestionados por el productor. Sus principales funcionalidades son la emisión y gestión de facturas —incluidas facturas rectificativas—, presupuestos, gastos, clientes y productos, así como la generación, por cada operación de facturación, de los registros de facturación de alta y de anulación previstos en el Reglamento, con cálculo de huella («hash») SHA-256 encadenada, incorporación del código «QR» tributario en la factura y remisión por medios electrónicos de los registros de facturación a la sede electrónica de la Agencia Estatal de Administración Tributaria de forma continuada, segura, correcta, íntegra, automática, consecutiva, instantánea y fehaciente, como sistema de emisión de facturas verificables («VERI\*FACTU»).

**e) Indicación de uso exclusivo como «VERI\*FACTU»:** Sí. El sistema informático se ha producido de tal manera que, a los efectos de cumplir con el Reglamento, solo puede funcionar exclusivamente como «VERI\*FACTU», de acuerdo con las especificaciones dadas en el apartado 2.6 del anexo de la Orden HAC/1177/2024.

**f) Indicación de soporte a varios obligados tributarios:** Sí. El sistema informático permite ser usado por varios obligados tributarios o por un mismo usuario para dar soporte a la facturación de varios obligados tributarios, de acuerdo con las especificaciones dadas en el apartado 2.6 del anexo de la Orden HAC/1177/2024.

**g) Tipos de firma utilizados para firmar los registros de facturación y de evento en caso de no utilizarse como «VERI\*FACTU»:** No aplicable. El sistema solo puede funcionar como «VERI\*FACTU» (véase la letra e).

**h) Productor del sistema informático:** Víctor Berthelius, profesional autónomo, que comercializa el sistema bajo la marca «Frihet».

**i) NIF del productor:** 54052380B

**j) Dirección postal de contacto del productor:** Calle Cervera, n.º 9, Radazul, 38109, Santa Cruz de Tenerife, España.

**k)** El productor declara que el sistema informático «Frihet», en la versión 1.0 indicada en esta declaración, **cumple con lo dispuesto en el artículo 29.2.j) de la Ley 58/2003, de 17 de diciembre, General Tributaria, en el Reglamento que establece los requisitos que deben adoptar los sistemas y programas informáticos o electrónicos que soporten los procesos de facturación de empresarios y profesionales, y la estandarización de formatos de los registros de facturación, aprobado por el Real Decreto 1007/2023, de 5 de diciembre, en la Orden HAC/1177/2024, de 17 de octubre, y en lo publicado en la sede electrónica de la Agencia Estatal de Administración Tributaria para todo aquello que complete las especificaciones de dicha orden.**

**l) Fecha y lugar de suscripción:** 11 de junio de 2026, Santa Cruz de Tenerife (España).

---

## Anexo — información adicional (artículo 15.2 de la Orden HAC/1177/2024)

- **Otras formas de contacto:** support@frihet.io
- **Direcciones de Internet del productor:** https://frihet.io (sitio web) · https://docs.frihet.io (documentación, incluida la relativa al sistema informático) · https://app.frihet.io (aplicación)
- **Resumen de cumplimiento de las especificaciones:** el sistema genera por cada factura expedida un registro de facturación de alta —y, en su caso, de anulación— con el contenido del capítulo II de la Orden HAC/1177/2024; calcula la huella SHA-256 de cada registro encadenándola con la del registro anterior (artículo 8 del Reglamento); incorpora en cada factura el código «QR» de verificación con la URL del servicio de cotejo de la sede electrónica de la AEAT; y remite los registros de facturación a la sede electrónica de la AEAT mediante servicio web con certificado electrónico, operando como sistema de emisión de facturas verificables.
- **Conservación de declaraciones:** el productor guarda y conserva las declaraciones responsables correspondientes a todas las versiones del sistema informático (artículo 13.3 del RD 1007/2023). Las declaraciones de versiones anteriores pueden solicitarse en support@frihet.io.

---

_Esta declaración responsable es un documento legal redactado en castellano. Para cualquier consulta sobre su contenido, contacta con support@frihet.io._

---

## Facturae B2G — Facturar a Administraciones Públicas
> Path: /cumplimiento/facturae-b2g

# Cómo facturar a Administraciones Públicas con Facturae 3.2.2

La Ley 25/2013 obliga a presentar facturas electrónicas en formato Facturae a cualquier entidad del sector público español. Frihet genera el XML firmado y gestiona los códigos DIR3 necesarios para que tus facturas sean aceptadas en FACe y otros portales B2G.

## Qué es Facturae y cuándo se usa

**Facturae 3.2.2** es el formato XML definido por el Ministerio de Hacienda para la facturación electrónica entre empresas y la Administración Pública española (B2G). Es obligatorio desde 2015 para facturas superiores a 5.000 € dirigidas a cualquier entidad del sector público. Desde 2017 se aplica sin umbral mínimo para la Administración General del Estado.

El estándar usa firma digital **XAdES-EPES enveloped** con el certificado electrónico del emisor (FNMT, ACCV, CATCert u otro reconocido). Sin firma válida, FACe rechaza la factura de forma automática.

## Códigos DIR3 — los tres identificadores obligatorios

Cada factura B2G requiere tres códigos de la base de datos DIR3 (Directorio Común de Unidades Orgánicas y Oficinas):

| Campo                  | Descripción                             | Ejemplo     |
| ---------------------- | --------------------------------------- | ----------- |
| **Oficina contable**   | Departamento que contabiliza la factura | `L01280796` |
| **Órgano gestor**      | Entidad que contrató el servicio        | `L01280796` |
| **Unidad tramitadora** | Unidad que gestiona el expediente       | `L01280796` |

Consulta los códigos DIR3 del organismo receptor en el [directorio oficial](https://face.gob.es/es/administraciones/directorio-administraciones) antes de emitir la factura. Los códigos son distintos para cada ministerio, consejería, ayuntamiento o entidad pública.

## Marcar un cliente como B2G en Frihet

Para habilitar Facturae en un cliente:

1. Ve a **Clientes** y abre el registro del cliente.
2. En la sección **Datos fiscales**, activa **Administración Pública (B2G)**.
3. Introduce los tres códigos DIR3: oficina contable, órgano gestor y unidad tramitadora.
4. Si el cliente es una entidad europea (Alemania, otros), introduce también el **Leitweg-ID** en el campo correspondiente.
5. Guarda el cliente.

A partir de ese momento, todas las facturas a ese cliente incluirán los campos DIR3 en el XML Facturae generado.

## Exportar el XML Facturae firmado

Una vez creada la factura al cliente B2G:

1. Abre la factura en estado **Enviada** o **Emitida**.
2. Haz clic en **Más opciones** → **Exportar factura electrónica**.
3. En el diálogo de exportación (`EInvoiceExportDialog`), selecciona el formato **Facturae 3.2.2 (España B2G)**.
4. Si tienes el certificado digital configurado, Frihet firma el XML automáticamente con XAdES-EPES.
5. Si no has subido aún el certificado, el sistema te redirige a **Configuración → Integraciones → Certificado digital**.
6. Descarga el archivo `.xsig` resultante.

El XML generado incluye:

- Esquema conforme a `facturae.gob.es` versión 3.2.2
- Firma XAdES-EPES con sellado de tiempo
- Códigos DIR3 del cliente B2G
- NIF del emisor, IBAN y datos de la empresa según tu perfil

## Presentar en FACe

FACe (Punto General de Entrada de Facturas Electrónicas) es el portal central para enviar facturas B2G a la Administración General del Estado y a los organismos adheridos.

### Envío directo desde Frihet

Frihet puede presentar la factura firmada en FACe mediante su servicio de presentación:

1. En la factura exportada, haz clic en **Enviar a FACe**.
2. Frihet envía el XML firmado al servicio SOAP de FACe.
3. Se muestra el **número de registro de entrada (RCF)** asignado por FACe.
4. El estado de la factura se actualiza en tiempo real: `Registrada → En tramitación → Pagada`.

### Envío manual en face.gob.es

Si prefieres gestionar el envío fuera de Frihet:

1. Accede a [face.gob.es](https://face.gob.es) con tu certificado electrónico.
2. Selecciona **Presentar factura** y sube el archivo `.xsig` descargado de Frihet.
3. FACe valida la firma, los códigos DIR3 y el NIF del emisor.
4. Guarda el **código de seguimiento** para consultar el estado posterior.

:::note Portales autonómicos
Algunas Comunidades Autónomas tienen portales propios además de FACe: FACE Autonómica (Cataluña usa e.FACT, Canarias usa FACCan, etc.). El XML Facturae 3.2.2 es compatible con todos ellos, aunque los códigos DIR3 pueden ser distintos.
:::

## Seguimiento del estado

Tras la presentación, la factura pasa por estos estados en FACe:

| Estado             | Descripción                                      |
| ------------------ | ------------------------------------------------ |
| **Registrada**     | Factura recibida y validada formalmente          |
| **En tramitación** | El órgano gestor ha recibido la factura          |
| **Reconocida**     | Conformidad con el servicio prestado             |
| **Aprobada**       | Autorizada para pago                             |
| **Pagada**         | Pago realizado                                   |
| **Rechazada**      | Error formal o discrepancia. Requiere corrección |

Frihet consulta el estado de forma automática y lo refleja en la línea de tiempo de la factura.

## Certificado digital

Para firmar con XAdES-EPES necesitas un certificado digital reconocido:

- **FNMT** (Fábrica Nacional de Moneda y Timbre) — el más común para personas físicas y jurídicas
- **ACCV** (Agencia de Tecnología y Certificación Electrónica, Valencia)
- **CATCert** (Agencia Catalana de Certificación)
- **Camerfirma**, **ANF AC**, **Firmaprofesional** y otras entidades acreditadas

Frihet almacena el certificado cifrado con AES-256-GCM. Nunca se expone en texto plano fuera del proceso de firma.

Para subir el certificado:

1. Ve a **Configuración → Integraciones → Certificado digital**.
2. Sube el archivo `.p12` o `.pfx` con la contraseña correspondiente.
3. Frihet valida el certificado y muestra la fecha de caducidad.

:::caution Renovación del certificado
Los certificados FNMT para personas jurídicas caducan cada 2 años. Frihet muestra un aviso 30 días antes de la caducidad. Una firma con certificado caducado es rechazada por FACe.
:::

## Rectificativas y abonos B2G

Las facturas rectificativas en B2G siguen el mismo proceso que las ordinarias. Frihet incluye el campo `TipoDocumento = FC` (rectificativa) y la referencia a la factura original en el XML. Presenta la rectificativa en FACe con el mismo proceso que una factura ordinaria.

## Preguntas frecuentes

**¿Qué ocurre si FACe rechaza la factura?**
FACe devuelve un código de error con la causa del rechazo (firma inválida, códigos DIR3 incorrectos, NIF no registrado como proveedor, etc.). Corrige el error indicado, regenera el XML firmado en Frihet y vuelve a presentar.

**¿Puedo facturar a un ayuntamiento que no está en FACe?**
Algunos ayuntamientos tienen portal propio. Frihet genera el XML Facturae válido para cualquier portal B2G. El envío a portales distintos de FACe se hace descargando el XML y subiéndolo manualmente.

**¿Es obligatorio el Leitweg-ID para clientes B2G en España?**
No. El Leitweg-ID es el identificador equivalente para Alemania (B2G alemán). En España se usan los códigos DIR3. Si tu cliente es una entidad pública alemana, introduce el Leitweg-ID en el campo correspondiente del cliente.

**¿Puedo enviar Facturae por PEPPOL?**
PEPPOL como red de transporte para Facturae B2G en España está en desarrollo. Actualmente FACe es la vía principal. El soporte PEPPOL AS4 está previsto en versiones futuras de Frihet.

## Referencias oficiales

- Facturae: [https://www.facturae.gob.es](https://www.facturae.gob.es)
- FACe portal: [https://face.gob.es](https://face.gob.es)
- DIR3 directorio: [https://face.gob.es/es/administraciones/directorio-administraciones](https://face.gob.es/es/administraciones/directorio-administraciones)
- Ley 25/2013: [https://www.boe.es/buscar/act.php?id=BOE-A-2013-12813](https://www.boe.es/buscar/act.php?id=BOE-A-2013-12813)
- Esquema XSD Facturae: [https://www.facturae.gob.es/formato/Paginas/version-3-2-2.aspx](https://www.facturae.gob.es/formato/Paginas/version-3-2-2.aspx)

## Relacionado

- [Factura electrónica (formatos EU)](/facturacion/factura-electronica)
- [VeriFactu](/cumplimiento/verifactu)
- [TicketBAI](/cumplimiento/ticketbai)
- [API REST](/desarrolladores/api-rest)

---

## IGIC Canarias — Modelos anuales y AIEM
> Path: /cumplimiento/igic-canarias

# IGIC Canarias — Modelos anuales y AIEM

El IGIC (Impuesto General Indirecto Canario) tiene un ciclo de declaracion anual distinto al IVA peninsular. Frihet gestiona los cinco modelos del cierre anual IGIC directamente desde la plataforma, incluyendo la comunicacion con la Agencia Tributaria Canaria (ATC) via SOAP.

## Que modelos cubre Frihet

| Modelo       | Nombre                                 | Periodicidad    | Quien presenta          |
| ------------ | -------------------------------------- | --------------- | ----------------------- |
| **M415**     | Operaciones con terceros > 3.005 €     | Anual (enero)   | Todas las empresas IGIC |
| **M425**     | Resumen anual IGIC                     | Anual (enero)   | Todas las empresas IGIC |
| **M418**     | Declaracion mensual grandes empresas   | Mensual         | Facturacion > 6M€/ano   |
| **AIEM**     | Arbitrio sobre importaciones (aduanas) | Por importacion | Importadores Canarias   |
| **ATC SOAP** | Presentacion electronica ATC           | —               | Canal de envio oficial  |

## Configuracion inicial

1. Ve a **Configuracion** → **Datos de empresa** → zona fiscal **Canarias**.
2. Activa el modulo **IGIC anual** en **Cumplimiento** → **IGIC**.
3. Introduce tu NIF/CIF y el numero de operador ATC si presentas el M418.

Frihet detecta automaticamente el tipo de empresa (gran empresa vs. pyme) segun el volumen de operaciones del ejercicio anterior.

## Modelo 415 — Operaciones con terceros

El M415 recoge todas las operaciones con un mismo tercero que superen **3.005,06 € anuales** (IVA/IGIC incluido). Equivale al Modelo 347 peninsular pero con codigo ATC propio.

```
Umbral M415: 3.005,06 € por tercero/ano
Plazo: 1-31 de enero del ano siguiente
Presentacion: ATC electronica (SOAP) o sede ATC
```

Frihet calcula el volumen acumulado por NIF/CIF de cliente y proveedor a lo largo del ejercicio. En enero abre el asistente M415 con la lista precalculada para revision y exportacion.

### Gotchas

- Operaciones con administraciones publicas (codigo 7) se declaran separadas del resto.
- Operaciones intracomunitarias desde Canarias NO generan M415 (el territorio es extracomunitario).
- Si un cliente tiene facturas rectificativas, Frihet las netea automaticamente antes de calcular el umbral.

## Modelo 425 — Resumen anual IGIC

El M425 es el cierre del ejercicio IGIC: totaliza las cuotas devengadas y soportadas del ano, cuadra con los M420 trimestrales presentados y calcula el resultado final (a devolver o a ingresar).

Frihet genera el M425 consolidando los cuatro trimestres M420 automaticamente:

1. Ve a **Cumplimiento** → **IGIC** → **M425 Resumen anual**.
2. Selecciona el ejercicio fiscal.
3. Revisa el cuadre trimestral — Frihet marca en rojo cualquier discrepancia.
4. Exporta el fichero `.xml` para presentacion ATC o usa el envio SOAP directo.

## Modelo 418 — Grandes empresas (mensual)

Las empresas cuya cifra de negocios supera **6.010.121,04 €** en el ejercicio anterior quedan obligadas a liquidar el IGIC **mensualmente** con el M418 en lugar del trimestral M420.

Frihet activa el M418 automaticamente cuando detecta el umbral de gran empresa. El ciclo mensual se refleja en el **Calendario Fiscal** con las fechas de vencimiento (dia 20 de cada mes).

```
Plazo M418: Hasta el dia 20 del mes siguiente
Ejemplo: IGIC enero → presentar antes del 20 febrero
```

## AIEM — Arbitrio sobre importaciones

El AIEM grava la importacion en Canarias de determinadas mercancias (vehiculos, bebidas, tabaco, productos energeticos). Frihet registra las operaciones de importacion vinculadas a proveedores extranjeros y genera el desglose AIEM para inclusion en la declaracion aduanera.

:::info
El AIEM no se gestiona desde la AEAT sino desde la **Consejeria de Hacienda del Gobierno de Canarias**. Frihet genera los datos para que tu despacho aduanero los incorpore al DUA (Documento Unico Aduanero).
:::

## Cliente ATC SOAP

Frihet integra el cliente SOAP oficial de la ATC para la presentacion electronica de modelos. La firma digital se realiza con el certificado de representante de entidad que hayas cargado en **Configuracion** → **Certificados digitales**.

```bash
# Verificar conexion ATC desde CLI Frihet
frihet compliance atc:ping --env production
# Respuesta esperada: ATC SOAP endpoint OK (200)
```

El log de cada envio queda registrado en **Cumplimiento** → **Historial de presentaciones** con el codigo de recepcion ATC.

## Edge cases

- **Sociedad nueva en Canarias**: si el primer ejercicio es inferior a 12 meses, el umbral gran empresa se prorratea proporcionalmente.
- **Operaciones exentas plenas** (exportaciones, entregas intracomunitarias): se declaran en M425 casilla 20 pero no generan cuota.
- **Regularizacion de bienes de inversion**: el M425 incluye la prorrata especial de bienes de inversion si has optado por ella.

## Relacionado

- [Modelo 420 trimestral IGIC](./modelo-420)
- [Modelos fiscales — resumen](./modelos-fiscales)
- [Conexiones bancarias para domiciliacion IGIC](../finanzas/conexiones-bancarias)
- [Certificados digitales](../configuracion/seguridad)

---

## Impuesto sobre Sociedades — M200 y M202
> Path: /cumplimiento/impuesto-sociedades

# Impuesto sobre Sociedades — M200 y M202

El Impuesto sobre Sociedades (IS) es la principal obligacion fiscal anual de las Sociedades Limitadas (SL) espanolas. Frihet automatiza los calculos del M200 (declaracion anual) y el M202 (pagos fraccionados trimestrales), incluyendo la bonificacion del 15% para nuevas SLs en los primeros dos ejercicios.

## Calendario obligatorio

| Modelo              | Concepto                   | Plazo                           |
| ------------------- | -------------------------- | ------------------------------- |
| **M202** (1er pago) | Pago fraccionado abril     | 1-20 abril                      |
| **M202** (2do pago) | Pago fraccionado octubre   | 1-20 octubre                    |
| **M202** (3er pago) | Pago fraccionado diciembre | 1-20 diciembre                  |
| **M200**            | Declaracion anual IS       | 1-25 julio (ejercicio anterior) |

## Modelo 200 — Declaracion anual

El M200 recoge el resultado contable del ejercicio, aplica los ajustes fiscales (diferencias permanentes y temporarias), y calcula la cuota integra sobre la **Base Neta Imponible (BNI)**.

### Como Frihet calcula la BNI

```
Resultado contable (PyG)
  + Diferencias permanentes positivas (gastos no deducibles)
  - Diferencias permanentes negativas (ingresos exentos)
  +/- Diferencias temporarias (amortizaciones, provisiones)
  - Bases imponibles negativas de ejercicios anteriores (BINs)
  = Base Imponible (BI)
  x Tipo impositivo
  = Cuota integra
  - Deducciones y bonificaciones
  = Cuota liquida
  - Retenciones y pagos fraccionados (M202)
  = Cuota diferencial (a ingresar o devolver)
```

Frihet importa automaticamente el resultado del **Libro de PyG** y aplica los ajustes que hayas configurado en **Contabilidad** → **Ajustes fiscales IS**.

### Tipos impositivos 2024-2026

| Tipo de entidad                                  | Tipo general |
| ------------------------------------------------ | ------------ |
| **SL general**                                   | 25%          |
| **Nueva SL (primeros 2 ejercicios con BNI > 0)** | 15%          |
| **Micropymes < 1M€ cifra negocios**              | 23%          |
| **Cooperativas protegidas**                      | 20%          |

:::tip Bonificacion nueva SL 15%
Frihet detecta automaticamente si tu SL esta en el primer o segundo ejercicio con base imponible positiva y aplica el tipo reducido del 15%. Puedes verificarlo en **Cumplimiento** → **IS** → **Tipo aplicable**.
:::

### Acceso al M200

1. Ve a **Cumplimiento** → **Impuesto sobre Sociedades** → **M200**.
2. Selecciona el ejercicio fiscal a declarar.
3. Revisa el cuadre con el balance y PyG contables.
4. Introduce deducciones especiales si aplican (I+D, creacion de empleo, etc.).
5. Genera el fichero `.xml` para presentacion en la sede AEAT o exporta el PDF de referencia.

## Modelo 202 — Pagos fraccionados

El M202 exige un pago a cuenta del IS tres veces al ano. Frihet calcula automaticamente el importe usando la **modalidad art. 40.2 de la LIS** (porcentaje sobre cuota del ultimo ejercicio liquidado):

```
Importe pago fraccionado = Cuota liquida M200 anterior × 18%
(primeros dos plazos: abril y octubre)
(tercer plazo diciembre: cuota M200 × 18% - pagos anteriores del ano)
```

Si eres pyme con cifra de negocios < 6M€, puedes optar por la modalidad art. 40.3 (porcentaje sobre base imponible del periodo en curso). Activa esta opcion en **Cumplimiento** → **IS** → **Modalidad de calculo M202**.

### Generar un M202

1. Ve a **Cumplimiento** → **IS** → **Pagos fraccionados**.
2. Frihet muestra los tres plazos del ano en curso con el importe calculado.
3. Revisa y ajusta si tienes datos actualizados del ejercicio.
4. Exporta el NRC (Numero de Referencia Completo) tras el pago telematico en AEAT.

```bash
# Registrar NRC de un pago M202 via CLI
frihet compliance is:m202 --plazo abril --nrc "2300000000000001234567890"
```

## Deducciones principales

Frihet incluye plantillas para las deducciones mas comunes del IS:

- **Deduccion por doble imposicion internacional** — dividendos de filiales extranjeras
- **Deduccion I+D+i** — gastos en investigacion y desarrollo (art. 35 LIS)
- **Creacion de empleo** — contratos indefinidos discapacitados
- **Donaciones** — entidades beneficiarias mecenazgo (Ley 49/2002)

Cada deduccion requiere documentacion de soporte. Frihet la solicita en el flujo de introduccion y la adjunta al expediente IS del ejercicio.

## Bases imponibles negativas (BINs)

Las perdidas fiscales de ejercicios anteriores compensan la BI sin limite de importe (aunque con un maximo del 70% de la BI del ejercicio para empresas con > 20M€ de cifra de negocios). Frihet lleva el registro acumulado de BINs y las aplica automaticamente al calcular el M200.

## Gotchas

- El M200 se presenta siempre en los **25 dias naturales siguientes** a los 6 meses desde el cierre del ejercicio. Para ejercicios cerrados a 31/12, el plazo es **1-25 julio**.
- Si el ejercicio fiscal no coincide con el ano natural, los plazos M202 se recalculan — contacta a soporte para configurarlo.
- Las entidades en regimen de atribucion de rentas (comunidades de bienes, sociedades civiles sin forma mercantil) **no presentan IS**.
- El M200 de una entidad recien constituida puede ser el primero con BNI positiva — Frihet lo marca para confirmar la aplicacion del 15%.

## Relacionado

- [Cierre de ejercicio contable](../contabilidad/cierre-ejercicio)
- [Perdidas y ganancias](../contabilidad/perdidas-ganancias)
- [Modelos fiscales trimestrales](./modelos-fiscales)
- [Dashboard fiscal](../dashboard-fiscal)

---

## Inmutabilidad y registro
> Path: /cumplimiento/inmutabilidad

# Inmutabilidad y registro

## Por qué la inmutabilidad

El RD 1007/2023 exige que todo Sistema Informático de Facturación (SIF) en España garantice la integridad de los registros fiscales. Esto significa que las facturas emitidas no pueden modificarse ni eliminarse.

Frihet implementa inmutabilidad a nivel de base de datos y de interfaz. Los registros fiscales se protegen automáticamente sin intervención del usuario.

## Facturas que no se pueden borrar

Las facturas en estado **Enviada**, **Cobrada** o **Vencida** no se pueden eliminar. Solo los borradores permiten eliminación.

Para anular una factura ya emitida:

1. Abre la factura
2. Haz clic en **Más opciones** → **Cancelar factura**
3. La factura pasa a estado **Cancelada**
4. Se genera un hash de ANULACION que queda registrado en la cadena

El documento permanece visible en el registro. No desaparece.

## Campos bloqueados

Una vez que una factura tiene hash calculado (`verifactu.hash`), los siguientes campos pasan a ser de solo lectura:

- Número de factura
- Fecha de expedición
- Cliente (nombre y NIF)
- Líneas de factura (descripción, cantidad, precio, tipo impositivo)
- Tipo de IRPF
- Régimen de IVA
- Tipo de operación

Estos campos están bloqueados tanto en la interfaz como en las reglas de base de datos. No es posible modificarlos por ninguna vía.

:::tip
Para corregir una factura ya emitida, crea una [factura rectificativa](../facturacion/abonos) vinculada a la original.
:::

## Numeración secuencial sin saltos

La numeración se genera en el servidor mediante un contador atómico. No depende del cliente ni del navegador.

- Cada serie tiene su propio contador independiente
- No es posible crear huecos en la numeración
- El número se asigna en el momento de la creación, no de forma manual
- El patrón de numeración es configurable (ver [Series y numeración](../facturacion/series-numeracion))

## Registro de auditoría

Cada factura mantiene un registro de cambios (audit log) que se genera automáticamente. Se registran las siguientes acciones:

- Creación del documento
- Modificaciones de campos (antes de bloqueo)
- Cambios de estado
- Cancelación

Cada entrada del registro incluye: fecha/hora, usuario, acción realizada y campos modificados.

El registro de auditoría es inmutable. No se pueden editar ni eliminar entradas del log.

## Cancelación vs. eliminación

| Acción | Cuándo | Qué ocurre |
|--------|--------|------------|
| Eliminar | Solo borradores | Se elimina el documento |
| Cancelar | Facturas emitidas | Estado "Cancelada", hash de ANULACION, documento permanece en registro |
| Rectificar | Facturas con errores | Se crea nueva factura rectificativa vinculada a la original |

---

**Anterior:** [VeriFactu](./verifactu) | **Siguiente:** [Modelos fiscales trimestrales](./modelos-fiscales)

---

## Libros registro
> Path: /cumplimiento/libro-registro

# Libros registro

## Que son los libros registro

Los libros registro son el registro oficial de todas las facturas emitidas y recibidas por tu negocio. Son obligatorios para la inspeccion fiscal y un requisito del RD 1007/2023 (VeriFactu).

Frihet genera dos libros registro como CSV:

- **Libro de Facturas Emitidas** — tus facturas a clientes
- **Libro de Facturas Recibidas** — los gastos (facturas de tus proveedores)

## Como exportar

### Facturas emitidas

1. Ve a **Facturacion** > **Facturas**
2. Haz clic en el boton **Libro Registro**
3. Selecciona trimestre y ano
4. Se descarga el CSV con todas las facturas del periodo

### Facturas recibidas

1. Ve a **Gastos**
2. Haz clic en el boton **Libro Registro**
3. Selecciona trimestre y ano
4. Se descarga el CSV con todos los gastos del periodo

Los borradores no se incluyen en ninguno de los dos libros.

## Libro de Facturas Emitidas

El CSV de facturas emitidas contiene 12 columnas:

| Columna | Descripcion |
|---------|-------------|
| Num. Factura | Numero de documento (serie + secuencia) |
| Fecha Expedicion | Fecha de emision de la factura |
| Fecha Operacion | Fecha de la operacion (igual a expedicion) |
| NIF Destinatario | Identificacion fiscal del cliente |
| Nombre Destinatario | Nombre o razon social del cliente |
| Base Imponible | Subtotal antes de impuestos |
| Tipo Impositivo | Porcentaje de IVA/IGIC aplicado |
| Cuota | Importe de impuesto repercutido |
| Recargo Equivalencia | Importe del recargo (si aplica) |
| Total Factura | Importe total de la factura |
| Tipo Operacion | Clasificacion de la operacion |
| Clave Regimen | Codigo de regimen fiscal |

### Tipos de operacion

Frihet clasifica automaticamente cada factura segun la ubicacion del cliente y el tipo impositivo:

| Tipo | Descripcion |
|------|-------------|
| Normal | Operacion sujeta con IVA/IGIC > 0% |
| Exportacion | Venta a clientes fuera de la UE |
| Intracomunitaria | Venta a empresa de otro pais UE |
| ISP | Inversion del Sujeto Pasivo (Peninsula a Canarias/Ceuta-Melilla) |
| Exenta | Operacion exenta (Art. 20 LIVA) |

### Claves de regimen

| Codigo | Significado |
|--------|-------------|
| 01 | Regimen general |
| 02 | Exportacion / operacion internacional |
| 03 | Regimen especial (exento en Peninsula) |
| 08 | Operaciones sujetas a IGIC/IPSI |

## Libro de Facturas Recibidas

El CSV de facturas recibidas (gastos) contiene 12 columnas:

| Columna | Descripcion |
|---------|-------------|
| Num. Factura | Numero de factura del proveedor |
| Fecha Recepcion | Fecha de recepcion del gasto |
| Fecha Factura | Fecha de emision por el proveedor |
| NIF Emisor | Identificacion fiscal del proveedor |
| Nombre Emisor | Nombre del proveedor |
| Base Imponible | Importe antes de impuestos |
| Tipo Impositivo | Porcentaje de impuesto soportado |
| Cuota Soportada | Importe de impuesto pagado |
| IRPF Retenido | Retencion IRPF aplicada (si aplica) |
| Total | Importe total del gasto |
| Tipo Impuesto | IVA, IGIC, IPSI o Exento |
| Bien de Inversion | Si es un bien de inversion (Si/No) |

## Formato de los archivos

- **Formato:** CSV (valores separados por comas)
- **Codificacion:** UTF-8 con BOM (compatible con Excel)
- **Nombre:** `Libro_Facturas_Emitidas_{trimestre}_{ano}_{NIF}.csv` o `Libro_Facturas_Recibidas_{trimestre}_{ano}_{NIF}.csv`
- **Orden:** Documentos ordenados por fecha ascendente

## Uso para inspeccion fiscal

Los libros registro son la herramienta principal para responder a requerimientos de la AEAT. Contienen toda la informacion necesaria para verificar:

- Correlatividad de la numeracion
- Desglose de impuestos por operacion
- Clasificacion fiscal correcta
- Trazabilidad de las operaciones

:::tip
Exporta los libros registro al final de cada trimestre y guardalos junto con la declaracion fiscal. La obligacion de conservacion es de **4 anos**.
:::

## Relacion con modelos fiscales

Los datos de los libros registro son la base para los modelos fiscales trimestrales:

- Las facturas emitidas alimentan el **IVA/IGIC devengado** del [Modelo 303](./modelo-303) o [Modelo 420](./modelo-420)
- Las facturas recibidas alimentan el **IVA/IGIC deducible** de esos mismos modelos
- Las retenciones IRPF de las facturas alimentan el [Modelo 130](./modelo-130)

## Relacion con VeriFactu

El libro de facturas emitidas incluye las claves de regimen necesarias para el cumplimiento [VeriFactu](./verifactu). La cadena de hash SHA-256 de cada factura se puede verificar por separado desde la propia factura.

---

**Anterior:** [Modelo 420](./modelo-420)

---

## Modelo 130 en Frihet: Cálculo Automático IRPF Autónomos 2026
> Path: /cumplimiento/modelo-130

# Modelo 130 — IRPF

El Modelo 130 es el pago fraccionado trimestral del IRPF para autonomos en **estimacion directa**. Aplica en todas las zonas fiscales de Espana (Peninsula, Canarias, Ceuta y Melilla).

## Quien debe presentarlo

- Autonomos dados de alta en estimacion directa (normal o simplificada)
- Que no tengan el 70% o mas de sus ingresos con retencion de IRPF

Si todas tus facturas llevan retencion de IRPF (15% o mas), puede que no estes obligado a presentar el M130. Consulta con tu asesor.

## Que calcula Frihet

El Modelo 130 se basa en un calculo acumulado del ano fiscal (YTD — Year To Date). Cada trimestre incluye los datos desde enero hasta el final del trimestre actual.

### Casillas principales

| Casilla | Concepto                          | Calculo                                                         |
| ------- | --------------------------------- | --------------------------------------------------------------- |
| 01      | Ingresos acumulados               | Suma de facturas cobradas (base imponible) desde enero          |
| 02      | Gastos deducibles acumulados      | Suma de gastos con IVA desde enero                              |
| 03      | Rendimiento neto                  | Casilla 01 - Casilla 02                                         |
| 04      | Porcentaje                        | 20% (fijo)                                                      |
| 05      | Pago fraccionado                  | 20% del rendimiento neto (minimo 0)                             |
| 06      | Retenciones IRPF acumuladas       | IRPF retenido en tus facturas desde enero                       |
| 07      | Pagos fraccionados anteriores     | Lo ya pagado en trimestres previos del mismo ano                |
| 08      | Total deducciones                 | Casilla 06 + Casilla 07                                         |
| 12      | Diferencia                        | Casilla 05 - Casilla 08                                         |
| 13      | A compensar                       | Si la diferencia es negativa, se compensa en trimestres futuros |
| 14      | **A ingresar**                    | Si positivo, lo que debes pagar a Hacienda                      |
| 15      | Reduccion por inicio de actividad | Solo primeros anos de actividad (Art. 110 LIRPF)                |

### Por que es acumulado

El M130 usa datos acumulados porque cada trimestre calcula el impuesto **del ano completo hasta la fecha** y resta lo ya pagado:

- **1T (enero-marzo):** Ingresos y gastos de enero a marzo
- **2T (abril-junio):** Ingresos y gastos de enero a junio, menos el pago del 1T
- **3T (julio-septiembre):** Ingresos y gastos de enero a septiembre, menos pagos de 1T y 2T
- **4T (octubre-diciembre):** Ingresos y gastos de enero a diciembre, menos pagos anteriores

Esto garantiza que al final del ano has pagado exactamente el 20% de tu rendimiento neto.

## Como usarlo en Frihet

1. Ve al **Calendario Fiscal**
2. Selecciona el trimestre y ano
3. Frihet muestra el calculo del M130 con datos reales
4. Si has realizado pagos fraccionados en trimestres anteriores, introduce el importe en **Pagos anteriores**
5. Descarga el PDF como referencia

Frihet guarda los ajustes de cada trimestre automaticamente para que no tengas que reintroducirlos.

## Ingresos

Frihet cuenta como ingresos la **base imponible** (subtotal antes de impuestos) de tus facturas **cobradas** en el periodo. Las facturas en borrador o pendientes de pago no se incluyen.

## Gastos deducibles

Los gastos se consideran deducibles cuando tienen un tipo de impuesto asociado (IVA, IGIC o IPSI). Los gastos marcados como "Exento" se consideran no deducibles para el M130.

La base del gasto se calcula como: importe total - impuesto soportado + IRPF retenido por el proveedor.

:::tip
Registra todos tus gastos en Frihet con la categoria correcta y el tipo de impuesto. Esto asegura que el M130 refleje correctamente tus gastos deducibles.
:::

## Retenciones IRPF

Si tus facturas incluyen retencion de IRPF (porque facturas a empresas como profesional), Frihet acumula ese importe y lo resta del pago fraccionado. Es dinero que ya has "adelantado" a Hacienda a traves de tus clientes.

## Ejemplo practico

Un autonomo con estos datos en el 2T (acumulado enero-junio):

**Facturas cobradas (acumulado):**

- 1T: 8.000 EUR (con 1.200 EUR IRPF retenido)
- 2T: 6.000 EUR (con 900 EUR IRPF retenido)
- Total acumulado: 14.000 EUR

**Gastos deducibles (acumulado):**

- 1T: 2.000 EUR
- 2T: 1.500 EUR
- Total acumulado: 3.500 EUR

**Pago fraccionado del 1T:** 820 EUR

**Calculo 2T:**

```
Casilla 01 (Ingresos acumulados): 14.000 EUR
Casilla 02 (Gastos acumulados): 3.500 EUR
Casilla 03 (Rendimiento neto): 10.500 EUR
Casilla 05 (20%): 2.100 EUR
Casilla 06 (Retenciones acumuladas): 2.100 EUR
Casilla 07 (Pagos anteriores 1T): 820 EUR
Casilla 08 (Total deducciones): 2.920 EUR
Casilla 12 (Diferencia): 2.100 - 2.920 = -820 EUR
Casilla 14 (A ingresar): 0 EUR (resultado negativo, nada que pagar)
```

En este caso, las retenciones y el pago del 1T ya cubren el impuesto del semestre. El importe negativo se compensa en trimestres futuros.

## Relacion con otros modelos

- El M130 se presenta **junto con** el [Modelo 303 (IVA)](./modelo-303) o el [Modelo 420 (IGIC)](./modelo-420) segun tu zona fiscal
- Al final del ano, los datos del M130 se trasladan a la **declaracion anual de la renta** (Modelo 100)
- El M130 NO sustituye al Modelo 100 — es un pago a cuenta

---

**Anterior:** [Modelo 303](./modelo-303) | **Siguiente:** [Modelo 420](./modelo-420)

---

## Modelo 303 — IVA
> Path: /cumplimiento/modelo-303

# Modelo 303 — IVA

El Modelo 303 es la autoliquidacion trimestral del IVA. Aplica a empresas y autonomos con domicilio fiscal en **Peninsula y Baleares**.

Si tu negocio esta en Canarias, consulta el [Modelo 420 (IGIC)](./modelo-420).

## Que calcula Frihet

Frihet genera el calculo completo del Modelo 303 a partir de tus facturas emitidas y gastos registrados en el trimestre:

### IVA Devengado (lo que has cobrado)

Se calcula a partir de tus facturas emitidas (excluye borradores):

| Casillas | Concepto | Calculo |
|----------|----------|---------|
| 01-02 | Regimen general 21% | Base + cuota al 21% |
| 03-04 | Regimen general 10% | Base + cuota al 10% |
| 05-06 | Regimen general 4% | Base + cuota al 4% |
| 13-18 | Recargo de equivalencia | Base + cuota por tipo (5,2% / 1,4% / 0,5%) |
| 27 | **Total IVA devengado** | Suma de todas las cuotas |

Ademas, Frihet clasifica automaticamente las operaciones especiales:

- **Operaciones exentas** (Art. 20 LIVA) — facturas con IVA 0% a clientes nacionales
- **Exportaciones** — ventas a clientes fuera de la UE
- **Intracomunitarias** — ventas a empresas de otros paises UE
- **ISP (Inversion del Sujeto Pasivo)** — ventas de Peninsula a Canarias/Ceuta-Melilla

### IVA Deducible (lo que has pagado)

Se calcula a partir de tus gastos registrados en el trimestre:

| Casillas | Concepto | Calculo |
|----------|----------|---------|
| 28-29 | Bienes y servicios corrientes | Base + cuota IVA de tus gastos |
| 30-31 | Bienes de inversion | Gastos marcados como bien de inversion (>3.000 EUR o marcado manual) |
| 45 | **Total IVA a deducir** | Suma de cuotas deducibles |

### Resultado

| Casilla | Concepto | Calculo |
|---------|----------|---------|
| 46 | Diferencia | Devengado - Deducible |
| 64 | A compensar de periodos anteriores | Importe negativo de trimestres previos |
| 69 | **Resultado de la liquidacion** | Diferencia - Compensacion |
| 71 | A ingresar | Resultado positivo (lo que debes a Hacienda) |

Si el resultado es negativo, se acumula como compensacion para el siguiente trimestre.

## Como usarlo en Frihet

1. Ve al **Calendario Fiscal**
2. Selecciona el trimestre y ano
3. Frihet muestra el desglose con todas las casillas
4. Si tienes importe a compensar de trimestres anteriores, introdúcelo en el campo correspondiente
5. Descarga el PDF como referencia para tu declaracion

Frihet guarda los ajustes (compensaciones, pagos anteriores) de cada trimestre automaticamente.

## Recargo de equivalencia

Si tus facturas incluyen recargo de equivalencia, Frihet lo calcula por separado:

| IVA | Recargo |
|-----|---------|
| 21% | 5,2% |
| 10% | 1,4% |
| 4% | 0,5% |

El recargo se suma al IVA devengado total (casillas 13-18).

## Bienes de inversion

Los gastos se clasifican como bien de inversion cuando:

- Estan marcados explicitamente como "Bien de inversion" en el formulario de gasto
- O superan 3.000 EUR (criterio heuristico)

Los bienes de inversion se deducen en casillas separadas (30-31) y pueden tener reglas de regularizacion distintas.

## Operaciones especiales

Frihet clasifica automaticamente tus facturas segun la ubicacion del cliente:

| Ubicacion del cliente | Clasificacion | IVA |
|----------------------|---------------|-----|
| Peninsula/Baleares | Normal | Tipo aplicable (21/10/4%) |
| UE (empresa) | Intracomunitaria | 0% (inversion sujeto pasivo) |
| Fuera UE | Exportacion | 0% |
| Canarias (desde Peninsula) | ISP | 0% (no sujeta) |
| Peninsula (exento) | Exenta Art. 20 | 0% |

Estas operaciones se reflejan informativamente en el Modelo 303 pero no generan cuota de IVA.

## Ejemplo practico

Un autonomo en Madrid con el siguiente trimestre:

**Facturas emitidas:**
- 3 facturas de consultoria al 21%: 5.000 EUR base
- 1 factura de formacion al 10%: 800 EUR base

**Gastos:**
- Alquiler oficina: 500 EUR + 105 EUR IVA
- Software: 200 EUR + 42 EUR IVA
- Ordenador (bien inversion): 1.500 EUR + 315 EUR IVA

**Calculo:**
```
IVA Devengado:
  21%: 5.000 x 21% = 1.050 EUR
  10%: 800 x 10% = 80 EUR
  Total devengado: 1.130 EUR

IVA Deducible:
  Bienes/servicios: 105 + 42 = 147 EUR
  Bienes inversion: 315 EUR
  Total deducible: 462 EUR

Resultado: 1.130 - 462 = 668 EUR (a ingresar)
```

---

**Anterior:** [Modelos fiscales](./modelos-fiscales) | **Siguiente:** [Modelo 130](./modelo-130)

---

## Modelo 420 — IGIC
> Path: /cumplimiento/modelo-420

# Modelo 420 — IGIC

El Modelo 420 es la autoliquidacion trimestral del IGIC (Impuesto General Indirecto Canario). Aplica a empresas y autonomos con domicilio fiscal en **Canarias**.

Si tu negocio esta en Peninsula o Baleares, consulta el [Modelo 303 (IVA)](./modelo-303).

## Tipos de IGIC

Canarias tiene su propio sistema de impuesto indirecto en lugar del IVA:

| Tipo | Porcentaje | Aplicacion |
|------|-----------|-----------|
| Tipo cero | 0% | Actividades exentas |
| Reducido | 3% | Servicios basicos, alimentacion |
| General | 7% | Mayoria de bienes y servicios |

Frihet normaliza automaticamente los tipos impositivos de tus facturas a estos tipos de IGIC para el calculo del Modelo 420.

## Que calcula Frihet

### IGIC Devengado (repercutido)

Se calcula a partir de tus facturas emitidas del trimestre:

| Casillas | Concepto | Calculo |
|----------|----------|---------|
| 01-02 | Tipo cero (0%) | Base + cuota |
| 03-04 | Reducido (3%) | Base + cuota |
| 05-06 | General (7%) | Base + cuota |
| 11 | Total IGIC repercutido | Suma de cuotas |
| 13 | ISP (Inversion del Sujeto Pasivo) | Adquisiciones con ISP |
| 15 | **Total devengado** | Repercutido + ISP |

### IGIC Deducible (soportado)

Se calcula a partir de tus gastos registrados con IGIC:

| Casillas | Concepto | Calculo |
|----------|----------|---------|
| 16 | Adquisiciones interiores | IGIC soportado en gastos |
| 17 | Importaciones | IGIC de importaciones (si aplica) |
| 22 | **Total deducible** | Suma de conceptos deducibles |

### Resultado

| Casilla | Concepto | Calculo |
|---------|----------|---------|
| 23 | Diferencia | Devengado - Deducible |
| 24 | A compensar de periodos anteriores | Importe negativo de trimestres previos |
| 26 | **Resultado** | Diferencia - Compensacion |

Si el resultado es positivo, es lo que debes ingresar al Gobierno de Canarias. Si es negativo, se compensa en el siguiente trimestre.

## Como usarlo en Frihet

1. Ve al **Calendario Fiscal**
2. Selecciona el trimestre y ano
3. Frihet muestra el desglose del M420 por tipo de IGIC
4. Si tienes importe a compensar de trimestres anteriores, introdúcelo
5. Descarga el PDF como referencia

## Diferencias con el Modelo 303

| Aspecto | M303 (IVA) | M420 (IGIC) |
|---------|-----------|-------------|
| Territorio | Peninsula y Baleares | Canarias |
| Tipos principales | 21%, 10%, 4% | 7%, 3%, 0% |
| Recargo equivalencia | Si (5,2% / 1,4% / 0,5%) | No aplica |
| Presentacion | AEAT (Agencia Tributaria) | Gobierno de Canarias (ATC) |
| Bienes de inversion | Casillas separadas (30-31) | Regularizacion en casilla 19 |

## Ejemplo practico

Un autonomo en Las Palmas con el siguiente trimestre:

**Facturas emitidas:**
- 5 facturas de servicios al 7%: 4.000 EUR base
- 2 facturas de productos al 3%: 1.200 EUR base

**Gastos con IGIC:**
- Material oficina: 300 EUR + 21 EUR IGIC
- Software: 150 EUR + 10,50 EUR IGIC

**Calculo:**
```
IGIC Devengado:
  7%: 4.000 x 7% = 280 EUR
  3%: 1.200 x 3% = 36 EUR
  Total devengado: 316 EUR

IGIC Deducible:
  Interiores: 21 + 10,50 = 31,50 EUR

Resultado: 316 - 31,50 = 284,50 EUR (a ingresar)
```

## Modelo 130 en Canarias

Aunque el IGIC sustituye al IVA, el **Modelo 130 (IRPF)** se presenta igualmente. Si eres autonomo en Canarias, debes presentar ambos modelos trimestralmente:

- [Modelo 420](./modelo-420) — IGIC (impuesto indirecto)
- [Modelo 130](./modelo-130) — IRPF (pago fraccionado de renta)

---

**Anterior:** [Modelo 130](./modelo-130) | **Siguiente:** [Libros registro](./libro-registro)

---

## Modelos 111, 115, 347, 349 y 390
> Path: /cumplimiento/modelos-111-115-347-349-390

<!-- AUTO-STUB 2026-05-05 -->

# Modelos 111, 115, 347, 349 y 390

> Frihet calcula y exporta automáticamente los modelos tributarios complementarios: retenciones IRPF (111), retenciones alquiler (115), operaciones con terceros (347), operaciones intracomunitarias (349) y resumen anual IVA (390).

## Overview

Además del Modelo 303 trimestral y el 130 de IRPF, Frihet cubre todos los modelos complementarios que necesita un autónomo o pyme española. Los modelos se generan a partir de los datos ya registrados en facturas y gastos — sin introducción manual de datos.

Todos los modelos están disponibles en **Cumplimiento → Modelos fiscales** y se pueden exportar como PDF (presentación visual) o TXT AEAT (formato fijo para importación en Sede Electrónica).

| Modelo  | Frecuencia | Qué declara                                                     |
| ------- | ---------- | --------------------------------------------------------------- |
| **111** | Trimestral | Retenciones IRPF (trabajo personal y actividades profesionales) |
| **115** | Trimestral | Retenciones sobre alquileres de locales de negocio              |
| **347** | Anual      | Operaciones con terceros superiores a 3.005,06 €                |
| **349** | Trimestral | Operaciones intracomunitarias (entregas y adquisiciones UE)     |
| **390** | Anual      | Resumen anual IVA — consolida los 4 Modelo 303 del año          |

## Quick start

1. Ve a **Cumplimiento → Modelos fiscales** y selecciona el modelo que necesitas.
2. Selecciona el trimestre o ejercicio y revisa los importes calculados.
3. Exporta en **PDF** para tu archivo o en **TXT AEAT** para importar directamente en la Sede Electrónica.

## Reference

- API: `GET /v1/tax-models/{model}` — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `calculate_tax_model` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Cumplimiento → Modelos fiscales

## Related

- [Modelo 303 (IVA)](/cumplimiento/modelo-303)
- [Modelo 130 (IRPF)](/cumplimiento/modelo-130)
- [Libro de registro](/cumplimiento/libro-registro)

---

## Modelos fiscales trimestrales
> Path: /cumplimiento/modelos-fiscales

# Modelos fiscales trimestrales

Frihet calcula automaticamente tus obligaciones fiscales trimestrales a partir de tus facturas y gastos. Los modelos disponibles dependen de tu zona fiscal.

## Que modelos aplican a tu negocio

Frihet detecta tu zona fiscal desde **Configuracion** > **Datos de empresa** y muestra solo los modelos que te corresponden:

| Zona fiscal | Impuesto indirecto | Modelo indirecto | IRPF |
|-------------|-------------------|-----------------|------|
| **Peninsula y Baleares** | IVA | [Modelo 303](./modelo-303) | [Modelo 130](./modelo-130) |
| **Canarias** | IGIC | [Modelo 420](./modelo-420) | [Modelo 130](./modelo-130) |
| **Ceuta y Melilla** | IPSI | — (sin modelo estandar AEAT) | [Modelo 130](./modelo-130) |

## Calendario de presentacion

Todos los modelos se presentan trimestralmente ante la AEAT (o Gobierno de Canarias para el M420):

| Trimestre | Periodo | Plazo de presentacion |
|-----------|---------|----------------------|
| 1T | Enero - Marzo | 1-20 de abril |
| 2T | Abril - Junio | 1-20 de julio |
| 3T | Julio - Septiembre | 1-20 de octubre |
| 4T | Octubre - Diciembre | 1-30 de enero del ano siguiente |

## Como acceder en Frihet

1. Ve al **Calendario Fiscal** en el menu principal
2. Selecciona el trimestre y ano
3. Frihet muestra los modelos aplicables con el calculo automatico
4. Revisa los datos y descarga el PDF de cada modelo

## Que calcula Frihet

Frihet genera un **preview** de cada modelo con los calculos oficiales basados en tus datos reales:

- **Facturas emitidas** (no borradores) del trimestre para calcular impuesto devengado
- **Gastos registrados** del trimestre para calcular impuesto deducible
- **Retenciones IRPF** aplicadas en tus facturas
- **Pagos anteriores** del mismo ano fiscal (acumulado)
- **Compensaciones** de trimestres anteriores

Los datos se guardan automaticamente por trimestre para que no tengas que reintroducirlos.

## Importante

:::warning
Frihet genera un preview informativo. **No es una declaracion oficial.** Para presentar el modelo ante la AEAT debes:

1. Revisar los calculos en Frihet
2. Descargar el PDF como referencia
3. Presentar la declaracion en la [sede electronica de la AEAT](https://sede.agenciatributaria.gob.es) o a traves de tu asesor fiscal
:::

## Modelos disponibles

- [**Modelo 303**](./modelo-303) — Autoliquidacion del IVA (Peninsula y Baleares)
- [**Modelo 130**](./modelo-130) — Pago fraccionado del IRPF (autonomos en estimacion directa)
- [**Modelo 420**](./modelo-420) — Autoliquidacion del IGIC (Canarias)

## Libros registro

Ademas de los modelos fiscales, Frihet permite exportar los **libros registro** oficiales necesarios para la inspeccion fiscal:

- [**Libro de Facturas Emitidas y Recibidas**](./libro-registro) — CSV con columnas oficiales para cada trimestre

---

**Anterior:** [Inmutabilidad y registro](./inmutabilidad) | **Siguiente:** [Modelo 303](./modelo-303)

---

## TicketBAI en País Vasco — Bizkaia, Gipuzkoa y Álava
> Path: /cumplimiento/ticketbai-pais-vasco

# TicketBAI en País Vasco: Bizkaia, Gipuzkoa y Álava/Araba

TicketBAI es el sistema de facturación electrónica obligatorio en los tres territorios forales del País Vasco. Cada Diputación Foral tiene su propia plataforma de recepción, sus propios endpoints y sus propias fechas de entrada en vigor. Frihet soporta los tres territorios con detección automática por código postal.

## Por qué hay tres sistemas distintos

Los territorios forales vascos tienen autonomía fiscal plena. Bizkaia, Gipuzkoa y Álava/Araba diseñaron sistemas técnicamente compatibles (mismo estándar XAdES, mismo encadenamiento SHA-256, mismo QR) pero con infraestructura de recepción separada. Que tu empresa esté en Bilbao o en Vitoria-Gasteiz determina a qué Hacienda Foral debes reportar y qué endpoint usa Frihet para el envío.

## Detección automática por código postal

Frihet identifica el territorio foral a partir del código postal de tu perfil fiscal:

| Prefijo | Territorio  | Sistema            | Hacienda Foral             |
| ------- | ----------- | ------------------ | -------------------------- |
| `48xxx` | Bizkaia     | BATUZ              | Hacienda Foral de Bizkaia  |
| `20xxx` | Gipuzkoa    | TicketBAI Gipuzkoa | Hacienda Foral de Gipuzkoa |
| `01xxx` | Álava/Araba | TicketBAI Álava    | Hacienda Foral de Álava    |

Si tu código postal no comienza con ninguno de estos prefijos, la sección TicketBAI no aparece en Configuración. Navarra (31xxx) tiene su propio sistema con normativa de la Hacienda Foral de Navarra y no está incluida en esta versión.

## Estructura de cada factura TicketBAI

Independientemente del territorio, cada factura TicketBAI contiene los mismos elementos obligatorios:

- **XML firmado con XAdES-BES** usando el certificado digital del contribuyente
- **Hash SHA-256 encadenado** con la factura inmediatamente anterior (`emisor|serie|numero|fecha|importe|hashAnterior`)
- **Identificador TBAI** asignado por la Hacienda Foral tras validar el envío
- **Código QR** generado a partir del TBAI real (nunca fabricado internamente)

El encadenamiento es inviolable: si un registro se altera, toda la cadena posterior queda invalidada.

## Bizkaia — BATUZ

BATUZ es el sistema de Hacienda Foral de Bizkaia. A diferencia de Gipuzkoa y Álava, usa SOAP con cabeceras HTTP personalizadas en lugar de REST.

### Endpoints

| Entorno    | URL                                                     |
| ---------- | ------------------------------------------------------- |
| Sandbox    | `https://pruebasarqueo.bizkaia.eus/N3B4000M/aurkezpena` |
| Producción | `https://sarrerak.bizkaia.eus/N3B4000M/aurkezpena`      |

### Cabeceras específicas de BATUZ

El servicio SOAP de Bizkaia exige cabeceras HTTP propias que otros sistemas no usan:

```
eus-bizkaia-n3-version: 1.0
eus-bizkaia-n3-idoperacion: {UUID único por envío}
eus-bizkaia-n3-nif: {NIF del emisor}
eus-bizkaia-n3-tipoComunicacion: A00
Content-Type: application/octet-stream; charset=UTF-8
```

Frihet gestiona estas cabeceras de forma automática en su servicio de envío BATUZ. No es necesaria ninguna configuración adicional.

### Respuesta esperada

BATUZ devuelve un resultado SOAP con:

- `CSV` — Código Seguro de Verificación para el contribuyente
- `IdentificadorTBAI` — identificador único de la factura en Bizkaia
- `Estado` — `Correcto`, `AceptadoConErrores` o `Incorrecto`

Frihet almacena el CSV e IdentificadorTBAI de forma segura junto a la factura y genera el QR a partir del IdentificadorTBAI real. Si BATUZ devuelve un estado de error, la factura queda marcada como pendiente de corrección.

### Fechas de obligatoriedad en Bizkaia

| Colectivo                                      | Desde        |
| ---------------------------------------------- | ------------ |
| Grandes contribuyentes (> €6M cifra negocio)   | 1 enero 2022 |
| Resto de empresas y autónomos                  | 1 enero 2023 |
| Software de facturación (cumplimiento técnico) | 1 enero 2022 |

## Gipuzkoa — TicketBAI REST

La Hacienda Foral de Gipuzkoa usa una API REST en lugar de SOAP, lo que simplifica la integración técnica.

### Endpoints

| Entorno    | URL                                                 |
| ---------- | --------------------------------------------------- |
| Sandbox    | `https://tbai-z.prep.gipuzkoa.eus/sarrerak/alta`    |
| Producción | `https://tbai-z.egoitza.gipuzkoa.eus/sarrerak/alta` |

### Método de envío

```
POST /sarrerak/alta
Content-Type: application/xml; charset=UTF-8
Authorization: {certificado de cliente en mTLS}
```

El cuerpo es el XML TicketBAI firmado con XAdES-BES. La respuesta devuelve el IdentificadorTBAI y el estado de validación en JSON.

### Fechas de obligatoriedad en Gipuzkoa

| Colectivo                                    | Desde          |
| -------------------------------------------- | -------------- |
| Contribuyentes en módulos                    | 1 enero 2022   |
| Autónomos en estimación directa simplificada | 1 octubre 2022 |
| Sociedades y autónomos restantes             | 1 julio 2023   |

## Álava/Araba — TicketBAI REST

La Hacienda Foral de Álava también usa REST, con estructura similar a Gipuzkoa pero dominio propio.

### Endpoints

| Entorno    | URL                                                          |
| ---------- | ------------------------------------------------------------ |
| Sandbox    | `https://pruebas-ticketbai.araba.eus/TicketBAI/v1/facturas/` |
| Producción | `https://ticketbai.araba.eus/TicketBAI/v1/facturas/`         |

### Método de envío

```
POST /TicketBAI/v1/facturas/
Content-Type: application/xml; charset=UTF-8
```

La respuesta incluye el estado de validación y el IdentificadorTBAI para las facturas aceptadas.

### Fechas de obligatoriedad en Álava

| Colectivo                                       | Desde        |
| ----------------------------------------------- | ------------ |
| Grandes empresas (> €6M)                        | 1 enero 2022 |
| Resto de contribuyentes con actividad económica | 1 enero 2023 |

## Certificado digital BYOC

TicketBAI exige firma con el certificado del contribuyente, no con un certificado de servicio. Frihet implementa un modelo **Bring Your Own Certificate (BYOC)**:

1. Ve a **Configuración → TicketBAI → Certificado digital**.
2. Sube el archivo `.p12` o `.pfx` con la contraseña del certificado.
3. Frihet cifra el certificado con AES-256-GCM y lo almacena de forma segura. La clave de cifrado nunca se expone ni sale del entorno seguro de firma.
4. En cada envío, Frihet descifra el certificado en memoria, firma el XML y lo descarta sin persistir la forma descifrada.

El certificado válido para TicketBAI puede ser:

- **FNMT** — Fábrica Nacional de Moneda y Timbre (personas físicas y jurídicas)
- **Izenpe** — Autoridad de certificación vasca (recomendado para contribuyentes forales)
- Otros certificados reconocidos por las Haciendas Forales (ACCV, ANF, Camerfirma)

:::caution Caducidad del certificado
Los certificados para personas jurídicas caducan. Frihet muestra un aviso 30 días antes. Una firma con certificado caducado es rechazada por la Hacienda Foral con error irrecuperable. Renueva el certificado antes de la caducidad y actualízalo en Configuración.
:::

## Probar en sandbox

El sandbox permite verificar la integración sin efectos fiscales:

1. Ve a **Configuración → TicketBAI**.
2. La sección solo aparece si tu código postal es de un territorio foral (48xxx, 20xxx, 01xxx).
3. Haz clic en **Probar sandbox** para enviar una factura de prueba al entorno de test de tu Hacienda Foral.
4. El resultado muestra el CSV de verificación y el IdentificadorTBAI si la prueba es exitosa.

En sandbox puedes enviar sin certificado real para verificar el formato XML y la conectividad. Para producción, el certificado es obligatorio.

## Pipeline técnico en Frihet

Frihet ejecuta el pipeline TicketBAI en su backend (infraestructura en la UE):

1. **Construcción del XML** — TicketBAI v1.2 conforme al esquema XSD de la Hacienda Foral correspondiente
2. **Firma XAdES-BES** — con el certificado BYOC descifrado en memoria
3. **Encadenamiento SHA-256** — calcula `hashAnterior` del último registro de la misma serie
4. **Detección de territorio** — enruta al endpoint correcto (BATUZ SOAP, Gipuzkoa REST, Álava REST)
5. **Envío y validación** — recibe CSV + IdentificadorTBAI
6. **Generación del QR** — a partir del IdentificadorTBAI real devuelto por la Hacienda
7. **Persistencia** — CSV, QR, hash y estado guardados de forma segura

Si el envío falla, la factura queda en estado `pendiente_tbai` y Frihet reintenta automáticamente con backoff exponencial.

## Verificación del estado vía MCP

Si usas el servidor MCP de Frihet, la herramienta `ticketbai_status` devuelve el estado actual de cualquier factura:

```
ticketbai_status(invoiceId: string)
→ { invoiceId, status, csv, qrUrl, province, tbaiIdentifier, submittedAt }
```

`status` puede ser: `submitted`, `accepted`, `rejected`, `pending`, `no_submission_yet`.

## Preguntas frecuentes

**¿Es lo mismo TicketBAI que VeriFactu?**
No. VeriFactu es el sistema de la AEAT para el resto de España. TicketBAI es el sistema de las Haciendas Forales vascas. Si tu empresa está en el País Vasco, usas TicketBAI. Ambos sistemas coexisten pero son independientes y no intercambian datos entre sí.

**¿Qué pasa si mi empresa tiene sedes en Bizkaia y en Madrid?**
Las facturas emitidas desde el establecimiento permanente en Bizkaia van a BATUZ. Las emitidas desde Madrid van a VeriFactu (AEAT). Frihet gestiona ambos sistemas en función del perfil fiscal activo en cada factura.

**¿Funciona TicketBAI para autónomos?**
Sí. El sistema es obligatorio para cualquier contribuyente con actividad económica en territorio foral, ya sea persona física (autónomo) o jurídica (empresa). Los tipos de documento y las series de numeración aplicables son los mismos.

**¿El sandbox usa datos reales?**
No. El sandbox de cada Hacienda Foral es un entorno de pruebas aislado. Los identificadores TBAI generados en sandbox no tienen validez fiscal y no aparecen en los registros de la Hacienda.

**¿Cuándo estará disponible el modo producción?**
El botón de activación en producción requiere que hayas subido un certificado digital válido en Configuración. Una vez subido, el sistema activa automáticamente el envío real a la Hacienda Foral correspondiente.

## Referencias oficiales

- BATUZ (Bizkaia): [https://www.batuz.eus](https://www.batuz.eus)
- Hacienda Foral de Gipuzkoa: [https://www.gipuzkoa.eus/es/hacienda/ticketbai](https://www.gipuzkoa.eus/es/hacienda/ticketbai)
- Hacienda Foral de Álava: [https://www.araba.eus/es/hacienda/ticketbai](https://www.araba.eus/es/hacienda/ticketbai)
- Especificación TicketBAI: [https://www.ticketbai.eus](https://www.ticketbai.eus)
- Izenpe (certificación vasca): [https://www.izenpe.eus](https://www.izenpe.eus)

## Relacionado

- [TicketBAI — guía rápida](/legal/ticketbai)
- [VeriFactu](/cumplimiento/verifactu)
- [Facturae B2G](/cumplimiento/facturae-b2g)
- [Cumplimiento fiscal en España](/compliance/spain) <!-- ES compliance overview -->

---

## TicketBAI
> Path: /cumplimiento/ticketbai

# TicketBAI

## Qué es TicketBAI

TicketBAI es el sistema de facturación electrónica obligatorio en los **territorios forales vascos**:

| Territorio  | Sistema            | Hacienda Foral             |
| ----------- | ------------------ | -------------------------- |
| Bizkaia     | BATUZ              | Hacienda Foral de Bizkaia  |
| Gipuzkoa    | TicketBAI Gipuzkoa | Hacienda Foral de Gipuzkoa |
| Álava/Araba | TicketBAI Álava    | Hacienda Foral de Álava    |

Cada factura emitida debe contener:

- **Firma XAdES-BES** con certificado digital del contribuyente
- **Hash SHA-256 encadenado** con la factura anterior (cadena inviolable)
- **Código QR** con el identificador TBAI oficial
- **Envío a la Hacienda Foral** mediante SOAP antes o al momento de entrega al cliente

## Detección automática

Frihet detecta automáticamente si tu empresa está en el País Vasco a partir del **código postal** de tu perfil fiscal:

| Prefijo | Territorio      |
| ------- | --------------- |
| 48xxx   | Bizkaia (BATUZ) |
| 20xxx   | Gipuzkoa        |
| 01xxx   | Álava/Araba     |

Si tu código postal no comienza con 48, 20 ni 01, la sección TicketBAI no aparece en los ajustes. Solo se muestra a los usuarios con dirección fiscal en territorio foral.

## Activar sandbox

En esta fase, Frihet incluye el **modo sandbox** completamente funcional:

1. Ve a **Configuración → TicketBAI**
2. La sección solo aparece si tu código postal es de un territorio foral
3. Haz clic en **Probar sandbox** para enviar una factura de prueba al entorno de test de la Hacienda Foral
4. El resultado muestra el CSV de verificación y el identificador TBAI si la prueba es exitosa

El modo sandbox usa el entorno de pruebas de Bizkaia (`pruebasarqueo.bizkaia.eus`) y no tiene efectos fiscales reales.

## Modo producción

El modo producción requiere un **certificado digital emitido por la Diputación Foral** correspondiente:

- **Bizkaia**: Hacienda Foral de Bizkaia — [batuz.eus](https://www.batuz.eus)
- **Gipuzkoa**: Hacienda Foral de Gipuzkoa — [gipuzkoa.eus](https://www.gipuzkoa.eus/hacienda)
- **Álava/Araba**: Hacienda Foral de Álava — [araba.eus](https://www.araba.eus/hacienda)

El botón **Activar producción** está desactivado hasta que se complete el soporte de certificados digitales en Frihet (previsto Q3 2026).

## Pipeline técnico

Frihet implementa el pipeline completo de TicketBAI en el backend:

1. **Construcción XML** — TicketBAI v1.2 per Bizkaia LROE schema
2. **Firma XAdES-BES** — certificado BYOC cifrado con AES-256-GCM
3. **Hash SHA-256** — `emisor|serie|numero|fecha|importe|hashAnterior`
4. **Envío SOAP** — BATUZ endpoint con cabeceras `eus-bizkaia-n3-*`
5. **Validación estricta** — BATUZ debe devolver CSV + IdentificadorTBAI (nunca se fabrican valores)
6. **Código QR** — generado a partir del tbaiIdentifier real de BATUZ
7. **Persistencia** — CSV + QR + hash guardados de forma cifrada e inmutable junto a la factura

## MCP (para agentes IA)

El servidor MCP de Frihet incluye la herramienta `ticketbai_status`:

```
ticketbai_status(invoiceId: string)
→ { invoiceId, status, csv, qrUrl, province, tbaiIdentifier, submittedAt }
```

Devuelve `status: "no_submission_yet"` si la factura nunca se ha enviado a TicketBAI.

## Preguntas frecuentes

**¿Es TicketBAI obligatorio para todas las empresas del País Vasco?**
Sí. Desde las fechas establecidas por cada Hacienda Foral, cualquier software de facturación en territorio foral debe cumplir con TicketBAI. Consulta el calendario de obligatoriedad en la web de tu Hacienda Foral.

**¿Es lo mismo que VeriFactu?**
No. VeriFactu es el sistema de la Agencia Tributaria estatal (AEAT) para el resto de España. TicketBAI es el sistema de las Haciendas Forales vascas. Son sistemas distintos con normativas diferentes. Si tu empresa está en el País Vasco, usas TicketBAI, no VeriFactu.

**¿Funciona el sandbox sin certificado?**
Para la fase de pruebas, el sandbox permite verificar la conectividad y el formato XML sin necesidad de certificado real. Para producción, el certificado es obligatorio.

**¿Qué pasa con las empresas en Navarra?**
Navarra tiene su propio sistema TicketBAI con normativa propia (Hacienda Foral de Navarra). No está incluido en esta versión. Los códigos postales 31xxx no activan la sección TicketBAI en Frihet.

---

## VeriFactu Fase 3: Envio a la AEAT
> Path: /cumplimiento/verifactu-fase3

# VeriFactu Fase 3: Envio a la AEAT

## Que es la Fase 3

La Fase 3 de VeriFactu es el envio automatico de los registros de facturacion a la Agencia Tributaria (AEAT) mediante mensajes SOAP/XML. Complementa las fases anteriores (hash SHA-256 y QR) con la transmision efectiva de cada alta y anulacion de factura al sistema SII de la AEAT.

Con esta fase activa, Frihet genera el XML conforme a la Orden HAC/1177/2024, lo firma con tu certificado digital y lo envia directamente a los servidores de la AEAT. Todo ocurre en segundo plano, sin intervencion manual.

:::info VeriFactu ≠ SII
Esta pagina describe el envio **VeriFactu** a la AEAT. El **SII (Suministro Inmediato de Información)** —obligatorio para empresas con facturacion superior a 6M EUR— es un sistema distinto y **forma parte de la hoja de ruta de Frihet** (planificado, todavia no disponible). No confundas ambos: solo VeriFactu envia hoy en dia de forma directa a la AEAT.
:::

## Certificado digital

Para enviar registros a la AEAT necesitas un certificado digital vigente. Frihet acepta certificados en formato `.pfx` o `.p12`.

### Donde obtener un certificado

| Emisor                                                                     | Tipo                      | Coste    |
| -------------------------------------------------------------------------- | ------------------------- | -------- |
| [FNMT (Fabrica Nacional de Moneda y Timbre)](https://www.sede.fnmt.gob.es) | Persona fisica o juridica | Gratuito |
| [CamCert (Camaras de Comercio)](https://www.camerfirma.com)                | Empresa                   | Variable |
| [ACCV (Comunitat Valenciana)](https://www.accv.es)                         | Regional                  | Gratuito |

### Subir el certificado

1. Ve a **Ajustes** > **Cumplimiento**
2. En la seccion **Certificado Digital**, haz clic en **Subir certificado**
3. Selecciona tu archivo `.pfx` o `.p12`
4. Introduce la contrasena del certificado

:::info Cifrado de la contrasena
La contrasena de tu certificado se cifra con AES-256-GCM antes de almacenarla. En ningun momento se guarda en texto plano.
:::

### Sandbox vs Produccion

El toggle **Modo sandbox** en **Ajustes** > **Cumplimiento** permite enviar registros al entorno de pruebas de la AEAT antes de activar el envio real.

- **Sandbox**: los registros se envian al endpoint de pruebas. La AEAT los valida pero no los registra oficialmente. Util para verificar que el certificado y los datos son correctos.
- **Produccion**: los registros se envian al endpoint oficial. Las facturas quedan registradas en el sistema SII de la AEAT.

:::tip
Activa el modo sandbox durante los primeros dias para confirmar que tu certificado funciona correctamente y que los datos se generan sin errores.
:::

## Envio automatico

### Activacion

1. Ve a **Ajustes** > **Cumplimiento**
2. Activa el toggle **Enviar automaticamente a AEAT**

Con este toggle activo, cada factura emitida o anulada se envia automaticamente:

### Flujo de alta (factura emitida)

1. Se calcula el hash SHA-256 de la factura (cadena inmutable)
2. Se genera el XML de alta conforme a la especificacion AEAT
3. Se firma el XML con tu certificado digital
4. Se envia via SOAP al endpoint de la AEAT
5. Se almacena la respuesta (CSV asignado o error)

### Flujo de anulacion (factura cancelada)

1. Se calcula el hash de anulacion con los 5 campos requeridos
2. Se genera el XML de anulacion
3. Se firma y envia al endpoint de la AEAT
4. Se almacena la respuesta y el estado de anulacion

Ambos flujos son fire-and-forget: el usuario puede seguir trabajando mientras el envio se procesa en segundo plano.

## Envio manual

Si el envio automatico no esta activo, o si necesitas reenviar una factura especifica:

1. Abre la factura en cuestion
2. Haz clic en el menu de acciones (tres puntos)
3. Selecciona **Enviar a AEAT**
4. Se muestra un dialogo de confirmacion con la preview del hash
5. Confirma para iniciar el envio

El envio manual sigue el mismo flujo tecnico que el automatico.

## Estados de envio

Cada factura muestra un badge con su estado de envio a la AEAT:

| Estado    | Badge               | Descripcion                                                 |
| --------- | ------------------- | ----------------------------------------------------------- |
| Pendiente | Outline (sin color) | Hash calculado, envio no iniciado                           |
| Enviado   | Gris                | Mensaje SOAP enviado, esperando respuesta de la AEAT        |
| Aceptado  | Verde               | La AEAT ha aceptado el registro y ha asignado un codigo CSV |
| Rechazado | Rojo                | La AEAT ha rechazado el registro. Ver detalle del error     |
| Error     | Rojo                | Error tecnico en el envio (red, certificado, timeout)       |

### Consultar el estado

El estado de envio es visible en:

- La vista de detalle de cada factura (badge junto al numero)
- El listado general de facturas (columna de estado)
- El [libro registro ampliado](#libro-registro-ampliado) (columnas adicionales)

## Reintentos automaticos

Cuando un envio falla por error tecnico (timeout, error de red, servicio AEAT no disponible), Frihet reintenta automaticamente:

- **Frecuencia**: cada 15 minutos
- **Maximo de intentos**: 3
- **Tras 3 fallos**: el estado queda como Error y requiere intervencion manual

Para reintentar manualmente una factura con estado Error:

1. Abre la factura
2. En el badge de estado rojo, haz clic en **Reintentar**
3. Se ejecuta un nuevo intento de envio

## Indicadores en PDF

Las facturas aceptadas por la AEAT incluyen informacion adicional en el PDF generado:

- **Badge "Registrada en AEAT"** en la cabecera del documento
- **Codigo CSV** asignado por la AEAT, junto al QR de verificacion

Estos indicadores solo aparecen cuando el estado de envio es **Aceptado**.

## Libro registro ampliado

Con la Fase 3 activa, el [libro registro](/cumplimiento/libro-registro) de facturas emitidas incluye 3 columnas adicionales:

| Columna               | Descripcion                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| Estado Envio AEAT     | Estado del envio del registro de alta (Pendiente, Enviado, Aceptado, Rechazado, Error) |
| CSV AEAT              | Codigo seguro de verificacion asignado por la AEAT al aceptar el registro              |
| Estado Anulacion AEAT | Estado del envio del registro de anulacion (si aplica)                                 |

Estas columnas se anaden al final del CSV exportado, despues de las 12 columnas estandar.

## Solucion de problemas

### "Certificado no configurado"

No se ha subido un certificado digital. Ve a **Ajustes** > **Cumplimiento** y sube tu archivo `.pfx` o `.p12`.

### "NIF no configurado"

El perfil fiscal no tiene NIF. Ve a **Ajustes** > **Perfil Fiscal** y completa tu identificador fiscal.

### Error SOAP / Error de conexion

Posibles causas:

- **Certificado expirado**: verifica la fecha de validez de tu certificado. Los certificados FNMT tienen una validez de 4 anos.
- **Contrasena incorrecta**: vuelve a subir el certificado con la contrasena correcta.
- **Servicio AEAT no disponible**: la AEAT tiene ventanas de mantenimiento. El sistema reintentara automaticamente.
- **Datos fiscales incompletos**: verifica que tu NIF, direccion fiscal y datos de empresa estan completos.

:::warning Certificado expirado
Un certificado expirado bloquea todos los envios. Renueva tu certificado en la FNMT o CamCert antes de la fecha de vencimiento.
:::

### Factura rechazada por la AEAT

La AEAT puede rechazar un registro por:

- NIF del emisor no coincide con el certificado
- Formato de fecha incorrecto
- Tipo de factura no valido para la operacion

Revisa el mensaje de error en el detalle de la factura. Corrige los datos y usa **Reintentar** para volver a enviar.

## Calendario legal

La obligacion de envio a la AEAT tiene plazos escalonados segun el RDL 15/2025:

| Tipo de contribuyente      | Fecha limite       |
| -------------------------- | ------------------ |
| Sociedades (S.L., S.A.)    | 1 de enero de 2027 |
| Autonomos (persona fisica) | 1 de julio de 2027 |

:::info
Frihet ya soporta el envio a la AEAT. Se recomienda activar el modo sandbox con antelacion para validar la configuracion antes de que la obligacion entre en vigor.
:::

## Relacion con otras fases

- **Fase 1 (Hash SHA-256)**: se calcula automaticamente en cada factura. Es la base del registro. Ver [VeriFactu](/cumplimiento/verifactu).
- **Fase 2 (QR AEAT)**: el codigo QR en el PDF enlaza a la sede electronica de la AEAT para verificacion.
- **Fase 3 (Envio AEAT)**: esta pagina. Transmision efectiva del registro a la AEAT via SOAP/XML.

---

**Anterior:** [VeriFactu](/cumplimiento/verifactu) | **Siguiente:** [Inmutabilidad y registro](/cumplimiento/inmutabilidad)

---

## VeriFactu
> Path: /cumplimiento/verifactu

# VeriFactu

## Qué es VeriFactu

VeriFactu es el sistema de facturación electrónica establecido por el RD 1007/2023 y la Orden HAC/1177/2024. Aplica a todos los **Sistemas Informáticos de Facturación (SIF)** que operan en España.

Su objetivo es garantizar la trazabilidad de las facturas y prevenir el fraude fiscal. Cada factura genera una huella digital (hash) que se encadena con la anterior, formando un registro inmutable verificable por la AEAT.

## Cómo cumple Frihet

El cumplimiento VeriFactu en Frihet está **siempre activo**. No hay toggle, no hay configuración extra, no hay módulo que activar. Frihet es uno de los pocos ERP que incluye VeriFactu de serie en todos los planes -- consulta las [funcionalidades completas](https://www.frihet.io/es/features).

Todo ocurre en segundo plano al crear o modificar facturas:

- El hash SHA-256 se calcula automáticamente en el servidor
- El código QR se genera en cada PDF
- Los campos fiscales se bloquean tras el registro
- La cadena de hash se mantiene de forma continua

El usuario no necesita hacer nada especial para cumplir con VeriFactu.

## Cadena de hash SHA-256

Cada factura genera un hash SHA-256 en el servidor. Este hash se encadena con el hash de la factura anterior, formando una cadena inmutable que garantiza la integridad del registro.

### Hash de Alta

Al crear una factura, el hash se calcula a partir de 8 campos:

| Campo                  | Descripción                                |
| ---------------------- | ------------------------------------------ |
| NIF emisor             | Identificación fiscal del emisor           |
| Número de factura      | Número completo (serie + secuencia)        |
| Fecha expedición       | En formato DD-MM-YYYY                      |
| Tipo factura           | F1, F2, R1-R5                              |
| Cuota total impuestos  | Suma de todos los impuestos                |
| Importe total          | Total de la factura                        |
| Hash anterior          | Hash de la factura inmediatamente anterior |
| Fecha/hora de registro | Timestamp del momento de generación        |

### Hash de Anulación

Al cancelar una factura, se genera un hash de anulación con 5 campos:

| Campo                  | Descripción                              |
| ---------------------- | ---------------------------------------- |
| NIF emisor             | Identificación fiscal del emisor         |
| Número de factura      | Número del documento cancelado           |
| Fecha expedición       | Fecha original de la factura             |
| Hash anterior          | Hash de la factura anterior en la cadena |
| Fecha/hora de registro | Timestamp de la anulación                |

Los campos críticos del hash son inmutables una vez calculado. No se pueden editar después de la generación del hash.

## Tipos de factura (TipoFactura)

Frihet asigna automáticamente el tipo de factura según las características del documento:

| Código | Tipo                                   | Descripción                                          |
| ------ | -------------------------------------- | ---------------------------------------------------- |
| F1     | Factura completa                       | Factura estándar (asignada por defecto)              |
| F2     | Factura simplificada                   | Facturas menores de 400 EUR sin NIF del destinatario |
| R1     | Rectificativa (art. 80.1-2, 80.6 LIVA) | Errores, descuentos retroactivos (más común)         |
| R2     | Rectificativa (art. 80.3 LIVA)         | Impago / crédito incobrable                          |
| R3     | Rectificativa (art. 80.4 LIVA)         | Concurso de acreedores                               |
| R4     | Rectificativa (resto)                  | Otros supuestos                                      |
| R5     | Rectificativa simplificada             | Rectificativa de factura simplificada                |

F2 se asigna automáticamente cuando el importe es inferior a 400 EUR y el destinatario no tiene NIF.

## Claves de régimen de IVA (ClaveRegimenIVA)

La clave de régimen identifica el tipo de operación fiscal. Frihet asigna el régimen general (01) por defecto.

| Código | Régimen                                 |
| ------ | --------------------------------------- |
| 01     | Régimen general                         |
| 02     | Exportación                             |
| 03     | Régimen especial de bienes usados       |
| 04     | Régimen especial de oro de inversión    |
| 05     | Régimen especial de agencias de viaje   |
| 06     | Régimen especial de grupos de entidades |
| 07     | Régimen especial del criterio de caja   |
| 08     | Operaciones sujetas a IPSI/IGIC         |

## QR AEAT en facturas

Todas las facturas PDF generadas por Frihet incluyen un código QR de verificación que enlaza a la sede electrónica de la AEAT.

**Formato de la URL del QR:**

```
https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif={NIF}&numserie={NUM}&fecha={DD-MM-YYYY}&importe={TOTAL}
```

Junto al QR aparece el texto: _"Factura verificable en la sede electrónica de la AEAT"_.

:::info
El código QR solo aparece cuando el perfil fiscal tiene un NIF configurado en **Configuración** → **Perfil fiscal**.
:::

## Declaración responsable del software

La declaración responsable cumple con el Art. 20 del RD 1007/2023. Es visible en **Configuración** → **Perfil fiscal** y contiene los siguientes datos:

| Campo          | Valor                                                            |
| -------------- | ---------------------------------------------------------------- |
| Software       | Frihet ERP v1.0                                                  |
| Fabricante     | (Se configura en **Ajustes** > **Cumplimiento** > **VeriFactu**) |
| NIF fabricante | (Se configura en **Ajustes** > **Cumplimiento** > **VeriFactu**) |
| Cadena de hash | SHA-256                                                          |
| Normativa      | RD 1007/2023, Orden HAC/1177/2024                                |

## Relación con modelos fiscales

VeriFactu se centra en la trazabilidad de las facturas (hash, QR, inmutabilidad). Los [modelos fiscales trimestrales](./modelos-fiscales) son un paso adicional donde se calculan las declaraciones a presentar ante Hacienda:

- [Modelo 303 (IVA)](./modelo-303) — para Península y Baleares
- [Modelo 420 (IGIC)](./modelo-420) — para Canarias
- [Modelo 130 (IRPF)](./modelo-130) — para todos los autónomos

Los datos VeriFactu (tipo de factura, clave de régimen) se incluyen automáticamente en los [libros registro](./libro-registro) exportados por Frihet.

## Fase 3: Envio a la AEAT

La Fase 3 de VeriFactu permite el envio automatico de los registros de facturacion directamente a la AEAT mediante mensajes SOAP/XML firmados con certificado digital. Con esta fase activa, cada factura emitida o anulada se transmite al sistema SII de la AEAT en segundo plano.

El envio requiere un certificado digital vigente (.pfx o .p12) configurado en **Ajustes** > **Cumplimiento**. Se puede activar en modo sandbox para pruebas antes de pasar a produccion.

Para la documentacion completa sobre configuracion, estados de envio, reintentos y solucion de problemas, consulta la [guia de Envio a la AEAT](./verifactu-fase3).

:::info Calendario de obligatoriedad
Sociedades (S.L., S.A.): 1 de enero de 2027. Autonomos: 1 de julio de 2027 (RDL 15/2025).
:::

## Normativa aplicable

- **Ley 11/2021** (Ley Antifraude) — Art. 29.2.j) LGT
- **RD 1007/2023** — Reglamento VeriFactu (RRSIF)
- **Orden HAC/1177/2024** — Especificaciones técnicas
- **RDL 15/2025** — Extensión de plazos

---

**Siguiente:** [Envio a la AEAT (Fase 3)](./verifactu-fase3) | [Inmutabilidad y registro](./inmutabilidad)

---

## Centro de acción
> Path: /dashboard-action-center

# Centro de acción

El **Centro de acción** es la primera tarjeta del [Dashboard](./dashboard.md). Resume en un solo bloque las cuatro áreas operativas que pueden requerir tu atención hoy: cobros, stock, fiscalidad y banca.

> **Restricción por diseño.** Si las cuatro áreas están a cero, el bloque entero no se muestra. Solo aparecen los carriles con señales reales — no hay relleno visual.

## Los cuatro carriles

El orden es siempre el mismo: **cobros → stock → fiscal → banco**. Cada carril aparece únicamente cuando su recuento es mayor que cero.

| Carril     | Señal de origen         | Qué cuenta                                                                                        | Botón                                                             |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Cobros** | `useInvoiceAging`       | Facturas vencidas (cualquier antigüedad >0 días) con su importe agregado                          | Revisar facturas → `/invoices`                                    |
| **Stock**  | `useLowStockProducts`   | Productos por debajo del punto de pedido configurado                                              | Revisar productos → `/products`                                   |
| **Fiscal** | `useTaxReadiness`       | Capacidades fiscales en estado `not_configured` para tu zona fiscal                               | Configurar fiscalidad → `/tax?tab=compliance#tax-readiness-panel` |
| **Banco**  | `useBankingActionQueue` | Suma de movimientos sin conciliar, marcados para revisar, sin categoría e importaciones recientes | Revisar banca → `/banking`                                        |

Cada botón te lleva a la pantalla donde puedes actuar. El carril fiscal abre directamente la pestaña _Cumplimiento_ de `/tax` y hace scroll al panel de capacidades fiscales; el resto enrutan al módulo correspondiente.

## Cómo se calcula la señal

El Centro de acción **no añade lógica nueva de negocio**. Compone cuatro hooks que ya existen en la app y aplica una regla de presentación:

- Si una métrica está a cero, el carril se omite.
- Si las cuatro están a cero, la tarjeta entera devuelve `null`.
- No hace nuevas lecturas a la base de datos; reutiliza los datos en tiempo real ya cargados por la vista.
- No llama al motor de IA ni a ninguna integración de banca de pago.
- No introduce nuevas reglas de acceso ni envía emails o notificaciones automáticas.

## Cuándo lo verás

Aparece en cuanto tu workspace tenga al menos uno de estos estados:

- Una o más facturas vencidas.
- Un producto por debajo del punto de pedido.
- Una capacidad fiscal sin configurar (por ejemplo, VeriFactu pendiente de certificado en zona peninsular).
- Movimientos bancarios sin conciliar, sin categoría o pendientes de revisión.

En cuentas nuevas y limpias, la tarjeta permanece oculta hasta que aparezca la primera señal real.

## Privacidad y control

- **No hay envíos automáticos.** El Centro de acción solo enruta. La decisión de enviar un recordatorio, conciliar un movimiento o configurar VeriFactu siempre la toma una persona dentro de la pantalla de destino.
- **No hay coste oculto.** Ningún carril dispara llamadas de pago a Tink, Salt Edge, Plaid, Open Salt ni Revolut. Las señales bancarias se derivan de transacciones ya descargadas por las integraciones gratuitas de tu plan.

## Preguntas frecuentes

**¿Puedo personalizar los carriles?** No por ahora. El conjunto (cobros / stock / fiscal / banco) es fijo para garantizar una lectura consistente del estado operativo.

**¿Por qué no aparece el Centro de acción en mi cuenta?** Porque las cuatro áreas están a cero, lo cual es buena señal. Aparecerá automáticamente cuando exista la primera acción pendiente.

**¿Sustituye al [Dashboard fiscal](./dashboard-fiscal.md)?** No. El Centro de acción es un resumen unificado; las pantallas de detalle siguen siendo el sitio para configurar e investigar.

## Disponibilidad

Disponible en todos los planes. Sin gate de tier, sin flag.

---

## Dashboard fiscal
> Path: /dashboard-fiscal

<!-- AUTO-STUB 2026-05-05 -->

# Dashboard fiscal

> El Dashboard Fiscal muestra tus obligaciones tributarias en tiempo real: estimación de IVA e IRPF del trimestre en curso, proyección de flujo de caja con impacto fiscal y alertas de vencimientos próximos.

## Overview

El Dashboard Fiscal de Frihet te da visibilidad de tu posición tributaria sin esperar al final del trimestre. A medida que emites facturas y registras gastos, la estimación del Modelo 303 (IVA) y el Modelo 130 (IRPF) se actualiza automáticamente. Así puedes provisionar el dinero necesario antes del vencimiento y evitar sorpresas.

Las tres secciones principales:

- **Estimación fiscal**: IVA repercutido, IVA soportado y cuota diferencial calculada en tiempo real. IRPF: ingresos, gastos deducibles y prepago estimado.
- **Flujo de caja proyectado**: ingresos previstos de facturas pendientes menos obligaciones fiscales del trimestre.
- **Calendario fiscal**: próximos vencimientos del trimestre con días restantes y acceso directo al modelo correspondiente.

## Quick start

1. Ve a **Dashboard → pestaña Fiscal** (o busca "dashboard fiscal" en el buscador de ajustes).
2. Revisa la estimación trimestral y el saldo proyectado tras impuestos.
3. Pulsa sobre cualquier modelo para ver el desglose completo o exportar.

## Reference

- MCP tool: `get_fiscal_summary` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Configuración → Perfil fiscal → Régimen tributario

## Related

- [Dashboard principal](./dashboard)
- [Modelos fiscales](/cumplimiento/modelos-fiscales)
- [Modelo 303 (IVA)](/cumplimiento/modelo-303)

---

## Dashboard
> Path: /dashboard

# Dashboard

El dashboard es la primera pantalla que ves al abrir Frihet. Muestra el estado financiero de tu negocio en tiempo real: ingresos, gastos, tendencias, previsiones y sugerencias de acción. Descubre todas las [funcionalidades de Frihet](https://www.frihet.io/es/features).

## KPIs principales

En la parte superior del dashboard se muestran cuatro indicadores clave:

| KPI | Qué muestra |
|-----|-------------|
| **Ingresos del mes** | Total facturado y cobrado en el mes actual, con variación porcentual respecto al mes anterior |
| **Gastos del mes** | Total de gastos registrados, con comparativa frente al mes anterior |
| **Beneficio neto** | Ingresos menos gastos del mes actual |
| **Objetivo mensual** | Barra de progreso hacia el objetivo de ingresos configurado en Configuración |

Cada KPI incluye una flecha de tendencia que indica si el valor ha subido o bajado respecto al periodo anterior.

## Métricas de salud del negocio

Tres métricas adicionales que ofrecen una visión más profunda de la actividad comercial:

- **Clientes activos** — Número de clientes con al menos una factura pagada en los últimos 90 días. Incluye tendencia respecto al periodo anterior.
- **Ingreso medio por cliente** — Ingresos del mes divididos entre el número de clientes facturados ese mes. Permite detectar si estás facturando más por cliente o diluyendo el ticket medio.
- **Tasa de retención** — Porcentaje de clientes del mes anterior que han generado al menos una factura pagada en el mes actual. Una tasa alta indica relaciones comerciales estables.

Para ver el detalle financiero por cliente (facturado, pendiente, historial), haz clic en el nombre del cliente o navega a [Detalle de cliente](./clientes/detalle-cliente).

## Gráfico de ingresos vs gastos

Gráfico de barras que muestra los últimos 12 meses de actividad financiera:

- **Barras verdes** — Ingresos mensuales
- **Barras rojas** — Gastos mensuales
- **Tooltip** — Al pasar el cursor sobre cualquier barra se muestra el importe exacto con formato de moneda

El gráfico se actualiza automáticamente con cada factura cobrada o gasto registrado.

## Previsión de ingresos

Extiende el gráfico de ingresos con una proyección a 3 meses basada en datos históricos:

- El cálculo usa la **media de los últimos 6 meses** de ingresos como base
- Las **facturas pendientes de cobro** se suman al primer mes de previsión con un factor de probabilidad del 70%
- Las barras de previsión se muestran con relleno translúcido y borde discontinuo para distinguirlas de los datos reales

La previsión solo aparece si existen al menos 3 meses de datos históricos. No sustituye una planificación financiera formal, pero ayuda a anticipar la tendencia.

## Desglose de gastos por categoría

Gráfico de donut que muestra la distribución de gastos del mes actual agrupados por categoría:

| Categoría | Color |
|-----------|-------|
| Material de oficina | Azul |
| Software y suscripciones | Violeta |
| Servicios profesionales | Naranja |
| Viajes y desplazamientos | Verde |
| Marketing y publicidad | Rosa |
| Suministros | Amarillo |
| Seguros | Gris |
| Otro | Gris claro |

La leyenda muestra el nombre de cada categoría, su color y el porcentaje sobre el total de gastos. Los gastos sin categoría asignada aparecen como "Otro".

## Sugerencias inteligentes

El dashboard analiza tu actividad y muestra hasta 4 sugerencias ordenadas por prioridad:

| Sugerencia | Prioridad | Cuándo aparece |
|------------|-----------|----------------|
| Facturas vencidas | Alta | Hay facturas con fecha de vencimiento pasada. Muestra el importe total pendiente. |
| Sin facturas este mes | Media | No has emitido ninguna factura en el mes actual. Sugiere crear una. |
| Objetivo de ingresos atrasado | Media | Los ingresos del mes están por debajo del ritmo necesario para alcanzar el objetivo. |
| Clientes inactivos (+90 días) | Media | Hay clientes que no han recibido factura en más de 90 días. Sugiere contactarlos. |
| Gastos sin categorizar | Media | Existen gastos registrados sin categoría asignada. |

Las sugerencias de prioridad alta aparecen primero. Si hay más de 4 activas, se muestran las más relevantes.

## Facturas vencidas

Widget dedicado que lista todas las facturas cuya fecha de vencimiento ha pasado sin haber sido marcadas como cobradas:

- Muestra número de factura, cliente, importe y días de retraso
- Cada entrada enlaza directamente a la factura para revisarla o enviar un recordatorio
- El total pendiente se muestra en la cabecera del widget

## Integraciones del dashboard

Si tienes integraciones configuradas, el dashboard incluye widgets adicionales:

- **Saldo Revolut** — Muestra el saldo actual de tu cuenta Revolut conectada. Requiere haber configurado la [integración con Revolut](./integraciones/revolut).
- **Accesos directos** — Enlaces rápidos a integraciones recomendadas que aún no has conectado (banco, pasarela de pago, herramientas de productividad)

## Atajos rápidos

En la parte inferior del dashboard hay cuatro botones de creación rápida:

- **Nueva factura** — Abre el formulario de factura
- **Nuevo gasto** — Abre el formulario de gasto
- **Nuevo presupuesto** — Abre el formulario de presupuesto
- **Nuevo cliente** — Abre el formulario de cliente

Estos atajos también son accesibles desde cualquier pantalla con `Alt+N` y seleccionando el tipo de documento.

---

**Siguiente:** [Facturas](./facturacion/facturas)

---

## Usar Frihet desde un agente de IA
> Path: /desarrolladores/ai-agent

# Usar Frihet desde un agente de IA

Frihet está construido para que un agente de IA lo opere de principio a fin. No es una API con una capa de IA encima: el ERP es nativo para agentes. Un asistente puede crear una factura, conciliar un banco, preparar un Modelo 303 o consultar tu tesorería — en lenguaje natural, con salida estructurada y trazable.

Esta página es el punto de entrada. Elige el canal que encaje con tu stack y estás operando en dos minutos.

```
Tu:      "Crea una factura para TechStart SL, 40 horas de consultoría a 75 EUR/h, vencimiento 1 marzo"
Agente:  Hecho. Factura INV-2026-089 — 3.000,00 EUR + 21% IVA = 3.630,00 EUR.
```

---

## Quickstart — servidor MCP

El [Model Context Protocol](https://modelcontextprotocol.io) es el estándar abierto para conectar agentes a herramientas. Frihet expone **157 herramientas** MCP — CRUD completo sobre facturación, gastos, clientes, banca, fiscal (Modelo 303/130/390/347, VeriFactu, TicketBAI), e-invoicing europeo y más.

Hay dos formas de conectarse. Elige una.

### Opción A — Remoto (cero instalación)

El endpoint `mcp.frihet.io` está siempre disponible. No instalas nada; el cliente autentica vía OAuth en el navegador o con tu API key.

```json
{
  "mcpServers": {
    "frihet": {
      "url": "https://mcp.frihet.io/mcp"
    }
  }
}
```

Clientes con soporte OAuth (Claude Desktop, Cursor, Smithery) abren una ventana de autorización la primera vez. Si tu cliente no soporta OAuth, pasa tu API key como `Authorization: Bearer fri_...`.

### Opción B — Local (stdio)

Para Claude Code, Cursor o cualquier cliente stdio, instala el paquete y exporta tu API key.

```json
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": { "FRIHET_API_KEY": "fri_tu_clave_aqui" }
    }
  }
}
```

Obtén tu API key en **app.frihet.io → Configuración → Desarrolladores → API Keys**.

---

## Divulgación progresiva (grouped mode)

Un agente que se enfrenta a 157 herramientas de golpe gasta contexto leyendo descripciones que no va a usar. El endpoint remoto agent-facing (`mcp.frihet.io`) resuelve esto con **divulgación progresiva**: en lugar del muro plano, `tools/list` devuelve resúmenes de una línea más tres meta-herramientas de descubrimiento:

- `list_tool_groups()` — los dominios disponibles (facturación, fiscal, banca, CRM, RRHH, stay, POS…) con su recuento.
- `search_tools(query)` — busca herramientas por texto libre y devuelve sólo las relevantes.
- `describe_tool(name)` — carga el esquema completo de una herramienta concreta, bajo demanda.

El agente lee el catálogo terso, busca lo que necesita y carga la profundidad sólo de las pocas herramientas que va a llamar. Cada herramienta sigue siendo invocable por su nombre real — no se quita nada, sólo se colapsa el listado. El paquete npm local se queda en modo `full` por defecto, porque los clientes locales gestionan su propio contexto.

Detalle completo en [Servidor MCP](./mcp-server).

---

## SDK y CLI

Si prefieres código a lenguaje natural, el SDK oficial y la CLI envuelven la misma API REST.

```bash
npm install @frihet/sdk      # cliente TypeScript tipado
npm install -g @frihet/cli   # frihet desde la terminal
```

```ts
import { Frihet } from '@frihet/sdk';
const frihet = new Frihet({ apiKey: process.env.FRIHET_API_KEY });
const invoice = await frihet.invoices.create({ clientId, lines, dueDate });
```

Referencia completa en [SDK y CLI](./sdk-cli).

---

## Otros canales

El mismo motor está expuesto en las plataformas donde ya vive tu automatización.

- **ChatGPT** — Frihet está disponible como app/GPT a través del endpoint `openai-mcp.frihet.io`, con la superficie de herramientas revisada para la política de OpenAI.
- **Zapier** — app nativa oficial (Beta pública). Conecta Frihet a más de [7.000+ apps](/integraciones/zapier) sin código: 14 triggers, 21 acciones y 8 búsquedas sobre facturas, gastos y clientes. [Ver en Zapier](https://zapier.com/apps/frihet/integrations).
- **n8n** — nodo oficial para flujos self-hosted.
- **Webhooks** — 27 eventos con firma HMAC-SHA256 para reaccionar a cambios en tiempo real. Ver [Webhooks](./webhooks).

---

## Superficie descubrible por IA

Cada subdominio de Frihet es citable por un agente que investiga "ERP español con IA". Si construyes sobre Frihet, estas rutas son tu contrato de descubrimiento:

| Recurso                  | URL                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Contexto LLM             | [`docs.frihet.io/llms.txt`](https://docs.frihet.io/llms.txt) · [`mcp.frihet.io/llms.txt`](https://mcp.frihet.io/llms.txt) |
| Especificación OpenAPI   | [`docs.frihet.io/openapi.json`](https://docs.frihet.io/openapi.json)                                                      |
| Referencia interactiva   | [`docs.frihet.io/api-reference`](/api-reference)                                                                          |
| Descriptor MCP           | [`mcp.frihet.io/.well-known/mcp`](https://mcp.frihet.io/.well-known/mcp)                                                  |
| Registro MCP (Anthropic) | [`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io/?q=io.frihet)                               |

---

## Ver también

- [Referencia interactiva de la API](/api-reference) — explora y prueba cada endpoint
- [Servidor MCP](./mcp-server) — las 157 herramientas en detalle
- [API REST](./api-rest) — auth, paginación, idempotencia, rate limiting
- [SDK y CLI](./sdk-cli)
- [Webhooks](./webhooks)

---

## API REST
> Path: /desarrolladores/api-rest

# API REST

La API REST de Frihet permite acceder y manipular los recursos de tu cuenta de forma programatica. Toda la comunicacion se realiza sobre HTTPS y las respuestas son JSON.

## URL base

```
https://api.frihet.io/v1
```

Todos los endpoints descritos en esta pagina son relativos a esta URL base.

**Descubrimiento:** Una peticion `GET` a la raiz (`https://api.frihet.io/`) devuelve los enlaces principales sin necesidad de autenticacion:

```json
{
  "name": "Frihet API",
  "version": "1.0.0",
  "docs": "https://docs.frihet.io/desarrolladores/api-rest",
  "openapi": "https://api.frihet.io/openapi.yaml",
  "mcp": "https://mcp.frihet.io",
  "status": "https://status.frihet.io"
}
```

La especificacion OpenAPI 3.1 esta disponible en `https://api.frihet.io/openapi.yaml`.

:::tip SDK disponible
Si usas TypeScript o JavaScript, el SDK oficial simplifica la integracion:

```bash
npm install @frihet/sdk
```

```typescript
import Frihet from '@frihet/sdk';
const frihet = new Frihet({ apiKey: 'fri_...' });
const invoices = await frihet.invoices.list({ status: 'overdue' });
```

Repositorio: [github.com/Frihet-io/frihet-sdk](https://github.com/Frihet-io/frihet-sdk)
:::

---

## Autenticacion

Cada peticion debe incluir una API key en la cabecera `X-API-Key`. Las claves se crean desde **Ajustes > Desarrolladores > API Keys** en el panel de Frihet.

Las claves tienen el prefijo `fri_` seguido de 32 bytes aleatorios codificados en base64url. Ejemplo: `fri_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678`.

```bash
curl https://api.frihet.io/v1/clients \
  -H "X-API-Key: fri_tu-clave-aqui"
```

Alternativamente, puedes enviar la clave como Bearer token en la cabecera `Authorization`:

```bash
curl https://api.frihet.io/v1/clients \
  -H "Authorization: Bearer fri_tu-clave-aqui"
```

### Seguridad de las claves

- La clave en texto plano solo se muestra **una vez**, en el momento de la creacion. No se puede recuperar despues.
- El servidor almacena un **hash SHA-256** de la clave. Incluso en caso de brecha de datos, la clave original no es recuperable.
- Puedes crear claves con **fecha de expiracion** configurable.
- Si sospechas que una clave ha sido comprometida, revocala inmediatamente desde el panel.

### Ciclo de vida de las claves

**Crear una clave:**

1. Ve a **Ajustes > Desarrolladores > API Keys**
2. Pulsa **Crear clave**
3. Asigna un nombre descriptivo (por ejemplo, `integracion-contabilidad`)
4. Opcionalmente, establece una **fecha de expiracion** en dias. Si lo dejas vacio, la clave no caduca
5. Copia la clave inmediatamente -- no podras verla de nuevo

**Expiracion:**

Las claves con fecha de expiracion dejan de funcionar automaticamente al cumplirse el plazo. Las peticiones con una clave expirada reciben un `401 Unauthorized`.

**Revocacion:**

Puedes revocar una clave en cualquier momento desde **Ajustes > Desarrolladores > API Keys**. La revocacion es **inmediata e irreversible**: las peticiones en curso con esa clave fallaran a partir de ese instante.

**Rotacion de claves:**

Para rotar una clave sin interrumpir el servicio:

1. Crea una nueva clave con el mismo alcance
2. Actualiza tu integracion para usar la nueva clave
3. Verifica que las peticiones funcionan correctamente
4. Revoca la clave anterior

**Monitorizacion:**

Cada clave muestra la fecha de **ultimo uso** en el panel de Ajustes. Revisa periodicamente las claves inactivas y revoca las que ya no se utilicen.

---

## Rate limiting

Cada clave API tiene un limite de **100 peticiones por minuto**. Si se excede, la API responde con un codigo `429`:

```json
{
  "error": "Rate limit exceeded",
  "message": "Maximum 100 requests per minute",
  "retryAfter": 60
}
```

### Cabeceras de rate limiting

Todas las respuestas de la API incluyen cabeceras para que puedas gestionar el limite de forma proactiva:

| Cabecera                | Descripcion                                             | Ejemplo      |
| ----------------------- | ------------------------------------------------------- | ------------ |
| `X-RateLimit-Limit`     | Peticiones permitidas por minuto                        | `100`        |
| `X-RateLimit-Remaining` | Peticiones restantes en la ventana actual               | `87`         |
| `X-RateLimit-Reset`     | Timestamp Unix (segundos) en que la ventana se reinicia | `1709312400` |

**Ejemplo de respuesta con cabeceras de rate limiting:**

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709312400
Content-Type: application/json
```

**Gestion del codigo 429:**

Cuando recibes un `429`, usa las cabeceras para calcular cuanto esperar antes de reintentar:

```javascript
async function fetchWithRateLimit(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const resetTimestamp = response.headers.get('X-RateLimit-Reset');
    const waitMs = Number(resetTimestamp) * 1000 - Date.now();
    await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1000)));
    return fetch(url, options);
  }

  return response;
}
```

**Recomendaciones:**

- Si recibes un `429`, espera hasta el timestamp indicado en `X-RateLimit-Reset` antes de reintentar.
- Monitoriza `X-RateLimit-Remaining` para frenar las peticiones antes de alcanzar el limite.
- Distribuye las peticiones en el tiempo en lugar de enviar rafagas.

---

## Tamano de peticion

El cuerpo de las peticiones POST, PUT y PATCH no puede exceder **1 MB**. Peticiones mayores reciben un codigo `413`.

---

## Recursos

La API expone 8 recursos principales: invoices, expenses, clients, products, quotes, vendors, deposits y webhooks. Todos soportan operaciones CRUD completas (GET, POST, PUT/PATCH, DELETE). Ademas, los clientes tienen subcolecciones CRM: contacts, activities y notes.

:::info PATCH vs PUT
Tanto `PUT` como `PATCH` aceptan actualizaciones parciales. No necesitas enviar el recurso completo -- solo los campos que quieras modificar.
:::

### Facturas (`/invoices`)

#### Listar facturas

```
GET /v1/invoices
```

**Parametros de consulta:**

| Parametro  | Tipo    | Por defecto | Descripcion                                                                    |
| ---------- | ------- | ----------- | ------------------------------------------------------------------------------ |
| `limit`    | integer | 50          | Resultados por pagina (maximo 100)                                             |
| `offset`   | integer | 0           | Numero de resultados a saltar (maximo 10.000)                                  |
| `status`   | string  | --          | Filtrar por estado: `draft`, `sent`, `partial`, `paid`, `overdue`, `cancelled` |
| `from`     | string  | --          | Fecha inicio (ISO 8601: `YYYY-MM-DD`). Filtra por `issueDate`                  |
| `to`       | string  | --          | Fecha fin (ISO 8601: `YYYY-MM-DD`). Filtra por `issueDate`                     |
| `clientId` | string  | --          | Filtrar por ID de cliente                                                      |
| `seriesId` | string  | --          | Filtrar por serie de numeracion                                                |
| `q`        | string  | --          | Busqueda de texto (nombre de cliente, numero, notas)                           |
| `cursor`   | string  | --          | Cursor para paginacion basada en cursor (ignora `offset`)                      |
| `fields`   | string  | --          | Campos a devolver, separados por coma (siempre incluye `id`)                   |

**Ejemplo:**

```bash
curl "https://api.frihet.io/v1/invoices?limit=10&status=paid&from=2026-01-01&to=2026-03-31" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "abc123",
      "clientName": "Acme S.L.",
      "items": [{ "description": "Consultoria", "quantity": 10, "unitPrice": 75 }],
      "status": "paid",
      "issueDate": "2026-01-15",
      "dueDate": "2026-02-15",
      "taxRate": 21,
      "notes": "",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-20T14:00:00.000Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
```

#### Obtener factura

```
GET /v1/invoices/:id
```

```bash
curl https://api.frihet.io/v1/invoices/abc123 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "id": "abc123",
  "clientName": "Acme S.L.",
  "items": [{ "description": "Consultoria", "quantity": 10, "unitPrice": 75 }],
  "status": "paid",
  "issueDate": "2026-01-15",
  "dueDate": "2026-02-15",
  "taxRate": 21,
  "notes": "",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T14:00:00.000Z"
}
```

#### Crear factura

```
POST /v1/invoices
```

**Campos requeridos:**

| Campo        | Tipo   | Descripcion                                                                       |
| ------------ | ------ | --------------------------------------------------------------------------------- |
| `clientName` | string | Nombre del cliente (max 10.000 caracteres)                                        |
| `items`      | array  | Lista de lineas de la factura. Cada linea: `{ description, quantity, unitPrice }` |

**Campos opcionales:**

| Campo       | Tipo   | Descripcion                                                          |
| ----------- | ------ | -------------------------------------------------------------------- |
| `status`    | string | `draft` (defecto), `sent`, `partial`, `paid`, `overdue`, `cancelled` |
| `issueDate` | string | Fecha de emision (ISO 8601). Por defecto: hoy                        |
| `dueDate`   | string | Fecha de vencimiento (ISO 8601)                                      |
| `notes`     | string | Notas internas (max 10.000 caracteres)                               |
| `taxRate`   | number | Porcentaje de impuesto (0-100). Ej: `21` para IVA 21%                |

**Estructura de cada linea (`items[]`):**

| Campo         | Tipo   | Requerido | Descripcion                                      |
| ------------- | ------ | --------- | ------------------------------------------------ |
| `description` | string | Si        | Descripcion del concepto (max 10.000 caracteres) |
| `quantity`    | number | Si        | Cantidad                                         |
| `unitPrice`   | number | Si        | Precio unitario                                  |

```bash
curl -X POST https://api.frihet.io/v1/invoices \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme S.L.",
    "items": [
      { "description": "Desarrollo web", "quantity": 40, "unitPrice": 60 }
    ],
    "dueDate": "2026-03-01",
    "taxRate": 21,
    "notes": "Proyecto Q1 2026"
  }'
```

**Respuesta (201):**

```json
{
  "id": "def456",
  "clientName": "Acme S.L.",
  "items": [{ "description": "Desarrollo web", "quantity": 40, "unitPrice": 60 }],
  "status": "draft",
  "issueDate": "2026-02-12",
  "dueDate": "2026-03-01",
  "taxRate": 21,
  "notes": "Proyecto Q1 2026",
  "createdAt": "2026-02-12T09:00:00.000Z",
  "updatedAt": "2026-02-12T09:00:00.000Z"
}
```

#### Actualizar factura (PUT o PATCH)

```
PUT /v1/invoices/:id
PATCH /v1/invoices/:id
```

Solo necesitas enviar los campos que quieras modificar. Los campos no incluidos permanecen sin cambios.

```bash
curl -X PATCH https://api.frihet.io/v1/invoices/def456 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "sent",
    "notes": "Enviada al cliente"
  }'
```

**Respuesta (200):** Objeto de factura actualizado.

:::caution
Si envias `items`, debes enviar el array completo -- no se admiten actualizaciones parciales de lineas individuales.
:::

#### Eliminar factura

```
DELETE /v1/invoices/:id
```

```bash
curl -X DELETE https://api.frihet.io/v1/invoices/def456 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta:** `204 No Content`

#### Descargar factura en PDF

```
GET /v1/invoices/:id/pdf
```

Devuelve el PDF de la factura como `application/pdf` con la cabecera `Content-Disposition: attachment`.

```bash
curl -o factura.pdf https://api.frihet.io/v1/invoices/abc123/pdf \
  -H "X-API-Key: fri_tu-clave-aqui"
```

#### Enviar factura por email

```
POST /v1/invoices/:id/send
```

Envia la factura al destinatario especificado a traves de Resend. Si la factura esta en estado `draft`, se actualiza automaticamente a `sent`.

**Campos:**

| Campo            | Tipo   | Requerido | Descripcion                                                         |
| ---------------- | ------ | --------- | ------------------------------------------------------------------- |
| `recipientEmail` | string | Si        | Email del destinatario (max 255 caracteres)                         |
| `recipientName`  | string | No        | Nombre del destinatario (max 200 caracteres)                        |
| `customMessage`  | string | No        | Mensaje personalizado en el cuerpo del email (max 5.000 caracteres) |
| `locale`         | string | No        | Idioma del email: `es` (defecto) o `en`                             |

```bash
curl -X POST https://api.frihet.io/v1/invoices/abc123/send \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "admin@acme.es",
    "recipientName": "Departamento de Contabilidad",
    "locale": "es"
  }'
```

**Respuesta (200):**

```json
{ "success": true, "messageId": "re_abc123..." }
```

#### Marcar factura como pagada

```
POST /v1/invoices/:id/paid
```

| Campo      | Tipo   | Requerido | Descripcion                                |
| ---------- | ------ | --------- | ------------------------------------------ |
| `paidDate` | string | No        | Fecha de pago (ISO 8601). Por defecto: hoy |

```bash
curl -X POST https://api.frihet.io/v1/invoices/abc123/paid \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "paidDate": "2026-03-15" }'
```

**Respuesta (200):**

```json
{ "success": true, "status": "paid", "paidAt": "2026-03-15" }
```

#### Crear factura rectificativa (abono)

```
POST /v1/invoices/:id/credit-note
```

Crea un abono o nota de credito a partir de una factura existente.

| Campo               | Tipo    | Requerido | Descripcion                                                                                       |
| ------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------- |
| `reason`            | string  | Si        | Motivo: `refund`, `discount`, `error`, `cancellation`, `other`                                    |
| `type`              | string  | No        | Tipo R de rectificacion: `R1`, `R2`, `R3`, `R4`, `R5`. Si se omite, se infiere del campo `reason` |
| `reasonDescription` | string  | No        | Descripcion libre del motivo                                                                      |
| `fullCredit`        | boolean | No        | `true` = abono total (tipo S), `false` = parcial (tipo I). Por defecto: `true`                    |
| `issueDate`         | string  | No        | Fecha de emision (YYYY-MM-DD). Por defecto: hoy                                                   |

```bash
curl -X POST https://api.frihet.io/v1/invoices/abc123/credit-note \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "error",
    "type": "R1",
    "reasonDescription": "Correccion de importe",
    "fullCredit": true
  }'
```

**Respuesta (201):**

```json
{
  "success": true,
  "creditNote": {
    "id": "xyz789",
    "documentNumber": "CN-F2026-0042",
    "originalInvoiceId": "abc123",
    "reason": "error",
    "type": "R1",
    "fullCredit": true,
    "issueDate": "2026-03-28",
    "createdAt": "2026-03-28T10:00:00.000Z"
  }
}
```

**Tipos R disponibles:**

| Tipo | Descripcion legal                                         |
| ---- | --------------------------------------------------------- |
| `R1` | Art. 80.1, 80.2, 80.6 y art. 6 del Real Decreto 1496/2003 |
| `R2` | Art. 80.3 — Concurso de acreedores                        |
| `R3` | Art. 80.4 — Creditos incobrables                          |
| `R4` | Resto de causas (devolucion, descuento, anulacion)        |
| `R5` | Facturas simplificadas (art. 7.2 del RD 1619/2012)        |

**Mapeo automatico de `reason` a tipo R cuando `type` se omite:**

| Motivo         | Tipo R inferido |
| -------------- | --------------- |
| `error`        | R1              |
| `refund`       | R4              |
| `discount`     | R4              |
| `cancellation` | R4              |
| `other`        | R4              |

#### Descargar factura en XML (EN16931)

```
GET /v1/invoices/:id/xml
```

Devuelve la factura como fichero XML de e-factura EN16931 en formato UBL 2.1 o CII (Cross Industry Invoice), segun la configuracion de la cuenta.

**Auth:** API key requerida (`X-API-Key`).

**Respuesta:** `application/xml` con cabecera `Content-Disposition: attachment`.

```bash
curl -o factura.xml "https://api.frihet.io/v1/invoices/abc123/xml" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200) — ejemplo UBL 2.1:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017</cbc:CustomizationID>
  <cbc:ID>F2026-0042</cbc:ID>
  <cbc:IssueDate>2026-01-15</cbc:IssueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <!-- ... -->
</Invoice>
```

**Errores posibles:**

| Codigo | Descripcion                                                                            |
| ------ | -------------------------------------------------------------------------------------- |
| `404`  | Factura no encontrada                                                                  |
| `422`  | La factura no tiene datos suficientes para generar el XML (p.ej., sin NIF del cliente) |

:::info Formato del XML
El formato (UBL 2.1 o CII) se configura en **Ajustes > Facturacion > E-factura**. UBL 2.1 es el formato por defecto y el requerido para VeriFactu y Facturae en Espana.
:::

#### Aplicar recargo por demora

```
POST /v1/invoices/:id/late-fee
```

Aplica un recargo por demora a una factura vencida. Genera una nota de debito con el importe calculado segun la configuracion de recargos de la cuenta (**Ajustes > Facturacion > Recargos por demora**).

**Auth:** API key requerida (`X-API-Key`).

**Requisito:** La factura debe estar en estado `overdue`. Si la factura no esta vencida, la API devuelve `422`.

**Body:** `{}` (vacio). Los parametros del recargo se toman de la configuracion de la cuenta.

```bash
curl -X POST "https://api.frihet.io/v1/invoices/abc123/late-fee" \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Respuesta (201):**

```json
{
  "success": true,
  "lateFee": {
    "id": "lf_abc789",
    "documentNumber": "DR-F2026-0001",
    "originalInvoiceId": "abc123",
    "type": "debit_note",
    "feeAmount": 18.15,
    "currency": "EUR",
    "daysOverdue": 22,
    "issueDate": "2026-03-28",
    "createdAt": "2026-03-28T10:00:00.000Z"
  }
}
```

**Errores posibles:**

| Codigo | Descripcion                                                                    |
| ------ | ------------------------------------------------------------------------------ |
| `404`  | Factura no encontrada                                                          |
| `422`  | La factura no esta en estado `overdue` o ya tiene un recargo por demora activo |

:::tip Configuracion de recargos
Define el porcentaje anual o importe fijo en **Ajustes > Facturacion > Recargos por demora**. El calculo usa la Ley 3/2004 (LMOC) para operaciones entre empresas por defecto.
:::

---

### Gastos (`/expenses`)

#### Listar gastos

```
GET /v1/expenses
```

**Parametros de consulta:**

| Parametro  | Tipo    | Por defecto | Descripcion                                        |
| ---------- | ------- | ----------- | -------------------------------------------------- |
| `limit`    | integer | 50          | Resultados por pagina (maximo 100)                 |
| `offset`   | integer | 0           | Numero de resultados a saltar                      |
| `from`     | string  | --          | Fecha inicio (ISO 8601). Filtra por `date`         |
| `to`       | string  | --          | Fecha fin (ISO 8601). Filtra por `date`            |
| `category` | string  | --          | Filtrar por categoria                              |
| `vendorId` | string  | --          | Filtrar por ID de proveedor                        |
| `q`        | string  | --          | Busqueda de texto (proveedor, descripcion, numero) |
| `cursor`   | string  | --          | Cursor para paginacion basada en cursor            |
| `fields`   | string  | --          | Campos a devolver, separados por coma              |

```bash
curl "https://api.frihet.io/v1/expenses?limit=20&from=2026-01-01" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "exp789",
      "description": "Licencia Adobe Creative Cloud",
      "amount": 59.99,
      "category": "software",
      "date": "2026-02-01",
      "vendor": "Adobe Inc.",
      "taxDeductible": true,
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-02-01T10:00:00.000Z"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}
```

#### Obtener gasto

```
GET /v1/expenses/:id
```

#### Crear gasto

```
POST /v1/expenses
```

**Campos requeridos:**

| Campo         | Tipo   | Descripcion                                   |
| ------------- | ------ | --------------------------------------------- |
| `description` | string | Descripcion del gasto (max 10.000 caracteres) |
| `amount`      | number | Importe del gasto                             |

**Campos opcionales:**

| Campo           | Tipo    | Descripcion                                  |
| --------------- | ------- | -------------------------------------------- |
| `category`      | string  | Categoria del gasto (max 10.000 caracteres)  |
| `date`          | string  | Fecha del gasto (ISO 8601). Por defecto: hoy |
| `vendor`        | string  | Proveedor (max 10.000 caracteres)            |
| `taxDeductible` | boolean | Si el gasto es deducible                     |

```bash
curl -X POST https://api.frihet.io/v1/expenses \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Licencia Adobe Creative Cloud",
    "amount": 59.99,
    "category": "software",
    "date": "2026-02-01",
    "vendor": "Adobe Inc.",
    "taxDeductible": true
  }'
```

**Respuesta (201):**

```json
{
  "id": "exp789",
  "description": "Licencia Adobe Creative Cloud",
  "amount": 59.99,
  "category": "software",
  "date": "2026-02-01",
  "vendor": "Adobe Inc.",
  "taxDeductible": true,
  "createdAt": "2026-02-12T09:15:00.000Z",
  "updatedAt": "2026-02-12T09:15:00.000Z"
}
```

#### Actualizar gasto (PUT o PATCH)

```
PUT /v1/expenses/:id
PATCH /v1/expenses/:id
```

```bash
curl -X PATCH https://api.frihet.io/v1/expenses/exp789 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 65.99, "taxDeductible": false }'
```

**Respuesta (200):** Objeto de gasto actualizado.

#### Eliminar gasto

```
DELETE /v1/expenses/:id
```

**Respuesta:** `204 No Content`

#### Marcar gasto como facturable

```
POST /v1/expenses/:id/billable
```

Vincula un gasto a un cliente para que se pueda facturar. Opcionalmente aplica un markup.

| Campo      | Tipo   | Requerido | Descripcion                    |
| ---------- | ------ | --------- | ------------------------------ |
| `clientId` | string | Si        | ID del cliente al que facturar |
| `markup`   | number | No        | Porcentaje de markup (0-1000%) |

```bash
curl -X POST https://api.frihet.io/v1/expenses/exp789/billable \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "cli001", "markup": 15 }'
```

Para desvincular el gasto:

```
DELETE /v1/expenses/:id/billable
```

---

### Clientes (`/clients`)

#### Listar clientes

```
GET /v1/clients
```

**Parametros de consulta:**

| Parametro | Tipo    | Por defecto | Descripcion                                                                                   |
| --------- | ------- | ----------- | --------------------------------------------------------------------------------------------- |
| `limit`   | integer | 50          | Resultados por pagina (maximo 100)                                                            |
| `offset`  | integer | 0           | Numero de resultados a saltar                                                                 |
| `from`    | string  | --          | Fecha inicio (ISO 8601). Filtra por `createdAt`                                               |
| `to`      | string  | --          | Fecha fin (ISO 8601). Filtra por `createdAt`                                                  |
| `stage`   | string  | --          | Filtrar por etapa del pipeline: `lead`, `contacted`, `proposal`, `active`, `inactive`, `lost` |
| `q`       | string  | --          | Busqueda de texto (nombre, email, NIF)                                                        |
| `cursor`  | string  | --          | Cursor para paginacion basada en cursor                                                       |
| `fields`  | string  | --          | Campos a devolver, separados por coma                                                         |

```bash
curl "https://api.frihet.io/v1/clients?limit=50" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

#### Obtener cliente

```
GET /v1/clients/:id
```

#### Crear cliente

```
POST /v1/clients
```

**Campos requeridos:**

| Campo  | Tipo   | Descripcion                                |
| ------ | ------ | ------------------------------------------ |
| `name` | string | Nombre del cliente (max 10.000 caracteres) |

**Campos opcionales:**

| Campo     | Tipo   | Descripcion                      |
| --------- | ------ | -------------------------------- |
| `email`   | string | Email de contacto                |
| `phone`   | string | Telefono                         |
| `taxId`   | string | NIF/CIF/VAT                      |
| `address` | object | Direccion (ver estructura abajo) |

**Estructura de `address`:**

| Campo        | Tipo   | Descripcion        |
| ------------ | ------ | ------------------ |
| `street`     | string | Calle y numero     |
| `city`       | string | Ciudad             |
| `state`      | string | Provincia o estado |
| `postalCode` | string | Codigo postal      |
| `country`    | string | Pais               |

Todos los campos de `address` son opcionales.

```bash
curl -X POST https://api.frihet.io/v1/clients \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme S.L.",
    "email": "admin@acme.es",
    "taxId": "B12345678",
    "address": {
      "street": "Calle Gran Via 42",
      "city": "Madrid",
      "postalCode": "28013",
      "country": "ES"
    }
  }'
```

**Respuesta (201):**

```json
{
  "id": "cli001",
  "name": "Acme S.L.",
  "email": "admin@acme.es",
  "taxId": "B12345678",
  "address": {
    "street": "Calle Gran Via 42",
    "city": "Madrid",
    "postalCode": "28013",
    "country": "ES"
  },
  "createdAt": "2026-02-12T09:30:00.000Z",
  "updatedAt": "2026-02-12T09:30:00.000Z"
}
```

#### Actualizar cliente (PUT o PATCH)

```
PUT /v1/clients/:id
PATCH /v1/clients/:id
```

```bash
curl -X PATCH https://api.frihet.io/v1/clients/cli001 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+34 912 345 678" }'
```

**Respuesta (200):** Objeto de cliente actualizado.

#### Eliminar cliente

```
DELETE /v1/clients/:id
```

**Respuesta:** `204 No Content`

---

### CRM: Personas de contacto, Actividades y Notas

Los clientes tienen tres subcolecciones para gestionar relaciones CRM: personas de contacto, actividades y notas. Todos los endpoints requieren un `clientId` valido en la URL.

#### Personas de contacto (`/v1/clients/:id/contacts`)

##### Listar contactos

```
GET /v1/clients/:id/contacts
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/contacts" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Obtener contacto

```
GET /v1/clients/:id/contacts/:contactId
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/contacts/con001" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Crear contacto

```
POST /v1/clients/:id/contacts
```

**Campos requeridos:**

| Campo  | Tipo   | Descripcion                      |
| ------ | ------ | -------------------------------- |
| `name` | string | Nombre de la persona de contacto |

**Campos opcionales:**

| Campo       | Tipo    | Descripcion                             |
| ----------- | ------- | --------------------------------------- |
| `email`     | string  | Email del contacto                      |
| `phone`     | string  | Telefono                                |
| `role`      | string  | Cargo o rol (ej. "Director financiero") |
| `isPrimary` | boolean | Si es el contacto principal del cliente |

```bash
curl -X POST https://api.frihet.io/v1/clients/cli001/contacts \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Garcia",
    "email": "maria@acme.es",
    "phone": "+34 612 345 678",
    "role": "Directora financiera",
    "isPrimary": true
  }'
```

**Respuesta (201):**

```json
{
  "id": "con001",
  "name": "Maria Garcia",
  "email": "maria@acme.es",
  "phone": "+34 612 345 678",
  "role": "Directora financiera",
  "isPrimary": true,
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:00:00.000Z"
}
```

##### Actualizar contacto

```
PATCH /v1/clients/:id/contacts/:contactId
```

```bash
curl -X PATCH https://api.frihet.io/v1/clients/cli001/contacts/con001 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "role": "CEO" }'
```

**Respuesta (200):** Objeto de contacto actualizado.

##### Eliminar contacto

```
DELETE /v1/clients/:id/contacts/:contactId
```

```bash
curl -X DELETE https://api.frihet.io/v1/clients/cli001/contacts/con001 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta:** `204 No Content`

#### Actividades (`/v1/clients/:id/activities`)

El timeline de actividades registra las interacciones con un cliente. Las actividades del sistema (como `invoice_created`, `quote_sent`, etc.) se generan automaticamente. Tambien puedes crear actividades manuales.

:::caution Inmutables
Las actividades son inmutables. No se pueden actualizar ni eliminar una vez creadas.
:::

##### Listar actividades

```
GET /v1/clients/:id/activities
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/activities" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Obtener actividad

```
GET /v1/clients/:id/activities/:activityId
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/activities/act001" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Crear actividad

```
POST /v1/clients/:id/activities
```

**Campos requeridos:**

| Campo   | Tipo   | Descripcion                                            |
| ------- | ------ | ------------------------------------------------------ |
| `type`  | string | Tipo de actividad: `call`, `email`, `meeting` o `task` |
| `title` | string | Titulo descriptivo de la actividad                     |

**Campos opcionales:**

| Campo         | Tipo   | Descripcion                        |
| ------------- | ------ | ---------------------------------- |
| `description` | string | Descripcion detallada              |
| `metadata`    | object | Datos adicionales en formato libre |

:::info Tipos de actividad
Los tipos `call`, `email`, `meeting` y `task` son para actividades creadas manualmente. Los tipos del sistema como `invoice_created`, `quote_sent` o `expense_linked` se generan automaticamente y no se pueden crear via API.
:::

```bash
curl -X POST https://api.frihet.io/v1/clients/cli001/activities \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "call",
    "title": "Llamada de seguimiento presupuesto Q2",
    "description": "Comentamos las condiciones del presupuesto. Pendiente de confirmar.",
    "metadata": {
      "duration": "15min",
      "outcome": "pending"
    }
  }'
```

**Respuesta (201):**

```json
{
  "id": "act001",
  "type": "call",
  "title": "Llamada de seguimiento presupuesto Q2",
  "description": "Comentamos las condiciones del presupuesto. Pendiente de confirmar.",
  "metadata": {
    "duration": "15min",
    "outcome": "pending"
  },
  "createdAt": "2026-03-15T14:30:00.000Z"
}
```

#### Notas (`/v1/clients/:id/notes`)

##### Listar notas

```
GET /v1/clients/:id/notes
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/notes" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Obtener nota

```
GET /v1/clients/:id/notes/:noteId
```

```bash
curl "https://api.frihet.io/v1/clients/cli001/notes/note001" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

##### Crear nota

```
POST /v1/clients/:id/notes
```

**Campos requeridos:**

| Campo     | Tipo   | Descripcion          |
| --------- | ------ | -------------------- |
| `content` | string | Contenido de la nota |

```bash
curl -X POST https://api.frihet.io/v1/clients/cli001/notes \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cliente interesado en plan Premium. Contactar en abril para renovacion."
  }'
```

**Respuesta (201):**

```json
{
  "id": "note001",
  "content": "Cliente interesado en plan Premium. Contactar en abril para renovacion.",
  "createdAt": "2026-03-15T16:00:00.000Z",
  "updatedAt": "2026-03-15T16:00:00.000Z"
}
```

##### Actualizar nota

```
PATCH /v1/clients/:id/notes/:noteId
```

```bash
curl -X PATCH https://api.frihet.io/v1/clients/cli001/notes/note001 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cliente interesado en plan Premium. Reunion confirmada 5 de abril."
  }'
```

**Respuesta (200):** Objeto de nota actualizado.

##### Eliminar nota

```
DELETE /v1/clients/:id/notes/:noteId
```

```bash
curl -X DELETE https://api.frihet.io/v1/clients/cli001/notes/note001 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta:** `204 No Content`

---

### Productos (`/products`)

#### Listar productos

```
GET /v1/products
```

Acepta `limit`, `offset`, `from` y `to` (filtra por `createdAt`).

#### Obtener producto

```
GET /v1/products/:id
```

#### Crear producto

```
POST /v1/products
```

**Campos requeridos:**

| Campo       | Tipo   | Descripcion                                            |
| ----------- | ------ | ------------------------------------------------------ |
| `name`      | string | Nombre del producto o servicio (max 10.000 caracteres) |
| `unitPrice` | number | Precio unitario                                        |

**Campos opcionales:**

| Campo         | Tipo   | Descripcion                         |
| ------------- | ------ | ----------------------------------- |
| `description` | string | Descripcion (max 10.000 caracteres) |
| `taxRate`     | number | Porcentaje de impuesto (0-100)      |

```bash
curl -X POST https://api.frihet.io/v1/products \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hora de consultoria",
    "unitPrice": 75,
    "description": "Consultoria estrategica",
    "taxRate": 21
  }'
```

**Respuesta (201):**

```json
{
  "id": "prod001",
  "name": "Hora de consultoria",
  "unitPrice": 75,
  "description": "Consultoria estrategica",
  "taxRate": 21,
  "createdAt": "2026-02-12T10:00:00.000Z",
  "updatedAt": "2026-02-12T10:00:00.000Z"
}
```

#### Actualizar producto (PUT o PATCH)

```
PUT /v1/products/:id
PATCH /v1/products/:id
```

```bash
curl -X PATCH https://api.frihet.io/v1/products/prod001 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{ "unitPrice": 85 }'
```

**Respuesta (200):** Objeto de producto actualizado.

#### Eliminar producto

```
DELETE /v1/products/:id
```

**Respuesta:** `204 No Content`

---

### Presupuestos (`/quotes`)

#### Listar presupuestos

```
GET /v1/quotes
```

**Parametros de consulta:**

| Parametro | Tipo    | Por defecto | Descripcion                                                            |
| --------- | ------- | ----------- | ---------------------------------------------------------------------- |
| `limit`   | integer | 50          | Resultados por pagina (maximo 100)                                     |
| `offset`  | integer | 0           | Numero de resultados a saltar                                          |
| `status`  | string  | --          | Filtrar por estado: `draft`, `sent`, `accepted`, `rejected`, `expired` |
| `from`    | string  | --          | Fecha inicio (ISO 8601). Filtra por `issueDate`                        |
| `to`      | string  | --          | Fecha fin (ISO 8601). Filtra por `issueDate`                           |

```bash
curl "https://api.frihet.io/v1/quotes?status=sent" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

#### Obtener presupuesto

```
GET /v1/quotes/:id
```

#### Crear presupuesto

```
POST /v1/quotes
```

**Campos requeridos:**

| Campo        | Tipo   | Descripcion                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `clientName` | string | Nombre del cliente (max 10.000 caracteres)                                 |
| `items`      | array  | Lineas del presupuesto. Cada linea: `{ description, quantity, unitPrice }` |

**Campos opcionales:**

| Campo        | Tipo   | Descripcion                                                  |
| ------------ | ------ | ------------------------------------------------------------ |
| `validUntil` | string | Fecha de validez (ISO 8601)                                  |
| `notes`      | string | Notas o condiciones (max 10.000 caracteres)                  |
| `status`     | string | `draft` (defecto), `sent`, `accepted`, `rejected`, `expired` |

```bash
curl -X POST https://api.frihet.io/v1/quotes \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Design Studio SL",
    "items": [
      { "description": "Desarrollo web", "quantity": 80, "unitPrice": 60 },
      { "description": "Diseno UX", "quantity": 20, "unitPrice": 55 }
    ],
    "validUntil": "2026-04-01",
    "notes": "Incluye 2 rondas de revision"
  }'
```

**Respuesta (201):**

```json
{
  "id": "quo001",
  "clientName": "Design Studio SL",
  "items": [
    { "description": "Desarrollo web", "quantity": 80, "unitPrice": 60 },
    { "description": "Diseno UX", "quantity": 20, "unitPrice": 55 }
  ],
  "status": "draft",
  "validUntil": "2026-04-01",
  "notes": "Incluye 2 rondas de revision",
  "createdAt": "2026-02-12T11:00:00.000Z",
  "updatedAt": "2026-02-12T11:00:00.000Z"
}
```

#### Actualizar presupuesto (PUT o PATCH)

```
PUT /v1/quotes/:id
PATCH /v1/quotes/:id
```

#### Eliminar presupuesto

```
DELETE /v1/quotes/:id
```

**Respuesta:** `204 No Content`

#### Descargar presupuesto en PDF

```
GET /v1/quotes/:id/pdf
```

Funciona igual que `/invoices/:id/pdf`. Devuelve `application/pdf`.

```bash
curl -o presupuesto.pdf https://api.frihet.io/v1/quotes/quo001/pdf \
  -H "X-API-Key: fri_tu-clave-aqui"
```

#### Enviar presupuesto por email

```
POST /v1/quotes/:id/send
```

Mismos campos que `/invoices/:id/send` (`recipientEmail`, `recipientName`, `customMessage`, `locale`). Si el presupuesto esta en estado `draft`, se actualiza automaticamente a `sent`.

---

### Proveedores (`/vendors`)

#### Listar proveedores

```
GET /v1/vendors
```

Acepta `limit`, `offset`, `from`, `to` (filtra por `createdAt`), `q`, `cursor`, `fields`.

#### Obtener proveedor

```
GET /v1/vendors/:id
```

#### Crear proveedor

```
POST /v1/vendors
```

**Campos requeridos:**

| Campo  | Tipo   | Descripcion          |
| ------ | ------ | -------------------- |
| `name` | string | Nombre del proveedor |

**Campos opcionales:**

| Campo     | Tipo   | Descripcion                                                               |
| --------- | ------ | ------------------------------------------------------------------------- |
| `email`   | string | Email de contacto                                                         |
| `phone`   | string | Telefono                                                                  |
| `taxId`   | string | NIF/CIF/VAT                                                               |
| `address` | object | Direccion (`street`, `city`, `province`, `zip`, `country`, `countryCode`) |

```bash
curl -X POST https://api.frihet.io/v1/vendors \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adobe Inc.",
    "email": "billing@adobe.com",
    "taxId": "US87-1166924"
  }'
```

#### Actualizar proveedor (PUT o PATCH)

```
PUT /v1/vendors/:id
PATCH /v1/vendors/:id
```

#### Eliminar proveedor

```
DELETE /v1/vendors/:id
```

**Respuesta:** `204 No Content`

---

### Depositos (`/deposits`)

Los depositos permiten registrar pagos anticipados o senales de clientes antes de emitir la factura final. Un deposito puede aplicarse total o parcialmente a una o varias facturas, o reembolsarse al cliente.

#### Listar depositos

```
GET /v1/deposits
```

**Parametros de consulta:**

| Parametro  | Tipo    | Por defecto | Descripcion                                                     |
| ---------- | ------- | ----------- | --------------------------------------------------------------- |
| `limit`    | integer | 50          | Resultados por pagina (maximo 100)                              |
| `offset`   | integer | 0           | Numero de resultados a saltar                                   |
| `clientId` | string  | --          | Filtrar por ID de cliente                                       |
| `status`   | string  | --          | Filtrar por estado: `pending`, `partial`, `applied`, `refunded` |
| `from`     | string  | --          | Fecha inicio (ISO 8601: `YYYY-MM-DD`). Filtra por `date`        |
| `to`       | string  | --          | Fecha fin (ISO 8601: `YYYY-MM-DD`). Filtra por `date`           |
| `cursor`   | string  | --          | Cursor para paginacion basada en cursor (ignora `offset`)       |
| `fields`   | string  | --          | Campos a devolver, separados por coma (siempre incluye `id`)    |

**Ejemplo:**

```bash
curl "https://api.frihet.io/v1/deposits?clientId=cli001&status=pending" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "dep001",
      "clientId": "cli001",
      "clientName": "Acme S.L.",
      "amount": 2000,
      "currency": "EUR",
      "date": "2026-03-15",
      "description": "Senal proyecto Q2",
      "paymentMethod": "bank_transfer",
      "reference": "TRF-20260315-001",
      "status": "pending",
      "appliedAmount": 0,
      "remainingAmount": 2000,
      "notes": "",
      "createdAt": "2026-03-15T10:00:00.000Z",
      "updatedAt": "2026-03-15T10:00:00.000Z"
    }
  ],
  "total": 5,
  "limit": 50,
  "offset": 0
}
```

#### Obtener deposito

```
GET /v1/deposits/{id}
```

```bash
curl https://api.frihet.io/v1/deposits/dep001 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "id": "dep001",
  "clientId": "cli001",
  "clientName": "Acme S.L.",
  "amount": 2000,
  "currency": "EUR",
  "date": "2026-03-15",
  "description": "Senal proyecto Q2",
  "paymentMethod": "bank_transfer",
  "reference": "TRF-20260315-001",
  "status": "pending",
  "appliedAmount": 0,
  "remainingAmount": 2000,
  "notes": "",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:00:00.000Z"
}
```

#### Crear deposito

```
POST /v1/deposits
```

**Campos requeridos:**

| Campo      | Tipo   | Descripcion                              |
| ---------- | ------ | ---------------------------------------- |
| `clientId` | string | ID del cliente                           |
| `amount`   | number | Importe del deposito (debe ser positivo) |

**Campos opcionales:**

| Campo           | Tipo   | Descripcion                                                   |
| --------------- | ------ | ------------------------------------------------------------- |
| `currency`      | string | Codigo ISO 4217 (3 caracteres). Por defecto: `EUR`            |
| `date`          | string | Fecha del deposito (ISO 8601: `YYYY-MM-DD`). Por defecto: hoy |
| `description`   | string | Descripcion o concepto del deposito (max 10.000 caracteres)   |
| `paymentMethod` | string | Metodo de pago: `bank_transfer`, `card`, `cash`, `other`      |
| `reference`     | string | Referencia del pago (max 500 caracteres)                      |
| `notes`         | string | Notas internas (max 10.000 caracteres)                        |

```bash
curl -X POST https://api.frihet.io/v1/deposits \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli001",
    "amount": 2000,
    "currency": "EUR",
    "date": "2026-03-15",
    "description": "Senal proyecto Q2",
    "paymentMethod": "bank_transfer",
    "reference": "TRF-20260315-001",
    "notes": "Pago anticipado confirmado por email"
  }'
```

**Respuesta (201):**

```json
{
  "id": "dep001",
  "clientId": "cli001",
  "clientName": "Acme S.L.",
  "amount": 2000,
  "currency": "EUR",
  "date": "2026-03-15",
  "description": "Senal proyecto Q2",
  "paymentMethod": "bank_transfer",
  "reference": "TRF-20260315-001",
  "status": "pending",
  "appliedAmount": 0,
  "remainingAmount": 2000,
  "notes": "Pago anticipado confirmado por email",
  "createdAt": "2026-03-15T10:00:00.000Z",
  "updatedAt": "2026-03-15T10:00:00.000Z"
}
```

#### Actualizar deposito (PATCH)

```
PATCH /v1/deposits/{id}
```

Solo necesitas enviar los campos que quieras modificar. Los campos no incluidos permanecen sin cambios.

```bash
curl -X PATCH https://api.frihet.io/v1/deposits/dep001 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Senal proyecto Q2 — actualizada",
    "notes": "Confirmado con contrato firmado"
  }'
```

**Respuesta (200):** Objeto de deposito actualizado.

#### Eliminar deposito

```
DELETE /v1/deposits/{id}
```

```bash
curl -X DELETE https://api.frihet.io/v1/deposits/dep001 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta:** `204 No Content`

:::caution
Solo se pueden eliminar depositos en estado `pending`. Si el deposito ya ha sido aplicado parcial o totalmente, la API devuelve `422`.
:::

#### Aplicar deposito a una factura

```
POST /v1/deposits/{id}/apply
```

Descuenta el deposito (total o parcial) del importe de una factura. Si el importe aplicado agota el saldo del deposito, el estado cambia a `applied`. Si queda saldo restante, el estado pasa a `partial`.

| Campo       | Tipo   | Requerido | Descripcion                                           |
| ----------- | ------ | --------- | ----------------------------------------------------- |
| `invoiceId` | string | Si        | ID de la factura a la que aplicar el deposito         |
| `amount`    | number | Si        | Importe a aplicar. No puede exceder `remainingAmount` |

```bash
curl -X POST https://api.frihet.io/v1/deposits/dep001/apply \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "abc123",
    "amount": 1500
  }'
```

**Respuesta (200):**

```json
{
  "success": true,
  "deposit": {
    "id": "dep001",
    "status": "partial",
    "appliedAmount": 1500,
    "remainingAmount": 500
  },
  "invoice": {
    "id": "abc123",
    "status": "partial",
    "amountDue": 800
  }
}
```

**Errores posibles:**

| Codigo | Descripcion                                                                    |
| ------ | ------------------------------------------------------------------------------ |
| `404`  | Deposito o factura no encontrados                                              |
| `422`  | El importe supera el saldo disponible, o la factura ya esta pagada o cancelada |

#### Reembolsar deposito

```
POST /v1/deposits/{id}/refund
```

Registra la devolucion total o parcial del deposito al cliente. El estado del deposito cambia a `refunded`.

| Campo    | Tipo   | Requerido | Descripcion                                                                   |
| -------- | ------ | --------- | ----------------------------------------------------------------------------- |
| `amount` | number | No        | Importe a reembolsar. Si se omite, se reembolsa el `remainingAmount` completo |
| `reason` | string | No        | Motivo del reembolso (max 1.000 caracteres)                                   |

```bash
curl -X POST https://api.frihet.io/v1/deposits/dep001/refund \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "reason": "Proyecto cancelado por el cliente"
  }'
```

**Respuesta (200):**

```json
{
  "success": true,
  "deposit": {
    "id": "dep001",
    "status": "refunded",
    "appliedAmount": 1500,
    "remainingAmount": 0,
    "refundedAmount": 500
  }
}
```

**Errores posibles:**

| Codigo | Descripcion                                                                              |
| ------ | ---------------------------------------------------------------------------------------- |
| `404`  | Deposito no encontrado                                                                   |
| `422`  | El importe supera el saldo disponible o el deposito ya ha sido reembolsado completamente |

---

## Operaciones por lote (`/batch`)

Todos los recursos principales soportan creacion en lote. Envia un array de hasta 50 elementos en una sola peticion.

```
POST /v1/{resource}/batch
```

**Recursos soportados:** `invoices`, `expenses`, `clients`, `vendors`, `products`, `quotes`, `deposits`

**Cuerpo de la peticion:**

```json
{
  "items": [
    {
      "clientName": "Acme SL",
      "items": [{ "description": "Hora consultoria", "quantity": 1, "unitPrice": 95 }]
    },
    {
      "clientName": "TechStart SL",
      "items": [{ "description": "Desarrollo web", "quantity": 8, "unitPrice": 60 }]
    }
  ]
}
```

```bash
curl -X POST https://api.frihet.io/v1/invoices/batch \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "clientName": "Acme SL", "items": [{ "description": "Consultoria", "quantity": 1, "unitPrice": 95 }] },
      { "clientName": "TechStart SL", "items": [{ "description": "Desarrollo", "quantity": 8, "unitPrice": 60 }] }
    ]
  }'
```

**Respuesta (207 Multi-Status):**

```json
{
  "results": [
    { "status": 201, "data": { "id": "inv_001", "clientName": "Acme SL", "status": "draft" } },
    { "status": 201, "data": { "id": "inv_002", "clientName": "TechStart SL", "status": "draft" } }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}
```

Si alguno de los elementos falla la validacion, el resto se crea igualmente. Los errores individuales se devuelven en el array `results`:

```json
{
  "results": [
    { "status": 201, "data": { "id": "inv_001", "clientName": "Acme SL" } },
    { "status": 400, "error": { "message": "Missing required field: items" } }
  ],
  "summary": { "total": 2, "succeeded": 1, "failed": 1 }
}
```

**Limites:**

| Concepto           | Limite      |
| ------------------ | ----------- |
| Elementos por lote | 50 maximo   |
| Tamano de peticion | 1 MB maximo |

---

## Idempotencia

Las peticiones `POST` aceptan una cabecera `Idempotency-Key` para evitar la creacion duplicada de recursos ante reintentos de red. Si la misma clave se envia dentro de las siguientes **24 horas**, la API devuelve la respuesta original sin ejecutar la operacion de nuevo.

```bash
curl -X POST https://api.frihet.io/v1/invoices \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "clientName": "Acme SL",
    "items": [{ "description": "Consultoria", "quantity": 10, "unitPrice": 95 }]
  }'
```

**Comportamiento:**

| Escenario                                            | Resultado                                       |
| ---------------------------------------------------- | ----------------------------------------------- |
| Primera peticion con la clave                        | Se crea el recurso normalmente                  |
| Peticion repetida con la misma clave (dentro de 24h) | Se devuelve la respuesta original, sin duplicar |
| Misma clave despues de 24h                           | Se trata como una peticion nueva                |

**Cabecera de respuesta:**

Cuando la API detecta una clave repetida, incluye la cabecera `X-Idempotent-Replayed: true` para que el consumidor sepa que la respuesta es una replica.

```
HTTP/1.1 201 Created
X-Idempotent-Replayed: true
Content-Type: application/json
```

**Requisitos:**

- La clave debe tener como maximo **64 caracteres**
- Recomendamos usar UUID v4
- Solo aplica a peticiones `POST` (crear recursos)

---

## Busqueda

Los endpoints de listado soportan busqueda de texto completo mediante el parametro `q`:

```bash
curl "https://api.frihet.io/v1/invoices?q=acme" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

La busqueda se aplica sobre los campos de texto principales del recurso (nombre de cliente, descripcion, notas, etc.). Se puede combinar con los filtros existentes (`status`, `from`, `to`).

---

## Endpoints de inteligencia

Estos endpoints proporcionan datos agregados y contexto de negocio. Son especialmente utiles para agentes de IA y dashboards externos.

### Contexto de negocio (`/context`)

```
GET /v1/context
```

Devuelve un resumen completo del negocio, pensado para alimentar a agentes de IA con el contexto necesario para tomar decisiones informadas. Incluye resumen financiero, actividad reciente, alertas y configuracion fiscal.

```bash
curl https://api.frihet.io/v1/context \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "business": {
    "name": "BRTHLS Studio",
    "taxId": "12345678A",
    "fiscalZone": "canarias",
    "currency": "EUR"
  },
  "summary": {
    "revenue": { "invoiced": 15000, "paid": 12000, "pending": 2000, "overdue": 1000 },
    "expenses": { "total": 4500 },
    "profit": 7500,
    "counts": { "invoices": 25, "clients": 12, "products": 5 }
  },
  "recentActivity": [
    {
      "type": "invoice.created",
      "id": "inv_001",
      "description": "Factura para Acme SL",
      "timestamp": "2026-03-18T10:00:00Z"
    },
    {
      "type": "expense.created",
      "id": "exp_042",
      "description": "Adobe Creative Cloud",
      "timestamp": "2026-03-17T14:30:00Z"
    }
  ],
  "alerts": [
    { "type": "overdue", "count": 2, "amount": 1000 },
    { "type": "tax_deadline", "model": "303", "dueDate": "2026-04-20" }
  ]
}
```

### P&L mensual (`/monthly`)

```
GET /v1/monthly?month=YYYY-MM
```

Devuelve la cuenta de resultados (P&L) de un mes concreto: ingresos facturados, gastos por categoria, beneficio neto y comparativa con el mes anterior.

```bash
curl "https://api.frihet.io/v1/monthly?month=2026-02" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "month": "2026-02",
  "revenue": {
    "invoiced": 8500.0,
    "collected": 6200.0,
    "outstanding": 2300.0
  },
  "expenses": {
    "total": 3100.0,
    "byCategory": {
      "software": 450.0,
      "marketing": 800.0,
      "office": 350.0,
      "professional_services": 1500.0
    }
  },
  "profit": 5400.0,
  "comparison": {
    "revenueChange": 12.5,
    "expenseChange": -5.2,
    "profitChange": 22.1
  }
}
```

### Cifras fiscales trimestrales (`/quarterly`)

```
GET /v1/quarterly?quarter=YYYY-Q1
```

Endpoint **legacy**. Devuelve cifras agregadas del trimestre para el Modelo 303 (IVA) y el Modelo 130 (IRPF). Toda la respuesta vive bajo `data`; `meta` lleva `requestId` y `timestamp`.

El parametro `quarter` usa el formato `YYYY-Q[1-4]` (por defecto, el trimestre actual).

```bash
curl "https://api.frihet.io/v1/quarterly?quarter=2026-Q1" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": {
    "period": "2026-Q1",
    "months": ["2026-01", "2026-02", "2026-03"],
    "modelo303": {
      "baseImponible": 12000.0,
      "cuotaRepercutida": 2520.0,
      "baseDeducible": 4500.0,
      "cuotaDeducible": 980.0,
      "resultado": 1540.0
    },
    "modelo130": {
      "ingresos": 12000.0,
      "gastos": 4500.0,
      "rendimientoNeto": 7500.0,
      "pagoFraccionado": 1500.0
    },
    "summary": {
      "totalRevenue": 14520.0,
      "totalExpenses": 5480.0,
      "invoiceCount": 8,
      "clientCount": 5
    }
  },
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-12T10:00:00Z"
  }
}
```

:::caution Divergencia: facturas borrador (`draft`)
`/quarterly` solo excluye facturas con estado `cancelled`, por lo que **incluye facturas en borrador (`draft`/proforma)** en los ingresos y en las cifras del 303/130. Esto puede **inflar** los importes frente a la liquidacion real.

Para cifras alineadas con AEAT (que excluyen tanto `cancelled` como `draft`), usa [`/v1/fiscal/modelo/{model}`](#modelos-fiscales-v1fiscalmodelo) — es la ruta autoritativa. Ademas, `/quarterly` no devuelve `model`, `readonly` ni la nota de AEAT, y su Modelo 303 es mas fino (sin `baseExenta`, `baseNoSujetaORC` ni `outOfScope`); el Modelo 130 de `/quarterly` no incluye `retencionesSoportadas`.
:::

:::tip
Los endpoints `/context`, `/monthly` y `/quarterly` estan disenados para ser un **punto de entrada para agentes de IA**. Proporcionan la informacion necesaria en una sola llamada, sin necesidad de consultar multiples endpoints individuales. Para datos fiscales code-truthful, prefiere `/v1/fiscal/modelo/{model}`.
:::

---

### Modelos fiscales (`/v1/fiscal/modelo`) {#modelos-fiscales-v1fiscalmodelo}

```
GET /v1/fiscal/modelo/{model}
```

Devuelve un resumen calculado de un modelo fiscal espanol a partir de las facturas y gastos ya almacenados. Es la ruta **autoritativa** para cifras fiscales: excluye tanto facturas `cancelled` como `draft` (proforma), alineandose con el criterio de AEAT.

:::warning No se presenta a AEAT
Este endpoint es de **solo lectura**. Calcula y agrega datos ya almacenados, pero **no presenta, firma ni transmite nada a AEAT** — ese es un acto fiscal irreversible que se mantiene fuera de la API a proposito. Cada respuesta incluye `readonly: true` y una `note` que lo recuerda.
:::

**Parametros de ruta:**

| Parametro | Valores             | Descripcion              |
| --------- | ------------------- | ------------------------ |
| `model`   | `303`, `130`, `390` | Modelo fiscal a calcular |

**Parametros de consulta:**

| Parametro | Aplica a     | Formato       | Descripcion                                           |
| --------- | ------------ | ------------- | ----------------------------------------------------- |
| `quarter` | `303`, `130` | `YYYY-Q[1-4]` | Trimestre. Por defecto, el trimestre actual           |
| `year`    | `390`        | `YYYY`        | Ano natural. Por defecto, el ano actual (suma Q1..Q4) |

:::note Campo `model`, no `modeloCode`
La respuesta identifica el modelo con el campo `model`, emitido como cadena literal (`"303"`, `"130"` o `"390"`). **No existe** un campo `modeloCode` ni un alias `model` para ningun otro nombre en esta respuesta.
:::

#### Modelo 303 (IVA trimestral)

```bash
curl "https://api.frihet.io/v1/fiscal/modelo/303?quarter=2026-Q1" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": {
    "model": "303",
    "period": "2026-Q1",
    "months": ["2026-01", "2026-02", "2026-03"],
    "modelo303": {
      "baseImponible": 12000.0,
      "cuotaRepercutida": 2520.0,
      "baseDeducible": 4500.0,
      "cuotaDeducible": 980.0,
      "resultado": 1540.0,
      "baseExenta": 0,
      "baseNoSujetaORC": 0,
      "outOfScope": {
        "igic": { "base": 0, "cuota": 0 },
        "ipsi": { "base": 0, "cuota": 0 }
      }
    },
    "summary": {
      "totalRevenue": 14520.0,
      "totalExpenses": 5480.0,
      "invoiceCount": 8,
      "expenseCount": 14,
      "clientCount": 5
    },
    "readonly": true,
    "note": "READ-ONLY summary. Not presented or submitted to AEAT."
  },
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-12T10:00:00Z"
  }
}
```

**Campos de `modelo303`:**

| Campo              | Tipo   | Descripcion                                                                                                 |
| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
| `baseImponible`    | number | Base de operaciones interiores sujetas a IVA                                                                |
| `cuotaRepercutida` | number | IVA devengado (repercutido a clientes)                                                                      |
| `baseDeducible`    | number | Base de gastos con IVA deducible                                                                            |
| `cuotaDeducible`   | number | IVA soportado deducible                                                                                     |
| `resultado`        | number | `cuotaRepercutida − cuotaDeducible`. Positivo = a pagar; negativo = a devolver/compensar                    |
| `baseExenta`       | number | Base de operaciones exentas (se declara, cuota cero)                                                        |
| `baseNoSujetaORC`  | number | Base de operaciones intracomunitarias / exportacion / inversion del sujeto pasivo (ISP)                     |
| `outOfScope`       | object | Operaciones en otros impuestos: `igic` e `ipsi`, cada uno con `base` y `cuota`. **No** forman parte del 303 |

#### Modelo 130 (pago fraccionado IRPF)

```bash
curl "https://api.frihet.io/v1/fiscal/modelo/130?quarter=2026-Q1" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": {
    "model": "130",
    "period": "2026-Q1",
    "months": ["2026-01", "2026-02", "2026-03"],
    "modelo130": {
      "ingresos": 12000.0,
      "gastos": 4500.0,
      "rendimientoNeto": 7500.0,
      "pagoFraccionado": 1500.0,
      "retencionesSoportadas": 0
    },
    "summary": {
      "totalRevenue": 14520.0,
      "totalExpenses": 5480.0,
      "invoiceCount": 8,
      "expenseCount": 14,
      "clientCount": 5
    },
    "readonly": true,
    "note": "READ-ONLY summary. Not presented or submitted to AEAT."
  },
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-12T10:00:00Z"
  }
}
```

**Campos de `modelo130`:**

| Campo                   | Tipo   | Descripcion                                                                       |
| ----------------------- | ------ | --------------------------------------------------------------------------------- |
| `ingresos`              | number | Ingresos del periodo                                                              |
| `gastos`                | number | Gastos del periodo                                                                |
| `rendimientoNeto`       | number | Rendimiento neto (`ingresos − gastos`)                                            |
| `pagoFraccionado`       | number | Pago fraccionado IRPF (20% del rendimiento neto, estimacion directa simplificada) |
| `retencionesSoportadas` | number | IRPF retenido por los clientes en las facturas emitidas                           |

:::note `retencionesSoportadas` solo en `/fiscal/modelo`
El campo `retencionesSoportadas` se devuelve aqui, en `/v1/fiscal/modelo/130`, pero **no** en el endpoint legacy `/v1/quarterly`.
:::

#### Modelo 390 (resumen anual de IVA)

```bash
curl "https://api.frihet.io/v1/fiscal/modelo/390?year=2026" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": {
    "model": "390",
    "period": "2026",
    "months": ["2026-01", "2026-02", "..."],
    "modelo390": {
      "baseImponible": 48000.0,
      "cuotaRepercutida": 10080.0,
      "baseDeducible": 18000.0,
      "cuotaDeducible": 3920.0,
      "resultadoAnual": 6160.0,
      "baseExenta": 0,
      "baseNoSujetaORC": 0,
      "outOfScope": {
        "igic": { "base": 0, "cuota": 0 },
        "ipsi": { "base": 0, "cuota": 0 }
      }
    },
    "summary": {
      "totalRevenue": 58080.0,
      "totalExpenses": 21920.0,
      "invoiceCount": 32,
      "expenseCount": 56,
      "clientCount": 11
    },
    "readonly": true,
    "note": "READ-ONLY annual VAT recap. Not presented or submitted to AEAT."
  },
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-12T10:00:00Z"
  }
}
```

:::note `resultadoAnual`, no `resultado`
El Modelo 390 es una proyeccion anual del mismo motor del 303 (suma de Q1..Q4). El resultado neto se llama `resultadoAnual` (no `resultado`).
:::

**Codigos de respuesta:**

| Codigo | Cuando ocurre                                                                      |
| ------ | ---------------------------------------------------------------------------------- |
| `200`  | Resumen calculado correctamente                                                    |
| `400`  | Formato de `quarter` o `year` invalido. Usa `YYYY-Q[1-4]` (303/130) o `YYYY` (390) |
| `404`  | Modelo desconocido. Usa `303`, `130` o `390`                                       |

Las respuestas de error tambien incluyen el bloque `meta` con `requestId` y `timestamp`.

---

## Dashboard financiero (`/summary`)

```
GET /v1/summary
```

Devuelve un resumen financiero del negocio: ingresos, gastos, beneficio y contadores.

**Parametros de consulta:**

| Parametro | Tipo   | Descripcion             |
| --------- | ------ | ----------------------- |
| `from`    | string | Fecha inicio (ISO 8601) |
| `to`      | string | Fecha fin (ISO 8601)    |

```bash
curl "https://api.frihet.io/v1/summary?from=2026-01-01&to=2026-03-31" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "period": { "from": "2026-01-01", "to": "2026-03-31" },
  "revenue": {
    "invoiced": 15000.0,
    "paid": 12000.0,
    "pending": 2000.0,
    "overdue": 1000.0
  },
  "expenses": { "total": 4500.0 },
  "profit": 7500.0,
  "counts": {
    "invoices": 25,
    "quotes": 8,
    "expenses": 42,
    "clients": 12,
    "products": 5
  },
  "invoicesByStatus": {
    "draft": 3,
    "sent": 5,
    "paid": 15,
    "overdue": 2
  },
  "overdue": { "count": 2, "amount": 1000.0 }
}
```

---

## Codigos de error

La API utiliza codigos HTTP estandar. Las respuestas de error incluyen un objeto JSON con los campos `error` y, opcionalmente, `message` y `details`.

| Codigo | Significado           | Descripcion                                                                            |
| ------ | --------------------- | -------------------------------------------------------------------------------------- |
| `400`  | Bad Request           | Falta un campo requerido, formato incorrecto o campo no permitido                      |
| `401`  | Unauthorized          | La API key no se ha proporcionado, es invalida, tiene formato incorrecto o ha expirado |
| `403`  | Forbidden             | La API key no tiene permisos para acceder a este recurso                               |
| `404`  | Not Found             | El recurso solicitado no existe                                                        |
| `405`  | Method Not Allowed    | El metodo HTTP no esta soportado para este endpoint                                    |
| `413`  | Payload Too Large     | El cuerpo de la peticion excede 1 MB                                                   |
| `422`  | Unprocessable Entity  | Datos validos pero el servidor no puede procesarlos (ej: perfil fiscal no configurado) |
| `429`  | Too Many Requests     | Se ha excedido el limite de 100 peticiones por minuto                                  |
| `500`  | Internal Server Error | Error interno del servidor                                                             |

### Estructura de las respuestas de error

**Error de validacion (400):**

```json
{
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["clientName"],
      "message": "Required"
    }
  ]
}
```

Los errores de validacion usan el formato de Zod. El campo `path` indica que campo contiene el error y `message` describe el problema.

**Clave invalida o expirada (401):**

```json
{
  "error": "Invalid or expired API key"
}
```

**Formato de clave invalido (401):**

```json
{
  "error": "Invalid API key format"
}
```

**Recurso no encontrado (404):**

```json
{
  "error": "Resource not found"
}
```

**Estado invalido en filtro (400):**

```json
{
  "error": "Invalid status filter",
  "message": "Valid values: draft, sent, paid, overdue, cancelled"
}
```

**Rate limit excedido (429):**

```json
{
  "error": "Rate limit exceeded",
  "message": "Maximum 100 requests per minute",
  "retryAfter": 60
}
```

**Error interno (500):**

```json
{
  "error": "Internal server error"
}
```

---

## Paginacion

Los endpoints de listado devuelven resultados paginados con la siguiente estructura:

```json
{
  "data": [],
  "total": 142,
  "limit": 50,
  "offset": 0
}
```

- `total`: numero total de registros que cumplen los filtros aplicados
- `limit`: numero de registros devueltos en esta pagina (maximo 100)
- `offset`: numero de registros saltados (maximo 10.000)

Para obtener la siguiente pagina:

```bash
curl "https://api.frihet.io/v1/invoices?limit=50&offset=50" \
  -H "X-API-Key: fri_tu-clave-aqui"
```

Los resultados se ordenan por la fecha natural del recurso en orden descendente (mas recientes primero):

- Facturas y presupuestos: `issueDate`
- Gastos: `date`
- Clientes y productos: `createdAt`

---

## Validacion estricta

La API usa **validacion estricta** (Zod strict mode). Las peticiones con campos desconocidos se rechazan con un error `400`:

```json
{
  "error": "Validation error",
  "details": [
    {
      "code": "unrecognized_keys",
      "keys": ["campoInventado"],
      "path": [],
      "message": "Unrecognized key(s) in object: 'campoInventado'"
    }
  ]
}
```

Esto previene errores silenciosos por typos en los nombres de los campos.

---

## CORS

La API soporta CORS para peticiones desde el navegador. Los origenes permitidos son:

- `https://app.frihet.io`
- `https://frihet.io`
- `https://www.frihet.io`

Para integraciones server-to-server, CORS no es relevante. Si necesitas acceder a la API desde un dominio diferente en el navegador, utiliza un proxy en tu backend.

---

## Cabeceras de seguridad

Todas las respuestas incluyen cabeceras de seguridad:

| Cabecera                 | Valor                                          |
| ------------------------ | ---------------------------------------------- |
| `X-Content-Type-Options` | `nosniff`                                      |
| `X-Frame-Options`        | `DENY`                                         |
| `X-XSS-Protection`       | `1; mode=block`                                |
| `X-API-Version`          | Version de la API (`2026-03-18`)               |
| `X-Request-Id`           | ID unico de la peticion (util para depuracion) |

---

## OAuth para MCP

El endpoint `POST /api/oauth/api-key` permite provisionar una API key automaticamente a traves del flujo OAuth de MCP. El servidor MCP usa este endpoint internamente -- no necesitas llamarlo directamente.

El flujo:

1. El usuario se autentica en la app de Frihet
2. El cliente MCP envia el token de sesion a `/api/oauth/api-key`
3. El servidor devuelve una nueva clave `fri_xxx...` etiquetada como "MCP OAuth"
4. La clave expira a los 365 dias

Limite: 5 claves activas por usuario. Si se supera el limite, el endpoint responde con un `429`.

---

## Buenas practicas

1. **Almacena la API key de forma segura.** Nunca la incluyas en codigo frontend, repositorios publicos o logs.
2. **Gestiona el rate limiting.** Implementa backoff exponencial si recibes un `429`.
3. **Usa paginacion.** No pidas todos los registros de golpe; itera con `limit` y `offset`.
4. **Verifica los codigos de respuesta.** No asumas que todas las peticiones seran exitosas.
5. **Rota las claves periodicamente.** Crea una nueva clave, actualiza tu integracion y revoca la anterior.
6. **Usa HTTPS siempre.** Todas las peticiones a la API deben ser sobre HTTPS.
7. **Usa filtros.** Los parametros `status`, `from` y `to` reducen la cantidad de datos transferidos.
8. **Aprovecha PATCH.** Para actualizaciones parciales, envia solo los campos modificados.

---

## Servidor MCP
> Path: /desarrolladores/mcp-server

# Servidor MCP

El servidor MCP de Frihet implementa el [Model Context Protocol](https://modelcontextprotocol.io) para que asistentes de IA puedan interactuar directamente con tu ERP. Crear facturas, registrar gastos, consultar clientes o gestionar presupuestos — todo desde tu IDE o terminal, en lenguaje natural.

**Version actual: 1.14.5** | 157 herramientas | 11 recursos | 10 prompts | Output estructurado | Compatible con 30+ agentes de IA. El endpoint remoto `mcp.frihet.io` sirve [divulgación progresiva](./ai-agent#divulgación-progresiva-grouped-mode) para no saturar el contexto del agente.

```
Tu:      "Crea una factura para TechStart SL, 40 horas de consultoria a 75 EUR/hora, vencimiento 1 marzo"
Claude:  Hecho. Factura INV-2026-089 creada. Total: 3.000,00 EUR + 21% IVA = 3.630,00 EUR.
```

---

## Que esperar (y que no)

El servidor MCP es un **puente stateless** entre tu asistente de IA y la API REST de Frihet. Cada llamada de herramienta se traduce en una peticion HTTP a la API.

**Lo que SI hace:**

- CRUD completo sobre facturas, gastos, clientes, productos, presupuestos y webhooks
- Busqueda de facturas por nombre de cliente
- Acceso a datos de referencia (tipos impositivos, calendario fiscal, categorias)
- Flujos de trabajo guiados (cierre mensual, preparacion fiscal, seguimiento de morosos)

**Lo que NO hace:**

- OCR de documentos (eso lo hace el asistente IA dentro de la app)
- Generacion de PDFs (usa la API REST directamente: `GET /v1/invoices/:id/pdf`)
- Procesamiento de pagos (los cobros se gestionan via Stripe Connect en la app)

---

## Requisitos

- Cuenta de Frihet con acceso a la API (planes de pago)
- API key generada desde el panel

### Obtener la API key

1. Inicia sesion en [app.frihet.io](https://app.frihet.io)
2. Ve a **Ajustes > Desarrolladores > API Keys**
3. Pulsa **Crear clave de API**
4. Copia la clave (empieza por `fri_`) — solo se muestra una vez

---

## Instalacion

### Universal (30+ agentes)

La forma mas rapida de instalar el servidor MCP y el skill de negocio:

```bash
npx skills add Frihet-io/frihet-mcp
```

Funciona con Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, y [30+ agentes mas](https://agentskills.io).

### MCP Registry

El servidor esta registrado como `io.frihet/erp` en el [MCP Registry oficial](https://registry.modelcontextprotocol.io/?q=io.frihet). Los clientes MCP compatibles con el registro pueden descubrirlo e instalarlo automaticamente por su nombre canonico.

### npx directo

```bash
npx -y @frihet/mcp-server@latest
```

No necesitas instalar nada globalmente. `npx` descarga y ejecuta la ultima version automaticamente.

### Configuracion manual

Hay dos modos de conexion: **local** (el servidor se ejecuta en tu maquina via `npx`) y **remoto** (conexion directa a `mcp.frihet.io`, sin instalar nada).

### Local (stdio)

```json
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server@latest"],
      "env": {
        "FRIHET_API_KEY": "fri_tu_clave_aqui"
      }
    }
  }
}
```

### Remoto (streamable-http)

```json
{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_tu_clave_aqui"
      }
    }
  }
}
```

### Configuracion por cliente

La estructura JSON es identica en todos los clientes. Solo cambia la ubicacion del fichero de configuracion.

| Cliente        | Fichero de configuracion                                                  |
| -------------- | ------------------------------------------------------------------------- |
| Claude Code    | `~/.claude/mcp.json`                                                      |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Cursor         | `.cursor/mcp.json` o `~/.cursor/mcp.json`                                 |
| Windsurf       | `~/.windsurf/mcp.json`                                                    |
| Cline          | Configuracion de VS Code o `.cline/mcp.json`                              |
| Codex CLI      | `~/.codex/config.toml` (seccion MCP)                                      |

:::tip
Si usas Claude Code, puedes anadir el servidor con un solo comando:

```bash
claude mcp add frihet -- npx -y @frihet/mcp-server@latest
```

Despues configura la variable `FRIHET_API_KEY` en el fichero `~/.claude/mcp.json` resultante.
:::

### Variables de entorno

| Variable           | Requerida | Valor por defecto          |
| ------------------ | --------- | -------------------------- |
| `FRIHET_API_KEY`   | Si        | --                         |
| `FRIHET_API_URL`   | No        | `https://api.frihet.io/v1` |
| `FRIHET_MCP_DEBUG` | No        | `0`                        |

- `FRIHET_API_URL` es util si apuntas a un entorno de staging o una instancia personalizada. Debe ser `https://` con un hostname bajo `frihet.io`.
- `FRIHET_MCP_DEBUG=1` activa logs de nivel debug (util para diagnosticar problemas).

---

## Flujo OAuth

El servidor MCP soporta autenticacion OAuth ademas de API key manual. Cuando un cliente MCP inicia el flujo OAuth:

1. El usuario se autentica en Frihet (email, Google, GitHub o Microsoft)
2. El cliente envia el token de sesion a `POST /api/oauth/api-key`
3. El servidor provisiona una nueva clave `fri_xxx...` etiquetada "MCP OAuth" con expiracion de 365 dias
4. La clave se usa automaticamente para las llamadas subsiguientes

Esto permite a los usuarios conectar el servidor MCP sin copiar claves manualmente.

---

## Herramientas disponibles (157)

El servidor expone **157 herramientas** organizadas en 30 categorias. Cada herramienta incluye output estructurado (`outputSchema` + `structuredContent`) para que los asistentes puedan parsear respuestas de forma fiable, ademas de anotaciones de seguridad y contenido. Bilingue (EN/ES).

> Wave Mature 1 (10-may-2026) anadio 6 categorias nuevas: **Banking** (5), **POS** (4), **Stay** (5), **Fiscal** (8: Modelo 303/130/390/180/347 + VeriFactu + TicketBAI), **Time** (4), **Recurring** (2). Las tablas detalladas para estas categorias se publicaran en proxima actualizacion.

### Facturas (12 herramientas)

| Herramienta            | Descripcion                               | Parametros clave                                                                                                |
| ---------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `list_invoices`        | Lista facturas con paginacion             | `limit`, `offset`, `status`, `clientId`, `from`, `to`                                                           |
| `get_invoice`          | Obtiene una factura por ID                | `id`                                                                                                            |
| `create_invoice`       | Crea una factura con lineas de detalle    | `clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`, `irpfRate` |
| `update_invoice`       | Actualiza campos de una factura (parcial) | `id`, y cualquier campo a modificar                                                                             |
| `delete_invoice`       | Elimina una factura permanentemente       | `id`                                                                                                            |
| `search_invoices`      | Busca facturas por nombre de cliente      | `clientName`, `limit`, `offset`                                                                                 |
| `send_invoice`         | Envia una factura por email               | `id`, `recipientEmail`, `customMessage`, `locale`                                                               |
| `mark_invoice_paid`    | Marca una factura como pagada             | `id`, `paidDate` (opcional)                                                                                     |
| `get_invoice_pdf`      | Descarga el PDF de una factura            | `id`                                                                                                            |
| `get_invoice_einvoice` | Genera e-factura EN16931 (XML)            | `id`                                                                                                            |
| `create_credit_note`   | Crea una factura rectificativa            | `id`, `reason`, `reasonDescription`, `fullCredit`                                                               |
| `apply_late_fee`       | Aplica recargo por demora                 | `id`, `amount` (opcional, auto-calcula si se omite)                                                             |

**Estados posibles de factura:** `draft`, `sent`, `partial`, `paid`, `overdue`, `cancelled`

### Gastos (5 herramientas)

| Herramienta      | Descripcion                           | Parametros clave                                                       |
| ---------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| `list_expenses`  | Lista gastos con paginacion           | `limit`, `offset`, `category`, `from`, `to`                            |
| `get_expense`    | Obtiene un gasto por ID               | `id`                                                                   |
| `create_expense` | Registra un nuevo gasto               | `description`, `amount`, `category`, `date`, `vendor`, `taxDeductible` |
| `update_expense` | Modifica un gasto existente (parcial) | `id`, y cualquier campo a modificar                                    |
| `delete_expense` | Elimina un gasto permanentemente      | `id`                                                                   |

### Clientes (5 herramientas)

| Herramienta     | Descripcion                             | Parametros clave                                                                  |
| --------------- | --------------------------------------- | --------------------------------------------------------------------------------- |
| `list_clients`  | Lista todos los clientes                | `limit`, `offset`, `stage`, `from`, `to`                                          |
| `get_client`    | Obtiene un cliente por ID               | `id`                                                                              |
| `create_client` | Registra un nuevo cliente               | `name`, `email`, `phone`, `taxId`, `address`, `fiscalZone`, `clientType`, `stage` |
| `update_client` | Actualiza datos de un cliente (parcial) | `id`, y cualquier campo a modificar                                               |
| `delete_client` | Elimina un cliente permanentemente      | `id`                                                                              |

### CRM (8 herramientas)

Herramientas para gestionar contactos, actividades y notas vinculados a un cliente.

| Herramienta              | Descripcion                              | Parametros clave                                                                |
| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------- |
| `list_client_contacts`   | Lista personas de contacto de un cliente | `clientId`, `limit`                                                             |
| `create_client_contact`  | Crea un contacto para un cliente         | `clientId`, `name`, `email`, `phone`, `role`, `isPrimary`                       |
| `delete_client_contact`  | Elimina un contacto                      | `clientId`, `contactId`                                                         |
| `list_client_activities` | Lista actividades de un cliente          | `clientId`, `limit`                                                             |
| `log_client_activity`    | Registra una actividad manual            | `clientId`, `type` (call/email/meeting/note_added/task), `title`, `description` |
| `list_client_notes`      | Lista notas de un cliente                | `clientId`, `limit`                                                             |
| `create_client_note`     | Crea una nota para un cliente            | `clientId`, `content`                                                           |
| `delete_client_note`     | Elimina una nota                         | `clientId`, `noteId`                                                            |

### Productos (5 herramientas)

| Herramienta      | Descripcion                              | Parametros clave                                                 |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `list_products`  | Lista productos y servicios              | `limit`, `offset`, `isActive`                                    |
| `get_product`    | Obtiene un producto por ID               | `id`                                                             |
| `create_product` | Crea un producto o servicio              | `name`, `unitPrice`, `description`, `sku`, `taxRate`, `irpfRate` |
| `update_product` | Modifica un producto existente (parcial) | `id`, y cualquier campo a modificar                              |
| `delete_product` | Elimina un producto permanentemente      | `id`                                                             |

### Presupuestos (6 herramientas)

| Herramienta    | Descripcion                            | Parametros clave                                                                            |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- |
| `list_quotes`  | Lista presupuestos                     | `limit`, `offset`, `status`, `clientId`, `from`, `to`                                       |
| `get_quote`    | Obtiene un presupuesto por ID          | `id`                                                                                        |
| `create_quote` | Crea un presupuesto para un cliente    | `clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status` |
| `update_quote` | Modifica un presupuesto (parcial)      | `id`, y cualquier campo a modificar                                                         |
| `delete_quote` | Elimina un presupuesto permanentemente | `id`                                                                                        |
| `send_quote`   | Envia un presupuesto por email         | `id`, `recipientEmail`, `customMessage`, `locale`                                           |

**Estados posibles de presupuesto:** `draft`, `sent`, `accepted`, `rejected`, `expired`

### Proveedores (5 herramientas)

| Herramienta     | Descripcion                               | Parametros clave                             |
| --------------- | ----------------------------------------- | -------------------------------------------- |
| `list_vendors`  | Lista proveedores                         | `limit`, `offset`                            |
| `get_vendor`    | Obtiene un proveedor por ID               | `id`                                         |
| `create_vendor` | Registra un nuevo proveedor               | `name`, `email`, `phone`, `taxId`, `address` |
| `update_vendor` | Modifica un proveedor existente (parcial) | `id`, y cualquier campo a modificar          |
| `delete_vendor` | Elimina un proveedor permanentemente      | `id`                                         |

### Inteligencia (4 herramientas)

Herramientas de analisis y contexto para que el asistente entienda la situacion del negocio.

| Herramienta            | Descripcion                                                     | Parametros clave                            |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------- |
| `get_business_context` | Contexto completo del negocio (perfil, metricas, configuracion) | —                                           |
| `get_monthly_summary`  | Resumen financiero del mes (ingresos, gastos, impuestos)        | `month` (YYYY-MM, opcional)                 |
| `get_quarterly_taxes`  | Preparacion fiscal trimestral (preview Modelo 303/130)          | `quarter` (YYYY-Q1, opcional), `fiscalZone` |
| `duplicate_invoice`    | Duplica una factura existente como borrador                     | `id`                                        |

### Anticipos / Depositos (7 herramientas)

| Herramienta      | Descripcion                                | Parametros clave                                                        |
| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
| `list_deposits`  | Lista anticipos con paginacion             | `limit`, `offset`, `clientId`, `status`, `from`, `to`                   |
| `get_deposit`    | Obtiene un anticipo por ID                 | `id`                                                                    |
| `create_deposit` | Crea un anticipo para un cliente           | `clientId`, `amount`, `description`, `date`, `notes`                    |
| `update_deposit` | Modifica un anticipo existente (parcial)   | `id`, y cualquier campo a modificar                                     |
| `delete_deposit` | Elimina un anticipo permanentemente        | `id`                                                                    |
| `apply_deposit`  | Aplica un anticipo a una factura existente | `depositId`, `invoiceId`, `amount` (opcional, aplica total si se omite) |
| `refund_deposit` | Registra la devolucion de un anticipo      | `id`, `refundDate` (opcional), `notes`                                  |

### Webhooks (5 herramientas)

| Herramienta      | Descripcion                         | Parametros clave                      |
| ---------------- | ----------------------------------- | ------------------------------------- |
| `list_webhooks`  | Lista webhooks configurados         | `limit`, `offset`                     |
| `get_webhook`    | Obtiene configuracion de un webhook | `id`                                  |
| `create_webhook` | Registra un endpoint de webhook     | `url`, `events[]`, `active`, `secret` |
| `update_webhook` | Modifica un webhook existente       | `id`, y cualquier campo a modificar   |
| `delete_webhook` | Elimina un webhook permanentemente  | `id`                                  |

Consulta [Webhooks](/desarrolladores/webhooks) para la lista completa de 27 eventos disponibles, formato del payload y verificacion HMAC.

---

## Recursos disponibles (11)

Los recursos MCP proporcionan datos de referencia y contexto en tiempo real. Los recursos estaticos estan siempre disponibles; los dinamicos requieren autenticacion con API key.

### Recursos estaticos (7)

| Recurso             | URI                                  | Descripcion                                                                 |
| ------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| Esquema API         | `frihet://api/schema`                | Resumen de endpoints, autenticacion, rate limits y codigos de error         |
| Tipos impositivos   | `frihet://tax/rates`                 | IVA (21/10/4%), IGIC (7/3/0%), IPSI, intracomunitario, IRPF (15%/7%)        |
| Calendario fiscal   | `frihet://tax/calendar`              | Fechas de presentacion trimestral (Modelo 303, 130, 420, 390)               |
| Categorias de gasto | `frihet://config/expense-categories` | 8 categorias con reglas de deducibilidad y tratamiento fiscal               |
| Estados de factura  | `frihet://config/invoice-statuses`   | Flujo de estados (borrador, enviada, pagada, vencida, anulada) con triggers |
| Divisas             | `frihet://config/currencies`         | 40 divisas soportadas con simbolos, decimales y formato                     |
| Paises              | `frihet://config/countries`          | 61 paises con zona fiscal y tipo impositivo por defecto                     |

### Recursos dinamicos (4)

Estos recursos devuelven datos en tiempo real de tu cuenta. Solo se registran cuando la conexion esta autenticada.

| Recurso           | URI                           | Descripcion                                                       |
| ----------------- | ----------------------------- | ----------------------------------------------------------------- |
| Perfil de negocio | `frihet://business-profile`   | Datos fiscales, zona fiscal, divisa y configuracion de tu empresa |
| Snapshot mensual  | `frihet://monthly-snapshot`   | Resumen financiero del mes en curso (ingresos, gastos, impuestos) |
| Facturas vencidas | `frihet://overdue-invoices`   | Lista de facturas vencidas con importes y dias de retraso         |
| Limites del plan  | `frihet://status/plan-limits` | Plan actual, uso de facturas/escaneos/mensajes IA y limites       |

---

## Prompts disponibles (10)

Los prompts son flujos de trabajo guiados que el asistente ejecuta paso a paso. Se invocan por nombre.

| Prompt                 | Descripcion                                                                                                  | Parametros                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `monthly-close`        | Cierre mensual: revisa facturas impagadas, categoriza gastos, verifica obligaciones fiscales, genera resumen | `month` (opcional)                |
| `onboard-client`       | Alta de cliente: determina tipo impositivo segun ubicacion, crea registro, genera presupuesto de bienvenida  | `clientName`, `country`, `region` |
| `quarterly-tax-prep`   | Preparacion fiscal trimestral: recopila facturas, calcula IVA/IGIC, genera preview del Modelo 303/130        | `quarter`, `fiscalZone`           |
| `overdue-followup`     | Seguimiento de morosos: identifica facturas vencidas, agrupa por cliente, redacta mensajes de cobro          | —                                 |
| `expense-batch`        | Procesamiento de gastos en lote: categoriza, aplica impuestos, verifica deducibilidad, crea con confirmacion | `fiscalZone`                      |
| `new-client-invoice`   | Alta de cliente + primera factura en un solo flujo                                                           | `clientName`, `country`           |
| `expense-report`       | Informe de gastos agrupado por categoria con totales y deducibilidad                                         | `month` (opcional)                |
| `year-end-close`       | Cierre anual: revision completa del ejercicio fiscal                                                         | `year`                            |
| `cash-flow-forecast`   | Prevision de flujo de caja a 3 meses basada en facturas y gastos recurrentes                                 | `months` (opcional)               |
| `invoice-aging-review` | Analisis de antigueedad de facturas por cobrar (aging buckets)                                               | —                                 |

:::tip
Puedes invocar un prompt directamente: _"Ejecuta el cierre mensual de febrero"_ o _"Prepara los impuestos del Q1"_.
:::

---

## Ejemplos de uso

Estas son peticiones reales en lenguaje natural que el asistente traduce a llamadas de herramientas MCP.

### Crear una factura

```
"Crea una factura para Acme SL con 10 horas de consultoria a 95 EUR/hora, vencimiento 15 de marzo"
```

El asistente llama a `create_invoice` con `clientName: "Acme SL"`, una linea de detalle (10 x 95) y `dueDate: "2026-03-15"`. Calcula el total automaticamente.

### Registrar un gasto

```
"Registra un gasto de 59.99 EUR en Adobe Creative Cloud, categoria software, deducible"
```

Llama a `create_expense` con `description`, `amount: 59.99`, `category: "software"` y `taxDeductible: true`.

### Buscar facturas de un cliente

```
"Busca todas las facturas de TechStart SL"
```

Llama a `search_invoices` con `clientName: "TechStart SL"` y devuelve las coincidencias con sus totales y estados.

### Consultar morosos

```
"Muestrame todas las facturas sin pagar"
```

Llama a `list_invoices` y filtra por `status: "sent"` o `"overdue"`, mostrando las vencidas ordenadas por importe.

### Dar de alta un cliente

```
"Nuevo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"
```

Llama a `create_client` con nombre, NIF, email y direccion.

### Configurar automatizacion

```
"Crea un webhook para notificar a https://mi-app.com/hook cuando se pague una factura"
```

Llama a `create_webhook` con `url` y `events: ["invoice.paid"]`.

### Actualizar un producto

```
"Sube el precio de la hora de consultoria a 85 EUR"
```

Llama a `update_product` con el `id` del producto y `unitPrice: 85`. Solo se modifica el campo indicado.

---

## Observabilidad

El servidor MCP v1.14.5 incluye logging estructurado y metricas de herramientas.

### Logging estructurado

Todos los logs se emiten como JSON a stderr (MCP usa stdout para mensajes del protocolo). Cada entrada incluye:

- `level`: `debug`, `info`, `warn`, `error`
- `service`: siempre `frihet-mcp`
- `timestamp`: ISO 8601
- `tool`: nombre de la herramienta (cuando aplica)
- `operation`: tipo de operacion (`tool_call`, `api_call`, `api_retry`, `startup`, `shutdown_metrics`)
- `durationMs`: tiempo de ejecucion en milisegundos
- `error`: detalles del error (message, code, statusCode)

Activa los logs de debug con `FRIHET_MCP_DEBUG=1`.

### Metricas de herramientas

El servidor registra en memoria las llamadas a cada herramienta: numero de invocaciones, errores y duracion media. Al cerrar el servidor (SIGINT/SIGTERM), se emite un resumen:

```json
{
  "level": "info",
  "message": "Shutdown after 3600s — 42 calls, 1 errors",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}
```

### Rate-limit retry automatico

Cuando la API responde con `429`, el servidor reintenta automaticamente con backoff exponencial (hasta 3 reintentos). Los reintentos se registran en el log:

```json
{
  "level": "warn",
  "message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
  "operation": "api_retry"
}
```

No necesitas gestionar el rate limiting manualmente — el servidor lo hace por ti.

---

## Transporte

El servidor MCP de Frihet soporta dos modos de transporte. Ambos exponen las mismas 157 herramientas, 11 recursos y 10 prompts.

### Local (stdio)

El servidor se ejecuta como proceso local en tu maquina. La comunicacion entre el cliente MCP y el servidor usa entrada/salida estandar (stdin/stdout).

- **Requiere:** Node.js instalado (se descarga automaticamente via `npx`)
- **Ventaja:** Menor latencia, funciona sin conexion a internet (excepto para las llamadas a la API)
- **Caso de uso:** Desarrollo diario, uso intensivo, entornos corporativos con restricciones de red

### Remoto (streamable-http)

El servidor se ejecuta en Cloudflare Workers. Tu cliente MCP se conecta directamente a `https://mcp.frihet.io/mcp` via HTTP.

- **Requiere:** Solo conexion a internet
- **Ventaja:** Sin instalacion local, sin dependencias, funciona en cualquier dispositivo
- **Caso de uso:** Configuracion rapida, equipos que prefieren no instalar paquetes, clientes que solo soportan transporte HTTP

:::info
Si tu cliente MCP no soporta `streamable-http` (algunos clientes antiguos solo soportan `stdio`), usa el modo local.
:::

---

## Manejo de errores

### Rate limiting

La API permite **100 peticiones por minuto** por clave. Si se excede el limite, el servidor devuelve un error `429` con el tiempo de espera en `retryAfter`.

El servidor MCP gestiona automaticamente el rate limiting con **backoff exponencial**: reintenta la peticion despues de esperar el tiempo indicado, sin intervencion del usuario. Maximo 3 reintentos.

### Errores de autenticacion

| Codigo | Causa                                         | Solucion                                                                      |
| ------ | --------------------------------------------- | ----------------------------------------------------------------------------- |
| `401`  | API key invalida, expirada o no proporcionada | Verifica que la clave en tu configuracion empieza por `fri_` y no ha expirado |
| `403`  | La clave no tiene permisos para este recurso  | Genera una nueva clave con los permisos necesarios                            |

### Otros errores

| Codigo | Descripcion                                                          |
| ------ | -------------------------------------------------------------------- |
| `400`  | Parametros incorrectos o campos requeridos faltantes                 |
| `404`  | El recurso solicitado no existe                                      |
| `408`  | Timeout de la peticion (30 segundos)                                 |
| `413`  | El cuerpo de la peticion excede 1 MB                                 |
| `422`  | Datos validos pero no procesables (ej: perfil fiscal no configurado) |
| `429`  | Limite de peticiones excedido (se reintenta automaticamente)         |
| `500`  | Error interno del servidor                                           |

Todos los errores devuelven un mensaje descriptivo bilingue (EN/ES) para que el asistente pueda comunicar el problema al usuario de forma clara.

---

## Limites

| Concepto                  | Valor                       |
| ------------------------- | --------------------------- |
| Peticiones por minuto     | 100 por API key             |
| Resultados por pagina     | 100 maximo (50 por defecto) |
| Cuerpo de peticion        | 1 MB maximo                 |
| Payload de webhook        | 100 KB maximo               |
| Webhooks por cuenta       | 20 maximo                   |
| Timeout de peticion       | 30 segundos                 |
| Reintentos por rate limit | 3 maximo                    |

---

## Diferencia con la API REST

|                    | Servidor MCP                                                   | API REST                                           |
| ------------------ | -------------------------------------------------------------- | -------------------------------------------------- |
| **Dirigido a**     | Asistentes de IA (Claude, Cursor, Windsurf)                    | Aplicaciones, scripts, integraciones               |
| **Comunicacion**   | Lenguaje natural a traves del cliente MCP                      | HTTP/JSON directo                                  |
| **Autenticacion**  | Variable de entorno en la config del cliente (u OAuth)         | Cabecera `X-API-Key` o `Authorization: Bearer`     |
| **Formato**        | Texto formateado + output estructurado para el asistente       | JSON crudo                                         |
| **Rate limiting**  | Gestionado automaticamente (backoff exponencial, 3 reintentos) | Manual (el consumidor debe implementar reintentos) |
| **Observabilidad** | Logging estructurado + metricas por herramienta                | Logs de peticion via `X-Request-Id`                |
| **Caso de uso**    | Hablar con tu ERP desde el IDE                                 | Construir integraciones programaticas              |

Internamente, el servidor MCP traduce cada llamada de herramienta en una peticion a la API REST. No duplica logica — es un puente stateless.

---

## Desarrollo

Para contribuir o ejecutar el servidor en modo desarrollo:

```bash
git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build
```

Ejecutar localmente:

```bash
FRIHET_API_KEY=fri_tu_clave node dist/index.js
```

Ejecutar con logs de debug:

```bash
FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js
```

Probar con el [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Recursos relacionados

- [API REST](/desarrolladores/api-rest) — Referencia completa de endpoints, autenticacion y codigos de error
- [Webhooks](/desarrolladores/webhooks) — Eventos disponibles, verificacion HMAC-SHA256 y politica de reintentos
- [Skill para Claude Code](/desarrolladores/skill-claude-code) — Capa de inteligencia de negocio sobre el servidor MCP
- [Codigo fuente (GitHub)](https://github.com/Frihet-io/frihet-mcp) — Repositorio del servidor MCP
- [Paquete npm](https://www.npmjs.com/package/@frihet/mcp-server) — `@frihet/mcp-server@1.14.5`
- [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.frihet) — `io.frihet/erp`
- [Endpoint remoto](https://mcp.frihet.io) — Servidor MCP alojado en Cloudflare Workers
- [Especificacion MCP](https://modelcontextprotocol.io) — Documentacion del protocolo

---

[Anterior: Webhooks](/desarrolladores/webhooks) | [Siguiente: Skill para Claude Code](/desarrolladores/skill-claude-code)

---

## Especificación OpenAPI
> Path: /desarrolladores/openapi-spec

# Especificación OpenAPI

:::tip Referencia interactiva
¿Prefieres explorar y probar la API en el navegador? La [**referencia interactiva**](/api-reference) renderiza esta misma especificación con un cliente "try it" integrado.
:::

La API pública de Frihet expone una especificación OpenAPI 3.1 completa en `GET /openapi.yaml`. La especificación describe todas las operaciones disponibles, sus parámetros, respuestas y modelos de datos, en un formato consumible por generadores de cliente, agentes de tool-calling y exploradores interactivos.

## Cómo funciona

La especificación se sirve en formato YAML como `text/yaml` con caché de 1 hora desde el endpoint público de la API. Cubre los recursos principales del producto: facturas, gastos, depósitos, clientes, productos, presupuestos, cobros, recurrentes y exportaciones. Para cada recurso, documenta los endpoints `GET/POST/PATCH/DELETE` con esquemas de petición y respuesta tipados.

El consumo habitual es de tres tipos. Para **generar clientes** en cualquier lenguaje (Python, Go, Java, Ruby, etc.) usando [OpenAPI Generator](https://openapi-generator.tech) o herramientas equivalentes — útil cuando no estás en TypeScript o necesitas un cliente en lenguaje no cubierto por el SDK oficial. Para **importar en Postman, Insomnia o Bruno** y tener una colección lista para probar la API de forma interactiva. Para **alimentar agentes de tool-calling** que descubren operaciones disponibles a partir de la especificación y construyen llamadas automáticamente.

Adicionalmente, una copia estática se publica en `docs.frihet.io/openapi.json` para que crawlers y agentes la encuentren desde el sitio de documentación sin necesidad de autenticarse contra la API.

La especificación se mantiene sincronizada con la implementación real. Si encuentras un endpoint en producción que no aparece o un campo con un tipo distinto al declarado, abre soporte para que el equipo lo corrija.

## Configuración

No requiere configuración. La especificación es pública y no necesita API key para consultarse. Para autenticarte contra los endpoints reales sí necesitas una API key — gestiónala desde **Configuración → Desarrolladores → API Keys**.

## Ver también

- [Referencia interactiva de la API](/api-reference) — explora y prueba cada endpoint
- [Especificación pública en docs.frihet.io/openapi.json](https://docs.frihet.io/openapi.json)
- [API REST](./api-rest)
- [SDK y CLI](./sdk-cli)

---

## Desarrolladores
> Path: /desarrolladores/resumen

# Desarrolladores

Frihet expone una API REST completa, un sistema de webhooks y un servidor MCP para que puedas integrar tu ERP con cualquier herramienta. Automatiza flujos de trabajo, sincroniza datos con tus sistemas existentes o construye integraciones a medida. Consulta todas las [funcionalidades de Frihet](https://www.frihet.io/es/features) y las [integraciones disponibles](https://www.frihet.io/es/integrations).

## Recursos principales

### [API REST](/desarrolladores/api-rest)

API RESTful con autenticacion por API key. Accede a facturas, gastos, clientes, productos, presupuestos y proveedores de forma programatica.

- Endpoints CRUD completos para 8 recursos: facturas, gastos, clientes, proveedores, productos, presupuestos, depositos y webhooks
- Subcollections CRM: contactos, actividades y notas por cliente
- 4 endpoints de inteligencia: `/summary`, `/context`, `/monthly`, `/quarterly`
- Acciones especiales: descargar PDF/XML, enviar por email, marcar como pagada, rectificativas, recargos, facturacion de gastos, depositos
- Creacion en lote (batch): hasta 50 registros por peticion
- Filtrado por estado, rango de fechas, busqueda full-text y paginacion (offset + cursor)
- Limite de 100 peticiones/minuto por clave
- Respuestas JSON estandarizadas con validacion estricta (Zod)

### [Webhooks](/desarrolladores/webhooks)

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta de Frihet. 27 tipos de evento con firma HMAC-SHA256 para verificar la autenticidad de cada payload.

- 27 tipos de evento (facturas, pagos, rectificativas, presupuestos, gastos, clientes, productos, cobros)
- Firma criptografica HMAC-SHA256 en cada entrega
- Reintentos automaticos con backoff exponencial (3 intentos)
- Circuit breaker: 3 fallos consecutivos pausa el webhook automaticamente
- Logs de entrega consultables desde el panel

### [Servidor MCP](/desarrolladores/mcp-server)

Servidor MCP oficial publicado en npm como `@frihet/mcp-server` (v1.14.5), registrado como `io.frihet/erp` en el MCP Registry. 157 herramientas para integrar Frihet con asistentes de IA (Claude, Cursor, Windsurf).

- 157 herramientas, 11 recursos, 10 prompts (facturas, gastos, clientes, CRM, productos, presupuestos, proveedores, inteligencia, webhooks, e-invoicing, Stay, POS, banking, fiscal, time, recurring, HR, payroll, onboarding, permissions, period close, IGIC, impuesto de sociedades, audit GL, gestoria)
- Transporte local (stdio) y remoto (mcp.frihet.io)
- Logging estructurado, metricas por herramienta, rate-limit retry automatico
- Autenticacion via API key o flujo OAuth
- Open source (MIT) en [GitHub](https://github.com/Frihet-io/frihet-mcp)

### [Skill para Claude Code](/desarrolladores/skill-claude-code)

Skill oficial que anade inteligencia de negocio sobre el servidor MCP. Comandos conversacionales, contexto fiscal espanol, recetas de flujos de trabajo y formateo de informes.

- Comandos: `/frihet invoice`, `/frihet expense`, `/frihet report`, `/frihet clients`
- Preparacion automatica del Modelo 303 (IVA trimestral)
- Cierre mensual, seguimiento de morosos, conversion presupuesto-factura
- Instalacion: `npx skills add Frihet-io/frihet-mcp`

---

## Modelo de tiers de integracion

Frihet organiza sus 100+ integraciones en tres niveles segun la profundidad de la conexion:

| Tier       | Nombre                  | Descripcion                                                                                         |
| ---------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| **Tier 1** | Full Sync               | Sincronizacion bidireccional completa vía servicios dedicados (import + webhooks + reconciliacion). |
| **Tier 2** | Credentials Only / Beta | Credenciales guardadas de forma segura. Sincronizacion automatica completa en roadmap.              |
| **Tier 3** | Webhook URL             | Genera una URL webhook para conectar con tus automatizaciones. Sin sync bidireccional.              |

Puedes ver el badge de tier de cada integracion en la pantalla de conexion dentro de la app.

---

## Integraciones soportadas

Frihet se conecta de forma nativa con mas de 100 herramientas. Cada integracion se puede complementar con la API REST y los webhooks para cubrir casos de uso avanzados. Consulta las [integraciones disponibles](https://www.frihet.io/es/integrations) en la web.

### Tier 1 — Full Sync (41 integraciones)

Sincronizacion bidireccional completa. Lista para produccion.

| Categoria          | Servicio                                                                                                                                                                                                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pagos**          | [PayPal](/integraciones/paypal), GoCardless, Stripe Revenue, Stripe Connect                                                                                                                                                                                                                                      |
| **Banca**          | Mercury, Pleo, Wise, Qonto                                                                                                                                                                                                                                                                                       |
| **E-commerce**     | [Shopify](/integraciones/shopify), [WooCommerce](/integraciones/woocommerce), [Gumroad](/integraciones/gumroad), [Lemon Squeezy](/integraciones/lemon-squeezy), [Etsy](/integraciones/etsy), [Square](/integraciones/square), [Squarespace](/integraciones/squarespace), [PrestaShop](/integraciones/prestashop) |
| **Contabilidad**   | Xero, QuickBooks Online, FreshBooks, Wave Accounting, Zoho Books, Sage Business Cloud, Lexoffice                                                                                                                                                                                                                 |
| **Time tracking**  | [Toggl](/integraciones/toggl), [Clockify](/integraciones/clockify), [Harvest](/integraciones/harvest)                                                                                                                                                                                                            |
| **Productividad**  | [Asana](/integraciones/asana), [Trello](/integraciones/trello), [Notion](/integraciones/notion)                                                                                                                                                                                                                  |
| **Calendario**     | [Google Calendar](/integraciones/google-calendar), [Outlook Calendar](/integraciones/outlook-calendar)                                                                                                                                                                                                           |
| **Almacenamiento** | [Google Drive](/integraciones/google-drive), [Google Sheets](/integraciones/google-sheets), [Dropbox](/integraciones/dropbox)                                                                                                                                                                                    |
| **Comunicacion**   | [Slack](/integraciones/slack)                                                                                                                                                                                                                                                                                    |
| **CRM**            | [HubSpot](/integraciones/hubspot), [Pipedrive](/integraciones/pipedrive), [Intercom](/integraciones/intercom)                                                                                                                                                                                                    |
| **Firma**          | [PandaDoc](/integraciones/pandadoc), [DocuSign](/integraciones/docusign), [HelloSign](/integraciones/hellosign)                                                                                                                                                                                                  |
| **Gastos**         | [Expensify](/integraciones/expensify)                                                                                                                                                                                                                                                                            |
| **Email**          | [Mailchimp](/integraciones/mailchimp)                                                                                                                                                                                                                                                                            |

### Tier 2 — Credentials Only / Beta (56 integraciones)

Credenciales conectadas y configuracion lista. Sincronizacion completa en roadmap.

| Categoria        | Servicios                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| **E-commerce**   | eBay, TikTok Shop, Printful, BigCommerce, Magento/Adobe Commerce                                |
| **CRM**          | Salesforce, Zoho CRM, Freshsales, Close CRM, Copper CRM                                         |
| **Logistica**    | Sendcloud, ShipStation, Correos Spain, SEUR, DHL Express, FedEx, UPS, Shippo                    |
| **RRHH**         | Factorial, Personio, BambooHR, Gusto, PayFit                                                    |
| **Marketing**    | Brevo, ConvertKit, ActiveCampaign, Lemlist, Beehiiv, Meta Marketing API, Google Ads API         |
| **TPV**          | SumUp POS, SumUp Payments, SumUp Invoices, Lightspeed Restaurant, Lightspeed X-Series           |
| **Comunicacion** | Discord Webhooks, Microsoft Teams Webhooks, Telegram Bot API                                    |
| **Freelance**    | Upwork                                                                                          |
| **Pagos**        | Adyen, Checkout.com, Braintree, Mollie, Bunq, Brex, Monzo Premium, N26 Business, Starling Bank |
| **Open Banking** | Tink, OpenBanking, PayPal Sandbox, Plaid, Revolut                                               |
| **Banca**        | [N26](/integraciones/n26)                                                                       |
| **Mensajeria**   | [WhatsApp](/integraciones/whatsapp)                                                             |
| **Marketplaces** | [Amazon Seller](/integraciones/amazon-seller)                                                   |
| **Contabilidad** | Bexio                                                                                           |

### Tier 3 — Webhook URL (2 integraciones)

Conecta via webhook personalizado a tus flujos de automatizacion.

| Servicio                    | Descripcion                                            |
| --------------------------- | ------------------------------------------------------ |
| [n8n](/integraciones/n8n)   | Flujos de automatizacion personalizados via webhook    |
| [Make](/integraciones/make) | Automatizacion visual con cientos de apps via webhooks |

### App nativa oficial — Zapier

[Zapier](/integraciones/zapier) tiene una **app nativa oficial de Frihet** (Beta publica, aprobada 26-jun-2026) con autenticacion por API key. 43 operaciones: 14 triggers, 21 acciones y 8 busquedas. Conecta Frihet con 7.000+ apps sin configurar webhooks manualmente. [Ver en Zapier →](https://zapier.com/apps/frihet/integrations)

---

## Seguridad

La seguridad es una prioridad en toda la capa de integraciones de Frihet.

- **Cifrado AES-256-GCM** para datos sensibles almacenados (tokens de integracion, secretos de webhook)
- **HMAC-SHA256** en cada entrega de webhook para verificar la autenticidad del payload
- **Hashing SHA-256** de las API keys en el servidor -- la clave en texto plano solo se muestra una vez al crearla
- **Validacion de formato** de API keys antes de procesarlas (prefijo `fri_`, longitud 40-60 caracteres, charset restringido)
- **Rate limiting** de 100 peticiones por minuto por clave API, respaldado por almacenamiento persistente
- **Validacion estricta** de datos con Zod — campos desconocidos se rechazan
- **Validacion de URL** en webhooks: solo se permiten endpoints HTTPS (excepto localhost en desarrollo)
- **Bloqueo de IPs privadas** para evitar SSRF en las URLs de webhook
- **Validacion de IDs de documento** para prevenir path traversal e inyeccion
- **Tokens con expiracion configurable** -- puedes crear claves con fecha de caducidad
- **Cabeceras de seguridad** en todas las respuestas: `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`

---

## SDKs y CLI

SDKs oficiales para integrar Frihet en tu stack:

| Paquete                                                    | Instalacion         | Descripcion                                                                    |
| ---------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
| [`@frihet/sdk`](https://www.npmjs.com/package/@frihet/sdk) | `npm i @frihet/sdk` | SDK TypeScript — `frihet.invoices.create()`, tipos completos, retry automatico |
| [`frihet`](https://www.npmjs.com/package/frihet)           | `npm i -g frihet`   | CLI — `frihet invoices list --status overdue`                                  |
| **Python**                                                 | Proximamente        | En desarrollo                                                                  |

```typescript
import Frihet from '@frihet/sdk';

const frihet = new Frihet({ apiKey: 'fri_...' });
const invoice = await frihet.invoices.create({
  clientName: 'Acme Corp',
  items: [{ description: 'Consulting', quantity: 10, unitPrice: 150 }],
});
```

Repositorio: [github.com/Frihet-io/frihet-sdk](https://github.com/Frihet-io/frihet-sdk)

---

## Limites y cuotas

| Recurso                        | Limite                      |
| ------------------------------ | --------------------------- |
| Peticiones API                 | 100/minuto por clave        |
| Tamano de peticion             | 1 MB maximo                 |
| Offset maximo                  | 10.000                      |
| Tamano de payload de webhook   | 100 KB maximo               |
| Webhooks por cuenta            | 20 maximo                   |
| Reintentos de webhook          | 3 intentos por entrega      |
| Resultados por pagina          | 100 maximo (50 por defecto) |
| Claves API activas por usuario | 5 maximo (via OAuth)        |

---

## Primeros pasos

1. Accede a **Ajustes > Desarrolladores > API Keys** en tu cuenta de Frihet
2. Crea una nueva API key y copia la clave (solo se muestra una vez)
3. Prueba la conexion con una peticion GET a `/v1/clients`
4. Configura webhooks para recibir eventos en tiempo real

```bash
curl -s https://api.frihet.io/v1/clients \
  -H "X-API-Key: fri_tu-clave-aqui" | head -c 200
```

Si la respuesta incluye tus clientes, la integracion esta funcionando. Consulta la [referencia de la API REST](./api-rest.md) para ver todos los endpoints disponibles.

---

## SDK y CLI
> Path: /desarrolladores/sdk-cli

# SDK y CLI

Frihet ofrece un SDK oficial de TypeScript y una CLI para gestionar tu negocio desde codigo o terminal. Ambos paquetes estan publicados en npm.

| Paquete | npm | Uso |
|---------|-----|-----|
| `@frihet/sdk` | [![npm](https://img.shields.io/npm/v/@frihet/sdk)](https://www.npmjs.com/package/@frihet/sdk) | SDK para Node.js / TypeScript |
| `frihet` | [![npm](https://img.shields.io/npm/v/frihet)](https://www.npmjs.com/package/frihet) | CLI para terminal |

---

## Instalacion

### SDK

```bash
npm install @frihet/sdk
```

### CLI

```bash
npm install -g frihet
```

---

## Autenticacion

Necesitas una API key. Generala en **Ajustes > Desarrolladores > API Keys** dentro de [app.frihet.io](https://app.frihet.io/settings/security). Las claves comienzan con `fri_`.

### SDK

```typescript
import Frihet from '@frihet/sdk';

const frihet = new Frihet({
  apiKey: 'fri_live_...',
});
```

Opciones adicionales:

| Opcion | Tipo | Por defecto | Descripcion |
|--------|------|-------------|-------------|
| `apiKey` | `string` | -- | Tu API key (obligatorio) |
| `baseUrl` | `string` | `https://api.frihet.io/v1` | URL base de la API |
| `timeout` | `number` | `30000` | Timeout en milisegundos |

### CLI

```bash
frihet login
# Introduce tu API key interactivamente

# O directamente:
frihet login --key fri_live_...
```

La key se guarda en `~/.frihet/config.json` con permisos `0600`. Tambien puedes usar la variable de entorno `FRIHET_API_KEY`.

---

## SDK — Inicio rapido

### Listar facturas

```typescript
import Frihet from '@frihet/sdk';

const frihet = new Frihet({ apiKey: 'fri_live_...' });

const page = await frihet.invoices.list({ limit: 10, status: 'paid' });
console.log(`${page.total} facturas pagadas`);

for (const inv of page.data) {
  console.log(`${inv.documentNumber} — ${inv.clientName} — ${inv.total}`);
}
```

### Crear una factura

```typescript
const invoice = await frihet.invoices.create({
  clientName: 'Acme S.L.',
  items: [
    { description: 'Consultoria', quantity: 10, unitPrice: 150 },
    { description: 'Desarrollo web', quantity: 1, unitPrice: 3000 },
  ],
  taxRate: 21,
  dueDate: '2026-04-15',
});

console.log(`Factura ${invoice.documentNumber} creada (${invoice.total} EUR)`);
```

### Buscar y actualizar

```typescript
// Busqueda por texto
const results = await frihet.clients.search('Acme');

// Actualizar un cliente
await frihet.clients.update(results.data[0].id, {
  email: 'nuevo@acme.com',
  fiscalZone: 'peninsula',
});
```

### Marcar factura como pagada y enviar por email

```typescript
await frihet.invoices.markPaid('inv_abc123');

await frihet.invoices.send('inv_abc123', {
  recipientEmail: 'cliente@acme.com',
  locale: 'es',
});
```

### Crear abono / factura rectificativa

```typescript
const creditNote = await frihet.invoices.createCreditNote('inv_abc123', {
  reason: 'error',
  reasonDescription: 'Correccion de importe',
  fullCredit: true,
});

console.log(`Abono ${creditNote.documentNumber} creado`);
```

CLI:

```bash
frihet invoices credit-note inv_abc123 --reason error --full
```

---

## CLI — Inicio rapido

### Ver estado del negocio

```bash
frihet status
# Revenue:   EUR 12.500,00
# Expenses:  EUR 3.200,00
# Net:       EUR 9.300,00

frihet status --month 2026-02
```

### Gestionar facturas

```bash
# Listar facturas
frihet invoices list --status paid --limit 5

# Buscar
frihet invoices list -q "Acme"

# Ver detalle
frihet invoices get inv_abc123

# Crear factura
frihet invoices create --client "Acme S.L." --item "Consultoria,10,150" --tax 21

# Marcar como pagada
frihet invoices paid inv_abc123

# Enviar por email
frihet invoices send inv_abc123 --to cliente@acme.com
```

### Gestionar gastos

```bash
# Listar gastos
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Crear gasto
frihet expenses create --desc "Hosting mensual" --amount 49.99 --category software --vendor "Hetzner"
```

### Gestionar clientes

```bash
# Listar clientes
frihet clients list

# Buscar
frihet clients list -q "Acme"

# Crear cliente
frihet clients create --name "Acme S.L." --email info@acme.com --tax-id B12345678 --zone peninsula
```

---

## Recursos disponibles

El SDK expone los siguientes recursos como propiedades de la instancia `Frihet`:

| Recurso | Propiedad | Metodos |
|---------|-----------|---------|
| Facturas | `frihet.invoices` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `markPaid`, `send`, `pdf`, `createBatch`, `createCreditNote` |
| Gastos | `frihet.expenses` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `createBatch` |
| Clientes | `frihet.clients` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
| Proveedores | `frihet.vendors` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
| Productos | `frihet.products` | `list`, `retrieve`, `create`, `update`, `del`, `search` |
| Presupuestos | `frihet.quotes` | `list`, `retrieve`, `create`, `update`, `del`, `search`, `pdf`, `send` |
| Webhooks | `frihet.webhooks` | `list`, `retrieve`, `create`, `update`, `del` + `verifySignature` (estatico) |
| Inteligencia | `frihet.intelligence` | `context`, `summary`, `monthly`, `quarterly` |

Todos los metodos `list` y `search` devuelven un objeto `Page<T>`:

```typescript
interface Page<T> {
  data: T[];
  total: number;
  limit: number;
  offset: number;
}
```

---

## Manejo de errores

El SDK lanza errores tipados para cada tipo de fallo:

```typescript
import Frihet, { AuthenticationError, NotFoundError, ValidationError, RateLimitError, TimeoutError } from '@frihet/sdk';

try {
  await frihet.invoices.retrieve('no-existe');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Factura no encontrada');
  } else if (err instanceof AuthenticationError) {
    console.log('API key invalida');
  } else if (err instanceof ValidationError) {
    console.log('Datos invalidos:', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limit. Reintentar en ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Timeout');
  }
}
```

| Clase | Codigo HTTP | Cuando |
|-------|-------------|--------|
| `AuthenticationError` | 401 | API key invalida o ausente |
| `NotFoundError` | 404 | Recurso no encontrado |
| `ValidationError` | 400 / 422 | Datos de entrada invalidos |
| `RateLimitError` | 429 | Limite de peticiones excedido |
| `TimeoutError` | -- | Sin respuesta en el timeout configurado |
| `APIError` | Otros | Error generico del servidor |

### Reintentos automaticos

El SDK reintenta automaticamente las peticiones que reciben codigos 429 (rate limit) o 5xx (error de servidor), hasta 3 veces con backoff exponencial. No necesitas implementar logica de reintentos.

---

## Idempotencia

Para operaciones de creacion, puedes enviar un `idempotencyKey` para evitar duplicados en caso de reintentos:

```typescript
await frihet.invoices.create(
  { clientName: 'Acme S.L.', items: [{ description: 'Servicio', quantity: 1, unitPrice: 500 }] },
  { idempotencyKey: 'mi-clave-unica-123' }
);
```

---

## Verificar webhooks

El SDK incluye un metodo estatico para verificar la firma HMAC-SHA256 de los webhooks:

```typescript
import { Webhooks } from '@frihet/sdk';

const isValid = Webhooks.verifySignature(
  rawBody,              // string o Buffer del body
  req.headers['x-frihet-signature'],  // cabecera de firma
  'whsec_tu_secreto',   // secreto del webhook
);
```

---

## Variables de entorno

| Variable | Descripcion |
|----------|-------------|
| `FRIHET_API_KEY` | API key (alternativa a `frihet login` en CLI o al constructor del SDK) |
| `FRIHET_API_URL` | URL base personalizada |

---

## Mas informacion

- [API REST](/desarrolladores/api-rest) — referencia completa de endpoints
- [Webhooks](/desarrolladores/webhooks) — eventos y verificacion de firma
- [Repositorio en GitHub](https://github.com/Frihet-io/frihet-sdk) — codigo fuente, issues, contribuciones
- [npm @frihet/sdk](https://www.npmjs.com/package/@frihet/sdk) | [npm frihet](https://www.npmjs.com/package/frihet)

---

## Skill para Claude Code
> Path: /desarrolladores/skill-claude-code

# Skill para Claude Code

La skill de Frihet para Claude Code convierte tu terminal en un asistente de gestion empresarial. No es solo acceso a la API — es inteligencia de negocio: contexto fiscal espanol, recetas de flujos de trabajo, informes financieros formateados y comandos en lenguaje natural.

## Requisitos

- [Claude Code](https://claude.ai/claude-code) instalado
- Cuenta de Frihet con acceso a la API (planes de pago)
- Servidor MCP de Frihet configurado ([ver instrucciones](/desarrolladores))

## Instalacion

### Recomendado: Un comando (30+ agentes)

```bash
npx skills add Frihet-io/frihet-mcp
```

Instala el skill y lo configura automaticamente. Funciona con Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, y [30+ agentes mas](https://agentskills.io).

### Alternativa: Copiar manualmente

```bash
curl -sL https://raw.githubusercontent.com/Frihet-io/frihet-mcp/main/skill/SKILL.md \
  -o ~/.claude/skills/frihet-mcp/SKILL.md --create-dirs
```

### Configurar el servidor MCP

Si aun no lo tienes, anade esto a tu `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_tu_clave_aqui"
      }
    }
  }
}
```

Obtener API key: **app.frihet.io > Configuracion > API > Crear clave**.

## Comandos

| Comando | Descripcion |
|---------|-------------|
| `/frihet status` | Resumen de cuenta: ultimas facturas, pagos pendientes, gastos del mes |
| `/frihet invoice` | Crear, listar o buscar facturas |
| `/frihet expense` | Registrar y consultar gastos |
| `/frihet clients` | Gestionar base de clientes |
| `/frihet quote` | Crear y gestionar presupuestos |
| `/frihet report` | Resumenes financieros (P&L, trimestral, morosos) |
| `/frihet webhooks` | Configurar triggers de automatizacion |
| `/frihet setup` | Configuracion guiada y test de conexion |

## Ejemplos de uso

### Crear una factura

```
/frihet invoice "Acme SL, 40 horas de consultoria a 75 EUR/hora, vencimiento 1 marzo"
```

Claude crea la factura con las lineas de detalle, calcula IVA al 21%, y confirma el numero asignado.

### Registrar gastos rapido

```
/frihet expense "47.50 gasolina 15 feb"
/frihet expense "Adobe CC 59.99 software"
/frihet expense "Comida cliente 23.40 restaurante"
```

La skill infiere la categoria y marca si es deducible segun las reglas fiscales espanolas.

### Preparar el IVA trimestral

```
/frihet report quarterly
```

Calcula automaticamente:
- IVA repercutido (cobrado en facturas)
- IVA soportado (pagado en gastos deducibles)
- Resultado a ingresar o compensar
- Datos listos para el Modelo 303

### Seguimiento de morosos

```
/frihet report unpaid
```

Lista facturas vencidas ordenadas por importe, dias de retraso, y sugiere acciones de seguimiento.

### Cierre mensual

```
/frihet report
```

Resumen completo del mes: ingresos facturados, gastos, resultado neto, IVA neto, facturas pendientes de cobro.

## Contexto fiscal integrado

La skill conoce el contexto fiscal espanol:

| Concepto | Detalle |
|----------|---------|
| IVA general | 21% |
| IVA reducido | 10% (alimentacion, transporte) |
| IVA superreducido | 4% (pan, libros, medicamentos) |
| IRPF profesionales | 15% (7% primeros 3 anos) |
| Modelo 303 | IVA trimestral: abr, jul, oct, ene |
| Modelo 130 | IRPF trimestral (estimacion directa) |
| Verifactu | Obligatorio: sociedades ene 2027, autonomos jul 2027 |

Tambien conoce las reglas de deducibilidad de gastos (gasolina 50%, comidas max 26.67 EUR/dia, etc.) y las aplica automaticamente al registrar gastos.

## Flujos de trabajo

La skill incluye recetas para operaciones comunes:

- **Cierre mensual** — Resumen de ingresos, gastos, IVA y resultado neto
- **Preparacion 303** — Pre-calculo del IVA trimestral con desglose por linea
- **Alta de cliente** — Crear cliente + primera factura en un solo paso
- **Presupuesto a factura** — Convertir un presupuesto aceptado en factura
- **Lote de gastos** — Registrar multiples gastos de una vez con categorizacion automatica
- **Morosos** — Facturas vencidas, ordenadas por importe, con dias de retraso

## Diferencia con el servidor MCP

| | Servidor MCP | Skill |
|---|---|---|
| **Alcance** | 157 herramientas | Herramientas + inteligencia de negocio |
| **Contexto** | Ninguno | Fiscal espanol, deducibilidad, calendario |
| **Flujos** | Operaciones unitarias | Recetas multi-paso (cierre, 303, conversion) |
| **Formato** | JSON crudo | Tablas y resumenes legibles |
| **Prerequisito** | API key | API key + servidor MCP |

La skill **usa** el servidor MCP por debajo. No duplica logica, anade contexto.

## Seguridad

- La API key se gestiona exclusivamente via variables de entorno en la config MCP
- La skill nunca muestra, loguea ni almacena tu API key
- Todos los datos viajan cifrados entre Claude Code, el servidor MCP y la API de Frihet
- El servidor MCP no almacena nada — puente stateless

## Enlaces

- [Codigo fuente (GitHub)](https://github.com/Frihet-io/frihet-mcp)
- [Servidor MCP (npm)](https://www.npmjs.com/package/@frihet/mcp-server)
- [API REST](/desarrolladores/api-rest)
- [Webhooks](/desarrolladores/webhooks)
- [Servidor MCP remoto](https://mcp.frihet.io)

---

## Webhooks
> Path: /desarrolladores/webhooks

# Webhooks

Los webhooks de Frihet permiten recibir notificaciones HTTP en tiempo real cuando ocurren eventos en tu cuenta. En lugar de hacer polling a la API, configura una URL y Frihet enviara un POST con los datos del evento en el momento en que se produzca.

## Configuracion

Puedes gestionar los webhooks desde el panel de Frihet (**Configuracion > Webhooks**) o de forma programatica a traves de la API REST.

### Desde el panel

1. Ve a **Configuracion > Webhooks** en tu cuenta de Frihet
2. Pulsa **Crear webhook**
3. Introduce un nombre descriptivo, la URL de destino y selecciona los eventos que quieres recibir
4. Opcionalmente, define un **secreto** para la verificacion HMAC (recomendado)
5. Guarda el webhook

### API REST de webhooks

Gestiona webhooks de forma programatica con los endpoints CRUD completos.

#### Listar webhooks

```
GET /v1/webhooks
```

```bash
curl https://api.frihet.io/v1/webhooks \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://mi-app.com/hook",
      "events": ["invoice.paid", "invoice.created"],
      "active": true,
      "createdAt": "2026-02-01T10:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

#### Obtener webhook

```
GET /v1/webhooks/:id
```

```bash
curl https://api.frihet.io/v1/webhooks/wh_abc123 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

#### Crear webhook

```
POST /v1/webhooks
```

| Campo | Tipo | Requerido | Descripcion |
|-------|------|-----------|-------------|
| `url` | string | Si | URL de destino (HTTPS obligatorio en produccion) |
| `events` | string[] | Si | Lista de tipos de evento a recibir |
| `secret` | string | No | Secreto para firma HMAC-SHA256 (recomendado) |
| `active` | boolean | No | Estado del webhook (defecto: `true`) |

```bash
curl -X POST https://api.frihet.io/v1/webhooks \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-app.com/hook",
    "events": ["invoice.paid", "expense.created"],
    "secret": "mi-secreto-hmac"
  }'
```

**Respuesta (201):**

```json
{
  "id": "wh_def456",
  "url": "https://mi-app.com/hook",
  "events": ["invoice.paid", "expense.created"],
  "active": true,
  "createdAt": "2026-03-18T10:00:00.000Z"
}
```

#### Actualizar webhook

```
PATCH /v1/webhooks/:id
```

Solo necesitas enviar los campos que quieras modificar.

```bash
curl -X PATCH https://api.frihet.io/v1/webhooks/wh_def456 \
  -H "X-API-Key: fri_tu-clave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["invoice.paid", "invoice.created", "expense.created"],
    "active": false
  }'
```

**Respuesta (200):** Objeto de webhook actualizado.

#### Eliminar webhook

```
DELETE /v1/webhooks/:id
```

```bash
curl -X DELETE https://api.frihet.io/v1/webhooks/wh_def456 \
  -H "X-API-Key: fri_tu-clave-aqui"
```

**Respuesta:** `204 No Content`

---

**Requisitos de la URL:**
- Debe usar HTTPS (se permite HTTP solo para `localhost` y `127.0.0.1` durante el desarrollo)
- No se permiten IPs privadas (10.x, 172.16-31.x, 192.168.x) para evitar ataques SSRF
- Debe responder con un codigo 2xx en menos de 30 segundos

**Limites:**
- Maximo **20 webhooks** por cuenta
- Payload maximo de **100 KB** por entrega

---

## Tipos de evento

Frihet emite **27 tipos de evento**, agrupados por recurso.

### Facturas (9 eventos)

| Evento | Descripcion |
|--------|-------------|
| `invoice.created` | Se ha creado una nueva factura |
| `invoice.updated` | Se ha modificado una factura existente |
| `invoice.generated` | Se ha generado una factura automaticamente (recurrente o desde presupuesto) |
| `invoice.one_off_created` | Se ha creado una factura puntual (no recurrente) |
| `invoice.paid` | Una factura ha sido marcada como pagada (completa) |
| `invoice.overdue` | Una factura ha superado su fecha de vencimiento |
| `invoice.voided` | Una factura ha sido anulada |
| `invoice.payment_status_updated` | El estado de pago ha cambiado (parcial, fallido, reembolsado) |
| `invoice.payment_failure` | Un intento de cobro automatico ha fallado |

### Pagos (3 eventos)

| Evento | Descripcion |
|--------|-------------|
| `payment.succeeded` | Un pago se ha completado correctamente (Stripe, portal de cliente) |
| `payment.requires_action` | Un pago requiere accion adicional (3D Secure, confirmacion bancaria) |
| `payment_receipt.created` | Se ha generado un recibo de pago |

### Facturas rectificativas (2 eventos)

| Evento | Descripcion |
|--------|-------------|
| `credit_note.created` | Se ha creado una factura rectificativa |
| `credit_note.generated` | Se ha generado automaticamente una rectificativa |

### Presupuestos (5 eventos)

| Evento | Descripcion |
|--------|-------------|
| `quote.created` | Se ha creado un nuevo presupuesto |
| `quote.updated` | Se ha modificado un presupuesto existente |
| `quote.accepted` | Un cliente ha aceptado un presupuesto (cambio de estado a `accepted`) |
| `quote.rejected` | Un cliente ha rechazado un presupuesto (cambio de estado a `rejected`) |
| `quote.expired` | Un presupuesto ha superado su fecha de validez |

### Gastos (2 eventos)

| Evento | Descripcion |
|--------|-------------|
| `expense.created` | Se ha registrado un nuevo gasto |
| `expense.updated` | Se ha modificado un gasto existente |

### Clientes (3 eventos)

| Evento | Descripcion |
|--------|-------------|
| `client.created` | Se ha dado de alta un nuevo cliente |
| `client.updated` | Se han modificado los datos de un cliente |
| `client.vies_check` | Se ha verificado el NIF-IVA de un cliente contra el sistema VIES de la UE |

### Productos (2 eventos)

| Evento | Descripcion |
|--------|-------------|
| `product.created` | Se ha creado un nuevo producto o servicio |
| `product.updated` | Se ha modificado un producto o servicio existente |

### Cobros (1 evento)

| Evento | Descripcion |
|--------|-------------|
| `dunning.finished` | El proceso de cobro automatico (dunning) ha finalizado para una factura |

---

## Estructura del payload

Cada entrega de webhook es una peticion `POST` con cuerpo JSON. La estructura es la misma para todos los tipos de evento:

```json
{
  "event": "invoice.paid",
  "timestamp": "2026-02-12T14:30:00.000Z",
  "data": {
    "id": "inv_abc123",
    "clientName": "Acme S.L.",
    "items": [
      { "description": "Consultoria", "quantity": 10, "unitPrice": 75 }
    ],
    "total": 750,
    "status": "paid",
    "paidAt": "2026-02-12T14:29:58.000Z",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-02-12T14:30:00.000Z"
  }
}
```

El campo `data` contiene el estado completo del recurso en el momento del evento.

---

## Cabeceras de entrega

Cada peticion de webhook incluye las siguientes cabeceras:

| Cabecera | Descripcion | Ejemplo |
|----------|-------------|---------|
| `Content-Type` | Tipo de contenido | `application/json` |
| `X-Frihet-Event` | Tipo de evento | `invoice.paid` |
| `X-Frihet-Delivery-Id` | Identificador unico de la entrega | `d4e5f6a7b8c9` |
| `X-Frihet-Timestamp` | Marca de tiempo ISO 8601 | `2026-02-12T14:30:00.000Z` |
| `X-Frihet-Signature` | Firma HMAC-SHA256 del payload | `sha256=a1b2c3d4e5f6...` |

La cabecera `X-Frihet-Signature` solo se incluye si has configurado un secreto en el webhook.

---

## Verificacion de firma

Si configuras un secreto al crear el webhook, Frihet firma cada payload con HMAC-SHA256. El proceso de verificacion consiste en:

1. Tomar el cuerpo de la peticion en bruto (raw body)
2. Calcular el HMAC-SHA256 usando el secreto como clave
3. Comparar el resultado con el valor de la cabecera `X-Frihet-Signature` (sin el prefijo `sha256=`)

### Con el SDK (recomendado)

```typescript
import { Webhooks } from '@frihet/sdk';

app.post('/webhook/frihet', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = Webhooks.verifySignature(
    req.body,
    req.headers['x-frihet-signature'],
    process.env.FRIHET_WEBHOOK_SECRET,
  );

  if (!isValid) return res.status(401).send('Firma invalida');

  const event = JSON.parse(req.body.toString());
  console.log(req.headers['x-frihet-event'], event.data);
  res.sendStatus(200);
});
```

### Ejemplo manual en Node.js

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const receivedSignature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(receivedSignature, 'hex')
  );
}

// Uso en un servidor Express
app.post('/webhook/frihet', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-frihet-signature'];
  const secret = process.env.FRIHET_WEBHOOK_SECRET;

  if (!signature || !verifyWebhookSignature(req.body.toString(), signature, secret)) {
    return res.status(401).send('Firma invalida');
  }

  const event = JSON.parse(req.body.toString());
  const eventType = req.headers['x-frihet-event'];

  console.log(`Evento recibido: ${eventType}`, event.data);

  // Procesar el evento segun su tipo
  switch (eventType) {
    case 'invoice.paid':
      // Actualizar tu sistema de contabilidad
      break;
    case 'expense.created':
      // Notificar al equipo financiero
      break;
  }

  res.status(200).send('OK');
});
```

### Ejemplo en Python

```python
import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = 'tu-secreto-aqui'

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    received = signature.replace('sha256=', '')

    return hmac.compare_digest(expected, received)

@app.route('/webhook/frihet', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Frihet-Signature', '')
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        abort(401)

    event = request.get_json()
    event_type = request.headers.get('X-Frihet-Event')

    print(f'Evento recibido: {event_type}')

    if event_type == 'invoice.paid':
        # Actualizar tu sistema de contabilidad
        pass
    elif event_type == 'quote.accepted':
        # Convertir presupuesto a factura
        pass

    return 'OK', 200
```

**Importante:** Usa siempre una comparacion en tiempo constante (`timingSafeEqual` en Node.js, `compare_digest` en Python) para evitar ataques de timing.

---

## Politica de reintentos

Si la entrega de un webhook falla (codigo de respuesta no-2xx o timeout), Frihet reintenta automaticamente con **backoff exponencial**:

| Intento | Retardo | Tiempo acumulado |
|---------|---------|------------------|
| 1 (inicial) | inmediato | 0s |
| 2 (primer reintento) | 2 segundos | 2s |
| 3 (segundo reintento) | 4 segundos | 6s |

- Maximo **3 intentos** por entrega (1 inicial + 2 reintentos)
- Retardo maximo de **30 segundos** entre reintentos
- Timeout de **30 segundos** por peticion
- Si los 3 intentos fallan, la entrega se marca como `failed`
- En cada reintento se incluye la cabecera `X-Frihet-Retry-Attempt` con el numero de intento

Los reintentos se procesan mediante un job que se ejecuta cada 5 minutos (hasta 50 entregas pendientes por ejecucion), garantizando la fiabilidad incluso si el proceso principal se reinicia.

### Circuit breaker

Si un webhook acumula **3 fallos consecutivos**, Frihet lo pausa automaticamente para proteger tanto tu endpoint como el sistema de entregas.

- El webhook pasa a estado `paused` con `pausedReason: "consecutive_failures"`
- No se envian mas entregas hasta que lo reactives manualmente
- Puedes reactivar el webhook desde el panel o via API (`PATCH /v1/webhooks/:id` con `active: true`)

Puedes consultar el **historial de entregas** de cada webhook desde el panel de Frihet, incluyendo el codigo de respuesta, el cuerpo de la respuesta (primeros 1000 caracteres) y los errores de cada intento.

---

## Pruebas

Desde el panel de Frihet puedes enviar un **evento de prueba** a cualquier webhook configurado. El payload de prueba tiene la siguiente estructura:

```json
{
  "event": "webhook.test",
  "timestamp": "2026-02-12T14:30:00.000Z",
  "data": {
    "message": "This is a test webhook from Frihet ERP"
  }
}
```

Esto permite verificar que tu endpoint esta accesible, que la firma se valida correctamente y que tu sistema procesa los eventos sin errores.

---

## Buenas practicas

### Responde rapido

Tu endpoint debe responder con un codigo `200` lo antes posible. Si necesitas realizar un procesamiento pesado (enviar emails, actualizar bases de datos externas, etc.), acepta el evento y procesalo de forma asincrona en una cola de trabajo.

### Gestiona la idempotencia

Es posible que un mismo evento se entregue mas de una vez (por ejemplo, si tu servidor respondio con un timeout pero proceso el evento). Usa el campo `X-Frihet-Delivery-Id` como clave de idempotencia para evitar duplicados.

### Verifica la firma siempre

Nunca confies en un webhook sin verificar la cabecera `X-Frihet-Signature`. Cualquier actor con acceso a tu URL podria enviar payloads falsos.

### Usa HTTPS

En produccion, tu endpoint debe estar protegido con HTTPS. Frihet rechaza URLs HTTP (excepto en desarrollo local).

### Monitoriza los fallos

Revisa periodicamente los logs de entrega en el panel de Frihet. Si ves entregas fallidas de forma recurrente, verifica que tu endpoint esta disponible y responde en menos de 30 segundos.

### Filtra los eventos

Suscribete solo a los eventos que necesitas. Cada webhook puede escuchar uno o varios tipos de evento. Cuantos menos eventos innecesarios proceses, menor sera la carga en tu servidor.

---

## Depuracion de entregas

Frihet registra el resultado de cada entrega de webhook. Puedes consultarlo desde el panel:

1. Ve a **Ajustes > Desarrolladores > Webhooks**
2. Pulsa sobre el webhook que quieres inspeccionar
3. Abre la pestana **Entregas**

Cada entrada muestra:

- **Codigo de respuesta** HTTP devuelto por tu endpoint
- **Tiempo de respuesta** en milisegundos
- **Cuerpo de la respuesta** (primeros 1000 caracteres)
- **Fecha y hora** de cada intento (incluidos los reintentos)
- **Estado** final: `delivered`, `retrying` o `failed`

### Problemas habituales

| Sintoma | Causa probable | Solucion |
|---------|----------------|----------|
| Todas las entregas fallan con timeout | Endpoint tarda mas de 30s en responder | Acepta el evento con un `200` inmediato y procesa de forma asincrona |
| Error SSL/TLS | Certificado expirado o cadena incompleta | Renueva el certificado y verifica la cadena con `openssl s_client` |
| Codigo 403 sistemático | Firewall bloqueando peticiones POST entrantes | Permite trafico desde las IPs de Google Cloud (`us-central1`) |
| Codigo 502/503 | Servidor caido o en mantenimiento | Revisa los logs de tu servidor y verifica que el proceso esta activo |

### Boton de prueba

En la pantalla de detalle de cada webhook, el boton **Enviar prueba** envia un evento sintetico `webhook.test` a tu URL. Usa este boton para verificar:

- Que la URL es accesible desde internet
- Que la firma HMAC se valida correctamente
- Que tu servidor responde con un codigo `2xx`

El resultado de la prueba aparece inmediatamente en el log de entregas.

---

## Resolucion de problemas

### No recibo webhooks

1. Verifica que la URL del webhook es correcta y accesible desde internet
2. Comprueba que el webhook esta en estado **activo** en el panel
3. Revisa los logs de entrega para ver si hay errores
4. Si usas un firewall, asegurate de que las peticiones POST entrantes desde Google Cloud (`us-central1`) estan permitidas

### Las firmas no coinciden

1. Verifica que estas usando el raw body de la peticion (antes de parsear el JSON)
2. Confirma que el secreto en tu codigo coincide con el configurado en el panel de Frihet
3. No modifiques ni reformatees el body antes de verificar la firma
4. Revisa que tu framework no esta parseando automaticamente el body antes de que puedas acceder al raw

### Los reintentos no llegan

1. Los reintentos se procesan cada 5 minutos. Si tu endpoint estuvo caido brevemente, puede que ya se hayan agotado los intentos
2. Revisa el historial de entregas para confirmar el estado de cada intento
3. Si los 3 intentos fallaron, la entrega no se reintentara de nuevo automaticamente

### Payload demasiado grande

Si el recurso asociado al evento es muy grande (muchas lineas en una factura, campos extensos), el payload puede superar el limite de 100 KB y la entrega sera rechazada. Simplifica los datos del recurso o contacta con soporte si necesitas un limite superior.

---

## Espacios de trabajo
> Path: /equipo/espacios-trabajo

# Espacios de trabajo

Si eres contable o gestor y tus clientes te han invitado a sus cuentas, puedes ver y gestionar sus datos desde tu propia cuenta de Frihet.

## Como funciona

Cuando un cliente te invita como **contable** a su cuenta:

1. Aparece un selector de espacios de trabajo en la barra lateral
2. Puedes cambiar entre tu cuenta y las de tus clientes con un clic
3. Al cambiar, todas las vistas (facturas, gastos, clientes) muestran los datos del cliente seleccionado
4. Un banner superior indica que estas viendo datos de otro usuario

## Que puedes hacer en el espacio de un cliente

Con el rol **contable**:

- **Leer**: facturas, presupuestos, gastos, clientes, proveedores, productos
- **Crear/editar**: facturas y gastos (con numeracion del cliente)
- **No puedes**: eliminar datos, cambiar configuracion, ver facturacion

Las facturas creadas en nombre de un cliente usan su serie de numeracion y aparecen en su cuenta.

## Panel de gestoria

Si tienes acceso a multiples clientes, la ruta `/gestoria` muestra un panel con:

- Tarjetas de cada cliente con su nombre, email y rol
- Proxima fecha fiscal trimestral
- Boton para abrir directamente su espacio de trabajo

Accede desde la barra lateral en **Mis clientes**.

## Portal de documentos del cliente

Los clientes que tienen un contable asignado ven un banner en su dashboard:

> "Tu gestoria tiene acceso a tus datos. Sube tus facturas de proveedor en Gastos."

Esto les facilita subir documentos que el contable necesita para la contabilidad.

## Seguridad

- Los permisos se verifican tanto en la interfaz como en el servidor
- Las operaciones de escritura y eliminacion se validan en la capa de datos
- La configuracion del propietario (perfil fiscal, facturacion, seguridad) nunca es accesible para miembros del equipo
- El registro de auditoria siempre identifica quien realizo cada accion

---

## App movil gestoria
> Path: /equipo/gestoria-movil

# App movil gestoria

La app movil de Frihet para gestorias permite gestionar expedientes de clientes sin estar delante del ordenador. Aprueba declaraciones, revisa documentos y comunica incidencias desde el movil con el mismo nivel de seguridad que la version web.

La app esta construida sobre la misma base de codigo que la web, lo que garantiza paridad de funcionalidades y actualizaciones automaticas.

:::caution Publicacion en stores pendiente
La build movil esta lista, pero **todavia no esta publicada en App Store ni Google Play**. Mientras tanto, usa Frihet desde el movil como **PWA** (web-app): abre `app.frihet.io` en el navegador del movil y "Anadir a pantalla de inicio". Las funciones nativas (push, swipe) llegaran con la publicacion en stores.
:::

## Instalacion

Hoy: instala la **PWA** desde el navegador del movil.

- **iOS (Safari)**: abre `app.frihet.io` → Compartir → "Anadir a pantalla de inicio" (requiere iOS 16+).
- **Android (Chrome)**: abre `app.frihet.io` → menu → "Instalar app" / "Anadir a pantalla de inicio" (requiere Android 10+).

Las apps nativas en App Store y Google Play se anunciaran cuando esten publicadas.

:::info Acceso restringido
Las funciones de gestoria estan disponibles exclusivamente para cuentas con el **modulo Gestoria** activo. Los clientes finales de la gestoria usan el portal web, no la app.
:::

Inicia sesion con las mismas credenciales que en web. Si tienes MFA activado, se solicita en el primer inicio de sesion por dispositivo.

## Swipe para aprobar expedientes

La funcionalidad central de la app es la **cola de aprobacion gestual**. Accede desde **Inicio** → **Pendientes de aprobacion**.

Cada expediente se muestra como una tarjeta con:

- Nombre del cliente
- Tipo de documento (M303, M130, M200, IRPF, etc.)
- Periodo declarado
- Importe a ingresar o devolver
- Fecha limite

**Gestos disponibles:**

| Gesto                  | Accion                                                       |
| ---------------------- | ------------------------------------------------------------ |
| Swipe derecha (verde)  | Aprobar — el cliente recibe notificacion de firma disponible |
| Swipe izquierda (rojo) | Rechazar — abre campo de motivo antes de confirmar           |
| Tap                    | Ver detalle completo del expediente                          |
| Swipe arriba           | Dejar para mas tarde (vuelve al final de la cola)            |

Cada aprobacion queda registrada en el audit trail con la marca de tiempo y el dispositivo (movil).

## Notificaciones push

Configura las notificaciones en **App** → **Configuracion** → **Notificaciones**:

| Evento                          | iOS  | Android | Telegram |
| ------------------------------- | ---- | ------- | -------- |
| Nuevo documento cliente         | Push | Push    | Opcional |
| Declaracion lista para revision | Push | Push    | Opcional |
| Vencimiento fiscal en 3 dias    | Push | Push    | Si       |
| Documento firmado por cliente   | Push | Push    | Opcional |
| Mensaje nuevo del cliente       | Push | Push    | Opcional |

Las notificaciones de vencimientos fiscales estan activadas por defecto y no pueden desactivarse (son criticas para el negocio).

Para activar las notificaciones por primera vez, la app solicita permiso del sistema operativo en el primer inicio.

## Documentos y adjuntos

Desde el movil puedes:

- **Ver** PDFs de declaraciones y documentos del cliente (visor nativo).
- **Firmar** documentos con firma digital del dispositivo (biometria o PIN).
- **Adjuntar** ficheros desde la camara o el almacenamiento del movil (ej: DNI del cliente, justificante bancario).
- **Descargar** documentos para revision offline.

El tamano maximo de adjunto desde movil es **20 MB**. Para ficheros mayores, usa la version web.

## Mensajeria con clientes

La app incluye el modulo de mensajeria contextual de Frihet. Los mensajes van vinculados al expediente del cliente — no es un chat generico. Accede desde **Cliente** → **Mensajes**.

:::tip
Los mensajes del movil y de la web estan sincronizados en tiempo real. Puedes empezar una conversacion en el movil y continuarla en el ordenador sin perder contexto.
:::

## Borradores offline (roadmap)

El soporte completo de borradores offline esta planificado para **Q4 2026**. Actualmente disponible en beta:

- **Disponible ahora**: leer expedientes y documentos sin conexion (cache 24h).
- **Beta**: crear notas e incidencias offline — se sincronizan al recuperar conexion.
- **Q4 2026**: crear y editar borradores de declaraciones offline con sincronizacion diferida.

Para unirte a la beta, activa **Configuracion** → **Cuenta** → **Funciones experimentales** → **Modo offline beta**.

## Seguridad

- **Biometria**: desbloqueo con Face ID / Touch ID / huella Android obligatorio si el dispositivo lo soporta.
- **Timeout de sesion**: la sesion se cierra automaticamente tras 30 minutos de inactividad en background.
- **Borrado remoto**: si pierdes el dispositivo, un administrador puede revocar el acceso desde **Configuracion** → **Dispositivos activos**.
- **Sin datos locales**: los documentos del cliente no se almacenan en el dispositivo — solo en cache cifrada temporal.

## Gotchas

- **Biometria corporativa**: en dispositivos con MDM (Mobile Device Management) empresarial, la biometria puede no estar disponible. En ese caso se usa PIN de 6 digitos.
- **Actualizaciones**: la app se actualiza automaticamente en background. Si ves comportamientos inesperados, fuerza la actualizacion desde la App Store / Google Play.
- **Modo oscuro**: disponible y respeta la configuracion del sistema operativo.
- **Tablets**: la app esta optimizada para movil pero es funcional en iPad y tablets Android. La experiencia en tablet es mejor desde el navegador web.

## Relacionado

- [Modulo Gestoria — resumen](./gestoria)
- [Portal white-label para clientes](./gestoria-whitelabel)
- [Self-onboard de clientes VIES](./gestoria-self-onboard)
- [Notificaciones](../configuracion/notificaciones)

---

## Self-onboard de clientes con VIES
> Path: /equipo/gestoria-self-onboard

# Self-onboard de clientes con VIES

El self-onboard permite que tus clientes completen su alta en el portal de gestoria de forma autonoma, sin que tengas que introducir sus datos manualmente. El cliente recibe un magic link por email, introduce su CIF/NIF y Frihet consulta automaticamente el censo AEAT y el registro VIES para pre-rellenar sus datos fiscales.

Esta funcionalidad reduce el tiempo de alta de un cliente de 15-20 minutos a menos de 3 minutos.

## Flujo completo

```
Tu (gestor) → Envia invitacion con magic link
  ↓
Cliente → Hace clic en el link (autenticacion sin password)
  ↓
Cliente → Introduce CIF/NIF
  ↓
Frihet → Consulta AEAT (censo) + VIES (si es intracomunitario)
  ↓
Cliente → Revisa y confirma datos pre-rellenados
  ↓
Cliente → Acepta condiciones y configura metodo de pago (Stripe)
  ↓
Tu → Recibes notificacion: cliente activo en portal
```

## Enviar invitacion a un cliente

1. Ve a **Gestoria** → **Clientes** → **Invitar cliente**.
2. Introduce el email del cliente y el nombre de la empresa (opcional).
3. Personaliza el mensaje de bienvenida si lo necesitas.
4. Haz clic en **Enviar invitacion**.

El cliente recibe un email desde tu dominio white-label (si esta configurado) con un enlace unico valido **72 horas**. Puedes reenviar la invitacion si caduca.

Tambien puedes enviar invitaciones en bloque desde **Gestoria** → **Clientes** → **Importar** → subir CSV con columnas `email, nombre_empresa`.

## Magic link — autenticacion sin password

El magic link autentica al cliente sin necesidad de crear una password. Al hacer clic en el enlace:

1. Frihet verifica que el token es valido y no ha caducado.
2. Crea una sesion segura para ese email.
3. El cliente accede directamente al formulario de alta — sin pantalla de login.

Una vez completado el alta, el cliente puede configurar una password o continuar usando magic links para cada acceso (configurable por el gestor en **Gestoria** → **Configuracion** → **Autenticacion clientes**).

## Auto-relleno AEAT y VIES

Al introducir el CIF/NIF, Frihet realiza dos consultas en paralelo:

### Consulta AEAT (censo)

Frihet consulta el **censo de contribuyentes AEAT** para verificar el NIF y recuperar:

- Razon social oficial
- Domicilio fiscal (calle, CP, municipio, provincia)
- Actividad economica principal (CNAE)
- Regimen de IVA (general, simplificado, recargo equivalencia)
- Zona fiscal (peninsula, Canarias, Ceuta/Melilla)

:::info
La consulta AEAT requiere que el NIF este activo en el censo. NIF de personas fisicas autonomas, CIF de sociedades y NIE de extranjeros autonomos son todos validos.
:::

### Consulta VIES (operadores intracomunitarios)

Si el cliente tiene actividades intracomunitarias, Frihet consulta el registro **VIES (VAT Information Exchange System)** de la Comision Europea para verificar el numero de operador intracomunitario (ROI) y recuperar:

- Estado del ROI (valido / no valido / no registrado)
- Nombre oficial en el registro VIES
- Pais de la sede

```
Ejemplo respuesta VIES:
{
  "valid": true,
  "countryCode": "ES",
  "vatNumber": "B12345678",
  "name": "EMPRESA EJEMPLO SL",
  "address": "CALLE MAYOR 1, 28013 MADRID"
}
```

Los datos VIES se usan automaticamente para las facturas intracomunitarias del cliente (tipo de IVA 0% con referencia ROI).

## Configuracion de pago — Stripe Connect

Si tu gestoria cobra a los clientes a traves de Frihet, el flujo de alta incluye la configuracion del metodo de pago via **Stripe Connect**:

1. El cliente introduce su tarjeta de credito o debito directamente en el formulario Stripe (PCI-compliant — Frihet no almacena datos de tarjeta).
2. Frihet asocia el cliente a tu cuenta Stripe Connect de gestoria.
3. Los cobros futuros (cuotas mensuales, servicios adicionales) se cargan automaticamente.

Si no usas cobros automaticos, desactiva Stripe en el flujo en **Gestoria** → **Configuracion** → **Cobros** → desactivar **Pago en el alta**.

## Estado del alta y seguimiento

Ve a **Gestoria** → **Clientes** → **En proceso de alta** para ver el estado de cada invitacion:

| Estado                 | Significado                                            |
| ---------------------- | ------------------------------------------------------ |
| Invitacion enviada     | El cliente aun no ha abierto el link                   |
| En progreso            | El cliente ha abierto el formulario                    |
| Pendiente confirmacion | El cliente ha completado el formulario — revision tuya |
| Activo                 | Alta completada — cliente con acceso al portal         |
| Caducado               | El magic link expiro sin completar el alta             |

Puedes reenviar la invitacion o extender el plazo desde cualquier estado.

## Gotchas

- **NIF no encontrado en AEAT**: ocurre con NIFs recien dados de alta o NIF de actividades sin obligaciones periodicas. En ese caso, el formulario pide introduccion manual.
- **VIES no disponible**: el servicio VIES de la UE tiene interrupciones periodicas (especialmente fines de semana). Frihet reintenta automaticamente 3 veces y si falla, pide introduccion manual con advertencia.
- **CIF invalido**: el sistema valida el algoritmo de control del CIF/NIF antes de consultar AEAT. NIFs con errores tipograficos se detectan inmediatamente.
- **Clientes extranjeros**: para clientes fuera de la UE, la consulta AEAT/VIES no aplica. El formulario pide TIN (Tax Identification Number) del pais de origen y el resto de campos manualmente.
- **Datos desactualizados en AEAT**: el censo AEAT puede tener datos con hasta 3 meses de retraso. El cliente debe confirmar los datos antes de finalizar el alta.

## Relacionado

- [Modulo Gestoria — resumen](./gestoria)
- [Portal white-label con dominio propio](./gestoria-whitelabel)
- [App movil gestoria](./gestoria-movil)
- [Stripe Connect](../integraciones/stripe-connect)

---

## Portal white-label con dominio propio
> Path: /equipo/gestoria-whitelabel

# Portal white-label con dominio propio

El modulo white-label permite que tus clientes accedan al portal de documentos y declaraciones bajo tu propio dominio (ej: `clientes.tuasesoria.es`) en lugar del dominio generico de Frihet. Esto refuerza la imagen de marca de tu gestoria y mejora la confianza del cliente.

Esta funcionalidad esta disponible en plan **Gestoria Pro**.

## Como funciona

Frihet proporciona la infraestructura (servidores, SSL, CDN) mientras tu aportas el dominio y la identidad visual. El proceso completo tarda menos de 5 minutos mas el tiempo de propagacion DNS (tipicamente 15-60 minutos).

## Asistente de configuracion de dominio

1. Ve a **Configuracion** → **Gestoria** → **Dominio personalizado**.
2. Introduce el subdominio que quieres usar. Recomendamos usar un subdominio (ej: `clientes.tuasesoria.es`), no el dominio raiz.
3. El asistente te muestra las instrucciones DNS especificas para tu dominio.

## Configuracion DNS — instrucciones CNAME

En el panel de tu proveedor de DNS (Cloudflare, GoDaddy, OVH, IONOS, etc.), crea el siguiente registro:

```
Tipo:    CNAME
Nombre:  clientes          (o el subdominio que hayas elegido)
Valor:   portal.frihet.io
TTL:     Auto / 3600
```

:::warning Dominio raiz (apex)
Si quieres usar el dominio raiz (ej: `tuasesoria.es` sin subdominio), debes usar un registro **ALIAS** o **ANAME** en lugar de CNAME. No todos los proveedores DNS soportan este tipo. En ese caso, recomendamos usar un subdominio como `portal.tuasesoria.es`.
:::

### Instrucciones por proveedor DNS popular

**Cloudflare:**

```
DNS → Add record → Type: CNAME → Name: clientes → Target: portal.frihet.io → Proxy: OFF (nube gris)
```

Importante: desactiva el proxy (nube naranja → nube gris) para que Frihet pueda gestionar el SSL.

**GoDaddy:**

```
DNS → Manage → Add → Type: CNAME → Host: clientes → Points to: portal.frihet.io → TTL: 1 hora
```

**IONOS (1&1):**

```
Dominios → Subdominos → Crear subdominio: clientes → Tipo: CNAME → Apunta a: portal.frihet.io
```

## Provision SSL automatica

Una vez que el CNAME propaga correctamente, Frihet detecta la configuracion y emite automaticamente un certificado SSL/TLS via **Let's Encrypt**. El proceso tarda entre 2 y 10 minutos tras la propagacion DNS.

El estado del SSL es visible en **Configuracion** → **Gestoria** → **Dominio personalizado**:

- Pendiente DNS: esperando propagacion del CNAME
- Emitiendo SSL: certificado en proceso (2-10 min)
- Activo: tu dominio esta funcionando con HTTPS
- Error: ver seccion de gotchas

El certificado se renueva automaticamente cada 90 dias — no necesitas hacer nada.

## Personalizacion de marca

Con el dominio activo, personaliza el portal en **Configuracion** → **Gestoria** → **Marca**:

| Elemento                      | Personalizable                     |
| ----------------------------- | ---------------------------------- |
| Logo (cabecera)               | Si — PNG/SVG, max 2MB              |
| Colores primario y secundario | Si — selector hex                  |
| Nombre de la gestoria         | Si — aparece en pie y emails       |
| Favicon                       | Si — ICO/PNG 32x32                 |
| Mensaje de bienvenida         | Si — texto libre, soporte Markdown |
| Correo de soporte al cliente  | Si — aparece en pie de pagina      |

Los colores y logo se aplican tambien a los **emails automaticos** enviados a tus clientes (notificaciones de declaracion lista, solicitudes de documentacion).

## Verificar que todo funciona

Tras la activacion, comprueba:

1. Accede a `https://clientes.tuasesoria.es` desde un navegador en modo incognito.
2. Verifica que el candado SSL esta activo (HTTPS verde).
3. Verifica que aparece tu logo y colores.
4. Accede con las credenciales de un cliente de prueba.

## Multiples portales (multi-marca)

Si gestionas varias marcas o lineas de negocio bajo la misma cuenta Frihet, puedes configurar hasta **3 dominios personalizados** en el plan Gestoria Pro. Cada dominio puede tener su propio logo y paleta de colores, pero comparten la base de datos de clientes de Frihet.

Para portales completamente separados (datos aislados), contacta a soporte para explorar la opcion de **instancias multi-tenant**.

## Gotchas

- **Propagacion DNS lenta**: en algunos proveedores DNS la propagacion puede tardar hasta 48h. Comprueba la propagacion en [dnschecker.org](https://dnschecker.org) antes de contactar a soporte.
- **Cloudflare con proxy activo**: si dejas el proxy de Cloudflare activo (nube naranja), Frihet no puede verificar el dominio y el SSL no se emite. Usa nube gris para este subdominio.
- **Certificado SSL bloqueado por CAA**: si tu dominio tiene registros CAA restrictivos, anade `letsencrypt.org` como CA autorizada.
- **Dominio ya usado**: cada dominio/subdominio solo puede apuntar a un portal Frihet. Si ya lo tienes configurado en otra cuenta, deberas quitarlo primero.
- **Email en el mismo dominio**: si usas `@tuasesoria.es` para correo, el registro CNAME del subdominio no afecta al correo — son registros independientes.

## Relacionado

- [Modulo Gestoria — resumen](./gestoria)
- [Self-onboard de clientes VIES](./gestoria-self-onboard)
- [App movil gestoria](./gestoria-movil)
- [Notificaciones a clientes](../configuracion/notificaciones)

---

## Panel de gestoría
> Path: /equipo/gestoria

# Panel de gestoría

> Un panel centralizado para gestorías y asesorías: genera declaraciones fiscales en lote, gestiona vencimientos, solicita documentos a tus clientes, recibe facturas por email y exporta la contabilidad de cada cliente al formato que use tu software (A3, ContaPlus, DATEV, Xero, QuickBooks o CSV).

## Qué puede hacer una gestoría con Frihet

- **Cockpit multi-cliente**: todas las empresas que gestionas en una sola pantalla, ordenadas por riesgo (las críticas primero), con estado de salud, próximo vencimiento fiscal y saldo vencido por cliente.
- **Declaraciones en lote**: genera M303, M130, M111 y M115 para varios clientes a la vez (PDF o TXT AEAT) y descárgalos en un ZIP.
- **Aging consolidado**: cobros pendientes de toda la cartera en un único cuadro, con tramos 1-30/31-60/61-90/90+ días.
- **Factura desde email**: reenvía la factura de un proveedor a una dirección del workspace y la IA la convierte en un borrador de factura.
- **Solicitudes de documentos**: pide documentación a cada cliente con prioridad y fecha límite; ellos la suben a su portal.
- **Exportación contable**: descarga cada cliente en el formato que necesite tu contabilidad.
- **Asesor gratis**: tu cliente te invita como contable sin que ocupes un asiento de pago.

## Invitar y aceptar clientes

Frihet conecta gestoría y cliente mediante el **rol de contable** dentro del workspace del cliente — no necesitas crear cuentas nuevas ni duplicar datos.

1. **El cliente te invita.** En su workspace, va a **Equipo → Invitar miembros** y te añade con el rol **Contable**.
2. **Aceptas la invitación.** Recibes un email con un enlace; al aceptar, ese cliente aparece en tu **Panel de gestoría**.
3. **Sin coste de asiento.** Un asesor invitado como contable **no consume un asiento de pago** del plan del cliente.

Cada cliente que aceptas se suma a tu cartera y aparece como una tarjeta en el cockpit.

## Tu cartera de clientes

El cockpit muestra una tarjeta por cliente con:

- **Estado de salud** (saludable / atención / crítico), derivado de un scoring determinista 0-100 (pago, volumen, engagement, antigüedad) con predicción de abandono.
- **Próximo vencimiento fiscal** con urgencia por color (rojo ≤7 días, ámbar ≤15 días), tomado del calendario fiscal real del cliente.
- **Saldo vencido** por tramos de antigüedad (30/60/90+).
- **Documentos pendientes** y badge de subidas sin leer en tiempo real.

Las tarjetas se ordenan automáticamente por riesgo: los clientes que necesitan atención aparecen primero.

## Entrar en un cliente

Tienes dos formas de operar sobre un cliente:

- **Sin cambiar de workspace.** Desde la propia tarjeta del cockpit puedes ejecutar **Acciones rápidas**: descargar PDF, TXT AEAT o una exportación contable de ese cliente directamente, sin salir del panel.
- **Entrando al workspace.** Haz clic en la tarjeta para abrir el workspace del cliente con tu rol de contable: ves sus datos, generas modelos y emites facturas en su nombre (numeración independiente por empresa).

## Solicitudes de documentos

El sistema de **solicitud de documentos** comunica gestoría y cliente dentro de Frihet:

1. Crea una solicitud con **título, descripción, prioridad y fecha límite**.
2. El cliente recibe un **email automático** (vía Resend) con un enlace directo a la pestaña **Solicitudes** de su portal.
3. El cliente **sube los ficheros** desde el portal (máx. 7 MB); al subirlos, la solicitud se marca como completada y tú ves un badge de subida sin leer en tiempo real.

Extras:

- **Plantillas reutilizables** con variables (`{{cliente.businessName}}`) y **envío masivo** a 50+ clientes de una vez.
- **WhatsApp en un clic**: mensaje pre-redactado con el enlace al portal.
- **Mensajería contextual**: hilos asociados a cada solicitud, modelo u obligación.

## Factura desde email (OCR)

Reenvía la factura de un proveedor a la dirección de recepción del workspace del cliente
(`receipts@<slug-del-workspace>.frihet.io`). La IA extrae **proveedor, fecha, importe e impuestos**
por OCR (Gemini) y **genera automáticamente un borrador** de factura listo para revisar.

:::note
Es un flujo de captura proveedor→borrador, no un reenvío de facturas ya emitidas. Revisa siempre el borrador antes de contabilizarlo.
:::

## Exportar a A3, ContaPlus y otros

Frihet exporta la contabilidad de cada cliente en **6 formatos**, para que importes en el software que ya uses:

| Formato              | Uso típico                   |
| -------------------- | ---------------------------- |
| **A3 (Innuva)**      | Gestorías en España          |
| **ContaPlus** (Sage) | Contabilidad PYME en España  |
| **DATEV**            | Alemania                     |
| **Xero**             | Internacional                |
| **QuickBooks**       | Internacional                |
| **CSV genérico**     | Cualquier importador / Excel |

Lánzalo desde **Acciones rápidas** en la tarjeta del cliente, o desde dentro de su workspace.

:::info
También hay exportación **SAF-T** disponible. **¿Usas ContaSol?** No hay un formato propio "ContaSol", pero el export **ContaPlus** (fichero `xDiario.txt`) es **compatible con ContaSol** (y con Sage 50 y A3 vía intermediario) — usa ContaPlus para importar en ContaSol.
:::

## Validación IA y cola de presentación

- **Validación IA**: antes de generar el TXT AEAT, Frihet revisa errores en los modelos (reglas + Gemini).
- **Cola de presentación**: revisa y aprueba las declaraciones generadas en lote antes de enviarlas — flujo auditado.
- **Auto-detección fiscal**: Frihet detecta por workspace los modelos aplicables (M303 mensual/trimestral según umbral REDEME, M115 desde gastos de alquiler, M130 vs M131, etc.).

## Permisos y requisitos

- El Panel de gestoría requiere **plan Premium/Enterprise** (la funcionalidad `gestoria` está gateada por plan).
- El acceso a los datos de un cliente exige ser **contable o propietario activo** de ese workspace; cualquier otra cuenta es rechazada silenciosamente.
- **Invitar miembros** a un workspace requiere permiso de gestión de equipo (rol Administrador); ver y operar el panel de gestoría no requiere ser Administrador.
- El asesor invitado como contable **no ocupa un asiento de pago** del plan del cliente.

## Caveats

- Los datos consolidados (aging cross-cliente, obligaciones) solo incluyen los workspaces donde eres contable o propietario activo.
- El flujo de factura desde email genera **borradores**: requieren revisión humana antes de contabilizar.
- No existe un formato de exportación llamado "ContaSol" como tal; el export **ContaPlus** (`xDiario.txt`) es el camino compatible con ContaSol.
- La herramienta de **aging por MCP** está disponible vía API/callable; su exposición en el servidor MCP público se habilita en la siguiente publicación.

## Preguntas frecuentes

### ¿Cómo empiezo a gestionar un cliente en Frihet?

Tu cliente te invita desde su workspace en **Equipo → Invitar miembros** con el rol **Contable**. Al aceptar el email de invitación, el cliente aparece en tu Panel de gestoría.

### ¿El acceso del asesor cuesta un asiento?

No. Un asesor o contable invitado a un workspace **no consume un asiento de pago** del plan del cliente.

### ¿Puedo presentar el Modelo 303 de varios clientes a la vez?

Sí. Usa **Acciones → Declaraciones en lote**, selecciona modelos y trimestre y descarga un ZIP con M303, M130, M111 y M115 en PDF o TXT AEAT.

### ¿A qué formatos contables puedo exportar?

A A3 (Innuva), ContaPlus, DATEV, Xero, QuickBooks y CSV genérico (y SAF-T). Si trabajas con **ContaSol**, usa el export **ContaPlus** (`xDiario.txt`), que es compatible.

### ¿Cómo recibo las facturas de mis clientes?

Tus clientes las suben a su portal en respuesta a una solicitud de documentos, o reenvían facturas de proveedor a `receipts@<slug>.frihet.io`, donde la IA las convierte en borradores.

### ¿Qué necesito para usar el panel?

Plan Premium/Enterprise y ser contable o propietario de los workspaces que gestionas. (Invitar nuevos miembros requiere además permiso de Administrador en ese workspace.)

## Quick start

1. Ve a **Equipo → Panel gestoría** (requiere rol Administrador + plan Premium/Enterprise).
2. Los clientes aparecen ordenados por riesgo: los críticos primero.
3. Usa **Acciones → Declaraciones en lote** para seleccionar modelos y trimestre, luego descarga el ZIP.

## Reference

- API: `GET /v1/gestoria/clients`, `POST /v1/gestoria/batch-models`, `POST /v1/gestoria/aging` — ver [API reference](/desarrolladores/api-rest)
- Settings: Equipo → Permisos → Gestoría

## Related

- [Invitar miembros](./invitar-miembros)
- [Espacios de trabajo](./espacios-trabajo)
- [Modelos fiscales](/cumplimiento/modelos-fiscales)

---

## Invitar miembros
> Path: /equipo/invitar-miembros

# Invitar miembros al equipo

Frihet permite invitar a otras personas a tu cuenta con diferentes niveles de acceso. Ideal para colaborar con socios, empleados o tu gestoria.

## Roles disponibles

| Rol | Lectura | Escritura | Eliminacion | Gestion equipo |
|-----|:-------:|:---------:|:-----------:|:--------------:|
| **Admin** | Todo | Todo | Todo | Si |
| **Editor** | Todo | Facturas, gastos, clientes, productos | No | No |
| **Contable** | Facturas, gastos, clientes, proveedores, productos | Facturas, gastos | No | No |
| **Visor** | Facturas, gastos | No | No | No |

## Como invitar

1. Ve a **Configuracion** > **Equipo**
2. Introduce el email del miembro y selecciona un rol
3. Pulsa **Enviar invitacion**
4. El invitado recibe un email con un enlace para aceptar

El enlace de invitacion es valido durante 7 dias. Si expira, puedes enviar una nueva invitacion.

## Aceptar una invitacion

Cuando recibes una invitacion:

1. Haz clic en el enlace del email
2. Si ya tienes cuenta en Frihet, inicia sesion
3. Si no, crea una cuenta con el mismo email de la invitacion
4. Seras redirigido al dashboard con acceso al espacio de trabajo

## Gestionar miembros

Desde **Configuracion** > **Equipo** puedes:

- Ver todos los miembros activos y sus roles
- Cambiar el rol de un miembro (solo el propietario)
- Eliminar un miembro del equipo

:::info Plan Premium
La funcionalidad de equipo esta disponible en el plan Premium.
:::

---

## Personas y RRHH
> Path: /equipo/personas

# Personas y RRHH

El modulo **Personas** (`/people`) centraliza la gestion de tu equipo: directorio de empleados, fichaje conforme al Estatuto de los Trabajadores, ausencias y visualizacion de quien esta presente en la oficina en cada momento.

## Pestanas del modulo

| Pestana | Ruta | Descripcion |
|---------|------|-------------|
| **Directorio** | `/people` | Lista y gestion de empleados |
| **Fichaje** | `/people` (widget) | Registro de entradas y salidas (Art. 35 ET) |
| **Ausencias** | `/people` (calendario) | Solicitudes y aprobacion de permisos |
| **Horas extra** *(en desarrollo)* | — | Seguimiento y compensacion de horas extra |
| **Rendimiento** *(en desarrollo)* | — | Evaluaciones y objetivos |
| **Engagement** *(en desarrollo)* | — | Encuestas y clima laboral |

---

## Directorio de empleados

El directorio muestra la lista de todos los empleados de la empresa con busqueda rapida, filtro por departamento y acceso al perfil individual.

### Campos del empleado

| Campo | Descripcion |
|-------|-------------|
| Nombre completo | Nombre y apellidos del empleado |
| Email | Correo corporativo o personal |
| Telefono | Opcional |
| Rol / Puesto | Titulo del cargo (ej: Diseniadora, Desarrollador) |
| Departamento | Agrupacion logica del equipo |
| Fecha de incorporacion | Alta en la empresa |
| Estado | Activo / Baja |

### Agregar un empleado

1. Ve a **Personas** > **Directorio**
2. Haz clic en **Nuevo empleado**
3. Rellena los datos del formulario
4. Haz clic en **Guardar**

El empleado aparece en el directorio y puede asociarse al sistema de fichaje desde ese momento.

### Editar un empleado

1. Haz clic sobre el nombre del empleado en la lista
2. Se abre la pagina de detalle (`/people/:id`)
3. Modifica los campos necesarios
4. Haz clic en **Guardar cambios**

### Pagina de detalle (`/people/:id`)

La vista de detalle del empleado concentra toda su informacion en un solo lugar:

- **Informacion personal** — Datos de contacto, rol y departamento
- **Historial de fichajes** — Registros de entrada y salida del empleado
- **Ausencias** — Permisos solicitados, aprobados y denegados
- **Horas extra** — Acumulado y desglose por periodo

---

## Fichaje (Art. 35 ET)

Frihet implementa el registro de jornada laboral conforme al **articulo 35 del Estatuto de los Trabajadores**, que obliga a las empresas a conservar los registros durante un minimo de cuatro anios y ponerlos a disposicion de los trabajadores, sus representantes y la Inspeccion de Trabajo.

### Como funciona el fichaje

El **ClockInWidget** esta visible en el modulo Personas para todos los empleados:

1. El empleado pulsa **Fichar entrada** al comenzar la jornada
2. El sistema registra la hora exacta con marca de tiempo UTC
3. Al terminar, pulsa **Fichar salida**
4. El registro queda almacenado con estado `completado`

Si un empleado olvida fichar, el administrador puede registrar la entrada o salida manualmente desde el perfil del empleado.

### Estados de un fichaje

| Estado | Descripcion |
|--------|-------------|
| **En curso** | Solo hay entrada registrada, aun no hay salida |
| **Completado** | Entrada y salida registradas |
| **Editado** | Un administrador ha corregido el registro |
| **Ausencia** | Dia justificado por permiso aprobado |

### Exportacion del registro de jornada

Desde el perfil del empleado o desde la seccion de informes puedes exportar el historial de fichajes a CSV para auditoria o entrega a Inspeccion de Trabajo.

:::info Obligacion legal
El registro diario de jornada es obligatorio para todas las empresas con trabajadores por cuenta ajena desde la reforma del Estatuto de los Trabajadores de 2019. Frihet conserva los registros de forma inmutable y auditada.
:::

---

## Ausencias

El calendario de ausencias permite a los empleados solicitar permisos y a los administradores aprobarlos o denegarlos.

### Tipos de ausencia

| Tipo | Descripcion |
|------|-------------|
| Vacaciones | Dias de disfrute del convenio o contrato |
| Baja por enfermedad | Incapacidad temporal |
| Permiso retribuido | Matrimonio, fallecimiento familiar, mudanza, etc. |
| Permiso no retribuido | Ausencia acordada sin retribucion |
| Teletrabajo | Dias de trabajo remoto (registro opcional) |

### Solicitar una ausencia (empleado)

1. Ve a **Personas** > **Ausencias**
2. Haz clic en **Nueva solicitud**
3. Selecciona el tipo de ausencia y el rango de fechas
4. Anade un comentario opcional
5. Haz clic en **Enviar solicitud**

El administrador recibe una notificacion para revisar la solicitud.

### Aprobar o denegar una solicitud (administrador)

1. En el **LeaveCalendar**, las solicitudes pendientes aparecen en amarillo
2. Haz clic sobre la solicitud
3. Selecciona **Aprobar** o **Denegar**
4. Opcionalmente, anade un comentario para el empleado

El empleado recibe la notificacion del resultado.

### Vista del calendario

El **LeaveCalendar** muestra todas las ausencias del equipo en formato mensual:

- **Verde** — Ausencias aprobadas
- **Amarillo** — Solicitudes pendientes
- **Rojo** — Solicitudes denegadas
- **Gris** — Festivos oficiales

Puedes filtrar por empleado o por departamento para ver la disponibilidad del equipo.

---

## Quien esta en la oficina (WhosIn)

La funcion **WhosIn** muestra en tiempo real quien ha fichado entrada y sigue en la oficina en este momento.

- Accesible desde el modulo Personas en la parte superior del Directorio
- Muestra el avatar, nombre y hora de entrada de cada empleado presente
- Los empleados que han fichado salida o estan de ausencia no aparecen

Util para coordinacion de equipos con trabajo hibrido o presencia variable.

---

## Horas extra

El seguimiento de horas extra registra automaticamente las horas trabajadas por encima de la jornada pactada.

- Frihet compara las horas fichadas con la jornada configurada para el empleado
- Las horas extra se acumulan por semana y mes
- Pueden compensarse con descanso o con retribucion adicional (segun politica de empresa)

El detalle esta disponible en la pagina de cada empleado (`/people/:id`).

---

## Permisos y roles

El acceso al modulo Personas esta controlado por el rol del usuario:

| Accion | Admin | Editor | Contable | Visor |
|--------|:-----:|:------:|:--------:|:-----:|
| Ver directorio | Si | Si | No | No |
| Crear / editar empleados | Si | No | No | No |
| Ver fichajes propios | Si | Si | Si | Si |
| Ver fichajes de otros | Si | No | No | No |
| Aprobar ausencias | Si | No | No | No |
| Exportar registros | Si | No | No | No |

:::info Plan Premium
El modulo Personas esta disponible en el plan Premium.
:::

---

**Siguiente paso:** [Invitar miembros al equipo](./invitar-miembros) o [Espacios de trabajo](./espacios-trabajo)

---

## Programa de partners
> Path: /equipo/programa-partners

# Programa de partners

El programa de partners de Frihet conecta a profesionales y empresas que recomiendan, implementan o construyen sobre Frihet ERP con su mercado natural de clientes. Hay cuatro tracks diferenciados según el rol y la relación comercial que el partner mantiene con sus clientes.

## Cómo funciona

La página pública del programa vive en [frihet.io/partners](https://www.frihet.io/es/partners) y describe las cuatro vías de partnership disponibles. **Gestorías y asesorías** que llevan la contabilidad y fiscalidad de varios negocios pueden onboardear a sus clientes en Frihet y gestionarlos desde un único panel multi-empresa con marca propia. **Developers** que construyen integraciones, automatizaciones o herramientas sobre la API y el SDK de Frihet entran al track técnico con acceso a soporte de ingeniería. **Agencies** que ofrecen servicios de migración, formación o consultoría sobre ERPs encuentran un track con materiales de venta, descuentos por volumen y certificación. **Consultants** independientes especializados en finanzas, fiscalidad o operaciones tienen un track de recomendación con seguimiento de leads.

Para entrar en el programa, rellena el formulario de la página pública con los datos básicos del negocio, el track de interés y una breve descripción de cómo trabajas. El equipo de Frihet revisa cada solicitud y se pone en contacto en los siguientes días hábiles para arrancar la conversación, validar el perfil y abrir el acceso a los recursos del track correspondiente.

Cada track tiene su propio set de incentivos y materiales: comisiones de recomendación, acceso anticipado a funcionalidades, soporte priorizado, formación, materiales co-brandeados y certificación oficial. Los detalles concretos se comparten durante el proceso de onboarding del partner.

## Configuración

No requiere configuración desde tu cuenta. Si ya eres usuario de Frihet y quieres además unirte al programa, rellena el mismo formulario desde la página pública. Para gestorías que ya operan en modo multi-cliente, existe el panel de gestoría dedicado descrito en [Gestoría](./gestoria) y [Gestoría con marca propia](./gestoria-whitelabel).

## Ver también

- [Página pública del programa](https://www.frihet.io/es/partners)
- [Gestoría](./gestoria)
- [Gestoría con marca propia](./gestoria-whitelabel)
- [Self-onboard de gestorías](./gestoria-self-onboard)

---

## RRHH y empleados
> Path: /equipo/rrhh-empleados

# RRHH y empleados

> Control horario legal, gestion de ausencias y directorio de equipo — todo integrado con el ERP.

## Overview

El modulo de RRHH de Frihet cubre las obligaciones laborales del Estatuto de los Trabajadores espanol: fichaje digital con control de jornada (Art. 34+35 ET), calculo automatico de horas extraordinarias, gestion de vacaciones y ausencias con calendario por pais, y directorio de empleados con perfil completo. El widget "quien esta" muestra presencia en tiempo real en el dashboard. Los 3 tools de IA del copiloto permiten consultar el equipo, el resumen de asistencia y el saldo de vacaciones por voz o chat.

## Quick start

1. Ve a Equipo → **Empleados** → **Nuevo empleado** para crear el primer perfil
2. El empleado descarga la PWA e inicia el fichaje desde su movil
3. Revisa el resumen de horas y ausencias en Equipo → **Asistencia**

## Reference

- API: `GET /v1/people/employees` — directorio; `POST /v1/people/clock-in` — fichaje
- MCP tool: `get_team_directory`, `get_attendance_summary`, `get_leave_balance` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Equipo → RRHH → Configuracion

---

## Facturas rectificativas
> Path: /facturacion/abonos

# Facturas rectificativas

Las facturas rectificativas (también llamadas notas de crédito o abonos) se usan para corregir errores, hacer devoluciones o ajustes en facturas ya emitidas. Son documentos oficiales que registran la anulación parcial o total de una factura anterior.

## ¿Cuándo usar una rectificativa?

### Devolución de productos

Cliente devuelve 2 de 5 unidades compradas:
- Creas una factura rectificativa con cantidad negativa
- Disminuyes el ingreso registrado

### Error en factura enviada

Facturaste a cliente A en lugar de B:
- Creas una rectificativa para revertir la original
- Creas una nueva factura para el cliente correcto

### Descuento retroactivo

Acordaste un 10% de descuento con el cliente:
- Creas una rectificativa por el 10%
- Se registra correctamente en contabilidad

### Cancelación de servicio

Cliente cancela servicio mensual en mitad de mes:
- Creas rectificativa por los días no usados
- Reembolsas la diferencia

### Cambio de margen o error de cálculo

Cometiste error en precio o impuestos:
- Creas rectificativa para corregir
- Emites nueva factura con datos correctos

## Crear una factura rectificativa

### Paso 1: Abre la factura original

1. Ve a **Facturación** → **Facturas**
2. Encuentra la factura que necesitas rectificar
3. Haz clic en **Crear rectificativa** (o **Más opciones** → **Crear rectificativa**)

### Paso 2: Frihet pre-rellena automáticamente

Se crea una nueva factura con:

- ✓ Número nuevo (serie de rectificativas: R-2026-001)
- ✓ Mismo cliente
- ✓ Líneas idénticas **pero con cantidades/montos negativos**
- ✓ Fecha actual
- ✓ Referencia a factura original (visible en PDF)

**Ejemplo:**
```
Factura original F-2026-0042:
  - Servicio web: 1 × €1,000 = €1,000

Rectificativa generada:
  - Servicio web: -1 × €1,000 = -€1,000
  - Total rectificativa: -€1,000
```

### Paso 3: Ajusta líneas si es necesario

Si necesitas rectificar sólo parcialmente:

1. Edita las cantidades (deja en negativo)
2. Elimina líneas que no necesitan ajuste
3. Agrega nuevas líneas si aplica (ej: nuevo servicio después de devolución)

**Ejemplo: Devolución parcial**
```
Factura original:
  - Widget A: 5 × €100 = €500
  - Widget B: 3 × €200 = €600
  - Total: €1,100

Rectificativa (cliente devuelve 2 Widget A):
  - Widget A: -2 × €100 = -€200
  - Total rectificativa: -€200
```

### Paso 4: Revisa total negativo

En una rectificativa:
- El **Subtotal será negativo**
- Los **impuestos serán negativos**
- El **Total a pagar será negativo** (dinero a devolver al cliente)

Esto es correcto. Frihet lo registra como abono.

### Paso 5: Envía la rectificativa

1. Haz clic en **Guardar como borrador** o **Enviar por email**
2. Se registra con hash VeriFactu como rectificativa (documento oficial)
3. Cliente recibe el PDF mostrando el reembolso

## Tipos de rectificativa

### Clasificación legal (tipos R1-R5)

Cada factura rectificativa tiene un tipo legal según la LIVA (Ley del IVA):

| Tipo | Artículo | Cuándo usar |
|------|----------|-------------|
| **R1** | Art. 80.1-2, 80.6 LIVA | Errores, descuentos retroactivos, devoluciones. Es el tipo más habitual. |
| **R2** | Art. 80.3 LIVA | Impago o crédito incobrable |
| **R3** | Art. 80.4 LIVA | Concurso de acreedores (insolvencia judicial) |
| **R4** | Resto de supuestos | Otros casos no cubiertos por R1-R3 |
| **R5** | Simplificada | Rectificativa de una factura simplificada (< 400 EUR sin NIF) |

Al crear una rectificativa, Frihet asigna R1 por defecto. Puedes cambiar el tipo en el formulario si corresponde otro supuesto.

### Método de rectificación

Frihet permite dos métodos:

| Método | Código | Descripción |
|--------|--------|-------------|
| **Por sustitución** | S | Anulas la factura original y la reemplazas. Las líneas se pre-rellenan con importes negativos. |
| **Por diferencias** | I | Emites solo la diferencia entre la factura original y la corrección. |

Selecciona el método al crear la rectificativa. El método por sustitución es el más habitual para devoluciones y anulaciones completas.

### Vinculación con la factura original

Cada rectificativa queda vinculada a la factura original de forma bidireccional:

- La rectificativa muestra una referencia a la factura original (número y fecha)
- La factura original muestra un indicador de que ha sido rectificada
- En la lista de facturas, las rectificativas se identifican con una etiqueta visual

### Motivo de rectificación

Al crear una rectificativa es obligatorio indicar el motivo (campo de texto). Este motivo aparece en el PDF y en el [libro registro](/cumplimiento/libro-registro).

### Rectificativa por diferencia (por error)

Se usa cuando cometiste error en factura original:

1. Emites rectificativa por la diferencia (método I)
2. El cliente solo ve una rectificativa

**Ejemplo:**
```
Factura original: €1,000 (error de cálculo)
Debía ser: €950
Rectificativa (I): -€50 (por error de cálculo)
```

### Rectificativa completa (anulación)

Se usa para anular completamente una factura:

1. Creas rectificativa con todas las líneas negativas (método S)
2. El efecto neto es €0
3. Luego creas nueva factura correcta

**Ejemplo:**
```
Factura original F-2026-0050: €1,000 (cliente equivocado)
Rectificativa R-2026-001 (S): -€1,000
Factura nueva F-2026-0051: €1,000 (cliente correcto)
```

### Rectificativa por devolución

Se usa cuando cliente devuelve productos/servicios:

1. Creas rectificativa por lo devuelto
2. El cliente recibe reembolso o crédito

**Ejemplo:**
```
Factura original F-2026-0045:
  - 10 camisetas × €25 = €250

Cliente devuelve 3 camisetas:
Rectificativa R-2026-002 (S):
  - Camisetas devueltas: -3 × €25 = -€75
```

## Registro fiscal

Cuando creas una rectificativa, Frihet automáticamente:

1. **La vincula a la original** en ambos sentidos
2. **Registra el tipo legal** (R1-R5) y el método (S/I)
3. **Calcula el hash** de la cadena VeriFactu (ver [VeriFactu](/cumplimiento/verifactu))
4. **Ajusta el IVA** (impuestos negativos en el registro)
5. **Aparece en el libro registro** con toda la información de rectificación

**Importante:** No marques la factura original como "Cancelada" si creas rectificativa. La rectificativa es el documento oficial de corrección.

## Estados de una rectificativa

Exactamente igual que una factura normal:

- **Borrador** — Sin enviar, editable
- **Enviada** — Enviada a cliente, registrada en cadena VeriFactu
- **Cobrada** — Si incluye descuento y el cliente lo acepta
- **Vencida** — Si es por reembolso y pasan días
- **Anulada** — Si decidiste no usarla

## Diferencia: Rectificativa vs. Anular factura

| Acción | Cuándo | Resultado |
|--------|--------|-----------|
| **Crear rectificativa** | Necesitas registro oficial de corrección | Dos documentos: original + rectificativa. Ambos en cadena VeriFactu |
| **Marcar como Anulada** | Factura nunca debería existir (error administrativo) | Un documento anulado. No aparece en reportes |

**Consejo:** Usa rectificativa cuando ya enviaste la factura al cliente. Usa "Anular" si fue un error antes de enviar.

## Reembolsos y créditos

Cuando creas una rectificativa con total negativo, Frihet ofrece tres opciones:

### Opción 1: Reembolso en cuenta bancaria

1. El cliente proporciona IBAN
2. Frihet (integración con Stripe) procesa automáticamente el reembolso
3. El dinero llega en 3-5 días bancarios
4. Facturas marcadas como Cobradas automáticamente

### Opción 2: Crédito en cuenta

1. No se reembolsa el dinero
2. Se crea un "saldo a favor" en la cuenta del cliente
3. En próxima factura, Frihet resta el crédito automáticamente
4. Cliente recibe factura por diferencia

**Ejemplo:**
```
Rectificativa: -€100 (crédito)
Factura siguiente: €500
Factura neta: €400 (Frihet resta el crédito)
```

### Opción 3: Esperar instrucciones del cliente

1. Enviás la rectificativa
2. Frihet queda en estado "Pendiente"
3. Cliente contacta para decidir reembolso o crédito

## Búsqueda de rectificativas

Ve a **Facturación** → **Rectificativas** para:

- Ver todas las rectificativas por separado (si lo prefieres)
- O ver dentro de **Facturas** con filtro "Incluir rectificativas"

Puedes filtrar por:

- Estado (Enviada, Cobrada, etc.)
- Cliente
- Rango de fechas
- Factura original a la que rectifican

## Reportes

Las rectificativas se muestran como:

- **Ingresos negativos** en el período que se generaron
- **Ajustes a ingresos** en reportes fiscales
- **Deducciones de IVA** (impuestos negativos)

Si tienes muchas rectificativas, analiza por qué:

- ¿Errores frecuentes en facturación?
- ¿Clientes que devuelven mucho?
- ¿ Errores de precificación?

## Ejemplo paso a paso

### Escenario: Devolución de servicio

**Factura original (15 de febrero):**
```
F-2026-0099
Cliente: Acme Corp
  - Consultoría (20 horas × €100): €2,000
  - IVA 21%: €420
Total: €2,420
```

Cliente usa 15 horas y cancela contrato:

**Pasos:**

1. Abre la factura F-2026-0099
2. Haz clic en **Crear rectificativa**
3. Frihet crea:
```
R-2026-003
Cliente: Acme Corp
  - Consultoría (devolución): -5 × €100 = -€500
  - IVA 21%: -€105
Total: -€605
```

4. Envía por email al cliente
5. Cliente elige: "Reembolso"
6. Frihet procesa el reembolso automáticamente

**Resultado en reportes:**
- Ingresos por consultoría: €2,000 - €500 = €1,500
- IVA ingresado: €420 - €105 = €315
- Reembolsos procesados: €605

## Rectificativas recurrentes

Si tienes **facturas recurrentes** y necesitas rectificar:

1. La rectificativa afecta **solo esa emisión**, no la recurrencia
2. La próxima emisión será normal (sin reducción)
3. Útil para descuentos puntuales o correcciones mensuales

---

**Anterior:** [Presupuestos](./presupuestos) | **Siguiente:** [Series y numeración](./series-numeracion)

---

## Acciones masivas
> Path: /facturacion/acciones-masivas

# Acciones masivas en facturas

> Selecciona varias facturas y ejecuta una accion sobre todas en un clic.

## Overview

Las acciones masivas permiten operar sobre grupos de facturas sin tener que abrir cada una individualmente. Desde la lista de facturas puedes seleccionar un rango o la pagina completa y ejecutar: marcar como pagadas, enviar por email, recordar pago, exportar a CSV o eliminar borradores. Util para cierres de mes y migraciones de datos.

## Quick start

1. En Facturacion, activa las casillas de las facturas que quieres modificar
2. Aparece la barra de acciones masivas en la parte inferior
3. Elige la accion: **Marcar pagadas** / **Enviar** / **Recordar** / **Exportar CSV** / **Eliminar**

## Reference

- API: `POST /v1/invoices/bulk` — acciones masivas via API (body: `{ids: [...], action: "mark_paid"}`)
- MCP tool: `bulk_invoice_action` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: no requiere configuracion previa

---

## Cobro multifactura
> Path: /facturacion/cobro-multifactura

# Cobro multifactura

> Un cliente te transfiere un importe global: Frihet lo distribuye automaticamente entre sus facturas pendientes.

## Overview

El cobro multifactura permite registrar un unico pago que cubre varias facturas de un mismo cliente. Frihet aplica el importe cronologicamente (las mas antiguas primero) y genera el audit trail correspondiente por cada factura afectada. El estado de cada factura se actualiza en tiempo real. Especialmente util cuando los clientes pagan facturas acumuladas al final del mes.

## Quick start

1. Desde el detalle del cliente → **Registrar pago**
2. Selecciona las facturas pendientes que cubre el pago
3. Introduce el importe total → **Confirmar** — Frihet distribuye automaticamente

## Reference

- API: `POST /v1/payments/multi` — body `{clientId, amount, invoiceIds: [...]}`
- MCP tool: `record_multi_payment` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: no requiere configuracion previa

---

## Cobros avanzados — Recargos, Remesas y Pagos múltiples
> Path: /facturacion/cobros-avanzados

<!-- AUTO-STUB 2026-05-05 -->

# Cobros avanzados — Recargos, Remesas y Pagos múltiples

> Gestiona cobros complejos: recargos por demora con cálculo automático, remesas de cobro (dunning) con reintentos automáticos vía Stripe, y aplicación de un pago único a varias facturas simultáneamente.

## Overview

Frihet ofrece tres mecanismos avanzados de cobro para reducir la morosidad y simplificar la gestión de pagos:

**Recargos por demora (late fees):** Calcula automáticamente el importe a reclamar según el método configurado (porcentaje, importe fijo o tipo legal), periodo de gracia, interés compuesto y tope máximo. Se añade al importe de la factura con un clic desde la vista de factura.

**Remesas automáticas (dunning):** Si el cliente paga con Stripe, Frihet reintenta el cobro automáticamente siguiendo un calendario de 4 pasos (3/5/7/14 días). Después de 3 fallos consecutivos bloquea el template; a los 30 días cancela el plan.

**Pagos múltiples:** Registra un único ingreso bancario y distribúyelo entre varias facturas pendientes del mismo cliente con asignación automática y alertas de exceso.

## Quick start

1. **Recargo por demora**: Abre la factura vencida → menú Acciones → **Añadir recargo por demora** → revisa el cálculo → confirma.
2. **Dunning**: Activa Stripe Connect y el sistema se encarga del ciclo automáticamente cuando un cobro falla.
3. **Pago múltiple**: Ve a **Cobros → Nuevo pago** → selecciona el cliente → marca las facturas a saldar → distribuye el importe → confirma.

## Reference

- API: `POST /v1/invoices/:id/late-fee`, `POST /v1/payments/multi` — ver [API reference](/desarrolladores/api-rest)
- Settings: Configuración → Pagos → Recargos por demora

## Related

- [Cobros y pagos](/facturacion/cobros-pagos)
- [Stripe Connect](/integraciones/stripe-connect)
- [Pagos parciales](/facturacion/pagos-parciales)

---

## Cobros y pagos
> Path: /facturacion/cobros-pagos

# Cobros y pagos

Este módulo te permite registrar y hacer seguimiento de los pagos que reciben tus clientes. Desde marcar manualmente como cobrado hasta recibir pagos online automáticamente.

## Marcar factura como cobrada

### Manualmente

Cuando el cliente te paga por fuera (transferencia, efectivo, cheque):

1. Abre la **factura** en el estado **Enviada**
2. Haz clic en **Marcar como cobrada**
3. Se abre un diálogo donde puedes especificar:
   - **Fecha de cobro** — Cuándo recibiste el dinero
   - **Método de pago** — Transferencia, Efectivo, Cheque, Otro
   - **Referencia** — Número de transacción (opcional)
   - **Notas privadas** — Para tu registro (no visible al cliente)

4. Haz clic en **Guardar**

La factura pasa a estado **Cobrada** y aparece en reportes de ingresos.

### En lote

Si varias facturas fueron pagadas juntas:

1. Ve a **Facturación** → **Facturas**
2. Selecciona las facturas (checkboxes)
3. Haz clic en **Acciones** → **Marcar como cobradas**
4. Se abre diálogo para confirmar
5. Todas cambian a **Cobrada** al mismo tiempo

**Tip:** Usa esta función después de reconciliar con tu banco.

## Pagos parciales

Si el cliente paga sólo parte de la factura:

1. Abre la factura
2. Haz clic en **Registrar pago parcial**
3. Especifica:
   - **Monto pagado** — Lo que recibiste (ej: €500 de €1,000)
   - **Fecha** — Cuándo
   - **Método** — Transferencia, etc.

4. Haz clic en **Guardar**

**Resultado:**
```
Factura: F-2026-0050
Total: €1,000
Pagado: €500
Pendiente: €500

Estado: Parcialmente cobrada
```

Frihet mantiene registro de cada pago parcial. Si el cliente hace varios pagos, puedes registrar cada uno.

### Indicador visual

En la lista de facturas, las facturas con pagos parciales muestran:

- Badge **ámbar** con estado "Pago parcial"
- Debajo del badge: monto pagado y total (ej: "500,00 EUR de 1.000,00 EUR")
- El estado cambia automáticamente a **Cobrada** cuando el monto pagado alcanza el total

## Métodos de pago

Frihet soporta varios métodos. Al marcar como cobrada, selecciona:

| Método | Descripción |
|--------|-------------|
| **Transferencia** | Bancaria nacional o internacional |
| **Efectivo** | Dinero en mano |
| **Cheque** | Recibido pero no cobrado aún |
| **Tarjeta** | Pago con tarjeta de crédito/débito |
| **Domiciliación** | Adeudo directo en cuenta cliente |
| **PayPal** | Pago vía PayPal |
| **Stripe** | Pago vía Stripe |
| **Otro** | Métodos adicionales |

## Términos de pago

Los términos definen cuánto tiempo tiene el cliente para pagar.

### Configurar términos en factura

1. Al crear factura, ve a **Opciones avanzadas**
2. En **Términos de pago**, selecciona:
   - **Inmediato** — Pago en el acto
   - **A 7 días** — Plazo de una semana
   - **A 14 días** — Dos semanas
   - **A 30 días** — Un mes (estándar)
   - **A 60 días** — Dos meses
   - **Personalizado** — Define tus propios días

3. Frihet calcula automáticamente:
   - **Fecha de emisión:** Hoy
   - **Fecha de vencimiento:** Fecha emisión + plazo

**Ejemplo:**
```
Factura emitida: 10 de febrero 2026
Términos: A 30 días
Vencimiento: 12 de marzo 2026
```

### Cambiar términos por cliente

Si todos tus clientes pagan a 60 días:

1. Ve a **Clientes** → Selecciona cliente
2. En **Configuración**, marca **Términos de pago por defecto**
3. Selecciona 60 días
4. Todas las futuras facturas a este cliente usarán 60 días

Puedes override en cada factura si es necesario.

## Pagos online (Stripe Connect)

Frihet integra **Stripe Connect** para recibir pagos en línea automáticamente.

### Activar Stripe Connect

1. Ve a **Configuración** → **Integraciones** → **Stripe**
2. Haz clic en **Conectar Stripe**
3. Se abre ventana de autenticación de Stripe
4. Autoriza a Frihet
5. Vuelves a Frihet (Stripe está conectado)

### Generar enlace de pago

Una vez Stripe está conectado:

1. Abre una **factura** en estado Enviada
2. Haz clic en **Generar enlace de pago**
3. Se crea un enlace único: `frihet.io/pay/abc123def`
4. Copia y comparte con cliente (email, SMS, etc.)

**Email automático:**

Si envías la factura por email desde Frihet, el enlace se incluye automáticamente:

```
Hola {CLIENTE},

Adjunto tu factura {NUMERO_FACTURA} por {TOTAL}.

[BOTÓN: Pagar ahora]

Plazo de pago: {FECHA_VENCIMIENTO}
```

### Flujo de pago

1. Cliente hace clic en enlace
2. Ve resumen de factura
3. Introduce datos de tarjeta (seguro, criptografía Stripe)
4. Confirma pago
5. Stripe procesa transacción
6. Frihet **automáticamente**:
   - Marca factura como **Cobrada**
   - Registra fecha y método de pago
   - Notifica al cliente: "Tu pago fue recibido"
   - Notifica a ti: "Factura F-2026-0123 pagada"
   - Transfiere dinero a tu cuenta bancaria

### Costos de Stripe

Stripe cobra comisión por cada pago:

- **Tarjetas**: 1.4% + €0.35 por transacción
- **Transferencias**: 0.8% + €0.35 por transacción

Frihet muestra el costo en el desglose de transacción.

**Ejemplo:**
```
Factura: €1,000
Comisión Stripe (1.4% + €0.35): €14.35
Monto neto a tu cuenta: €985.65
```

### Estados de pago en Stripe

- **Pendiente** — Enlace generado, cliente aún no pagó
- **Procesando** — Stripe está procesando
- **Completado** — Pago recibido, dinero en tu cuenta
- **Fallido** — Rechazado (fondos insuficientes, etc.)
- **Reembolsado** — Cliente pidió devolución

Frihet sincroniza todos estos estados automáticamente.

## Domiciliación bancaria (adeudo directo)

Si acuerdas con clientes pago por adeudo directo (SEPA):

1. Solicita al cliente su IBAN
2. En **Configuración** → **Métodos de pago**, activa **Domiciliación SEPA**
3. Sube firma SEPA del cliente (opcional)
4. Al crear factura, selecciona **Método: Domiciliación**
5. Frihet inicia cobro automáticamente en fecha de vencimiento

**Ventajas:**
- Automático (sin necesidad de cliente recordar)
- Costo muy bajo (€0.35 por transacción)
- Ideal para suscripciones/recurrentes

**Desventajas:**
- Cliente puede rechazarlo
- Frihet debe estar integrado con tu banco

## Recordatorios de pago

### Automáticos por vencer

1. Ve a **Configuración** → **Notificaciones**
2. En **Recordatorios de pago**, selecciona:
   - Notificar N días antes del vencimiento
   - Notificar cada día después del vencimiento

3. Frihet envía automáticamente al cliente un email:

**Ejemplo de email (3 días antes):**
```
Hola {CLIENTE},

Tu factura F-2026-0050 vence en 3 días ({FECHA_VENCIMIENTO}).

Monto: {TOTAL}
Número: {NUMERO_FACTURA}

[Enlace de pago si Stripe está activo]

Gracias.
```

### Enviar recordatorio manual

Puedes enviar un recordatorio de pago directamente desde Frihet, sin necesidad de abrir tu cliente de correo:

1. Localiza la factura (estado Enviada, Vencida o Pago parcial)
2. Abre el menú de acciones (tres puntos)
3. Haz clic en **Enviar recordatorio**
4. Frihet envía un email al cliente con:
   - Asunto: "Recordatorio de pago - Factura [NUMERO]"
   - Datos de la factura, monto pendiente, fecha de vencimiento
   - Enlace de pago (si Stripe Connect está activo)

El envío se realiza a través de Resend (el mismo motor de email nativo de Frihet), sin pasar por tu cliente de correo.

También puedes enviarlo desde el asistente IA: "Envía recordatorio de la factura F-2026-050".

## Gestionar atrasos

Las facturas que vencen sin ser pagadas se marcan automáticamente como **Vencidas**.

### Ver facturas vencidas

1. Ve a **Facturación** → **Facturas**
2. Filtra por estado **Vencida**
3. Ves todas las facturas con pago retrasado

### Análisis de atrasos

Ve a **Reportes** → **Atrasos** para:

| Métrica | Descripción |
|---------|-------------|
| **Total vencido** | Dinero que debería haber entrado |
| **Facturas vencidas** | Número de facturas sin pagar |
| **Promedio de atraso** | Cuántos días de retraso promedio |
| **Cliente con mayor deuda** | Quién debe más |
| **Proyección de cobro** | Cuándo esperas cobrar |

**Ejemplo:**
```
Total vencido: €3,450
Facturas vencidas: 12
Promedio atraso: 23 días
Mayor deudor: Acme Corp (€1,200, 45 días)
```

### Acciones por atraso

1. **Enviar recordatorio** — Email automático
2. **Llamar cliente** — Contacto directo
3. **Marcar como cobrada** (si finalmente pagó)
4. **Crear factura rectificativa** (si va a cancelar)
5. **Escalar a gestoría** — Si el atraso es muy largo

## Reembolsos

Cuando un cliente solicita devolución de dinero:

### Opción 1: Crear factura rectificativa

1. Abre factura original
2. Haz clic en **Crear rectificativa**
3. Frihet crea nota de crédito por el monto
4. Especifica en rectificativa: "Reembolso por `{RAZÓN}`"

### Opción 2: Reembolso con Stripe

Si el pago fue con Stripe:

1. Abre factura (estado Cobrada)
2. Haz clic en **Procesar reembolso**
3. Selecciona monto (total o parcial)
4. Haz clic en **Confirmar reembolso**
5. Stripe devuelve dinero a tarjeta cliente (3-5 días)

**Automáticamente:**
- Se crea factura rectificativa
- Se registra reembolso en Stripe
- Cliente recibe notificación

## Reconciliación bancaria

Periódicamente (semanal o mensual), reconcilia Frihet con tu banco:

1. Ve a **Reportes** → **Cobros**
2. Descarga resumen de pagos en período
3. Compara con extracto bancario
4. Verifica que todos coincidan

**Buscar discrepancias:**
- Facturas marcadas como cobradas pero sin depósito bancario
- Depósitos sin factura asociada
- Diferencia de fechas (Frihet registra fecha de cobro, banco registra fecha de valor)

Si hay discrepancias:
1. Revisa si fue pago parcial (registraste monto incorrecto)
2. Verifica comisiones Stripe (reduce monto neto)
3. Busca devoluciones o rechazos

## Exportar datos de cobros

Para contabilidad o análisis:

1. Ve a **Reportes** → **Cobros**
2. Aplica filtros (período, cliente, etc.)
3. Haz clic en **Exportar a CSV**
4. Descarga archivo con:
   - Número de factura
   - Cliente
   - Monto
   - Fecha de pago
   - Método de pago
   - Estado

Importable en Excel, contabilidad, o herramientas de análisis.

## Integración contable

Si tienes integración contable (Twinfield, Xero, etc.):

Frihet reporta automáticamente:
- ✓ Ingresos realizados (facturas cobradas)
- ✓ Ingresos devengados (facturas enviadas)
- ✓ Pagos recibidos (método, fecha)
- ✓ Comisiones (Stripe, etc.)

No necesitas doble entrada manual.

## Casos de uso comunes

### Cliente recurrente a 60 días

1. Configura cliente: Términos de pago = 60 días
2. Cada factura automáticamente vence en 60 días
3. Establece recordatorio: 55 días (una semana antes)
4. Cliente paga como siempre

### Pago inmediato con Stripe

1. Creas factura
2. Generas enlace de pago de inmediato
3. Cliente paga online en el acto
4. Factura se marca cobrada automáticamente

### Mezcla de métodos

Mismo cliente, diferentes facturas:
- Factura A: A 30 días (transferencia)
- Factura B: Pago inmediato (Stripe)
- Factura C: Domiciliación SEPA (automática)

Frihet maneja todos sin problema.

---

**Anterior:** [Impuestos](./impuestos) | **Volver a:** [Facturación](./facturas)

---

## Cupones y descuentos
> Path: /facturacion/cupones

# Cupones y descuentos

Los cupones permiten ofrecer descuentos a tus clientes de forma controlada. Puedes crear codigos de descuento fijo o porcentual con limites de uso y fecha de expiracion.

## Crear un cupon

1. Ve a **Ajustes > Cupones**
2. Pulsa **Crear cupon**
3. Configura los parametros:

| Campo | Descripcion |
|-------|-------------|
| Nombre | Nombre interno del cupon (ej. "Descuento bienvenida") |
| Codigo | Codigo que el cliente introduce (ej. WELCOME10) |
| Tipo | **Porcentaje** (ej. 10%) o **Importe fijo** (ej. 50 EUR) |
| Valor | Porcentaje o importe del descuento |
| Limite de uso | Numero maximo de veces que se puede usar (opcional) |
| Limite por cliente | Usos maximos por cliente individual (opcional) |
| Fecha de expiracion | Fecha hasta la que el cupon es valido (opcional) |

## Aplicacion del descuento

El cupon se aplica **antes de impuestos** (pre-tax):

```
Subtotal:        1.000,00 EUR
Cupon WELCOME10:  -100,00 EUR (10%)
Base imponible:    900,00 EUR
IVA 21%:           189,00 EUR
Total:           1.089,00 EUR
```

## Gestion de cupones

Desde **Ajustes > Cupones** puedes:

- Ver todos los cupones activos y expirados
- Consultar el numero de usos de cada cupon
- Desactivar un cupon sin eliminarlo
- Editar los limites y fecha de expiracion

## Limites

| Concepto | Valor |
|----------|-------|
| Cupones activos | Sin limite |
| Longitud del codigo | 3-50 caracteres |
| Descuento maximo (porcentaje) | 100% |
| Descuento maximo (fijo) | Sin limite |

---

## Enlace de pago
> Path: /facturacion/enlace-pago

# Enlace de pago

> Stripe Connect integrado: el cliente hace clic, paga, y la factura se marca cobrada automaticamente.

## Overview

Los enlaces de pago permiten que tus clientes paguen facturas online sin necesidad de llamadas ni transferencias manuales. Frihet genera un enlace unico por factura con checkout Stripe alojado — tarjeta, Bizum, SEPA — y publica un codigo QR en el PDF para pagos instantaneos. El estado de la factura se actualiza en tiempo real al recibir el pago.

## Quick start

1. Abre cualquier factura y pulsa **Compartir** → **Enlace de pago**
2. Copia el enlace o incluye el QR en el PDF ya generado
3. El cliente paga via Stripe; Frihet marca la factura como `paid` automaticamente

## QR de pago SEPA (EPC)

Ademas del enlace de checkout Stripe, Frihet incluye un **codigo QR SEPA** conforme al estandar **EPC069-12 v2.0** en el PDF de las facturas en EUR. Es un QR de transferencia bancaria _scan-to-pay_: el cliente lo escanea con la app de su banco y los datos de la transferencia (IBAN, beneficiario, importe y concepto) se rellenan automaticamente.

- Disponible para los **33 paises de la zona SEPA** y facturas denominadas en **EUR**
- No requiere Stripe: funciona con cualquier app de banca movil compatible con QR EPC
- Se genera junto al PDF de la factura, sin pasos adicionales

A diferencia del enlace de pago Stripe (tarjeta, Bizum, SEPA via checkout alojado), el QR EPC inicia una **transferencia bancaria directa** desde la app del cliente. Ambos pueden convivir en la misma factura.

## Reference

- API: `GET /v1/invoices/:id/payment-link` — devuelve URL de checkout Stripe
- MCP tool: `get_invoice_payment_link` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Configuracion → Integraciones → Stripe Connect

---

## Factura electronica
> Path: /facturacion/factura-electronica

# Factura electronica

Frihet genera facturas electronicas estructuradas conformes a la norma europea EN16931. A diferencia del PDF, una e-factura es un archivo XML que los sistemas contables del receptor pueden procesar de forma automatica, sin reescribir datos a mano.

Disponible en planes **Premium+**.

:::info Generacion vs. envio
Frihet **genera y valida** el XML estructurado de cada e-factura de forma automatica. La **transmision** a las redes oficiales (FACe, SDI, KSeF, Chorus Pro) depende del pais y, hoy, la mayoria de canales operan en modo de descarga manual o entorno de pruebas (sandbox). El unico flujo que se registra de forma automatica y real en produccion es el encadenamiento de hash **VeriFactu** (Espana). Consulta el [estado por canal](#estado-por-canal) mas abajo antes de asumir envio automatico.
:::

---

## Estado por canal {#estado-por-canal}

Lo que ocurre **hoy** con cada canal cuando guardas o emites una factura. La generacion del XML es automatica en todos; el envio no.

| Canal | Pais | Generacion XML | Transmision (estado real) |
|-------|------|----------------|---------------------------|
| **VeriFactu** | Espana | Automatica | **Cadena de hash en produccion, automatica.** Envio a AEAT solo si activas `autoSubmit` + certificado de produccion + plan Pro o superior (ver [VeriFactu](#verifactu-espana)) |
| **FACe** (B2G) | Espana | Automatica | XML listo para **subida manual**. El envio automatico a FACe esta en modo *mock* por defecto; solo se activa en entornos de desarrollo o con credenciales reales configuradas |
| **XRechnung** | Alemania | Automatica | Descarga del XML para entrega al portal del organismo |
| **Fattura PA / SDI** | Italia | Automatica | **Solo descarga.** La transmision al SDI requiere alta como intermediario acreditado, todavia no provisionada (ver abajo) |
| **Factur-X / Chorus Pro** | Francia | Automatica | **Solo descarga / sandbox.** El conector Chorus Pro opera en entorno de pruebas hasta configurar credenciales de produccion (ver [Factur-X](#factur-x-pdf-con-xml-embebido)) |
| **KSeF** | Polonia | Automatica | **Solo entorno de pruebas (sandbox).** Sin emision a produccion por defecto |

> No asumas envio automatico a una red oficial salvo que la tabla lo indique explicitamente. Cuando un canal esta en *mock* o *sandbox*, Frihet produce el XML correcto pero no realiza la entrega real al organismo.

---

## Formatos soportados

| Formato | Estandar | Uso principal |
|---------|----------|---------------|
| **UBL 2.1** | OASIS UBL | Internacional, PEPPOL, Espana |
| **CII** | UN/CEFACT Cross Industry Invoice | Alemania, Francia, Europa central |
| **Factur-X** | PDF/A-3 con XML embebido | Francia, Alemania (ZUGFeRD) |

Los tres formatos cumplen EN16931 y son interoperables dentro del ecosistema europeo.

### Adaptaciones por pais

Frihet genera automaticamente la variante correcta segun el pais del destinatario o la configuracion de tu empresa:

| Pais | Formato / Estandar |
|------|--------------------|
| Espana | UBL 2.1 + VeriFactu |
| Alemania | XRechnung (UBL o CII) |
| Italia | Fattura PA (XML propio) |
| Francia | Factur-X (PDF/A-3 + CII) |
| Polonia | KSeF (XML, ver [estado por canal](#estado-por-canal)) |
| Red PEPPOL | UBL 2.1 via PEPPOL BIS |
| Otros paises EU | EN16931 UBL o CII segun preferencia |

---

## Configuracion

1. Ve a **Ajustes** → **Facturacion** → **E-factura**
2. Selecciona el formato por defecto para tu empresa
3. Si usas PEPPOL, introduce tu **PEPPOL ID** (ej: `0188:ES12345678A`)
4. Para Fattura PA (Italia), anade el **Codice SDI** del destinatario
5. Guarda los cambios

Puedes sobrescribir el formato en cada factura individual desde el panel de opciones avanzadas.

---

## Generar una e-factura

### Automaticamente al guardar o enviar

Frihet genera el XML estructurado de forma automatica cada vez que guardas o envias una factura. No hay ningun paso adicional para producir el archivo: queda adjunto al registro de la factura y puede descargarse en cualquier momento. La **transmision** a las redes oficiales sigue las reglas del [estado por canal](#estado-por-canal) — generar el XML no equivale a enviarlo al organismo.

### Descargar el XML

1. Abre la factura en estado **Enviada** o **Cobrada**
2. Haz clic en **Mas opciones** → **Descargar XML**
3. Se descarga el archivo en el formato configurado (ej: `F-2026-0001_UBL.xml`)

### Via API

```
GET /v1/invoices/:id/xml
Authorization: Bearer {API_KEY}
Accept: application/xml
```

El endpoint devuelve el XML segun el formato configurado en la factura o en la cuenta. Puedes forzar un formato concreto con el parametro `?format=ubl|cii|facturx`.

Consulta la referencia completa en [API REST](../desarrolladores/api-rest).

---

## Factur-X: PDF con XML embebido {#factur-x-pdf-con-xml-embebido}

Factur-X combina un PDF legible por humanos con un XML EN16931 embebido en el propio archivo (formato PDF/A-3). El receptor puede abrir el PDF como cualquier otro o procesarlo automaticamente si su software lo soporta.

Cuando el formato configurado es Factur-X:

- El PDF de la factura se genera en PDF/A-3
- El XML CII se incrusta como adjunto interno (`factur-x.xml`)
- El archivo resultante cumple el perfil **EN16931** (anteriormente ZUGFeRD 2.1)

No hay ninguna diferencia en el flujo de envio por email: Frihet adjunta el Factur-X al correo igual que el PDF normal.

:::info Chorus Pro (Francia) — descarga y sandbox
La generacion de Factur-X es completa y automatica. La **transmision a Chorus Pro / PPF** (la plataforma publica francesa) opera en **entorno de pruebas (sandbox) por defecto** y solo conmuta a produccion cuando se configuran credenciales reales de Chorus Pro. Mientras tanto, el flujo recomendado es descargar el Factur-X y entregarlo por tu canal habitual. Mas detalle en [Cumplimiento Francia](../compliance/france).
:::

---

## VeriFactu (Espana) {#verifactu-espana}

Para empresas espanolas, cada factura emitida se incorpora a la cadena de hash VeriFactu de forma automatica. Frihet calcula un hash **SHA-256 encadenado** real, conforme a la especificacion de la AEAT (Orden HAC/1177/2024), en el momento de emitir la factura. La e-factura UBL incluye los campos obligatorios del sistema VeriFactu:

- Hash SHA-256 encadenado (huella `Huella` = hash del registro anterior)
- Datos de identificacion del emisor y numero de serie
- Marca de primer registro de la cadena cuando corresponde

El **encadenamiento de hash es automatico y se ejecuta en produccion** sin que tengas que hacer nada: se dispara al escribir/emitir la factura.

:::warning Envio a AEAT — no automatico por defecto
Calcular la cadena de hash **no es lo mismo** que presentar la factura a la AEAT. La **remision automatica a la AEAT** solo ocurre cuando se cumplen las tres condiciones:

1. Tienes `autoSubmit` activado en tu configuracion VeriFactu
2. Usas un **certificado de produccion** (no el de sandbox, que es el valor por defecto)
3. Tu plan es **Pro, Premium o Enterprise** (la emision a produccion esta restringida por plan en el servidor; un plan desconocido o gratuito se deniega por seguridad)

El entorno **sandbox** de la AEAT esta disponible en cualquier plan para pruebas. Sin estas condiciones, Frihet mantiene la cadena de hash pero no transmite a la AEAT.
:::

Para mas detalle, consulta [VeriFactu](../cumplimiento/verifactu).

---

## XRechnung (Alemania)

XRechnung es el estandar obligatorio para facturas a administraciones publicas alemanas. Frihet genera XRechnung en formato UBL 2.1 o CII segun la preferencia del receptor.

Campos requeridos adicionales frente a EN16931 basico:

| Campo | Descripcion |
|-------|-------------|
| Leitweg-ID | Identificador de enrutamiento del receptor publico |
| Buyer reference | Referencia interna del comprador |
| Numero de pedido | Obligatorio en muchos organismos |

Introduce el **Leitweg-ID** en el campo correspondiente al crear la factura (aparece cuando el pais del cliente es Alemania).

---

## Fattura PA (Italia)

Para facturas dirigidas a la administracion publica italiana o transacciones B2B/B2C en Italia, Frihet genera el formato XML propio del sistema **SDI (Sistema di Interscambio)**. El XML se descarga listo para subida manual al SDI a traves de tu intermediario acreditado (gestor, software de envio, portal Fatture e Corrispettivi).

:::warning Estado — descarga manual hoy
La generacion del XML FatturaPA esta disponible y es automatica. La **transmision automatica al SDI** desde Frihet opera en modo de pruebas (*mock*) por defecto y, para produccion, requiere alta como intermediario acreditado ante el Agenzia delle Entrate y certificados de produccion, todavia no provisionados. Hoy el flujo es: descargar el XML y subirlo al SDI por tu intermediario. Esta en roadmap. Mas detalle en [Cumplimiento Italia](../compliance/italy).
:::

Campos adicionales requeridos:

| Campo | Descripcion |
|-------|-------------|
| Codice SDI | Codigo de destinacion del receptor |
| Codice Fiscale | Identificacion fiscal italiana |
| Regime fiscale | Regimen fiscal del emisor (ej: RF01 ordinario) |

Configura estos datos en el perfil del cliente antes de emitir la factura.

---

## PEPPOL

PEPPOL es la red europea de intercambio electronico de documentos (facturas, pedidos, albaranes). Frihet genera el UBL 2.1 conforme al perfil **PEPPOL BIS**, listo para circular por la red.

:::info PEPPOL — generacion del UBL, entrega via Access Point externo
Frihet **produce el UBL compatible con PEPPOL BIS** y te permite registrar el **PEPPOL ID** del emisor y del receptor (ej: `0188:ES12345678A`). La **entrega a la red PEPPOL la realiza un Access Point** (proveedor certificado): Frihet no actua como Access Point ni enruta los documentos a la red por si mismo. El flujo soportado hoy es:

1. Configura tu **PEPPOL ID** y los datos del receptor
2. Frihet genera el UBL PEPPOL BIS de la factura
3. Entregas ese UBL a traves de tu Access Point para su circulacion por la red

No asumas envio directo a PEPPOL desde Frihet sin un Access Point conectado.
:::

---

## Validacion

Frihet valida el XML generado contra el esquema EN16931 antes de entregarlo. Si hay campos obligatorios ausentes (NIF del receptor, datos bancarios, etc.), se muestra un aviso con los campos que hay que completar antes de poder generar la e-factura.

---

## Requisitos del plan

La generacion de facturas electronicas esta disponible a partir del plan **Premium+**. En planes inferiores puedes descargar PDF pero no XML estructurado ni envio PEPPOL.

Consulta la comparativa completa en [frihet.io/precios](https://www.frihet.io/es/pricing).

---

**Anterior:** [Cobros y pagos](./cobros-pagos) | **Siguiente:** [Pagos parciales](./pagos-parciales)

---

## Facturas recurrentes
> Path: /facturacion/facturas-recurrentes

# Facturas recurrentes

Las facturas recurrentes te permiten automatizar la facturación de servicios que se repiten: suscripciones mensuales, mantenimiento trimestral, retenciones anuales, etc. Una vez configuradas, Frihet genera y envía facturas automáticamente.

## ¿Cuándo usar facturas recurrentes?

Usa recurrentes cuando:

- El cliente paga por un servicio **fijo cada mes/trimestre/año**
- Las **líneas no cambian** (o cambian muy poco)
- Quieres que **Frihet genere automáticamente** la factura en la fecha pactada

**Ejemplos:**

- Cuota mensual de hosting: €50/mes
- Servicio de consultoría: €1,500/trimestre
- Licencia anual de software: €2,000/año
- Mantenimiento de equipos: €300/mes

Si las líneas o montos varían cada mes, considera presupuestos recurrentes o facturación manual.

## Crear una factura recurrente

### Paso 1: Abre el cliente

1. Ve a **Clientes** → Selecciona el cliente
2. Abre la pestaña **Facturación recurrente**
3. Haz clic en **Nueva factura recurrente**

O directamente desde **Facturación** → **Facturas recurrentes** → **Nueva recurrente**.

### Paso 2: Configura la frecuencia

| Opción         | Descripción                          | Ejemplo                                          |
| -------------- | ------------------------------------ | ------------------------------------------------ |
| **Diaria**     | Se genera cada día                   | Ideal para servicios puntuales                   |
| **Semanal**    | Se genera cada semana                | Cada lunes                                       |
| **Mensual**    | Se genera cada mes en la misma fecha | Día 1 de cada mes                                |
| **Trimestral** | Cada 3 meses                         | 1 de enero, 1 de abril, 1 de julio, 1 de octubre |
| **Anual**      | Una vez al año                       | 1 de enero de cada año                           |

**¿Qué día del mes?** Selecciona en **Próxima emisión** — por defecto es el día actual.

**Nota:** Si eliges día 31 y hay un mes con menos días, Frihet usa el último día disponible.

### Paso 3: Agrega líneas

Exactamente igual que en una factura normal:

- Concepto (descripción del servicio)
- Cantidad
- Precio unitario
- Tipo de IVA

**Consejo:** Usa descripciones claras para que el cliente entienda qué está pagando. Ej: "Hosting web - Febrero 2026" en lugar de "Servicio".

### Paso 4: Establece el período de validez

**Inicio:** Cuándo comienza la recurrencia (por defecto, hoy)

**Fin:** Cuándo termina (opcional)

- Si dejas vacío, se repite indefinidamente
- Si especificas fecha, Frihet la genera hasta ese día y luego se detiene

**Ejemplo:** Contrato de enero a diciembre 2026 → Inicio: 1/1/2026, Fin: 31/12/2026

### Paso 5: Configura notificaciones (opcional)

**Notificar antes de generar:**

- Activa esta opción si quieres ser notificado días antes de que se genere la factura
- Útil para revisar datos o hacer ajustes antes de que sea automática
- Frihet te envía un email N días antes (configurable)

**Ejemplo:** Si es recurrente mensual y activas "Notificar 3 días antes", recibirás un email el día 28 de cada mes para revisar antes del día 1.

### Paso 6: Guarda

Haz clic en **Guardar recurrente**. Frihet mostrará:

- "Próxima emisión: X de febrero 2026"
- "Estado: Activa"

## Administrar recurrentes

### Ver todas las recurrentes

1. Ve a **Facturación** → **Facturas recurrentes**
2. Ves una lista con:
   - Cliente
   - Frecuencia (Mensual, Trimestral, etc.)
   - Próxima emisión
   - Total por emisión
   - Estado (Activa, Pausada, Finalizada)

### Editar una recurrente

1. Abre la recurrente desde la lista
2. Haz cambios en líneas, cliente, frecuencia, etc.
3. Haz clic en **Guardar cambios**

**Nota:** Los cambios **no afectan** a las facturas ya generadas, sólo a las futuras.

### Pausar temporalmente

Si el cliente está en pausa pero seguirá siendo cliente después:

1. Abre la recurrente
2. Haz clic en **Pausar**
3. Se detiene la generación hasta que hagas clic en **Reanudar**

### Finalizar una recurrente

Cuando el cliente se va o el servicio termina:

1. Abre la recurrente
2. Haz clic en **Marcar como finalizada**
3. Frihet genera la última factura (si toca) y detiene la recurrencia

### Eliminar una recurrente

Si la creaste por error:

1. Abre la recurrente (debe estar en borrador o pausada)
2. Haz clic en **Eliminar**

**Nota:** No puedes eliminar recurrentes que ya hayan generado facturas. En su lugar, usa "Finalizar".

## Proceso de generación automática

Frihet ejecuta automáticamente mediante un **proceso programado** que se activa en la fecha de emisión configurada:

1. **Identifica** todas las recurrentes con fecha de emisión = hoy
2. **Genera** una factura nueva por cada recurrente
3. **Copia** automáticamente:
   - Líneas exactas (concepto, cantidad, precio, IVA)
   - Datos del cliente
   - Serie de numeración
   - Descuentos (si hay)
4. **Envía** por email (si está activado)
5. **Registra en VeriFactu** automáticamente

### Qué NO se copia

- El estado anterior (siempre se crea en "Enviada" si se auto-notifica)
- Las fechas de pago (nuevas fechas basadas en términos de pago configurados)
- Comentarios privados

### Notificaciones

Recibes notificación cuando:

- Una recurrente fue generada exitosamente
- Ocurrió un error en la generación (ej: cliente sin email)
- Te notifiques 3 días antes (si lo configuraste)

## Personalización avanzada

### Líneas con cantidades variables

Si el servicio tiene cantidades que varían (ej: hosting + tráfico extra), tienes dos opciones:

**Opción 1: Línea fija + línea opcional**

- Agrega dos líneas: una fija (hosting base) y otra vacía (tráfico extra)
- Cada mes edita la segunda línea antes de generarse

**Opción 2: Script personalizado (PRO)**

- Usa integraciones personalizadas para actualizar cantidades automáticamente
- Contacta a soporte para configurar

### Incluir descripción variable (fecha, período)

En el concepto, usa variables dinámicas:

- `{MONTH}` → Se reemplaza por el mes de emisión (Febrero 2026)
- `{YEAR}` → Año (2026)

**Ejemplo:**

- Concepto: `Hosting - {MONTH}`
- Se genera como: "Hosting - Febrero 2026"

### Aplicar descuentos automáticos

Si el cliente tiene descuento por volumen o pago anticipado:

1. Abre la recurrente
2. En **Descuento global**, especifica el porcentaje
3. Se aplica a cada generación automáticamente

## Reportes de recurrentes

Desde **Reportes** → **Facturación recurrente**, ves:

| Métrica                                  | Descripción                                     |
| ---------------------------------------- | ----------------------------------------------- |
| **Ingresos recurrentes mensuales (MRR)** | Suma de todas las recurrentes mensuales activas |
| **Ingresos recurrentes anuales (ARR)**   | MRR × 12                                        |
| **Tasa de retención de clientes**        | Recurrentes activas vs. históricas              |
| **Próximas 30 días a generar**           | Facturas que Frihet emitirá próximamente        |

Estos reportes te ayudan a entender la salud de tu negocio de forma recurrente.

## Integración con pagos

Si tienes **Stripe Connect** o **pagos online** activados:

1. Frihet marca automáticamente la factura como "Pendiente de pago"
2. Genera un enlace de pago único para el cliente
3. Si el cliente paga en línea, Frihet marca la factura como cobrada automáticamente

Aprende más en [Cobros y pagos](./cobros-pagos).

## Casos de uso comunes

### Freelancer con retención mensual fija

- Cliente: Acme Corp
- Frecuencia: Mensual
- Línea: "Desarrollo web - Febrero 2026 | 1 × €2,000"
- IRPF: 15%
- Total por mes: €1,700

### Agencia con servicio trimestral

- Cliente: Marketing Ltd
- Frecuencia: Trimestral (1 de enero, abril, julio, octubre)
- Líneas: SEO (€500) + Social media (€800) + Analítica (€300)
- Total trimestral: €1,600

### SaaS con diferentes planes

Crea una recurrente por plan:

- Plan Basic: €29/mes
- Plan Professional: €99/mes
- Plan Enterprise: €500/mes

Cada cliente tiene su recurrente con su plan específico.

---

**Anterior:** [Facturas](./facturas) | **Siguiente:** [Presupuestos](./presupuestos)

---

## Facturas
> Path: /facturacion/facturas

# Facturas

Las facturas son el corazón de tu negocio en Frihet. Aquí aprenderás a crearlas, editarlas, cambiar su estado y todo lo que necesitas saber sobre su ciclo de vida.

## Crear una factura

### Método 1: Desde cero

1. Abre el módulo **Facturación** → **Facturas**
2. Haz clic en **Nueva factura** (o usa `Alt+N`)
3. Selecciona el cliente de la lista (o créalo al vuelo escribiendo su nombre)
4. Agrega líneas de artículos/servicios
5. Revisa impuestos, descuentos y total
6. Haz clic en **Guardar como borrador** o **Enviar directamente**

### Método 2: Desde un presupuesto

1. Ve a **Presupuestos** y abre el que quieras convertir
2. Haz clic en **Convertir a factura**
3. Frihet copiará automáticamente cliente, líneas y ajustes
4. Guarda o envía

### Método 3: Duplicar una factura anterior

1. Abre la factura que quieras duplicar
2. Haz clic en **Más opciones** → **Duplicar**
3. Se creará una copia en borrador con un nuevo número
4. Edita según sea necesario

## Estructura de una factura

### Datos del cliente

- **Nombre cliente** — Obligatorio
- **NIF/CIF cliente** — Usado para VeriFactu y cumplimiento fiscal
- **Email cliente** — Para enviar la factura automáticamente
- **Dirección** — Mostrada en PDF

### Líneas de artículos

Cada línea contiene:

| Campo | Descripción |
|-------|-------------|
| Concepto | Descripción del artículo/servicio |
| Cantidad | Número de unidades |
| P.U. (Precio unitario) | Precio sin impuestos |
| Descuento | Porcentaje o cantidad fija |
| Total línea | Se calcula automáticamente |
| Tipo de IVA | 21%, 10%, 4%, 0% exento, u otros |

**Tip:** Puedes seleccionar artículos del catálogo con `Ctrl+Space` en el campo de concepto, y Frihet rellenará automáticamente precio e IVA.

### Totales y retenciones

Frihet calcula automáticamente:

- **Subtotal** — Suma de todas las líneas
- **Descuentos** — Aplicados a nivel de factura (opcional)
- **Base imponible** — Subtotal menos descuentos
- **Impuestos** — IVA y otros tributos por cada tipo
- **Retenciones (IRPF)** — Si aplica
- **Total a pagar** — Cantidad final

## Estados de una factura

### Borrador

- Factura no enviada ni registrada
- Puedes editarla libremente
- No aparece en reportes fiscales ni en la cadena de hash VeriFactu
- Acciones: Editar, Enviar, Convertir a rectificativa, Duplicar, Eliminar

### Enviada

- Has enviado el PDF al cliente
- No puedes editar líneas (sólo metadatos como email)
- Se ha registrado en la cadena de hash VeriFactu
- Acciones: Marcar como cobrada, Crear rectificativa, Reenviar por email, Ver PDF

### Cobrada

- El cliente ha pagado
- Totalmente ejecutada
- Aparece en reportes como ingreso
- Acciones: Ver PDF, Crear rectificativa, Desmarcar como cobrada (si fue error)

### Vencida

- Ha pasado la fecha de vencimiento y no está marcada como cobrada
- Frihet asigna automáticamente este estado
- Se muestra en reportes de atrasos
- Acciones: Marcar como cobrada, Enviar recordatorio por email

### Anulada

- Cancelada intencionalmente (no confundir con rectificativa)
- Se usa cuando la factura no debería existir
- No aparece en reportes de ingresos
- **Nota:** Para devoluciones, usa facturas rectificativas en su lugar

## Editar una factura

### En borrador

Puedes cambiar cualquier cosa: cliente, líneas, impuestos, todo.

1. Abre la factura
2. Haz los cambios necesarios
3. Haz clic en **Guardar**

### Enviada

Si necesitas corregir algo después de enviar:

1. **No edites la factura original** — Esto rompe la trazabilidad
2. En su lugar, crea una **factura rectificativa** (nota de crédito)
3. O llama a soporte si es un error evidente

## Impuestos

Frihet soporta múltiples tipos de impuestos españoles:

### IVA (Impuesto sobre el Valor Añadido)

- **21%** — Tipo general (servicios, productos)
- **10%** — Tipo reducido (hostelería, alimentos)
- **4%** — Tipo superreducido (medicinas, libros)
- **0%** — Exento de IVA (servicios específicos)

**¿Cómo funciona?** Cada línea de artículo tiene su propio tipo de IVA. Frihet suma todos los IVAs por tipo.

### IGIC (Impuesto General Indirecto Canario)

Si tu empresa está en Canarias:

- Frihet detecta automáticamente tu domicilio fiscal
- Usa IGIC en lugar de IVA (tipos: 0%, 2.5%, 5.5%, 9%)
- No necesitas hacer nada especial

### IRPF (Retención)

Algunos sectores (construcción, consultoría) requieren retención:

1. Abre la factura
2. En la sección **Retenciones**, activa **Aplicar IRPF**
3. Selecciona el porcentaje (15%, 7%, etc. según tipo de servicio)
4. Frihet resta automáticamente del total

**Importante:** La retención se refleja en el [Modelo 130](/cumplimiento/modelo-130) para tu declaración trimestral de IRPF.

### Recargo de equivalencia

Para distribuidores y actividades asimiladas:

1. Habilítalo en **Configuración** → **Impuestos**
2. Al crear una factura, activa **Recargo de equivalencia**
3. Se aplica porcentualmente (0.5%, 1.4%, 1.75%) según tipo de IVA

## Descuentos

Frihet permite dos tipos:

### Descuentos por línea

- Se aplican a nivel de artículo individual
- Pueden ser porcentaje (ej: 10%) o cantidad fija (ej: €5)
- Se ve directamente en la línea

### Descuentos globales

- Se aplican a toda la factura
- Útil para ofertas especiales o bonificaciones
- Aparece entre subtotal y base imponible

## PDF y envío

### Descargar PDF

1. Abre la factura
2. Haz clic en **Descargar PDF** (o `Alt+D`)
3. Se descarga como `F-2026-0001.pdf` (según tu serie de numeración)

El PDF incluye:

- Datos de tu empresa (logo, dirección, teléfono)
- Datos del cliente
- Número y fecha de factura
- Todas las líneas con detalle de impuestos
- Totales
- Condiciones de pago
- Código QR (si está habilitado en Configuración)

### Enviar por email

Frihet envía facturas directamente por email con el PDF adjunto, sin necesidad de cliente de correo externo.

**Desde la factura:**

1. Haz clic en **Enviar por email** (o `Alt+E`)
2. Se abre el diálogo de envío con los siguientes campos:
   - **Para** — Se auto-rellena con el email del cliente
   - **CC / BCC** — Campos opcionales para copias (ej: tu gestoría)
   - **Asunto** — Pre-generado con el número de factura, editable
   - **Mensaje** — Texto personalizable con saludo al cliente
3. Puedes previsualizar el email antes de enviarlo
4. Haz clic en **Enviar**

El email incluye automáticamente:
- PDF de la factura como adjunto
- Enlace de pago online (si Stripe Connect está activo)
- Resumen del importe y fecha de vencimiento

**Desde la lista de facturas (envío en lote):**

1. Selecciona una o más facturas (checkbox)
2. Haz clic en **Acciones** → **Enviar por email**
3. Cada factura se envía al email de su respectivo cliente

**Enviar recordatorio de pago:**

1. Localiza la factura (estado Enviada, Vencida o Pago parcial)
2. Abre el menú de acciones (tres puntos)
3. Haz clic en **Enviar recordatorio**
4. Se envía un email al cliente con los datos de la factura pendiente y enlace de pago

Frihet registra automáticamente en la factura que fue enviada (campo "Última notificación").

## Búsqueda y filtros

En la **lista de facturas** puedes:

### Filtrar por estado

- `Cmd+F` — Abre búsqueda rápida
- **Estados:** Borrador, Enviada, Cobrada, Vencida, Anulada
- Marca/desmarca estados en el panel de filtros

### Filtrar por cliente

- Escribe en **Buscar cliente...**
- Muestra sólo facturas de ese cliente

### Filtrar por rango de fechas

- **Desde** y **Hasta** — Rango de emisión
- Usa calendarios rápidos: "Este mes", "Último mes", "Este año"

### Búsqueda por número

- Busca por número de factura: `F-2026-0001`
- Busca por NIF del cliente

## Acciones en lote (Bulk actions)

Selecciona varias facturas y aplica acciones a todas:

1. Marca los checkboxes de las facturas
2. Haz clic en **Acciones** en la barra superior
3. Opciones disponibles:
   - **Marcar como enviadas**
   - **Marcar como cobradas**
   - **Marcar como vencidas** (para manejo manual)
   - **Eliminar borrador** (solo borradores)
   - **Exportar a CSV**

## Panel de estadísticas

En la parte superior de **Facturas** ves cuatro métricas en tiempo real:

| Métrica | Descripción |
|---------|-------------|
| **Total facturado** | Suma de todas las facturas del mes (enviadas + cobradas) |
| **Pendiente de cobro** | Suma de facturas enviadas pero no cobradas |
| **Cobrado este mes** | Ingresos del mes actual (solo marcadas como cobradas) |
| **Vencido** | Suma de facturas con fecha de vencimiento pasada |

Haz clic en cualquier métrica para filtrar la lista automáticamente.

## Numeración y series

Las facturas se numeran automáticamente según la **serie de numeración** configurada (ej: F-2026-0001).

Aprende más en [Series y numeración](./series-numeracion).

## Cumplimiento fiscal

Cuando envías una factura en Frihet:

- Se genera el hash SHA-256 de [VeriFactu](/cumplimiento/verifactu) automáticamente
- Se incluye en los [modelos fiscales trimestrales](/cumplimiento/modelos-fiscales) y [libros registro](/cumplimiento/libro-registro)
- Aparece en reportes fiscales
- Los datos de cliente, impuestos y total son inmutables (trazabilidad)

---

Consulta todas las [funcionalidades de facturación](https://www.frihet.io/es/features) o compara con otras soluciones en la [página de Frihet](https://www.frihet.io/es).

**Siguiente paso:** [Presupuestos](./presupuestos) o [Facturas recurrentes](./facturas-recurrentes)

---

## Piloto fiscal automático
> Path: /facturacion/fiscal-autopilot

# Piloto fiscal automático

El piloto fiscal automático es el motor reactivo que aplica las reglas fiscales correctas a cada factura en función del cliente, el país de destino y la naturaleza de la operación. Te muestra avisos en tiempo real sobre cómo se va a tratar fiscalmente la factura antes de emitirla.

## Cómo funciona

Cuando creas o editas una factura, el formulario consulta el motor fiscal en dos momentos clave. Al cargar el formulario, carga el contexto completo del cliente — país, NIF, condición de empresa o particular, exenciones aplicables — para preparar tipos de IVA por defecto y reglas asociadas. Cuando cambias el país de destino del cliente o el tipo de producto, recalcula y muestra una vista previa instantánea del tratamiento fiscal aplicable.

La vista previa identifica tres patrones críticos. **IVA inverso** — si vendes a una empresa de otro país UE con número VIES válido, el piloto te indica que la factura debe emitirse sin IVA con la mención correspondiente al sujeto pasivo invertido. **Requisitos de factura electrónica** — si el cliente es una administración pública española o requiere un formato concreto (Facturae, XRechnung, FatturaPA, KSeF), el piloto avisa antes de emitir para que añadas los códigos DIR3 o Leitweg-ID necesarios. **Elegibilidad SEPA** — si la moneda es EUR y el cliente está en zona SEPA, sugiere generar el código QR EPC en el PDF para que el pago sea de un tap.

Si el cliente no tiene NIF válido o falta información del país, el piloto lo marca como aviso y pide completar el dato antes de continuar. Las correcciones se reflejan en los totales y avisos sin necesidad de recargar la página.

## Configuración

El piloto fiscal funciona por defecto en todas las cuentas y no requiere configuración explícita. Para que la detección de IVA inverso funcione correctamente, asegúrate de que tus clientes UE tengan el NIF intracomunitario validado en VIES desde la ficha del cliente. Para clientes B2G españoles, marca el cliente como administración pública y rellena los códigos DIR3 — el piloto los exigirá automáticamente al exportar Facturae.

Los avisos del piloto no bloquean la emisión: son recomendaciones para que decidas con contexto. Si quieres forzar un tratamiento distinto al sugerido, puedes ajustar el tipo de IVA o la mención manualmente desde el formulario.

## Ver también

- [Facturas](./facturas)
- [Impuestos](./impuestos)
- [Factura electrónica](./factura-electronica)
- [QR SEPA EPC](./enlace-pago)

---

## Gestión de stock
> Path: /facturacion/gestion-stock

<!-- AUTO-STUB 2026-05-05 -->

# Gestión de stock

> Frihet descuenta automáticamente el stock de productos al publicar una factura y lo restaura si la cancelas — con alertas visuales cuando el inventario está bajo.

## Overview

Si vendes productos físicos, Frihet mantiene el inventario actualizado sin trabajo extra. Al añadir un producto a una factura y publicarla, el stock disponible se reduce automáticamente. Si cancelas o eliminas la factura, el stock se restaura. Todo el ciclo es atómico — no hay desincronías.

Las alertas de stock bajo aparecen en la lista de productos con un badge visual cuando el inventario cae por debajo del umbral configurado por producto.

## Quick start

1. Ve a **Productos** y abre un producto. Activa **Control de stock** e introduce el stock inicial.
2. Configura el umbral de alerta de stock bajo (por defecto: 5 unidades).
3. Al emitir facturas con ese producto, verás el stock actualizado en tiempo real en la lista de productos.

## Reference

- API: `GET /v1/products/:id` (campo `stockQuantity`) — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `get_product`, `update_product` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Productos → Editar producto → Control de stock

## Related

- [Catálogo de productos](/productos/catalogo)
- [Precios e impuestos](/productos/precios-impuestos)
- [Crear facturas](/facturacion/facturas)

---

## Importar facturas
> Path: /facturacion/importar-facturas

# Importar facturas

> Migra desde cualquier sistema en minutos: OCR extrae los datos, tu revisas y confirmas.

## Overview

El asistente de importacion de facturas permite subir PDFs de facturas emitidas desde sistemas anteriores (Quaderno, Excel, etc.) y convertirlos a facturas Frihet en 3 pasos. Gemini OCR extrae automaticamente cliente, fecha, importe, lineas de detalle e impuestos. Frihet valida el resultado y senala campos con baja confianza para que los corrijas antes de confirmar.

## Quick start

1. Ve a Facturacion → **Importar** (icono subida) → **Nueva importacion**
2. Arrastra uno o varios PDFs → el OCR extrae los datos automaticamente
3. Revisa los campos resaltados → **Confirmar importacion**

## Reference

- API: `POST /v1/invoices/import` — sube PDF para extraccion OCR
- MCP tool: `import_invoices` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Facturacion → Importar

---

## Impuestos
> Path: /facturacion/impuestos

# Impuestos

Frihet soporta los principales impuestos españoles y territoriales. Aquí aprenderás cómo configurarlos y aplicarlos correctamente en tus facturas.

## Tipos de impuestos soportados

### IVA (Impuesto sobre el Valor Añadido)

El impuesto principal en España. Frihet soporta:

| Tipo | Porcentaje | Aplicación |
|------|-----------|-----------|
| **General** | 21% | Servicios, productos, mayoría de casos |
| **Reducido** | 10% | Hostelería, alimentación, ciertos servicios |
| **Superreducido** | 4% | Medicinas, libros, periódicos |
| **Exento** | 0% | Servicios financieros, educación, sanidad pública |

### IGIC (Impuesto General Indirecto Canario)

Para empresas en Canarias (reemplaza IVA):

| Tipo | Porcentaje | Aplicación |
|------|-----------|-----------|
| Tipo cero | 0% | Actividades exentas |
| Reducido | 3% | Servicios básicos, alimentación |
| General | 7% | Mayoría de bienes y servicios |

### IPSI (Impuesto sobre Producción, Servicios e Importación)

Para Ceuta y Melilla (reemplaza IVA):

- Porcentajes similares a IGIC
- Se aplica automáticamente si tu domicilio fiscal está en Ceuta/Melilla

### IRPF (Impuesto sobre la Renta de Personas Físicas)

Retenciones aplicadas a servicios profesionales:

| Tipo | Porcentaje | Aplicación |
|------|-----------|-----------|
| Servicios generales | 15% | Consultoría, asesoría, diseño |
| Profesiones liberales | 19% | Abogados, contables, arquitectos |
| Actividades artísticas | 7% | Músicos, diseñadores gráficos |
| Construcción | 3% | Obra, reforma |
| Arrendamientos | 19% | Si alquilas inmuebles |
| Actividades económicas | 1% | Otras actividades |

### Recargo de equivalencia

Para distribuidores y operadores asimilados:

| Tipo de IVA | Recargo |
|------------|---------|
| 4% | 0,5% |
| 10% | 1,4% |
| 21% | 5,2% |

Se suma al IVA, no lo reemplaza.

## Configurar impuestos

### Acceder a la configuración

1. Ve a **Configuración** → **Impuestos**
2. Verás todos los impuestos disponibles según tu zona fiscal

### Detectar automáticamente por ubicación

Cuando creas tu cuenta o cambias domicilio fiscal:

1. Ve a **Configuración** → **Empresa**
2. Especifica tu dirección
3. Frihet detecta automáticamente:
   - Si estás en España (IVA)
   - Si estás en Canarias (IGIC)
   - Si estás en Ceuta/Melilla (IPSI)
4. Los impuestos se actualizan automáticamente

### Deshabilitar impuestos

Si no aplican a tu negocio (ej: exención IVA):

1. Ve a **Configuración** → **Impuestos**
2. Deshabilita los que no uses
3. No aparecerán en el selector al crear facturas

## Aplicar impuestos en una factura

### IVA por línea

Cada línea de artículo/servicio tiene su propio tipo de IVA:

1. En el formulario de factura, ve a cada línea
2. En el campo **Tipo de IVA**, selecciona:
   - 21% (estándar)
   - 10% (reducido)
   - 4% (superreducido)
   - 0% (exento)
3. Frihet calcula automáticamente el impuesto

**Cálculo:**
```
Línea: Consultoría web
Cantidad: 1
Precio unitario: €1,000
Tipo IVA: 21%

Subtotal línea: €1,000
IVA (21%): €210
Total línea: €1,210
```

### Total de impuestos en factura

Frihet suma automáticamente todos los IVAs por tipo:

```
Líneas:
  - Consultoría (21%): €1,000 → IVA €210
  - Diseño (10%): €500 → IVA €50
  - Libro/referencia (4%): €100 → IVA €4
  - Servicio financiero (0%): €100 → IVA €0

Subtotal: €1,700

Desglose IVA:
  - IVA 21%: €210
  - IVA 10%: €50
  - IVA 4%: €4
  - Total IVA: €264

Total factura: €1,964
```

### IRPF (Retenciones)

Si aplica retención a tu trabajo:

1. En la factura, ve a la sección **Retenciones**
2. Marca **Aplicar IRPF**
3. Selecciona porcentaje según tu profesión
4. Frihet resta automáticamente del total

**Cálculo:**
```
Servicios: €1,000
IVA (21%): €210
Subtotal: €1,210
IRPF (15%, sobre base): -€150
Total a pagar: €1,060

Nota: El cliente te paga €1,060, y te deja €150 de retención
```

### Recargo de equivalencia

Si eres distribuidor:

1. En la factura, ve a **Opciones avanzadas**
2. Marca **Aplicar recargo de equivalencia**
3. Se suma automáticamente al IVA

**Cálculo:**
```
Producto: €100
IVA (21%): €21
Recargo (5,2%): €5,20
Total: €126,20
```

## Casos especiales

### Servicios intracomunitarios

Si vendes servicios a empresa de otro país EU:

1. El cliente debe ser empresario/profesional
2. Necesitas su VAT ID (número de IVA europeo)
3. En la factura, marca **Operación intracomunitaria**
4. Aplica IVA 0% (responsabilidad del cliente)

### Exportaciones a fuera EU

Si vendes a clientes fuera EU:

1. Marca **Exportación/fuera EU**
2. Aplica IVA 0%
3. Necesitas documentación de aduana

### Operaciones con Canarias

Si tu empresa está en España peninsular y vendes a Canarias:

1. Pregunta a Hacienda si aplica IVA 0% o IGIC
2. Varía según tipo de producto
3. En duda, contacta a asesor

### Cambios de normativa

Si hay cambio de tipos de IVA (ej: sube de 21% a 23%):

1. Frihet mantiene histórico de tipos por período
2. Automáticamente usará nuevos tipos en nuevas facturas
3. Las antiguas mantienen su tipo original

## Reportes de impuestos

Ve a **Reportes** → **Impuestos** para:

### Resumen por tipo

```
IVA 21%:    €5.234 base imponible | €1.099 IVA
IVA 10%:    €1.000 base imponible | €100 IVA
IVA 4%:     €500 base imponible   | €20 IVA
IVA 0%:     €200 (exento)         | €0 IVA

Total IVA devengado: €1,219
```

### Por período

Filtrable por mes, trimestre o año. Importante para:

- Declaración de IVA trimestral
- Libro de facturas emitidas
- Justificación ante Hacienda

### IRPF pagado

```
Retenciones IRPF aplicadas: €3,450
Facturas retenciones: 23

Promedio retención: €150
```

### Recargo de equivalencia

```
Total recargo aplicado: €87.50
Número de transacciones: 50
```

## Declaraciones fiscales trimestrales

Frihet calcula automáticamente tus modelos fiscales trimestrales a partir de tus facturas y gastos. Los modelos disponibles dependen de tu zona fiscal:

- **Península y Baleares:** [Modelo 303 (IVA)](/cumplimiento/modelo-303) + [Modelo 130 (IRPF)](/cumplimiento/modelo-130)
- **Canarias:** [Modelo 420 (IGIC)](/cumplimiento/modelo-420) + [Modelo 130 (IRPF)](/cumplimiento/modelo-130)
- **Ceuta y Melilla:** [Modelo 130 (IRPF)](/cumplimiento/modelo-130)

Para más información, consulta la sección de [Modelos fiscales trimestrales](/cumplimiento/modelos-fiscales).

## Auditar cálculos de impuestos

Si necesitas revisar cálculos manuales:

1. Abre una factura
2. Haz clic en **Ver desglose de impuestos**
3. Se muestra fórmula de cálculo:
   ```
   Base imponible: €1,000
   × IVA 21%: €210
   = Total: €1,210
   ```

## Exenciones y casos especiales

### Empresa de seguros

- Operaciones de seguros: IVA 0%
- Asesoramiento de seguros: IVA 21% (generalmente)

### Actividades sanitarias

- Servicios sanitarios: IVA 0%
- Medicinas: IVA 0%
- Óptica: IVA 0%
- Equipo médico: IVA 0% o 4%

### Educación

- Clases y cursos: IVA 0%
- Material escolar: IVA 0% o 10%
- Libros: IVA 4%

### Transporte

- Pasaje de transporte: IVA 4%
- Cargas: IVA 10%
- Servicios logísticos: IVA 21%

**Consejo:** Si no estás seguro del tipo aplicable, **consulta a asesor fiscal**. Frihet permite cambiar el tipo manualmente antes de enviar.

## Declaración de IVA trimestral

Frihet calcula automáticamente tu declaración trimestral con casillas oficiales:

1. Ve al **Calendario Fiscal**
2. Selecciona trimestre y año
3. Frihet muestra el desglose completo:
   - IVA devengado por tipo (21%, 10%, 4%)
   - IVA deducible (gastos con IVA)
   - Operaciones especiales (exentas, exportaciones, intracomunitarias, ISP)
   - Resultado de la liquidación
4. Descarga el **PDF** como referencia para tu asesor

No es la declaración oficial (debes presentarla en la [sede de la AEAT](https://sede.agenciatributaria.gob.es)), pero calcula todas las casillas para facilitar el proceso.

Para el detalle completo del cálculo, consulta la documentación del [Modelo 303](/cumplimiento/modelo-303).

## Errores comunes

### ❌ Mezclar IVA con IRPF

Son impuestos diferentes:
- **IVA:** Lo que sube el precio para el cliente
- **IRPF:** Lo que el cliente retiene de tu pago

En profesionales liberales: Ambos aplican.

**Correcto:**
```
Servicios: €1,000
IVA (21%): €210
Subtotal: €1,210
IRPF (15%, sobre €1,000): -€150
Total: €1,060
```

### ❌ Aplicar IVA reducido a servicios generales

IVA 10% es para:
- Hostelería (comida/bebida)
- Algunos transportes
- Reparaciones

**No usar** en consultoría, diseño, desarrollo (esos son 21%).

### ❌ Olvidar recargo si eres distribuidor

Si tu régimen es "Recargo de equivalencia", **debes** aplicarlo. No es opcional.

## Contactar a Hacienda

Si tienes dudas sobre qué impuesto aplica:

1. Consulta a tu **asesor fiscal** (recomendado)
2. O contacta **Agencia Tributaria** (¿+34 901 333 555)
3. O usa el simulador online: `aeat.es`

---

**Anterior:** [Series y numeración](./series-numeracion) | **Siguiente:** [Cobros y pagos](./cobros-pagos)

---

## Pagos parciales
> Path: /facturacion/pagos-parciales

# Pagos parciales

Los pagos parciales permiten registrar cobros por partes contra una misma factura. Util cuando el cliente paga en plazos o cuando se reciben transferencias fraccionadas.

:::info Plan Pro o superior
Los pagos parciales estan disponibles a partir del plan Pro.
:::

## Registrar un pago parcial

1. Abre la factura en cuestion
2. Pulsa **Registrar pago**
3. Introduce el importe recibido
4. Opcionalmente, anade fecha de pago y metodo

Frihet actualiza automaticamente:

- **Importe pagado acumulado** (`paidAmount`): suma de todos los pagos registrados
- **Estado de la factura**: cambia a `partial` mientras quede saldo pendiente
- **Saldo restante**: visible en el detalle de la factura

## Flujo de estados

| Estado | Condicion |
|--------|-----------|
| `sent` | Factura enviada, sin pagos registrados |
| `partial` | Al menos un pago, pero el total no cubre el importe |
| `paid` | La suma de pagos iguala o supera el total de la factura |

El cambio de estado es automatico — no necesitas actualizar manualmente.

## Historial de pagos

Cada factura con pagos parciales muestra un historial completo:

- Fecha de cada pago
- Importe
- Metodo de pago
- Quien registro el pago

El historial es inmutable (audit trail) y se incluye en las exportaciones.

## Notificaciones

Cuando se registra un pago parcial:

- Se envia email de confirmacion al cliente (si las notificaciones estan habilitadas)
- El evento `invoice.payment_status_updated` se dispara en webhooks
- El dashboard refleja el cambio en las metricas de cobro

## API

El endpoint `POST /v1/invoices/:id/paid` acepta pagos parciales via el campo `paidDate`. El estado de la factura se actualiza automaticamente segun el importe acumulado.

---

## Presupuestos
> Path: /facturacion/presupuestos

# Presupuestos

Los presupuestos (o cotizaciones) te permiten presentar ofertas a clientes antes de emitir la factura. Son documentos formales que muestran precio, alcance e incluyen una fecha de validez.

## ¿Presupuesto vs. Factura?

| Aspecto | Presupuesto | Factura |
|--------|------------|---------|
| **Propósito** | Oferta / Cotización | Cobro de trabajo realizado |
| **Genera ingresos** | No (aún no) | Sí |
| **Se reporta a Hacienda** | No | Sí (VeriFactu) |
| **Tiene vencimiento** | Sí (típicamente 30 días) | Sí (términos de pago) |
| **Puede editarse** | Sí, mientras esté en borrador | No, después de enviar |
| **Flujo siguiente** | Convertir a factura | Marcar como cobrada |

**Consejo:** Usa presupuestos para trabajos grandes, proyectos personalizados o cuando necesites aprobación antes de empezar.

## Crear un presupuesto

### Desde cero

1. Ve a **Facturación** → **Presupuestos**
2. Haz clic en **Nuevo presupuesto** (o `Alt+N`)
3. Selecciona o crea cliente
4. Agrega líneas con descripción, cantidad y precio
5. Revisa total
6. Haz clic en **Guardar como borrador** o **Enviar**

### Desde un cliente

1. Ve a **Clientes** → Selecciona el cliente
2. En la pestaña **Presupuestos**, haz clic en **Nuevo presupuesto**
3. Se pre-rellena con los datos del cliente

### Duplicar un presupuesto anterior

1. Abre el presupuesto que quieras copiar
2. Haz clic en **Más opciones** → **Duplicar**
3. Se crea una copia en borrador
4. Edita según sea necesario

## Estructura de un presupuesto

Prácticamente idéntica a una factura:

### Encabezado

- Número automático (serie configurable: P-2026-001)
- Fecha de emisión
- Cliente (nombre, NIF, email, dirección)

### Líneas de servicios/productos

| Campo | Descripción |
|-------|-------------|
| Concepto | Descripción detallada del trabajo |
| Cantidad | Horas, unidades, etc. |
| P.U. | Precio unitario (sin IVA) |
| Descuento | Por línea |
| Total línea | Calculado automáticamente |
| IVA | Tipo aplicable (21%, 10%, 4%, etc.) |

**Tip:** Sé específico en los conceptos. Ej: "Diseño de landing page (5 revisiones incluidas)" en lugar de "Diseño".

### Totales

- Subtotal
- Descuentos
- Base imponible
- Impuestos desglosados
- **Total presupuesto**

### Validez

- **Válido desde** — Fecha de emisión (automática)
- **Válido hasta** — Hasta cuándo puede el cliente aceptarlo (por defecto +30 días)
- Frihet calcula automáticamente: "Válido por 30 días"

### Términos de pago (opcional)

- Condiciones de pago
- Formas de pago aceptadas
- Nota al pie

### Mensajes personalizados

- **Mensaje de bienvenida** — Se muestra al inicio del presupuesto
- **Mensaje de cierre** — Llamada a la acción, instrucciones, contacto

**Ejemplos:**

**Bienvenida:** "Hola `{CLIENTE}`, aquí está el presupuesto para tu proyecto."

**Cierre:** "Si aceptas este presupuesto, envía un email a info@ejemplo.com o firma digitalmente en el enlace abajo."

## Estados de un presupuesto

### Borrador

- No enviado
- Puedes editarlo libremente
- No visible al cliente
- Acciones: Editar, Enviar, Convertir a factura, Duplicar, Eliminar

### Enviado

- Compartido con el cliente por email
- Cliente puede verlo online (si activaste compartir enlace)
- No puedes editar líneas (sólo metadatos)
- Acciones: Convertir a factura, Enviar recordatorio, Marcar como aceptado, Rechazar, Reenviar, Ver PDF

### Aceptado

- Cliente aceptó la oferta
- Presupuesto ganado
- Aparece en reportes como pipeline
- Acciones: Convertir a factura, Ver PDF
- **Siguiente paso:** Convierte a factura cuando hagas el trabajo

### Rechazado

- Cliente rechazó la oferta
- Se usa para seguimiento y análisis de pérdidas
- Aparece en reportes de oportunidades perdidas
- Acciones: Ver PDF, Duplicar, Reactivar como borrador

## Convertir presupuesto a factura

### Cuándo hacerlo

Convierte a factura cuando:

1. El cliente aceptó (o implícitamente si ya empezaste el trabajo)
2. Completaste el trabajo/servicio
3. Estás listo para cobrar

### Cómo hacerlo

**Opción 1: Desde el presupuesto**

1. Abre el presupuesto
2. Haz clic en **Convertir a factura**
3. Se crea una factura con:
   - Mismo cliente, líneas, impuestos
   - Número nuevo (serie de facturas, no de presupuestos)
   - Fecha actual
   - Estado: Enviada
4. Haz clic en **Guardar** o **Enviar por email**

**Opción 2: Desde la lista de presupuestos**

1. Selecciona uno o más presupuestos
2. Haz clic en **Acciones** → **Convertir a facturas**
3. Se generan N facturas (una por presupuesto)

### Cambios permitidos antes de convertir

Si el presupuesto está en estado Borrador, puedes cambiar:

- Cantidades (si el alcance cambió)
- Precios (si renegociaste)
- Líneas (agregar/quitar servicios)
- Descuentos (si aplicas promoción)

**Nota:** Una vez enviado, no puedes editar. Crea un nuevo presupuesto si necesitas cambios.

## Buscar y filtrar presupuestos

### Búsqueda rápida

- `Cmd+F` — Abre búsqueda
- Busca por número (P-2026-001) o nombre cliente

### Filtros disponibles

- **Estado:** Borrador, Enviado, Aceptado, Rechazado
- **Fecha:** Este mes, último mes, rango personalizado
- **Cliente:** Escribe para filtrar
- **Monto:** Presupuestos mayores a X euros

### Vistas guardadas

Crea vistas personalizadas:

1. Aplica filtros
2. Haz clic en **Guardar vista** (icono ⭐)
3. Dale un nombre: "Presupuestos mayores a 1000€", "Pendientes aceptación", etc.
4. Accede rápidamente desde el selector de vistas

## Compartir con clientes

### Enviar por email

1. Abre el presupuesto (estado Borrador o Enviado)
2. Haz clic en **Enviar por email**
3. Se pre-rellena el email del cliente
4. Personaliza asunto y mensaje
5. Haz clic en **Enviar**

**Plantilla por defecto:**

```
Asunto: Presupuesto P-2026-001

Hola {CLIENTE},

Adjunto encontrarás el presupuesto solicitado. Es válido hasta el {FECHA_VENCIMIENTO}.

Si tienes preguntas o quieres modificar algo, no dudes en contactarme.

Saludos,
{TU_NOMBRE}
```

### Descargar PDF

1. Abre el presupuesto
2. Haz clic en **Descargar PDF**
3. Se guarda como `P-2026-001.pdf`

El PDF incluye:

- Tu logo y datos de empresa
- Todos los detalles del presupuesto
- Fecha de validez de forma prominente
- Código QR (si está activado)
- Sección de "Aceptación" para que el cliente firme (opcional)

### Generar enlace compartible

Algunos presupuestos soportan enlace compartible (PRO):

1. Abre el presupuesto
2. Haz clic en **Compartir enlace**
3. Se genera una URL como `frihet.io/q/abc123def`
4. Comparte con el cliente (email, chat, etc.)
5. El cliente ve el presupuesto online sin necesidad de app

## Personalizaciones avanzadas

### Variables dinámicas

Usa variables en campos de texto que se reemplazan automáticamente:

| Variable | Reemplazo |
|----------|-----------|
| `{CLIENTE}` | Nombre del cliente |
| `{EMPRESA}` | Tu nombre de empresa |
| `{FECHA}` | Fecha de hoy |
| `{FECHA_VENCIMIENTO}` | Fecha de validez |
| `{TOTAL}` | Monto total |
| `{CONTACTO}` | Tu email de contacto |

**Ejemplo en Cierre:**

```
Gracias {CLIENTE}, esperamos tu confirmación antes del {FECHA_VENCIMIENTO}.
Contacta a {CONTACTO} si tienes dudas.
```

### Plantillas de presupuesto

Si repites el mismo tipo de presupuesto (ej: auditorías SEO, diseño web), crea una plantilla:

1. Crea un presupuesto con líneas estándar
2. Haz clic en **Guardar como plantilla**
3. Dale nombre: "Diseño web básico", "Auditoría SEO", etc.
4. Al crear nuevo, selecciona plantilla y se pre-rellena

## Reportes y análisis

Ve a **Reportes** → **Presupuestos** para:

| Métrica | Útil para |
|---------|-----------|
| **Presupuestos por aceptar** | Seguimiento de leads |
| **Tasa de aceptación** | ¿Cuántos de los enviados se cierran? |
| **Valor medio de presupuesto** | Ticket promedio |
| **Presupuestos vencidos sin respuesta** | Identificar leads fríos |
| **Análisis por cliente** | Clientes más valiosos |
| **Proyección si se aceptaran todos** | Análisis what-if |

**Ejemplo:** Si tu tasa de aceptación es 60% y tienes €20k en presupuestos pendientes, esperas cerrar €12k.

## Integración con CRM

Si tienes integración con **CRM** (Twenty, Pipedrive, etc.):

- Los presupuestos Enviados automáticamente crean oportunidades
- Al marcar como Aceptado, se actualiza la oportunidad
- Sincronización bidireccional de datos

Aprende más en [Integraciones](../integraciones/stripe).

## Flujo completo: De presupuesto a cobro

```
1. PRESUPUESTO (Borrador)
   ↓
2. Cliente recibe por email
   ↓
3. Cliente acepta
   ↓ PRESUPUESTO (Aceptado)
   ↓
4. Conviertes a FACTURA (Enviada)
   ↓
5. Cliente recibe factura
   ↓
6. Cliente paga
   ↓ FACTURA (Cobrada)
   ↓
7. Registrado en reportes como ingreso
```

---

**Anterior:** [Facturas recurrentes](./facturas-recurrentes) | **Siguiente:** [Facturas rectificativas](./abonos)

---

## Recargos por demora
> Path: /facturacion/recargos-demora

# Recargos por demora

> Aplica recargos legalmente validos en facturas vencidas sin calcular manualmente.

## Overview

Frihet calcula automaticamente los recargos por demora en facturas no pagadas en plazo. Soporta tres metodos: importe fijo por factura, porcentaje sobre el principal, o interes legal del dinero (configurable por pais). El recargo aparece como linea adicional en la factura o como nota en el historial, segun la configuracion del usuario. Funciona con el motor de dunning para aplicarse antes del primer recordatorio.

## Quick start

1. Ve a Configuracion → Facturacion → **Recargos por demora**
2. Activa la opcion y elige el metodo (fijo / porcentaje / interes legal)
3. Las facturas que superen el plazo de pago mostraran el recargo calculado automaticamente

## Reference

- API: `PATCH /v1/invoices/:id` con campo `lateFeeConfig` para configurar por factura
- MCP tool: `apply_late_fee` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Configuracion → Facturacion → Recargos

---

## Recordatorios de pago
> Path: /facturacion/recordatorios-pago

# Recordatorios de pago

> Cobra mas rapido sin llamar: recordatorios manuales y dunning automatico integrados.

## Overview

Frihet permite enviar recordatorios de pago a clientes con facturas vencidas desde la vista de factura con un clic. Para equipos que gestionan muchas facturas, el sistema de dunning automatico envia hasta 4 recordatorios escalonados (dias 1, 7, 14, 30 tras vencimiento) con estado rastreable por factura. Cada recordatorio incluye el enlace de pago Stripe del cliente.

## Quick start

1. Abre la factura vencida → pulsa **Recordar pago** en el menu de acciones
2. Revisa el asunto y cuerpo del email → **Enviar**
3. Para dunning automatico: Configuracion → Automatizaciones → activar **Recordatorios automaticos**

## Reference

- API: `POST /v1/invoices/:id/remind` — envia recordatorio manual
- MCP tool: `send_payment_reminder` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Configuracion → Automatizaciones

---

## Series y numeracion
> Path: /facturacion/series-numeracion

# Series y numeracion

La numeracion de facturas debe cumplir con requisitos fiscales espanoles. Frihet permite crear series personalizadas con patrones flexibles para que tus facturas se numeren automaticamente, con contadores independientes por serie.

## Que es una serie

Una serie es un grupo de facturas con su propio patron de numeracion y contador independiente. Son utiles cuando necesitas separar lineas de negocio, sucursales, o tipos de facturacion bajo un mismo NIF.

**Ejemplo:** un autonomo con dos actividades:

- **Serie FRI** para su SaaS: FRI20260001, FRI20260002, etc.
- **Serie BRT** para consulting: BRT20260001, BRT20260002, etc.

Cada serie tiene su propio contador que avanza de forma independiente.

## Como funciona la numeracion sin series

Si no configuras series, Frihet usa un unico patron global con un solo contador. Este es el comportamiento por defecto para nuevas cuentas:

1. Ve a **Configuracion** > **Facturacion**
2. En la seccion de numeracion, define tu patron (ej: `F{YEAR}{SEQ4}`)
3. Cada factura recibe el siguiente numero secuencial

Para la mayoria de autonomos con una sola actividad, esto es suficiente.

## Acceder a la configuracion de series

1. Ve a **Configuracion** > **Facturacion**
2. Baja hasta la seccion **Series de Facturacion**
3. Veras tus series configuradas (si las hay)

## Crear una serie

### Primera vez

Cuando anadis tu primera serie, Frihet migra automaticamente tu configuracion actual:

1. Haz clic en **Anadir serie**
2. Frihet crea una serie "Por defecto" con tu patron y contador actuales
3. Puedes renombrarla y anadir mas series

Esta migracion es transparente: tus facturas existentes no se ven afectadas.

### Anadir mas series

1. Haz clic en **Anadir serie**
2. Completa los campos:
   - **ID** — Identificador corto y unico (ej: `fri`, `brt`, `consulting`). No se puede cambiar despues.
   - **Nombre** — Nombre descriptivo (ej: "Frihet SaaS", "BRTHLS Consulting")
   - **Patron** — Formula de numeracion (ej: `FRI{YEAR}{SEQ4}`)
3. El contador empieza en 1 automaticamente

Puedes tener hasta 10 series.

### Serie por defecto

Exactamente una serie debe ser la por defecto. Es la que se preselecciona al crear una factura nueva.

Para cambiar la serie por defecto, haz clic en **Establecer por defecto** en la serie deseada.

## Variables del patron

El patron usa variables dinamicas que se reemplazan automaticamente:

| Variable | Descripcion | Ejemplo |
|----------|-------------|---------|
| `{YEAR}` | Ano actual de 4 digitos | 2026, 2027 |
| `{MONTH}` | Mes con 2 digitos (01-12) | 01, 02, ..., 12 |
| `{SEQ3}` | Secuencia de 3 digitos (001, 002...) | 001, 002, 999 |
| `{SEQ4}` | Secuencia de 4 digitos (0001, 0002...) | 0001, 0002, 9999 |
| `{SEQ5}` | Secuencia de 5 digitos (00001, 00002...) | 00001, 00002, 99999 |

El prefijo de serie (FRI, BRT, F, etc.) se escribe directamente en el patron, no es una variable separada.

## Ejemplos de patrones

**Con prefijo de serie (recomendado para multi-actividad):**
```
FRI{YEAR}{SEQ4}

Resultado: FRI20260001, FRI20260002, ..., FRI20269999
```

**Patron clasico con guiones:**
```
F-{YEAR}-{SEQ4}

Resultado: F-2026-0001, F-2026-0002, ..., F-2026-9999
```

**Con mes (para distinguir por periodo):**
```
F-{YEAR}{MONTH}-{SEQ3}

Resultado: F-202601-001, F-202602-001, ...
```

**Minimalista (solo secuencia):**
```
{SEQ4}

Resultado: 0001, 0002, ...
```

**Con separador de barra:**
```
F/{YEAR}/{SEQ3}

Resultado: F/2026/001, F/2026/002, ...
```

## Seleccionar serie al crear factura

Si tienes mas de una serie configurada, al crear una factura veras un selector de serie:

1. Abre el formulario de nueva factura
2. En la seccion de fechas, selecciona la serie deseada
3. El numero se asignara automaticamente segun el patron y contador de esa serie

Si solo tienes una serie (o no usas series), no aparece ningun selector y la numeracion funciona automaticamente.

## Auto-reset anual

Al cambiar de ano, el contador de cada serie vuelve a 1 automaticamente (si tienes activada la politica de reset anual).

**Ejemplo:**
- 31 de diciembre 2025: Ultima factura FRI20250523
- 1 de enero 2026: Primera factura FRI20260001

Esta politica se configura en **Configuracion** > **Facturacion** > **Politica de reseteo**. Las opciones son:

- **Anual** (recomendado): El contador se reinicia cada 1 de enero
- **Nunca**: El contador continua indefinidamente

## Editar una serie

Puedes editar el nombre y patron de una serie existente directamente en la seccion de series.

**Importante:** Los cambios afectan a futuras facturas, NO a las ya generadas. El contador continua donde estaba.

**Ejemplo:**
- Generaste facturas FRI20260001 a FRI20260050 con patron viejo
- Cambias el patron a `FRIHET-{YEAR}-{SEQ4}`
- La proxima factura sera FRIHET-2026-0051 (el contador continua)

## Eliminar una serie

1. Haz clic en el boton de eliminar en la serie
2. Confirma la eliminacion

Las facturas existentes que usaban esa serie no se ven afectadas (mantienen su numero).

Si eliminas la serie por defecto, la primera serie restante se convierte automaticamente en la por defecto.

## Cambiar el contador

Cada serie muestra el proximo numero que se asignara. Puedes ajustar este numero manualmente si necesitas continuar una numeracion de otro sistema.

**Ejemplo:**
- Migras desde Excel donde ibas por la factura 500
- Ajustas el contador a 501
- La proxima factura en esa serie empezara en 501

## Cambiar serie de una factura existente

Una vez emitida la factura, NO puedes cambiar su numero ni su serie (requisito fiscal). El numero es inmutable.

Si necesitas usar una serie diferente:

1. Crea una nueva factura con la serie correcta
2. Cancela o rectifica la factura original si es necesario

## Casos de uso comunes

### Autonomo con varias actividades

Separar ingresos por linea de negocio:

```
Serie: Consulting
Patron: CON{YEAR}{SEQ4}
Resultado: CON20260001

Serie: Formacion
Patron: FORM{YEAR}{SEQ4}
Resultado: FORM20260001
```

### Empresa con sucursales

Una serie por ubicacion:

```
Serie: Facturas Madrid
Patron: FM-{YEAR}-{SEQ4}
Resultado: FM-2026-0001

Serie: Facturas Barcelona
Patron: FB-{YEAR}-{SEQ4}
Resultado: FB-2026-0001
```

### Diferentes tipos de clientes

```
Serie: Clientes Nacionales
Patron: F-{YEAR}-{SEQ4}
Resultado: F-2026-0001

Serie: Clientes Internacionales
Patron: FI-{YEAR}-{SEQ3}
Resultado: FI-2026-001
```

### Migracion desde otro sistema

Si vienes de Excel, otro ERP, o facturacion manual:

1. Crea una serie con el patron que usabas
2. Ajusta el contador al siguiente numero que te toca
3. Las nuevas facturas continuan la numeracion sin saltos

## Requisitos fiscales

La numeracion de facturas en Espana debe:

- Ser **correlativa** (sin saltos)
- Ser **unica** (no repetir numeros)
- Tener **identificacion clara** (serie + numero)
- Estar **en orden cronologico** (sin antedatar)

Frihet garantiza esto automaticamente mediante un **contador atomico en el servidor**. La numeracion se genera de forma centralizada para evitar duplicados o saltos, incluso si varias personas crean facturas simultaneamente. No es posible crear manualmente un numero fuera de secuencia.

Cuando usas series, cada serie mantiene su propia secuencia correlativa de forma independiente. Esto cumple con el RD 1619/2012 que permite series distintas siempre que cada una sea correlativa.

Esta numeracion sin saltos es tambien un requisito del [RD 1007/2023 (VeriFactu)](/cumplimiento/verifactu) y se aplica de forma transparente.

## Branding personalizado por serie

Cada serie puede tener su propio branding visual, independiente del branding global de tu cuenta. Esto permite que facturas de diferentes lineas de negocio tengan identidades visuales distintas.

### Configurar branding de serie

1. Ve a **Configuracion** > **Facturacion** > **Series de Facturacion**
2. En la serie que quieras personalizar, haz clic en **Personalizar branding**
3. Configura los campos disponibles:
   - **Logo de serie** — Se muestra en el PDF en lugar del logo global
   - **Nombre comercial** — Nombre de la linea de negocio (ej: "Frihet" vs "BRTHLS Consulting")
   - **Color de acento** — Color para titulos y cabeceras de tabla en el PDF
   - **Pie de factura** — Texto personalizado al pie de pagina

### Como funciona la prioridad

Cuando generas un PDF, Frihet resuelve el branding en este orden:

1. Si la factura pertenece a una serie con branding propio → usa el de la serie
2. Si la serie no tiene branding (o no tiene ese campo) → usa el branding global de tu cuenta

Esto significa que puedes personalizar solo el logo de una serie y mantener el color y footer globales.

### Casos de uso

**Autonomo con dos marcas:**
- Serie FRI: logo Frihet, color negro, footer "Frihet — Software de gestion"
- Serie BRT: logo BRTHLS, color gris, footer "BRTHLS Consulting"

**Misma marca, diferentes pies:**
- Serie nacional: footer con cuenta bancaria espanola
- Serie internacional: footer con cuenta IBAN + SWIFT

### Indicador visual

Las series con branding personalizado muestran una etiqueta **Branding propio** en la configuracion, para que identifiques rapidamente cuales tienen sobreescrituras activas.

## Libro Registro

Las facturas de todas las series se incluyen en el Libro Registro, accesible desde la lista de facturas. El numero de documento (con su prefijo de serie) se refleja automaticamente en la columna correspondiente.

Para exportar el Libro Registro como CSV, ve a **Facturas** y usa la opcion de **Libro Registro**.

---

**Anterior:** [Facturas rectificativas](./abonos) | **Siguiente:** [Impuestos](./impuestos)

---

## Norma AEB-43 — Importacion de extractos bancarios
> Path: /finanzas/aeb43-norma43

# Norma AEB-43 — Importacion de extractos bancarios

La Norma 43 (AEB-43) es el estandar espanol para el intercambio de extractos bancarios entre bancos y software de gestion. Cualquier banco espanol puede generar un fichero `.43` o `.txt` con el movimiento de tu cuenta. Frihet lo importa directamente, categoriza las transacciones y las reconcilia con tus facturas.

Esta funcionalidad es util cuando no tienes conexion bancaria Open Banking activa o cuando necesitas importar movimientos historicos.

## Obtener el fichero desde tu banco

La mayoria de bancos espanoles permiten descargar el extracto en Norma 43 desde la banca online:

| Banco         | Ruta habitual                                     |
| ------------- | ------------------------------------------------- |
| **CaixaBank** | Cuentas → Movimientos → Exportar → Norma 43       |
| **BBVA**      | Cuentas → Movimientos → Descargar → Fichero AEB43 |
| **Santander** | Cuentas → Extracto → Exportar → Formato AEB       |
| **Sabadell**  | Cuentas → Extracto → Descargar → Norma 43         |
| **Bankinter** | Cuentas → Movimientos → Exportar → .Q43           |

El fichero tiene extension `.43`, `.q43` o `.txt` dependiendo del banco. Frihet acepta todos.

## Importar en Frihet

1. Ve a **Finanzas** → **Conciliacion bancaria** → **Importar extracto**.
2. Selecciona la cuenta bancaria de destino.
3. Arrastra el fichero AEB-43 o haz clic en **Seleccionar fichero**.
4. Frihet analiza el fichero y muestra una previsualizacion de los movimientos.
5. Confirma la importacion. Las transacciones aparecen inmediatamente en la cola de conciliacion.

Frihet detecta automaticamente movimientos duplicados (mismo importe, fecha y concepto) y los marca para revision antes de importar.

## Especificacion del formato

El formato AEB-43 es de ancho fijo. Cada registro tiene 80 caracteres:

```
Posicion  Longitud  Campo
1-2       2         Codigo de registro (11=cabecera cuenta, 22=movimiento, 33=fin)
3-6       4         Codigo de banco
7-10      4         Codigo de oficina
11-12     2         Digito control
13-22     10        Numero de cuenta (BBAN)
23-24     2         Ano (YY)
25-26     2         Fecha valor (mes)
27-28     2         Fecha valor (dia)
29-30     2         Fecha operacion (mes)
31-32     2         Fecha operacion (dia)
33        1         Haber/Debe (1=haber, 2=debe)
34-47     14        Importe (12 enteros + 2 decimales, sin separador)
48-49     2         Clave concepto (01=transferencia, 02=cheque, 06=domiciliacion...)
50-61     12        Referencia 1
62-75     14        Referencia 2
76-80     5         Libre
```

Los registros de tipo `22` con clave `00-99` van seguidos de hasta tres registros de tipo `23` con el concepto textual (hasta 38 caracteres cada uno).

## Parser @frihet/aeb43-parser

Para integraciones custom o scripts de migracion, puedes usar el parser oficial de Frihet:

```bash
npm install @frihet/aeb43-parser
```

```typescript
import { parseAEB43, AEB43Statement } from '@frihet/aeb43-parser';
import { readFileSync } from 'fs';

const raw = readFileSync('extracto.43', 'latin1'); // AEB-43 usa ISO-8859-1
const statement: AEB43Statement = parseAEB43(raw);

console.log(statement.account); // { bank: '0049', office: '0075', ... }
console.log(statement.entries); // Array de movimientos
// [{ date: '2026-03-15', valueDate: '2026-03-15', amount: -245.50, description: 'RECIBO LUZ ENDESA' }, ...]
```

```typescript
// Tipos exportados
interface AEB43Entry {
  operationDate: Date;
  valueDate: Date;
  amount: number; // positivo = haber, negativo = debe
  conceptCode: string; // '01' = transferencia, etc.
  description: string; // concepto concatenado de registros tipo 23
  ref1: string;
  ref2: string;
}

interface AEB43Statement {
  bank: string;
  office: string;
  account: string;
  entries: AEB43Entry[];
  openingBalance: number;
  closingBalance: number;
  currency: string; // siempre 'EUR' para cuentas espanolas
}
```

### Encoding importante

Los ficheros AEB-43 usan codificacion **ISO-8859-1** (Latin-1), no UTF-8. El parser lo maneja internamente, pero si lees el fichero manualmente especifica `'latin1'` como encoding.

## Reconciliacion automatica post-importacion

Tras la importacion, Frihet aplica las **reglas bancarias** activas para categorizar transacciones automaticamente. Las que no matcheen quedan en estado **pendiente** en la cola de conciliacion para revision manual.

Las transacciones importadas via AEB-43 se marcan con el icono de fichero (en lugar del icono de conexion bancaria) para distinguirlas de las obtenidas por Open Banking.

## Gotchas

- **Encoding**: algunos bancos exportan con codificacion mixta (cabecera Latin-1, movimientos UTF-8). Frihet normaliza automaticamente, pero si ves caracteres extranios en la previsualizacion, exporta de nuevo desde el banco seleccionando explicitamente Latin-1 o ASCII.
- **Saldo de apertura**: el registro de cabecera (tipo `11`) incluye el saldo de apertura del periodo. Si importas periodos solapados, Frihet usa la fecha de operacion para deduplicar, no el saldo.
- **Ficheros multi-cuenta**: un fichero AEB-43 puede contener multiples cuentas (multiples bloques `11...33`). Frihet los detecta y te pide asignar cada cuenta a una cuenta de Frihet.
- **Limite historico**: Frihet acepta importaciones de hasta 5 anos de historia. Movimientos mas antiguos requieren contactar a soporte.

## Relacionado

- [Conciliacion bancaria](./conciliacion-bancaria)
- [Reglas bancarias](./reglas-bancarias)
- [Conexiones bancarias Open Banking](./conexiones-bancarias)
- [Constructor de reglas bancarias](./reglas-bancarias-constructor)

---

## Conciliación bancaria
> Path: /finanzas/conciliacion-bancaria

<!-- AUTO-STUB 2026-05-05 -->

# Conciliación bancaria

> Importa extractos en OFX, MT940 o CSV y deja que Frihet empareje automáticamente cada movimiento con la factura o gasto correspondiente usando coincidencia difusa e IA categorizadora.

## Overview

Frihet incluye un pipeline de 5 estados para cada transacción bancaria importada: `raw → recognized → matched → categorized → excluded`. La conciliación automática usa coincidencia difusa por importe, fecha y referencia. Para transacciones sin coincidencia directa, la IA categorizadora usa el historial previo para sugerir categoría y cuenta contable.

Las reglas bancarias te permiten automatizar la categorización futura: define condiciones (rango de importe, descripción, comerciante) y la acción (categoría, cuenta, etiqueta) para que el sistema las aplique sin intervención.

## Quick start

1. Ve a **Finanzas → Conexiones bancarias** y sube tu extracto (OFX, MT940 o CSV).
2. Frihet importa las transacciones y ejecuta la conciliación automática.
3. Revisa las transacciones `sin emparejar`, confirma las sugerencias o asígnalas manualmente.

## Reference

- API: `POST /v1/banking/import`, `GET /v1/banking/transactions` — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `reconcile_transactions` — ver [MCP reference](/desarrolladores/mcp-server)
- Settings: Finanzas → Reglas bancarias

## Related

- [Conexiones bancarias](./conexiones-bancarias)
- [Reglas bancarias](./reglas-bancarias)
- [Informes contables](/contabilidad/informes-contables)

---

## Conexiones bancarias
> Path: /finanzas/conexiones-bancarias

# Conexiones bancarias

El modulo de banca de Frihet conecta directamente con tus cuentas bancarias para importar transacciones, reconciliar con facturas y gastos, y mantener un registro financiero en tiempo real sin entrada manual de datos.

Esta funcionalidad requiere plan **Pro o superior**.

## Proveedores de conexion

Frihet integra dos vias para conectar cuentas bancarias:

| Proveedor             | Cobertura                | Tipo de conexion    |
| --------------------- | ------------------------ | ------------------- |
| **Tink Open Banking** | 6.000+ bancos europeos   | Open Banking (PSD2) |
| **Revolut Business**  | Cuentas Revolut Business | API directa         |

### Tink Open Banking

Tink es la plataforma de Open Banking lider en Europa. La conexion usa el estandar PSD2, que obliga a los bancos a compartir datos de manera segura con aplicaciones autorizadas.

**Bancos compatibles (ejemplos):**

- Espana: BBVA, Santander, CaixaBank, Bankinter, Sabadell, ING, Openbank
- Europa: Deutsche Bank, BNP Paribas, ING, Rabobank, Nordea, SEB, Handelsbanken
- Reino Unido: Barclays, HSBC, NatWest, Lloyds, Monzo, Starling

Para ver el listado completo, usa el buscador dentro de **Banca** → **Nueva conexion**.

### Revolut Business

Si usas Revolut Business como cuenta principal o secundaria, la integracion es directa via API. No necesitas pasar por el flujo de Open Banking.

Consulta la guia especifica en [Integraciones → Revolut](/integraciones/revolut).

## Conectar un banco

1. Ve a **Banca** en el menu lateral
2. Haz clic en **Conectar cuenta bancaria**
3. Selecciona tu banco (busca por nombre o pais)
4. Frihet abre una ventana segura de autenticacion de tu banco
5. Introduce tus credenciales directamente en la interfaz del banco (Frihet nunca ve tus credenciales)
6. Autoriza el acceso a los datos de movimientos
7. La conexion se activa y Frihet importa los ultimos 90 dias de transacciones

El proceso completo tarda menos de 2 minutos.

### Permisos solicitados

Frihet solicita unicamente acceso de **lectura** a:

- Saldo de cuenta
- Historial de transacciones (movimientos)
- Datos de la cuenta (IBAN, nombre del titular)

Frihet **no** puede iniciar pagos ni modificar datos en tu banco.

### Duracion de la conexion

Por normativa PSD2, las conexiones bancarias requieren reautorizacion periodica (habitualmente cada 90 dias). Frihet te notificara cuando sea necesario renovar el acceso.

## Cuentas bancarias

Una vez conectadas, tus cuentas aparecen en **Banca** → **Cuentas**:

| Campo                     | Descripcion                                     |
| ------------------------- | ----------------------------------------------- |
| **Banco**                 | Logo e identificacion de la entidad             |
| **Nombre de cuenta**      | Nombre o alias que asignes                      |
| **IBAN**                  | Numero de cuenta internacional                  |
| **Saldo actual**          | Saldo en tiempo real (si el banco lo provee)    |
| **Ultima sincronizacion** | Cuando se importaron movimientos por ultima vez |
| **Estado**                | Activa / Reautorizacion necesaria               |

Puedes gestionar varias cuentas del mismo o distinto banco.

## Transacciones

### Ver transacciones

Ve a **Banca** → **Transacciones** para ver todos los movimientos importados.

La lista muestra:

- Fecha y hora de la transaccion
- Descripcion original del banco
- Importe (positivo = entrada, negativo = salida)
- Estado de reconciliacion: **Reconciliada**, **Pendiente**, **Excluida**
- Categoria asignada (por regla, por IA, o manualmente)
- Documento vinculado (factura, gasto, deposito)

### Filtros disponibles

| Filtro          | Opciones                               |
| --------------- | -------------------------------------- |
| Cuenta          | Una o varias cuentas conectadas        |
| Rango de fechas | Personalizado o periodos rapidos       |
| Estado          | Reconciliada / Pendiente / Excluida    |
| Tipo            | Entrada / Salida                       |
| Categoria       | Cualquier categoria de gasto o ingreso |

### Sincronizar transacciones

Frihet sincroniza automaticamente una vez al dia. Para sincronizar en el momento:

1. Abre **Banca** → **Cuentas**
2. Haz clic en **Sincronizar** junto a la cuenta
3. Los nuevos movimientos se importan en segundos

## Reconciliacion

La reconciliacion es el proceso de emparejar transacciones bancarias con documentos en Frihet (facturas cobradas, gastos registrados, depositos).

### Reconciliacion automatica

Frihet intenta reconciliar automaticamente cuando:

- El importe coincide exactamente con una factura pendiente de cobro
- La fecha de la transaccion es cercana a la fecha de vencimiento de la factura
- El nombre del pagador coincide con el nombre del cliente

Cuando Frihet encuentra coincidencia, la transaccion aparece con estado **Sugerencia de reconciliacion**.

### Confirmar una reconciliacion sugerida

1. Abre la transaccion con sugerencia pendiente
2. Frihet muestra el documento propuesto (factura, gasto, etc.)
3. Revisa que los datos coincidan
4. Haz clic en **Confirmar reconciliacion**

La factura pasa a estado **Cobrada** y la transaccion queda vinculada.

### Reconciliacion manual

Si Frihet no encuentra coincidencia automatica:

1. Abre la transaccion
2. Haz clic en **Reconciliar manualmente**
3. Busca la factura, gasto o deposito correspondiente
4. Confirma

### Reconciliacion con gastos

Las salidas de dinero se reconcilian con gastos registrados en Frihet:

1. La transaccion (salida) aparece como **Pendiente**
2. Frihet busca gastos con importe y fecha similar
3. Confirmas la coincidencia
4. El gasto queda marcado como **Pagado**

### Transacciones sin documento

Si una transaccion no corresponde a ningun documento existente, puedes:

- **Crear gasto directamente** desde la transaccion (rellena el importe y fecha automaticamente)
- **Crear deposito** si es un anticipo de cliente
- **Excluir** si es una transaccion interna o que no necesitas registrar

## Importacion de extractos bancarios

Si tu banco no esta disponible en Tink, puedes importar el extracto manualmente.

### Formatos soportados

| Formato | Extension | Descripcion                                         |
| ------- | --------- | --------------------------------------------------- |
| **CSV** | `.csv`    | Exportacion estandar de la mayoria de bancos        |
| **OFX** | `.ofx`    | Open Financial Exchange (formato bancario estandar) |
| **QFX** | `.qfx`    | Formato Quicken (compatible con OFX)                |

### Importar un extracto

1. Ve a **Banca** → **Importar extracto**
2. Selecciona la cuenta bancaria destino (o crea una cuenta manual)
3. Sube el fichero
4. Frihet detecta el formato y muestra una previsualizacion de las transacciones
5. Revisa el mapeo de columnas si es necesario
6. Haz clic en **Importar**

Frihet evita duplicados: si una transaccion ya existe (misma fecha e importe), no se importa de nuevo.

## Categorizacion con IA

Frihet usa inteligencia artificial para categorizar automaticamente las transacciones importadas.

El modelo analiza la descripcion original del banco y asigna una categoria:

**Ejemplos:**

| Descripcion del banco       | Categoria asignada  |
| --------------------------- | ------------------- |
| `AMAZON MKTPLACE AMZN.DE`   | Material de oficina |
| `NOMINAS EMPLEADOS FEBRERO` | Nominas             |
| `REPSOL SERVICIO TENERIFE`  | Combustible         |
| `GOOGLE CLOUD BILLING`      | Software y SaaS     |
| `SEGURIDAD SOCIAL CUOTA`    | Seguridad Social    |

La IA mejora con el tiempo: cuando corriges una categoria manualmente, aprende para futuras transacciones del mismo proveedor.

Para definir reglas fijas de categorizacion, usa [Reglas bancarias](./reglas-bancarias).

## Plan y limitaciones

| Caracteristica              | Gratis | Pro     | Premium  | Enterprise |
| --------------------------- | ------ | ------- | ---------- | ---------- |
| Conexiones bancarias (Tink) | —      | Hasta 3 | Ilimitadas | Ilimitadas |
| Importacion CSV/OFX         | —      | Si      | Si         | Si         |
| Reconciliacion automatica   | —      | Si      | Si         | Si         |
| Categorizacion IA           | —      | Si      | Si         | Si         |
| Reglas bancarias            | —      | Si      | Si         | Si         |
| Historial importado         | —      | 90 dias | 2 anos     | Ilimitado  |

Para cambiar de plan, ve a **Configuracion** → [Planes y facturacion](/configuracion/planes-facturacion).

## Seguridad

- Las credenciales bancarias **nunca pasan por Frihet**. La autenticacion se hace directamente en la interfaz de tu banco (OAuth2).
- Los datos de transacciones se transmiten cifrados (TLS 1.3).
- Frihet solicita unicamente acceso de lectura. No puede iniciar pagos.
- Tink esta regulado como AISP (Account Information Service Provider) bajo PSD2 y supervisado por autoridades financieras europeas.

---

**Siguiente paso:** [Reglas bancarias](./reglas-bancarias) para automatizar la categorizacion de transacciones.

---

## Depositos y anticipos
> Path: /finanzas/depositos

# Depositos y anticipos

Los depositos permiten registrar pagos anticipados o senales de clientes antes de emitir la factura final. Cuando llega el momento de facturar, puedes aplicar el deposito al importe de la factura.

## Crear un deposito

1. Ve a **Finanzas > Depositos** en el menu lateral
2. Pulsa **Nuevo deposito**
3. Selecciona el cliente y completa los datos:

| Campo | Requerido | Descripcion |
|-------|-----------|-------------|
| Cliente | Si | Cliente que realiza el anticipo |
| Importe | Si | Cantidad recibida |
| Descripcion | Si | Concepto del anticipo (ej. "Senal proyecto Q2") |
| Fecha de recepcion | Si | Fecha en que se recibio el pago |
| Divisa | No | Por defecto EUR. Soporta 40 divisas |
| Metodo de pago | No | Transferencia, tarjeta, efectivo, etc. |
| Referencia de pago | No | Numero de transferencia u otro identificador |

## Aplicar deposito a una factura

Cuando emitas la factura asociada al trabajo prepagado:

1. Abre el deposito desde **Finanzas > Depositos**
2. Pulsa **Aplicar a factura**
3. Selecciona la factura destino
4. Indica el importe a aplicar (puede ser parcial)

El importe aplicado se descuenta automaticamente del saldo de la factura. Si el deposito cubre el total, la factura se marca como pagada.

Un mismo deposito puede aplicarse a varias facturas hasta agotar su saldo.

## Reembolsar un deposito

Si el trabajo no se realiza o el cliente solicita la devolucion:

1. Abre el deposito
2. Pulsa **Reembolsar**
3. Indica el importe a devolver (por defecto: saldo restante completo)

El reembolso queda registrado en el historial del deposito.

## Estados del deposito

| Estado | Descripcion |
|--------|-------------|
| Recibido | Deposito registrado, saldo completo disponible |
| Parcialmente aplicado | Parte del deposito se ha descontado de facturas |
| Aplicado | Todo el importe se ha asignado a facturas |
| Reembolsado | El deposito ha sido devuelto al cliente (total o parcial) |

## Multi-divisa

Los depositos respetan la configuracion de [multi-divisa](/configuracion/multi-divisa) de tu cuenta. Puedes registrar depositos en cualquiera de las 40 divisas soportadas.

## API

Los depositos estan disponibles en la API REST con endpoints CRUD completos y acciones de aplicacion y reembolso. Consulta la [referencia de la API](/desarrolladores/api-rest) para detalles.

---

## Constructor visual de reglas bancarias
> Path: /finanzas/reglas-bancarias-constructor

# Constructor visual de reglas bancarias

El constructor visual de reglas bancarias de Frihet permite crear logica de categorizacion avanzada sin escribir codigo. A diferencia de las [reglas bancarias basicas](./reglas-bancarias) (coincidencia simple por texto), el constructor soporta condiciones anidadas, multiples acciones y division de transacciones entre varias categorias.

Esta funcionalidad esta disponible en plan **Premium o superior**.

## Acceso al constructor

Ve a **Finanzas** → **Reglas bancarias** → **Nueva regla** → **Constructor avanzado**.

## Bloques de condicion

El constructor usa bloques que puedes arrastrar y reorganizar:

### Campos disponibles para condiciones

| Campo             | Tipo                                                    | Ejemplo                          |
| ----------------- | ------------------------------------------------------- | -------------------------------- |
| **Descripcion**   | Texto (contiene / no contiene / es exactamente / regex) | `GOOGLE`, `/^RECIBO\s+LUZ/i`     |
| **Importe**       | Numerico (&gt;, &lt;, =, entre)                         | `> 1000`, `entre 50 y 500`       |
| **Direccion**     | Haber / Debe                                            | entrada o salida                 |
| **Fecha**         | Dia de la semana, rango de fechas                       | `lunes a viernes`, `trimestre 1` |
| **Proveedor**     | Nombre normalizado del proveedor detectado              | `Endesa`, `Hacienda`             |
| **Referencia**    | Referencia 1 o 2 del AEB-43                             | `RF23-00001`                     |
| **Cuenta origen** | Cuenta bancaria de Frihet                               | seleccion de lista               |

### Operadores logicos

Combina condiciones con **Y** (AND) o **O** (OR). Anida bloques para logica compleja:

```
SI (
  descripcion contiene "GOOGLE"
  O descripcion contiene "GSUITE"
)
Y importe > 10
→ ENTONCES: Categoria = Software y SaaS
```

Para crear un bloque anidado, arrastra una condicion sobre otra — aparece el selector AND/OR automaticamente.

## Acciones disponibles

Una regla puede ejecutar varias acciones en secuencia:

| Accion                        | Descripcion                                           |
| ----------------------------- | ----------------------------------------------------- |
| **Asignar categoria**         | Categoria de gasto o ingreso                          |
| **Asignar proyecto**          | Vincula al proyecto o centro de coste                 |
| **Asignar cliente/proveedor** | Identifica la contraparte                             |
| **Crear gasto automatico**    | Genera el gasto en el modulo Gastos                   |
| **Dividir transaccion**       | Reparte el importe entre varias categorias            |
| **Excluir de conciliacion**   | Marca como "no reconciliar" (transferencias internas) |
| **Notificar**                 | Envia alerta Telegram/email al propietario            |

## Division de transacciones

La division es especialmente util para recibos que agrupan conceptos diferentes (alquiler + comunidad, nomina + anticipo):

1. En el bloque de acciones, selecciona **Dividir transaccion**.
2. Define el numero de partes (hasta 10).
3. Para cada parte indica: importe (fijo o porcentaje) y categoria.

```
Transaccion: -1.800 € "TRANSFERENCIA COWORKING ENERO"
Division:
  - 1.200 € → Alquiler oficina
  -   450 € → Luz y agua (incluida en alquiler)
  -   150 € → Servicios adicionales / Limpieza
```

Frihet valida que la suma de partes cuadre con el importe total antes de guardar.

## Orden de prioridad

Las reglas se evaluan en orden de prioridad (numero visible en la lista). La primera regla que coincide gana — las siguientes se ignoran para esa transaccion.

Arrastra las reglas en la lista para cambiar el orden. Las reglas del sistema (presets) aparecen al final y tienen prioridad mas baja por defecto.

## Proveedores Open Banking — Estado Q3 2026

El constructor de reglas se enriquece con datos normalizados cuando tienes una conexion Open Banking activa. La disponibilidad por proveedor es:

| Proveedor                | Estado     | Datos normalizados                | Division auto |
| ------------------------ | ---------- | --------------------------------- | ------------- |
| **Tink** (Visa)          | Disponible | Nombre proveedor, categoria MCC   | Si            |
| **OpenSalt / Salt Edge** | Disponible | Nombre proveedor, logo            | Parcial       |
| **Revolut Business**     | Disponible | Nombre contraparte, referencia    | Si            |
| **Plaid**                | Q3 2026    | Nombre proveedor, categoria Plaid | Planificado   |

:::info Roadmap Q3 2026
Plaid estara disponible en Q3 2026 con soporte para cuentas UK/US y datos de categoria enriquecidos. Si usas Plaid ahora, las reglas funcionan sobre el texto del extracto (sin normalizacion de proveedor).
:::

## Simular una regla antes de activarla

Antes de activar una regla nueva puedes simularla sobre tus ultimas 90 dias de movimientos:

1. En el constructor, haz clic en **Simular**.
2. Frihet muestra las transacciones que habrian sido afectadas con la regla activa.
3. Revisa falsos positivos y ajusta las condiciones.
4. Activa la regla cuando el resultado sea el esperado.

## Gotchas

- **Regex con caracteres especiales**: los acentos en regex requieren el flag `/u`. Ejemplo: `descripcion regex /NÓMINA/u`.
- **Reglas en conflicto**: si dos reglas podrian aplicarse a la misma transaccion, la de menor numero de orden (mayor prioridad) gana siempre. El sistema no advierte de conflictos — usa la simulacion para detectarlos.
- **Division y deduccion de IVA**: cuando divides una transaccion, asigna el IVA/IGIC manualmente a cada parte si las categorias tienen tipos distintos. Frihet no calcula IVA proporcional en divisiones automaticamente.
- **Reglas sobre importaciones AEB-43**: funcionan igual que sobre movimientos Open Banking, pero sin datos de proveedor normalizado.

## Relacionado

- [Reglas bancarias basicas (presets)](./reglas-bancarias)
- [Conciliacion bancaria](./conciliacion-bancaria)
- [Conexiones bancarias Open Banking](./conexiones-bancarias)
- [Importacion AEB-43](./aeb43-norma43)

---

## Reglas bancarias
> Path: /finanzas/reglas-bancarias

# Reglas bancarias

Las reglas bancarias permiten categorizar automaticamente las transacciones importadas segun criterios definidos por ti. En lugar de categorizar cada movimiento a mano, defines la regla una vez y Frihet la aplica a todas las transacciones futuras (y pasadas) que coincidan.

Esta funcionalidad esta disponible en plan **Pro o superior**.

Para configurar las reglas, ve a **Ajustes** → **Reglas bancarias**.

## Como funcionan las reglas

Cada regla tiene dos partes:

1. **Condicion** — Cuando aplica la regla (descripcion contiene, importe, proveedor)
2. **Accion** — Que hace Frihet cuando la condicion se cumple (asignar categoria, excluir, crear gasto)

Frihet evalua las reglas en orden de prioridad. La primera regla que coincide se aplica; el resto se ignoran.

**Ejemplo:**

```
Regla: "Google"
  Condicion: Descripcion contiene "GOOGLE"
  Accion: Categoria → Software y SaaS
```

Cada vez que Frihet importa una transaccion con "GOOGLE" en la descripcion (Google Ads, Google Workspace, Google Cloud), la categoriza automaticamente como Software y SaaS.

## Presets incluidos

Frihet incluye 12 reglas preconfiguradas que puedes activar con un clic:

| Preset                       | Coincide con                         | Categoria                                |
| ---------------------------- | ------------------------------------ | ---------------------------------------- |
| **Google Workspace / Cloud** | GOOGLE                               | Software y SaaS                          |
| **Amazon Business**          | AMAZON, AMZN                         | Material de oficina                      |
| **Seguridad Social**         | SEGURIDAD SOCIAL, TGSS               | Seguridad Social                         |
| **Nominas**                  | NOMINA, NOMINAS, SALARIOS            | Nominas                                  |
| **Combustible**              | REPSOL, CEPSA, BP, GALP              | Combustible                              |
| **Telefonia**                | MOVISTAR, VODAFONE, ORANGE, MASMOVIL | Telefonia                                |
| **Electricidad**             | ENDESA, IBERDROLA, NATURGY           | Electricidad                             |
| **Seguros**                  | MAPFRE, AXA, ALLIANZ, GENERALI       | Seguros                                  |
| **Alquiler oficina**         | ALQUILER, ARRENDAMIENTO              | Alquiler                                 |
| **Microsoft**                | MICROSOFT, MSFT                      | Software y SaaS                          |
| **Stripe**                   | STRIPE                               | Ingresos (entrada) / Comisiones (salida) |
| **Hacienda / AEAT**          | HACIENDA, AGENCIA TRIBUTARIA, AEAT   | Impuestos                                |

Para activar un preset:

1. Ve a **Ajustes** → **Reglas bancarias**
2. Haz clic en **Presets disponibles**
3. Activa los que necesites con el switch

Puedes editar cualquier preset despues de activarlo.

## Crear una regla personalizada

1. Ve a **Ajustes** → **Reglas bancarias**
2. Haz clic en **Nueva regla**
3. Define las condiciones y la accion
4. Guarda

### Condiciones disponibles

Puedes combinar varias condiciones en una sola regla (todas deben cumplirse):

| Condicion       | Operador                                | Ejemplo                         |
| --------------- | --------------------------------------- | ------------------------------- |
| **Descripcion** | Contiene / No contiene / Es exactamente | Descripcion contiene "NETFLIX"  |
| **Importe**     | Mayor que / Menor que / Entre / Igual a | Importe entre 9 y 20 EUR        |
| **Tipo**        | Entrada / Salida                        | Tipo es Salida                  |
| **Cuenta**      | Es / No es                              | Cuenta es "BBVA principal"      |
| **Proveedor**   | Es / Contiene                           | Proveedor contiene "Telefonica" |

**Nota:** La condicion de descripcion no distingue mayusculas de minusculas.

### Acciones disponibles

| Accion                          | Descripcion                                                 |
| ------------------------------- | ----------------------------------------------------------- |
| **Asignar categoria**           | Categoriza la transaccion con la categoria elegida          |
| **Crear gasto automaticamente** | Genera un gasto en Frihet con los datos de la transaccion   |
| **Excluir transaccion**         | Marca la transaccion como excluida (no aparece en reportes) |
| **Asignar proveedor**           | Vincula la transaccion a un contacto existente en Frihet    |
| **Marcar para revision**        | Añade un indicador para revisar manualmente                 |

### Ejemplo: regla con multiples condiciones

```
Regla: "Alquiler mensual oficina"
  Condicion 1: Descripcion contiene "ALQUILER"
  Condicion 2: Importe entre 800 y 1.200 EUR
  Condicion 3: Tipo es Salida
  Accion: Categoria → Alquiler / Crear gasto automaticamente
```

Solo se aplica a transacciones salientes entre 800 y 1.200 EUR con la palabra "ALQUILER". No afecta a depositos de fianza ni a otros arrendamientos de importe diferente.

## Orden de prioridad

Las reglas se evaluan de arriba a abajo. Si dos reglas pueden coincidir con la misma transaccion, gana la de mayor prioridad (mas arriba en la lista).

Para cambiar el orden:

1. Ve a **Ajustes** → **Reglas bancarias**
2. Arrastra las reglas usando el icono de orden (seis puntos) a la izquierda de cada regla
3. Los cambios se guardan automaticamente

**Consejo:** Coloca las reglas mas especificas antes que las genericas. Una regla "GOOGLE ADS" debe ir antes que una regla general "GOOGLE".

## Aprendizaje automatico

Cuando corriges manualmente la categoria de una transaccion, Frihet aprende para el futuro.

**Como funciona:**

1. Frihet importa una transaccion de "MAILCHIMP INC"
2. La categoriza automaticamente como "Marketing"
3. Tu la corriges a "Software y SaaS"
4. Frihet crea internamente una regla aprendida: "MAILCHIMP → Software y SaaS"
5. La proxima transaccion de MAILCHIMP ya se categoriza correctamente

Las reglas aprendidas aparecen en **Ajustes** → **Reglas bancarias** → **Aprendidas** y puedes convertirlas en reglas formales o eliminarlas.

## Aplicar reglas a transacciones existentes

Si creas o modificas una regla, puedes aplicarla a transacciones ya importadas:

1. Abre la regla (editar)
2. Haz clic en **Aplicar a transacciones existentes**
3. Frihet muestra cuantas transacciones coinciden con una previsualizacion
4. Confirma para aplicar

Esto es util cuando configuras reglas por primera vez y tienes meses de transacciones sin categorizar.

## Coincidencia por lotes (batch matching)

Para reconciliar multiples transacciones de golpe:

1. Ve a **Banca** → **Transacciones**
2. Filtra por estado **Pendiente**
3. Selecciona las transacciones que quieras procesar (checkboxes)
4. Haz clic en **Aplicar reglas en lote**
5. Frihet ejecuta todas las reglas activas sobre la seleccion
6. Se muestra un resumen: N transacciones categorizadas, N sin coincidencia

Las transacciones sin coincidencia quedan como Pendientes para revision manual.

## Gestion de reglas

### Activar / desactivar reglas

Cada regla tiene un switch de activacion. Desactivar una regla no la elimina: deja de aplicarse hasta que la reactives. Util para reglas estacionales (ej: gastos de feria anual).

### Duplicar una regla

Si necesitas una regla similar a una existente:

1. Abre la regla
2. Haz clic en **Duplicar**
3. Modifica las condiciones necesarias en la copia

### Exportar / importar reglas

Puedes exportar todas tus reglas como JSON para hacer copia de seguridad o trasladarlas a otra cuenta Frihet:

- **Exportar:** **Ajustes** → **Reglas bancarias** → **Exportar como JSON**
- **Importar:** **Ajustes** → **Reglas bancarias** → **Importar JSON**

## Estadisticas de reglas

En la vista de lista de reglas, cada una muestra:

| Metrica                  | Descripcion                                                                       |
| ------------------------ | --------------------------------------------------------------------------------- |
| **Aplicaciones totales** | Cuantas transacciones ha categorizado esta regla                                  |
| **Ultima aplicacion**    | Fecha de la ultima transaccion que coincidio                                      |
| **Precision**            | Porcentaje de veces que la categorizacion fue correcta (no corregida manualmente) |

Usa estas metricas para identificar reglas poco utiles o con baja precision que conviene revisar.

---

**Anterior:** [Conexiones bancarias](./conexiones-bancarias) | **Siguiente:** [Depositos y anticipos](./depositos)

---

## Categorias de gastos
> Path: /gastos/categorias

# Categorías de gastos

Frihet clasifica tus gastos en categorías fiscales que se mapean directamente a las deductibilidades permitidas por Hacienda.

## Categorías predeterminadas

El sistema viene con categorías estándar para cualquier tipo de negocio:

### Materiales y suministros

- **Materias primas**: Materiales que forman parte del producto final
- **Suministros de oficina**: Papel, tinta, artículos consumibles
- **Embalaje**: Cajas, cintas, protección de envíos
- **Combustibles y carburantes**: Gasolina, diésel para vehículos empresa

Estos gastos son **100% deductibles** de la base imponible del IRPF/Sociedades.

### Servicios profesionales

- **Asesoría y consultoría**: Honorarios de consultores, contables
- **Servicios técnicos**: Reparaciones, mantenimiento de equipos
- **Publicidad y márketing**: Anuncios, diseño, gestión redes sociales
- **Servicios financieros**: Comisiones bancarias, gastos de gestoría

Deductibilidad **100%** si el servicio se relaciona con actividad empresarial.

### Infraestructura y hosting

- **Alquiler de servidor**: Hosting compartido, VPS, cloud
- **Dominios y SSL**: Renovación de dominios, certificados
- **Almacenamiento**: Servidores NAS, backups cloud
- **Herramientas SaaS**: Subscripciones (contabilidad, CRM, email marketing)

Gastos **100% deductibles** como servicios prestados por terceros.

### Vivienda y oficina

- **Alquiler de oficina**: Alquiler total (si es local separado)
- **Alquiler de despacho en casa**: Deducible según m² dedicado
- **Servicios de oficina**: Teléfono, internet, agua, luz (proporcionalmente)
- **Limpieza y mantenimiento**: Servicios de limpieza profesional

Deductibilidad según grado de uso empresarial. La vivienda personal tiene limitaciones.

### Transportes y desplazamientos

- **Combustible**: Gasolina para viajes de negocio
- **Peajes y aparcamiento**: Pagos de peajes, estacionamiento
- **Transporte público**: Billetes de avión, tren, autobús para viajes de negocio
- **Viáticos**: Alojamiento y comidas durante desplazamientos

Deductible **100%** si es desplazamiento directo de negocio. Los desplazamientos de casa a oficina NO son deductibles.

### Otros gastos

- **Seguros empresariales**: Responsabilidad civil, accidentes trabajo
- **Cuotas profesionales**: Colegios profesionales
- **Formación y cursos**: Educación profesional relacionada
- **Libros y revistas**: Material profesional
- **Aportaciones a fondos**: Pensiones privadas, fondos inversión (según regulación)

Deductibilidad según naturaleza específica del gasto.

## Mapeo fiscal automático

Cuando registras un gasto en Frihet:

1. **Seleccionas categoría** → Sistema obtiene la deductibilidad permitida
2. **Aplicamos el tipo fiscal** (IVA/IGIC/IPSI) → Calcula deducción
3. **Generamos asientos** → El gasto aparece en declaración fiscal correctamente

Frihet mantiene actualizado el mapeo según cambios normativos (en plan Premium).

## Crear categoría personalizada

Si necesitas una categoría propia:

1. Ve a **Configuración > Gastos > Categorías personalizadas**
2. Crea nueva categoría con nombre y código
3. Asigna deductibilidad por defecto (0-100%)
4. Aplica a futuros gastos

**Nota**: Las categorías personalizadas se aplican solo a tu cuenta. Para cambios que afecten a todos los usuarios, contacta con soporte.

## Análisis por categoría

En **Reportes > Desglose de gastos**:

- Ve el total gastado por categoría (mes, trimestre, año)
- Compara contra presupuesto si lo has establecido
- Exporta desglose por categoría para tus registros
- Identifica áreas donde puedes optimizar costes

## Cambios normativos

Frihet avisa cuando cambios fiscales afectan a tus categorías. Por ejemplo:

- Cambio de porcentaje de IVA
- Nueva deducción permitida
- Restricción de deductibilidad

Recibe notificación en dashboard y portal de cliente.

---

## Escaneo de recibos con IA
> Path: /gastos/escaneo-ocr

# Escaneo de recibos con IA

Sube una foto de tu recibo o factura y Frihet usa visión artificial (Gemini AI) para extraer automáticamente los datos. Ahorra tiempo escribiendo datos manualmente.

## Cómo funciona

### En móvil

1. Abre Frihet en tu teléfono
2. Ve a **Gastos > Nuevo gasto > Cámara**
3. Apunta la cámara al recibo (asegúrate de que sea legible)
4. Frihet captura la foto y envía a análisis
5. Revisa los datos extraídos y confirma

### En desktop

1. Ve a **Gastos > Nuevo gasto > Subir recibo**
2. Selecciona archivo JPG, PNG o PDF del ordenador
3. Frihet analiza la imagen
4. Revisa y confirma datos

## Datos que extrae la IA

Frihet reconoce automáticamente:

- **Proveedor/empresa**: Nombre del negocio que emitió el recibo
- **Importe total**: Cantidad pagada (con o sin impuestos)
- **Fecha**: Cuándo se realizó la transacción
- **Número de factura**: Referencia interna del recibidor
- **Desglose de impuestos**: IVA, IGIC u otro (si aparece)
- **Concepto**: Descripción del gasto (servicios, productos)

La IA también **detecta automáticamente**:

- Si es factura (documento fiscal) o recibo simple
- Tipo de negocio (restaurante, tienda, servicios)
- Si hay retención IRPF indicada

## Revisar y confirmar

Antes de guardar, Frihet te muestra los datos extraídos:

```
Proveedor:        Telefónica [editable]
Importe:          45,99 EUR [editable]
Fecha:            15 feb 2026 [editable]
Nº Factura:       INV-2026-0145 [editable]
IVA:              21% [editable]
Categoría:        Servicios (detectada)
```

Puedes **editar cualquier campo** si la IA cometió un error. Por ejemplo:

- Si detectó mal el importe (imagen con mala calidad)
- Si confundió la categoría
- Si no extrajo el número de factura

Después de revisar, haz clic **Guardar** y el gasto se registra con archivo adjunto automático.

## Límites por plan

Frihet ofrece escaneo de IA según tu suscripción. Compara los [planes y precios](https://www.frihet.io/es/pricing) para elegir el que mejor se adapte a tu negocio.

| Plan | Escaneos/mes | Límite de tamaño | Soporte |
|------|-------------|-------------------|---------|
| **Free** | 5 | 5 MB | Comunitario |
| **Pro** | 50 | 25 MB | Email (24h) |
| **Premium** | 200 | 100 MB | Priority (4h) |

Si agota escaneos, puedes:
- Esperar al mes siguiente (se restablecen automáticamente)
- Upgradear tu plan
- Registrar el gasto manualmente

## Consejos para mejores resultados

### Foto clara del recibo

- Iluminación suficiente (sin sombras)
- Recibo completamente visible en el encuadre
- Ángulo perpendicular al documento (no oblicuo)
- Sin reflejos de pantalla o flash

### Calidad de la imagen

- Resolución mínima: 2MP (recomendado 8MP+)
- Formato: JPG, PNG o PDF
- Evita documentos muy viejos o degradados (tinta borrosa)

### Documentos problemáticos

Frihet puede tener dificultad con:

- Recibos térmicos muy antiguos (tinta decolorada)
- Documentos con muchos idiomas mezclados
- Logos o imágenes que ocupan el 80%+ de la página
- Escritura a mano

En esos casos, rellena manualmente (es más rápido que esperar a que falle la IA).

## Privacidad y seguridad

- Las imágenes se envían a Google Gemini API para análisis
- Se procesan de forma **anónima** (sin asociar a tu cuenta antes del análisis)
- Los archivos se borran de los servidores de Google **tras 30 minutos**
- Tu conexión es **HTTPS encriptada**
- El archivo adjunto se guarda en tus servidores Frihet (no en Google)

Frihet **nunca** vende datos de escaneos a terceros.

## Solucionar problemas

### "No se detectó ningún recibo"

- Comprueba que es un recibo/factura real (no foto de pantalla)
- Sube una versión más clara
- Intenta manualmente si la imagen es muy antigua

### "Importe incorrecto"

- La IA probablemente confundió impuestos con total
- Edita el campo **Importe** antes de confirmar
- Si ocurre frecuentemente con un proveedor, avisa a soporte

### "Se agotaron escaneos"

- Cambia a plan superior
- O registra manualmente (lleva 30 segundos por recibo)

## Próximas mejoras

Estamos trabajando en:

- Escaneo de **múltiples recibos** en una foto
- Extracción de **detalles de línea** (producto, cantidad, precio unitario)
- Reconocimiento de **QR** en facturas electrónicas
- Importación automática desde **correo electrónico** (facturas recibidas)

---

## Gastos facturables
> Path: /gastos/gastos-facturables

<!-- AUTO-STUB 2026-05-05 -->

# Gastos facturables

> Registra gastos que corren a cargo del cliente — viajes, materiales, subcontratas — márcalos como facturables y añádelos a la siguiente factura sin volver a introducir datos.

## Overview

Cuando incurres en gastos por cuenta de un cliente (suplidos, desplazamientos, alojamiento, materiales), Frihet te permite marcarlos como facturables en el momento de registrarlos. Al crear la factura para ese cliente, aparecerá la lista de gastos facturables pendientes para añadirlos con un clic — ya con el importe, descripción y fecha correctos.

Los gastos facturables también se registran contablemente de forma correcta: primero como gasto, luego como ingreso al incluirse en la factura.

## Quick start

1. Al registrar un gasto, activa el switch **Facturable** y selecciona el cliente al que pertenece.
2. Al crear la siguiente factura para ese cliente, pulsa **Añadir gastos facturables** en el formulario.
3. Selecciona los gastos pendientes y confírmalos — se añaden como líneas de factura automáticamente.

## Reference

- API: `PATCH /v1/expenses/:id` (campo `billable: true, clientId`) — ver [API reference](/desarrolladores/api-rest)
- MCP tool: `mark_expense_billable` — ver [MCP reference](/desarrolladores/mcp-server)

## Related

- [Registrar gastos](./registrar-gastos)
- [Categorías de gastos](./categorias)
- [Crear facturas](/facturacion/facturas)

---

## Gastos recurrentes
> Path: /gastos/gastos-recurrentes

# Gastos recurrentes

Configura gastos automáticos para servicios y pagos que se repiten cada mes, trimestre o año. Frihet registra automáticamente cada ocurrencia en la fecha correcta.

## Crear gasto recurrente

### Paso 1: Accede al formulario

Ve a **Gastos > Nuevo recurrente** o desde un gasto existente haz clic en **Convertir a recurrente**.

### Paso 2: Define el gasto base

Especifica los datos que se repiten:

- **Proveedor**: Amazon, Telefónica, Oficina Catastral, etc.
- **Importe**: Cantidad fija (si varía cada mes, deberás editar manualmente)
- **Categoría**: Clasificación fiscal (servicios, alquiler, seguros)
- **Tipo de impuesto**: IVA/IGIC/Exento según corresponda
- **Número de factura**: Patrón opcional (ej: `INV-{YYYY}-{MM}` genera INV-2026-02)
- **Descripción**: Detalle del gasto (ej: "Hosting Cloud Platform")

### Paso 3: Configura la frecuencia

Elige cuándo se repite:

- **Mensual**: Día fijo cada mes (ej: 1º de cada mes, 15º)
- **Bimensual**: Cada 2 meses
- **Trimestral**: 4 veces al año (ej: 10 ene, 10 abr, 10 jul, 10 oct)
- **Semestral**: 2 veces al año
- **Anual**: Una vez cada año

Si el día seleccionado no existe (ej: 31 de mes con 30 días), Frihet ajusta automáticamente al último día disponible.

### Paso 4: Define fechas de inicio y fin

- **Comienza**: Primera ocurrencia del gasto
- **Termina**: Cuándo deja de repetirse (obligatorio, previene gastos fantasma)
  - Si es indefinido, pon una fecha lejana (ej: 2099)
  - Si cancelas un servicio, actualiza esta fecha

## Ejemplos de gastos recurrentes

### Alquiler de oficina

- Proveedor: `Tu arrendador`
- Importe: 1.200 EUR
- Frecuencia: Mensual, día 1
- Categoría: Alquiler de oficina
- Período: 2026-01-01 a 2027-12-31 (contrato 2 años)

### Subscripción SaaS

- Proveedor: `Stripe`
- Importe: 29 EUR
- Frecuencia: Mensual, día 15
- Categoría: Herramientas SaaS
- Período: 2026-02-15 a indefinido (aún activa)

### Seguro empresarial

- Proveedor: `AXA Seguros`
- Importe: 450 EUR
- Frecuencia: Anual, 1 de enero
- Categoría: Seguros empresariales
- Período: 2025-01-01 a 2026-12-31 (2 años de póliza)

### Cuota profesional trimestral

- Proveedor: `Colegio Profesional Abogados`
- Importe: 120 EUR
- Frecuencia: Trimestral
- Categoría: Cuotas profesionales
- Período: 2026-01-01 a 2099-12-31 (indefinido)

## Gestión de recurrentes

### Ver tus gastos recurrentes

Ve a **Gastos > Recurrentes** para ver una lista de todos tus gastos automáticos:

- **Siguiente ocurrencia**: Cuándo se registrará el próximo gasto
- **Última ocurrencia**: Cuándo fue la última (útil para auditoría)
- **Próximos 3 meses**: Vista rápida de gastos programados
- **Total anual**: Estimado del gasto anual (importe × 12 / frecuencia)

### Editar o pausar

Si cambia el importe o necesitas pausar temporalmente:

1. Selecciona el gasto recurrente
2. Haz clic en **Editar**
3. Modifica el importe o la fecha de término
4. Confirma

Los cambios se aplican **a partir de la siguiente ocurrencia**. Los gastos registrados en el pasado no se modifican.

Para pausar sin eliminar:

1. Abre el gasto recurrente
2. Establece **Termina** en fecha de hoy
3. Crea uno nuevo cuando se reactive

### Eliminar

Si cancelas un servicio:

1. Abre el gasto recurrente
2. Haz clic en **Eliminar** o establece **Termina** en fecha de hoy
3. Los gastos anteriores se mantienen en tu historial

## Gastos variables

Si el importe cambia cada mes (ej: factura de luz/agua), Frihet ofrece:

### Opción 1: Reclasificar manualmente

Registra el recurrente con importe promedio y **edita cada mes** con el importe real.

### Opción 2: No usar recurrente

Registra manualmente cada gasto cuando llega la factura. Lleva 20 segundos.

### Opción 3: Importación de banco

Si tu banco exporta a Frihet, los gastos se detectan automáticamente (algunos bancos lo soportan en plan Premium).

## Estados de recurrente

Cada gasto automático tiene estado:

- **Activo**: Se registra automáticamente cada período
- **Pausado**: Pausado temporalmente (no genera gastos nuevos, pero mantiene histórico)
- **Finalizado**: Término alcanzado o eliminado manualmente
- **Fallido**: Error al registrar (ej: falta de fondos en banco) — requiere intervención

Los fallos se notifican en **Notificaciones** para que corrijas manualmente.

## Impacto fiscal

### Declaración de impuestos

Los gastos recurrentes registrados automáticamente aparecen en:

- Resumen de deducción mensual
- Informe anual de gastos por categoría
- Exportación para declaración (modelo 130, 347, etc.)

Son tratados como gastos normales para propósitos fiscales.

### Cash flow

Frihet genera un gráfico de flujo de caja previsto en **Reportes > Predicción** que incluye:

- Gastos recurrentes futuros
- Ingresos proyectados
- Saldo previsto para los próximos 3, 6, 12 meses

Útil para planificación financiera.

## Automación avanzada (plan Premium)

En plan Premium, puedes:

- **Exportar gastos recurrentes** a herramientas de contabilidad
- **Configurar alertas** antes de gastar (ej: aviso 7 días antes del pago)
- **Vincular a presupuesto** (si supera límite, alerta automática)
- **Integración con API**: Consulta gastos programados vía API REST

Contacta con soporte para configurar.

---

## Registrar gastos
> Path: /gastos/registrar-gastos

# Registrar gastos

Registra cada gasto de tu negocio manualmente con todos los detalles fiscales necesarios. Frihet mantiene un registro completo para deducción de impuestos y auditoría.

## Campos obligatorios

Al crear un gasto debes especificar:

- **Proveedor**: Nombre del vendedor o empresa
- **Importe**: Cantidad gastada (sin decimales innecesarios)
- **Fecha**: Día en que se realizó el gasto
- **Categoría**: Clasificación fiscal (materiales, servicios, suministros, etc.)

## Configuración fiscal

### Tipo de IVA

Selecciona el régimen que aplica a este gasto:

- **IVA**: Impuesto sobre Valor Añadido (21%, 10%, 4% según el producto/servicio)
- **IGIC**: Impuesto General Indirecto Canario (aplicable en Canarias)
- **IPSI**: Impuesto sobre la Producción, los Servicios y la Importación (Ceuta y Melilla)
- **Exento**: Gasto sin derecho a deducción de impuesto

El sistema calcula automáticamente la deducción permitida según el tipo seleccionado.

### Retención IRPF

Si el gasto está sujeto a retención de IRPF (ej: servicios de profesionales, trabajos autónomos), especifica:

- **Porcentaje de retención**: 15%, 19%, 21% según el tipo de servicio
- **Base imponible**: El sistema deduce automáticamente del importe total

Frihet genera automáticamente los justificantes de retención para reconciliación fiscal.

## Detalles adicionales

- **Número de factura**: Referencia del documento original (obligatorio para auditoría)
- **Descripción**: Concepto del gasto (ej: "Servicio de hosting mes de febrero")
- **Archivos adjuntos**: Sube el recibo o factura escaneada (PDF, JPG, PNG)

Los archivos adjuntos se almacenan de forma segura y están disponibles para descargar en cualquier momento.

## Búsqueda y filtrado

Encuentra gastos rápidamente:

- Filtra por **rango de fechas** (este mes, trimestre, año fiscal)
- Busca por **proveedor** o **número de factura**
- Agrupa por **categoría** para analizar gastos
- Ordena por **importe** o **fecha**

## Estados del gasto

Cada gasto tiene un estado:

- **Borrador**: No validado fiscalmente
- **Confirmado**: Registrado y listo para deducción
- **Conciliado**: Apareado con banco si la importación lo detectó

Pasar un gasto a "Confirmado" lo bloquea contra ediciones accidentales y lo incluye en cálculos fiscales.

---

## Consultas sobre tus datos
> Path: /ia/consultas-datos

# Consultas sobre tus datos

Pregunta al asistente sobre tus datos financieros. Devuelve respuestas en **KPI cards**, tablas o análisis de texto.

## Ejemplos de consultas

### Ingresos y facturación

**"¿Cuánto he facturado este trimestre?"**
- El asistente suma todas tus facturas del trimestre actual
- Devuelve un KPI card con el total
- Incluye comparativa con trimestre anterior

**"¿Cuánto he facturado este mes vs el mes pasado?"**
- Comparativa mes a mes
- Porcentaje de cambio
- Gráfico de tendencia

**"¿Cuántas facturas tengo en enero?"**
- Cantidad de facturas
- Total facturado en enero
- Desglose por cliente

### Clientes y ventas

**"¿Quién es mi mejor cliente?"**
- Cliente que más ha gastado
- Monto total en relación contigo
- Número de facturas
- Mes en que más compró

**"¿Cuál es mi cliente más frecuente?"**
- Cliente con más facturas
- Promedio de factura
- Última compra

**"¿Cuáles son mis top 5 clientes?"**
- Ranking por monto facturado
- Cada uno con su total y número de facturas
- Tendencia (subiendo o bajando)

**"¿Cuántos clientes tengo activos?"**
- Conteo de clientes con al menos 1 factura este año
- Clientes inactivos (sin actividad > 6 meses)
- Nuevos clientes este mes

### Vencimientos y cobros

**"¿Cuántas facturas vencidas tengo?"**
- Listado de facturas sin pagar
- Monto total vencido
- Cliente y fecha de vencimiento

**"¿Cuál es mi próximo vencimiento?"**
- Facturas por vencer en los próximos 30 días
- Monto total
- Ordenadas por fecha

**"¿Cuánto cobré el mes pasado?"**
- Total de pagos recibidos
- Por cliente
- Tasa de cobro (% de lo que facturaste)

**"¿Quién debe más dinero?"**
- Clientes con facturas impagadas
- Monto adeudado por cada uno
- Días desde vencimiento

### Gastos y costes

**"¿Cuáles son mis gastos este mes?"**
- Total de gastos registrados
- Desglose por categoría
- Mayor gasto individual

**"¿Cuáles son mis gastos más comunes?"**
- Categorías con más gastos
- Promedio por categoría
- Comparativa mes a mes

**"¿Cuánto gasto en [categoría]?"**
- Total en una categoría específica
- Puede ser: Material, Servicios, Viajes, etc.
- Últimas transacciones en esa categoría

**"¿Cuál es mi margen?"**
- Ingresos - Gastos = Beneficio
- Porcentaje de margen
- Desglose por cliente si quieres

### Impuestos y retención

**"¿Cuántos impuestos debo?"**
- Simulación de IVA a pagar
- IRPF estimado si procede
- Base imponible

**"¿Cuál es mi situación fiscal?"**
- Resumen de facturas con y sin IVA
- Deuda fiscal estimada
- Próximo vencimiento de declaración

**"¿Qué retenciones me han hecho?"**
- Total de retenciones IRPF
- Por cliente o por período
- Retenciones pendientes

### Análisis y tendencias

**"¿Cuál es mi promedio de factura?"**
- Monto promedio por documento
- Comparado con meses anteriores
- Indicador de si tus precios suben/bajan

**"¿Cuál es mi facturación proyectada este año?"**
- Extrapolación basada en el promedio actual
- Comparada con años anteriores (si existen datos)

**"¿Cuáles son mis épocas bajas?"**
- Meses con menos ingresos
- Meses con más gastos
- Recomendaciones para estabilizar

## Formatos de respuesta

El asistente devuelve respuestas en varios formatos:

### KPI Cards

Para métricas simples:

```
📊 Facturación este trimestre
€15.340,00

↑ 12% vs trimestre anterior
```

### Tablas

Para comparativas o listados:

| Cliente | Monto | Facturas | Última compra |
|---------|-------|----------|---------------|
| Empresa A | €5.200 | 8 | 15 ene 2025 |
| Juan Garcia | €3.100 | 5 | 8 ene 2025 |

### Gráficos

Para tendencias (en chat visual):

- Facturación por mes
- Gastos vs ingresos
- Top clientes

### Análisis de texto

Para preguntas complejas con contexto:

> "Tus ingresos han crecido un 23% este trimestre. Principalmente gracias a dos clientes: Empresa A (+€2.400) y Startup B (+€1.800). Sin embargo, tus gastos también subieron un 15%, principalmente en Material (€350 más). Tu margen actual es del 68%."

## Preguntas más complejas

### Comparativas personalizadas

**"¿Cómo fue enero respecto a diciembre?"**
- Ingresos: Enero vs Diciembre
- Gastos: Enero vs Diciembre
- Margen: Comparativa

**"¿Qué clientes son más rentables?"**
- Si conoces costes asociados a cada cliente
- Calcula margen por cliente
- Sugiere dónde enfocarse

### Proyecciones

**"¿Cuándo alcanzaré los €10.000 mensuales?"**
- Basado en tu crecimiento actual
- Con tendencia lineal o exponencial

**"¿Cuál será mi mejor mes del año?"**
- Análisis estacional
- Recomendación de cuándo lanzar campañas

## Limitaciones

El asistente **no puede**:

- Acceder a datos de integraciones de terceros (Stripe, Shopify, etc.) — solo tus facturas y gastos manuales
- Comparar con competidores
- Predecir el futuro con 100% de precisión
- Hacer análisis que requieren más de 12 meses de datos (si es tu primer mes)

## Consejos para mejores análisis

✅ **Sé claro en lo que quieres:**
- "¿Cuánto facturé en enero?" (bueno)
- "¿Cómo van los números?" (vago)

✅ **Especifica períodos:**
- "Este trimestre" vs "Este año" vs "Los últimos 90 días"

✅ **Mantén tus gastos categorizados:**
- Permite análisis más profundos
- El asistente puede sugerir optimizaciones

✅ **Registra datos regularmente:**
- Mejor análisis con más datos históricos
- Las tendencias se ven más claras

---

**Siguiente paso:** [Subir documentos al chat](./subir-documentos)

---

## Crear facturas por texto
> Path: /ia/crear-facturas-por-texto

# Crear facturas por texto

El asistente IA convierte texto natural en facturas completas. Escribe como hablarías y confirma antes de guardar.

## Ejemplos rápidos

### Ejemplo 1: Factura simple

**Tú:**
> Crea factura para Juan Garcia por 500 euros de diseño web

**El asistente:**
- Detecta cliente: Juan Garcia (o crea uno nuevo)
- Concepto: Diseño web
- Importe: €500,00
- Fecha: Hoy
- Te muestra preview para confirmar

### Ejemplo 2: Factura con múltiples líneas

**Tú:**
> Factura a Empresa SL: 10 horas de consultoría a 80 euros la hora, más 200 de gastos de viaje

**El asistente:**
- Detecta cliente: Empresa SL
- Línea 1: Consultoría - 10 h × €80 = €800
- Línea 2: Gastos de viaje - €200
- Total: €1.000,00

### Ejemplo 3: Factura con IVA específico

**Tú:**
> Crea factura para María Rodriguez, 1500 euros de servicios de traducción, IVA 21%

**El asistente:**
- Cliente: María Rodriguez
- Base: €1.500,00
- IVA (21%): €315,00
- Total: €1.815,00

## Elementos que reconoce

El asistente extrae automáticamente:

| Elemento | Ejemplos |
|----------|----------|
| **Cliente** | "Juan Garcia", "Empresa SL", "El cliente que vino ayer" |
| **Concepto** | "Diseño web", "10 horas de consultoría", "Reparación de ordenador" |
| **Cantidad** | "500 euros", "1.500€", "10 horas a 80 la hora" |
| **Fecha** | "Hoy", "30 de enero", "Próxima semana" |
| **IVA** | "Con IVA", "Exento de IVA", "IVA 21%" |
| **Notas** | "Pago a 30 días", "Condiciones especiales" |

## Flujo de creación

1. **Escribe tu petición** en el chat
2. **El asistente interpreta** los datos
3. **Revisa el preview** (cliente, concepto, importe, fecha)
4. **Confirma o corrige** antes de guardar
5. **La factura se crea** automáticamente

Si algo no es exacto:

- Puedes editar directamente en el preview
- O decir "Corrige el cliente a..." y el asistente ajusta
- Las cantidades se recalculan automáticamente

## Funciona también para gastos y presupuestos

### Crear gastos

**Tú:**
> Registra gasto de 45 euros en Material de oficina, hoy

**El asistente:**
- Gasto: €45,00
- Categoría: Material de oficina (detectada automáticamente)
- Fecha: Hoy

### Crear presupuestos

**Tú:**
> Presupuesto a Cliente SL: 5 horas de desarrollo a 120 euros, válido hasta fin de mes

**El asistente:**
- Cliente: Cliente SL
- Línea: Desarrollo - 5 h × €120 = €600
- Fecha vencimiento: Fin de mes
- Estado: Presupuesto (no facturado)

## Consejos para mejores resultados

### Sé específico

❌ "Crea una factura"
✅ "Crea factura para Juan Garcia por 500 euros de diseño web"

### Incluye cantidades claras

❌ "Cobrar algo por trabajar"
✅ "500 euros de diseño" o "10 horas a 80 euros"

### Menciona el cliente por su nombre

El asistente busca clientes existentes:

- "Juan Garcia" → busca en tus contactos
- Si no existe, pregunta antes de crear

### Usa formatos naturales para dinero

Todos estos funcionan:
- "500 euros"
- "500€"
- "500,00"
- "quinientos euros"

## Casos especiales

### Cliente nuevo

Si mencionas un cliente que no existe, el asistente:

- Confirma que es nuevo
- Te permite agregar datos fiscales (opcional)
- Crea el contacto automáticamente

### Descuentos y recargos

**Tú:**
> Factura a Juan Garcia: 1000 euros de servicios, con 10% descuento

**El asistente:**
- Base: €1.000,00
- Descuento (-10%): -€100,00
- Total: €900,00

### Múltiples conceptos en una línea

**Tú:**
> Factura a Empresa SL: 20 horas de consultoría a 75 euros, 8 horas de desarrollo a 100 euros

**El asistente:**
- Línea 1: Consultoría - 20 h × €75 = €1.500
- Línea 2: Desarrollo - 8 h × €100 = €800
- Total: €2.300

## Después de crear

Una vez confirmada la factura:

- Se guarda automáticamente
- Puedes editarla desde el listado de facturas
- Se sincroniza con tus integraciones (si conectaste Stripe, etc.)
- Aparece en tus reportes financieros

---

**Siguiente paso:** [Consultar datos sobre tus facturas](./consultas-datos)

---

## Exportar datos desde el chat
> Path: /ia/exportar-datos

# Exportar datos desde el chat

Exporta tus datos a CSV o PDF sin salir del chat. El asistente genera el archivo y te lo entrega como descarga directa.

## Herramientas de exportación

| Herramienta | Formato | Datos que exporta |
|-------------|---------|-------------------|
| `exportToCSV` | CSV (compatible con Excel, Sheets, Numbers) | Facturas, gastos, presupuestos, clientes, productos |
| `exportToPDF` | PDF | Resúmenes financieros, listados, informes |

## Ejemplos de uso

### Exportar facturas a CSV

```
"Exporta mis facturas de enero a marzo a CSV"
```

El asistente genera un archivo CSV con todas las facturas del período, incluyendo: número, cliente, fecha, importe, IVA, total y estado.

### Exportar gastos a PDF

```
"Exporta el resumen de gastos de este trimestre a PDF"
```

Genera un PDF con el desglose por categoría, totales y período.

### Exportar clientes

```
"Exporta todos mis clientes a CSV"
```

Incluye: nombre, email, NIF/CIF, dirección, teléfono y total facturado.

### Exportar productos

```
"Exporta mi catálogo de productos a CSV"
```

Incluye: nombre, descripción, precio unitario, unidad, tipo impositivo y SKU.

## Filtros disponibles

Puedes aplicar filtros en lenguaje natural:

- **Por período**: "facturas de Q1", "gastos de marzo", "este año"
- **Por estado**: "facturas pagadas", "facturas pendientes", "borradores"
- **Por cliente**: "facturas de Acme SL"
- **Por categoría**: "gastos de Software", "gastos de Viajes"
- **Por importe**: "facturas de más de 1.000 euros"

## Formato CSV

Los archivos CSV se generan con:

- Separador: punto y coma (`;`) — compatible con Excel en español
- Codificación: UTF-8 con BOM
- Decimales: coma (`,`) para importes
- Fechas: formato `DD/MM/YYYY`

## Flujo de descarga

1. Pide la exportación en el chat
2. El asistente procesa los datos y genera el archivo
3. Aparece un enlace de descarga en la conversación
4. Descarga el archivo (disponible durante 24 horas)

---

**Siguiente paso:** [Impuestos y fiscalidad desde el chat](./impuestos-ia)

---

## Impuestos y fiscalidad
> Path: /ia/impuestos-ia

# Impuestos y fiscalidad desde el chat

El asistente conoce el sistema fiscal español y puede calcular tus obligaciones trimestrales directamente en el chat. No necesitas abrir otra pantalla ni consultar manuales.

## Herramientas fiscales

| Herramienta | Qué calcula | Cuándo usarla |
|-------------|-------------|---------------|
| `calculateModelo303` | IVA trimestral (Modelo 303) | Antes de presentar la autoliquidación trimestral de IVA |
| `calculateModelo130` | IRPF trimestral (Modelo 130) | Antes del pago fraccionado trimestral de autónomos |
| `getTaxCalendar` | Plazos fiscales próximos | Para saber cuándo vencen tus obligaciones |

## Calcular el Modelo 303 (IVA)

```
"Calcula mi Modelo 303 del primer trimestre"
```

El asistente:

1. Recopila todas tus facturas emitidas del trimestre
2. Calcula el IVA devengado por tipo (21%, 10%, 4%)
3. Recopila tus gastos deducibles con IVA soportado
4. Calcula la diferencia: IVA devengado - IVA soportado
5. Muestra el resultado a ingresar o a devolver

### Ejemplo de respuesta

```
Modelo 303 — Q1 2026

IVA devengado
  Base 21%:    12.500,00 EUR → IVA: 2.625,00 EUR
  Base 10%:     2.000,00 EUR → IVA:   200,00 EUR
  Total devengado:              2.825,00 EUR

IVA soportado
  Gastos deducibles:            1.340,00 EUR

Resultado:    1.485,00 EUR (a ingresar)
Plazo:        Hasta 20 abril 2026
```

## Calcular el Modelo 130 (IRPF)

```
"¿Cuánto debo de IRPF este trimestre?"
```

El asistente:

1. Suma tus ingresos (rendimiento neto) del trimestre
2. Aplica el 20% de pago fraccionado
3. Resta retenciones practicadas por clientes
4. Resta pagos de trimestres anteriores del mismo ejercicio
5. Muestra el resultado

### Ejemplo de respuesta

```
Modelo 130 — Q1 2026

Rendimiento neto acumulado:    14.500,00 EUR
Pago fraccionado (20%):         2.900,00 EUR
Retenciones soportadas:           870,00 EUR
Pagos anteriores:                   0,00 EUR

Resultado:    2.030,00 EUR (a ingresar)
Plazo:        Hasta 20 abril 2026
```

## Calendario fiscal

```
"¿Cuándo tengo que presentar impuestos?"
```

El asistente muestra los plazos próximos según tu zona fiscal:

| Modelo | Período | Plazo |
|--------|---------|-------|
| 303 (IVA) | Q1 | 1-20 abril |
| 303 (IVA) | Q2 | 1-20 julio |
| 303 (IVA) | Q3 | 1-20 octubre |
| 303 (IVA) | Q4 | 1-30 enero (año siguiente) |
| 130 (IRPF) | Q1-Q4 | Mismos plazos que el 303 |
| 390 (resumen anual IVA) | Anual | 1-30 enero |
| 420 (IGIC) | Q1-Q4 | Mismos plazos (solo Canarias) |

## Qué sabe el asistente sobre impuestos

### Tipos impositivos

- **IVA** — Península y Baleares: 21% (general), 10% (reducido), 4% (superreducido)
- **IGIC** — Canarias: 7% (general), 3% (reducido), 0% (tipo cero)
- **IPSI** — Ceuta y Melilla: tipos específicos
- **IRPF** — 15% retención general, 7% nuevos autónomos (primeros 3 años)

### Zonas fiscales

El asistente aplica el régimen correcto según la zona fiscal configurada en tu cuenta:

- **Península y Baleares** — IVA + Modelo 303
- **Canarias** — IGIC + Modelo 420
- **Ceuta y Melilla** — IPSI

### Operaciones especiales

El asistente identifica automáticamente:

- Operaciones intracomunitarias (sin IVA, inversión del sujeto pasivo)
- Exportaciones (exentas de IVA)
- Recargo de equivalencia
- Operaciones con retención IRPF

### Reglas de VeriFactu

Si tienes VeriFactu activo, el asistente lo tiene en cuenta al calcular. Los cálculos fiscales se basan en facturas con cadena de hash válida.

## Limitaciones

Los cálculos del asistente son **simulaciones orientativas**. No sustituyen la declaración oficial ante la AEAT. Consulta siempre con tu asesor fiscal antes de presentar.

Para la referencia completa sobre cumplimiento fiscal en Frihet, consulta:

- [Modelo 303 (IVA)](/cumplimiento/modelo-303)
- [Modelo 130 (IRPF)](/cumplimiento/modelo-130)
- [Modelo 420 (IGIC)](/cumplimiento/modelo-420)
- [VeriFactu](/cumplimiento/verifactu)

---

**Siguiente paso:** [Operaciones masivas](./operaciones-masivas)

---

## AI Insights — Deteccion de anomalias
> Path: /ia/insights-anomalias

# AI Insights — Deteccion de anomalias

AI Insights analiza continuamente tus datos financieros y detecta variaciones significativas respecto al trimestre anterior (QoQ — Quarter over Quarter). Cuando una metrica sale del patron esperado, Frihet la marca como anomalia y genera una explicacion en lenguaje natural con Gemini.

El objetivo no es alarmar, sino darte contexto antes de que tengas que buscarlo.

## Que metricas analiza Frihet

| Categoria         | Metrica                       | Umbral de alerta por defecto      |
| ----------------- | ----------------------------- | --------------------------------- |
| **Ingresos**      | Facturacion mensual total     | > 20% variacion QoQ               |
| **Ingresos**      | Ticket medio por cliente      | > 15% caida QoQ                   |
| **Gastos**        | Gastos por categoria          | > 30% aumento en una categoria    |
| **Margen**        | Margen bruto                  | > 10 puntos porcentuales de caida |
| **Cobros**        | Dias de cobro medio (DSO)     | > 15 dias aumento QoQ             |
| **Fiscal**        | IVA devengado vs. facturacion | > 5% desviacion                   |
| **Flujo de caja** | Saldo proyectado 30 dias      | < umbral configurado              |
| **Clientes**      | Clientes activos              | > 10% caida QoQ                   |

Los umbrales son configurables en **IA** → **Insights** → **Configuracion de alertas**.

## Como funciona la deteccion

1. **Calculo de deltas QoQ**: Frihet compara cada metrica con el mismo periodo del trimestre anterior y con la media movil de los ultimos 4 trimestres.
2. **Puntuacion de anomalia**: se calcula una puntuacion (0-100) combinando la magnitud de la variacion y la consistencia historica. Solo las anomalias con puntuacion > 60 se muestran en la interfaz.
3. **Clasificacion**: `Critica` (>85), `Alta` (70-85), `Media` (60-70).
4. **Generacion de explicacion**: Gemini recibe el delta, el contexto de los ultimos 4 trimestres y los datos anonimizados (ver seccion GDPR) y genera una explicacion en espanol.

## Panel de Insights

Accede desde **IA** → **Insights** o desde el **Dashboard** → bloque Insights (si esta activado).

El panel muestra las anomalias activas ordenadas por severidad:

```
CRITICA  Gastos de marketing +47% QoQ
         "El gasto en marketing de este trimestre (€8.450) es un 47% superior
          al trimestre anterior (€5.750). La mayor parte del incremento proviene
          de la categoria 'Meta Ads' (+€2.100) registrada en los ultimos 15 dias."
         [Ver detalle] [Marcar como revisada] [Ajustar umbral]

ALTA     Dias de cobro medio 68 dias (+18 vs Q1)
         "El periodo medio de cobro ha aumentado de 50 a 68 dias. Los clientes
          con mayor impacto son Empresa A (90 dias) y Empresa B (85 dias),
          que representan el 40% de la facturacion pendiente."
         [Ver clientes] [Marcar como revisada]
```

## Privacidad y GDPR — IDs opacos

Cuando Gemini genera las explicaciones, Frihet **nunca envia** nombres de clientes, NIFs, CIFs o datos de identificacion directa al modelo. Todos los identificadores se sustituyen por IDs opacos antes de la llamada a la API:

```
Datos enviados a Gemini (anonimizados):
{
  "client_id": "c_8f2a1b",     // no "EMPRESA EJEMPLO SL"
  "amount": 12450.00,
  "period": "Q1-2026",
  "category": "marketing"
}
```

La sustitucion y re-identificacion ocurre en los servidores de Frihet (Europa). Gemini solo recibe datos numericos y categoricos — nunca informacion personal identificable.

:::info Base legal GDPR
El procesamiento para Insights se basa en el **interes legitimo** del responsable del tratamiento (art. 6.1.f RGPD): mejorar la gestion financiera de la empresa usuario. Los datos de clientes (terceros) se anonimizan antes de salir del entorno controlado de Frihet. Ver [Politica de privacidad](../legal/privacidad).
:::

## Explicaciones de Gemini — como interpretarlas

Las explicaciones son orientativas, no diagnosticos definitivos. Gemini no tiene acceso al contexto completo de tu negocio — no sabe si lanzaste una campana intencionada, si tuviste una baja estacional o si firmaste un contrato nuevo.

Cada explicacion incluye un nivel de confianza:

- **Alta confianza**: el modelo tiene suficiente historico (>4 trimestres) y la variacion es consistente con un patron detectado.
- **Media confianza**: historico limitado o variacion atipica sin patron previo.
- **Baja confianza**: primer trimestre o datos insuficientes — la explicacion es especulativa.

Puedes proporcionar contexto adicional a Gemini pulsando **Anadir contexto** en la tarjeta de anomalia. Ese contexto se incluye en la siguiente generacion de explicacion para esa metrica.

## Alertas y notificaciones

Configura cuando quieres ser notificado:

1. Ve a **IA** → **Insights** → **Alertas**.
2. Selecciona los canales: email, notificacion push (movil), Telegram.
3. Define la frecuencia: en tiempo real, resumen diario (08:00) o resumen semanal (lunes 09:00).
4. Filtra por severidad minima: recibir solo Criticas, Criticas+Altas, o todas.

El **resumen semanal de insights** es el formato recomendado para la mayoria de usuarios — evita el ruido de alertas individuales y presenta todas las anomalias de la semana en un solo email/mensaje.

## Marcar como revisada

Cuando has revisado una anomalia y entiendes la causa, marcala como **Revisada** con una nota opcional. Esto:

- La mueve al historial (ya no aparece en el panel activo).
- La nota queda registrada en el expediente de la metrica.
- Si la anomalia persiste el trimestre siguiente, aparece de nuevo automaticamente.

## Gotchas

- **Primer trimestre con Frihet**: con menos de 2 trimestres de datos, los deltas QoQ no pueden calcularse. Insights muestra un mensaje informativo y no genera alertas hasta tener datos suficientes.
- **Empresa estacional**: si tu negocio tiene alta estacionalidad (turismo, hosteleria, agricultura), los deltas QoQ pueden disparar muchas alertas falsas en temporada alta/baja. Ajusta los umbrales o usa la comparacion **YoY** (ano contra ano) en lugar de QoQ desde **Insights** → **Configuracion** → **Modo comparacion**.
- **Categorias sin historial**: una categoria de gasto nueva (sin datos en trimestres anteriores) genera un falso positivo de +100%. Frihet marca estas anomalias con etiqueta **Nueva categoria** y las excluye del calculo de severidad.
- **Latencia de datos**: los insights se recalculan cada 6 horas. Un gasto registrado ahora puede tardar hasta 6 horas en aparecer en el panel de insights.

## Relacionado

- [Que puede hacer el asistente IA](./que-puede-hacer)
- [Dashboard fiscal](../dashboard-fiscal)
- [Informes de cumplimiento](../informes/informes-cumplimiento)
- [Prevision de tesoreria](../informes/prevision-tesoreria)

---

## Operaciones masivas
> Path: /ia/operaciones-masivas

# Operaciones masivas

Actualiza o elimina varios registros a la vez desde el chat. Todas las operaciones masivas requieren **confirmación explícita** antes de ejecutarse.

## Herramientas disponibles

| Herramienta | Qué hace | Registros afectados |
|-------------|----------|---------------------|
| `bulkUpdateInvoices` | Cambia el estado de varias facturas | Facturas |
| `bulkUpdateExpenses` | Cambia la categoría de varios gastos | Gastos |
| `bulkDeleteDrafts` | Elimina borradores de facturas o presupuestos | Facturas borrador, presupuestos borrador |

## Actualizar facturas en lote

### Marcar como pagadas

```
"Marca como pagadas todas las facturas de enero"
```

El asistente:

1. Busca todas las facturas de enero con estado `sent` o `overdue`
2. Muestra un resumen: cantidad de facturas, importe total, listado de clientes
3. Te pide confirmación
4. Actualiza el estado a `paid` y registra la fecha de cobro

### Cambiar estado

```
"Cambia a enviadas todas las facturas en borrador de Acme SL"
```

El asistente busca los borradores del cliente indicado, muestra el resumen y espera confirmación.

### Filtros que puedes usar

- **Por período**: "de enero", "del Q1", "de este mes"
- **Por cliente**: "de Acme SL", "de Juan Garcia"
- **Por estado**: "en borrador", "pendientes", "vencidas"
- **Por importe**: "de más de 500 euros", "menores de 100 euros"

## Actualizar gastos en lote

### Cambiar categoría

```
"Cambia todos los gastos de 'Otros' a 'Software'"
```

El asistente:

1. Busca todos los gastos con categoría "Otros"
2. Muestra cuántos hay y el importe total
3. Te pide confirmación
4. Actualiza la categoría de todos a "Software"

### Otros ejemplos

```
"Marca como deducibles todos los gastos de transporte"
```

```
"Cambia la categoría de los gastos de 'Servicios' de enero a 'Consultoría'"
```

## Eliminar borradores

### Eliminar facturas en borrador

```
"Elimina todos los borradores de facturas"
```

El asistente:

1. Cuenta los borradores existentes
2. Muestra el listado con cliente, importe y fecha
3. Te pide confirmación con un mensaje claro: "Se eliminarán X facturas borrador por un total de Y EUR"
4. Elimina tras tu confirmación

### Eliminar presupuestos en borrador

```
"Elimina todos los presupuestos en borrador"
```

Mismo flujo: lista, resumen, confirmación, ejecución.

## Flujo de confirmación

Todas las operaciones masivas siguen este flujo:

1. **El asistente busca** los registros que coinciden con tu petición
2. **Muestra un resumen** con la cantidad, el importe total y los registros afectados
3. **Te pide confirmación explícita** — "¿Confirmas esta operación?"
4. **Ejecuta la operación** solo después de que confirmes
5. **Muestra el resultado** — cuántos registros se actualizaron o eliminaron

Si no confirmas, la operación se cancela sin cambios.

### Ejemplo de diálogo

```
Tú: "Marca como pagadas todas las facturas de febrero"

Asistente: "He encontrado 8 facturas de febrero por un total de 12.340,00 EUR:
- F-2026-012 — Acme SL — 3.200,00 EUR
- F-2026-013 — Design Co — 1.500,00 EUR
- ...
¿Confirmas marcar las 8 como pagadas?"

Tú: "Sí"

Asistente: "Hecho. 8 facturas marcadas como pagadas."
```

## Deshacer

Las operaciones masivas **no se pueden deshacer automáticamente**. Si necesitas revertir un cambio, puedes:

- Usar el mismo comando con el estado anterior: "Cambia a enviadas las facturas de febrero"
- Editar cada registro individualmente desde la interfaz

Las eliminaciones de borradores son permanentes. El asistente te advierte antes de ejecutar.

## Seguridad

- Solo se pueden eliminar registros en estado **borrador** (nunca facturas enviadas, pagadas o anuladas)
- Las facturas con cadena VeriFactu activa no se pueden eliminar
- Se requiere confirmación explícita en todos los casos
- El registro de actividad guarda quién ejecutó la operación y cuándo

---

**Siguiente paso:** [Subir documentos al chat](./subir-documentos)

---

## Qué puede hacer el asistente
> Path: /ia/que-puede-hacer

# Qué puede hacer el asistente

El asistente IA de Frihet está impulsado por **Google Gemini** y cuenta con **50+ herramientas** para acelerar tus tareas cotidianas. Desde crear documentos hasta calcular impuestos trimestrales, el asistente opera con contexto real de tu negocio. Descubre todas las [capacidades de IA de Frihet](https://www.frihet.io/es/features).

## Capacidades por categoría

### Crear documentos por lenguaje natural

Escribe de forma natural y el asistente crea facturas, gastos y presupuestos automáticamente:

- **Facturas**: "Crea factura para Juan Garcia por 500 euros de diseño web"
- **Gastos**: "Registra gasto de 45 euros en Material de oficina"
- **Presupuestos**: "Presupuesto a Cliente SL: 3 horas de consultoría a 100 euros"
- **Facturas recurrentes**: "Crea factura recurrente mensual a Acme Corp por 500 euros de hosting"
- **Gestión de recurrentes**: "Lista mis facturas recurrentes activas"
- **Cancelar recurrentes**: "Cancela la recurrente de mantenimiento para ClienteX"

El asistente extrae clientes, conceptos, cantidades e importes. Siempre revisas antes de confirmar.

### Búsqueda de datos y análisis

Consulta tus datos con preguntas naturales:

- "¿Cuánto he facturado este trimestre?"
- "¿Quién es mi mejor cliente?"
- "¿Cuántas facturas vencidas tengo?"
- "Resumen de gastos por categoría"
- "¿Cuál es la rentabilidad de mi cliente Acme Corp?"
- "Registra un pago parcial de 500 euros en la factura F-2026-050"

El asistente devuelve **KPI cards**, **gráficos inline** o respuestas en texto con el contexto que necesitas.

### Exportar datos

Exporta tus datos directamente desde el chat, sin navegar a ninguna pantalla:

| Herramienta | Qué hace | Ejemplo |
|-------------|----------|---------|
| `exportToCSV` | Exporta facturas, gastos, presupuestos, clientes o productos a CSV | "Exporta mis facturas de Q1 a CSV" |
| `exportToPDF` | Genera un PDF con tus datos | "Exporta el resumen de gastos de marzo a PDF" |

Más detalle en [Exportar datos desde el chat](./exportar-datos).

### Impuestos y cumplimiento fiscal

El asistente conoce el sistema fiscal español (IVA, IGIC, IRPF) y puede calcular tus obligaciones trimestrales:

| Herramienta | Qué hace | Ejemplo |
|-------------|----------|---------|
| `calculateModelo303` | Calcula el IVA trimestral (Modelo 303) | "Calcula mi Modelo 303 del Q1" |
| `calculateModelo130` | Calcula el IRPF trimestral (Modelo 130) | "¿Cuánto debo de IRPF este trimestre?" |
| `getTaxCalendar` | Muestra plazos fiscales próximos | "¿Cuándo tengo que presentar impuestos?" |

El asistente aplica automáticamente los tipos correctos según tu zona fiscal (Península, Canarias, Ceuta/Melilla) y conoce las reglas de VeriFactu. Más detalle en [Impuestos y fiscalidad](./impuestos-ia).

### Conciliación bancaria

Conecta tu banco y deja que el asistente haga el matching automático:

| Herramienta | Qué hace | Ejemplo |
|-------------|----------|---------|
| `reconcileTransactions` | Cruza movimientos bancarios con facturas y gastos | "Concilia los movimientos de esta semana" |
| `getUnreconciledTransactions` | Lista movimientos sin emparejar | "¿Qué movimientos bancarios no están conciliados?" |

### Operaciones masivas

Actualiza o elimina varios registros de una vez. Todas las operaciones masivas requieren **confirmación explícita** antes de ejecutarse:

| Herramienta | Qué hace | Ejemplo |
|-------------|----------|---------|
| `bulkUpdateInvoices` | Marca varias facturas como pagadas o cambia su estado | "Marca como pagadas todas las facturas de enero" |
| `bulkUpdateExpenses` | Cambia la categoría de varios gastos a la vez | "Cambia todos los gastos de 'Otros' a 'Software'" |
| `bulkDeleteDrafts` | Elimina todos los borradores de facturas o presupuestos | "Elimina todos los presupuestos en borrador" |

Más detalle en [Operaciones masivas](./operaciones-masivas).

### Escaneo de documentos (OCR)

Sube fotografías de recibos, facturas o documentos. El asistente:

- Extrae datos automáticamente
- Reconoce concepto, importe, fecha
- Crea gastos o facturas directamente
- Soporta PDF, JPG, PNG

### Resúmenes financieros

Obtén análisis rápidos:

- Comparativas mes a mes
- Proyecciones de ingresos
- Análisis de rentabilidad por cliente
- Métricas de salud del negocio (clientes activos, retención)
- Registro de pagos parciales o totales
- Alertas de vencimientos próximos

## Encadenar acciones en un solo prompt

El asistente soporta **workflow chaining**: ejecutar varias acciones en secuencia con un solo mensaje.

```
"Crea una factura para Acme SL por 2.000 euros de consultoría y envíala por email"
```

El asistente:

1. Crea la factura con los datos indicados
2. Genera el PDF
3. Envía el email al cliente

Otros ejemplos de encadenamiento:

```
"Exporta mis facturas de Q1 a CSV y calcula el Modelo 303"
```

```
"Marca como pagadas las facturas de enero y genera un resumen del mes"
```

```
"Concilia los movimientos bancarios y muéstrame los que quedan sin emparejar"
```

El asistente ejecuta cada paso en orden y te muestra el resultado de cada uno.

## Gráficos inline

El asistente genera visualizaciones directamente en el chat:

- **Barras de desglose** — Gastos por categoría, facturación por cliente
- **Donut de estado** — Proporción de facturas pagadas, pendientes, vencidas
- **Línea de tendencia** — Evolución de ingresos o gastos mes a mes

Los gráficos usan diseño monocromo alineado con la identidad visual de Frihet. Aparecen automáticamente cuando la respuesta contiene datos financieros comparables.

## Caché semántica

Las consultas idénticas devuelven respuestas cacheadas durante 5 minutos. Si preguntas lo mismo dos veces seguidas, la segunda respuesta es instantánea. El caché se invalida automáticamente cuando se crean, modifican o eliminan registros.

## Comandos rápidos

Usa **slash commands** para acciones directas:

| Comando | Función |
|---------|---------|
| `/factura` | Crear factura rápidamente |
| `/gasto` | Registrar gasto |
| `/pendientes` | Ver facturas por cobrar |
| `/resumen` | Resumen financiero del mes |
| `/clientes` | Listar clientes y estadísticas |
| `/ayuda` | Ver todos los comandos |
| `/meta` | Objetivo de facturación del mes |
| `/impuestos` | Simulador de impuestos estimados |
| `/cobros` | Últimos pagos recibidos |
| `/recurrentes` | Facturas recurrentes activas |
| `/rentabilidad` | Rentabilidad por cliente |
| `/exportar` | Exportar datos a CSV o PDF |
| `/conciliar` | Conciliar movimientos bancarios |
| `/modelo303` | Calcular IVA trimestral |
| `/modelo130` | Calcular IRPF trimestral |

## Todas las herramientas (50+)

Referencia completa de las herramientas del asistente, organizadas por categoría:

| Categoría | Herramientas | Descripción |
|-----------|-------------|-------------|
| **Facturas** | createInvoice, listInvoices, getInvoice, updateInvoice, deleteInvoice, searchInvoices | CRUD completo de facturas |
| **Gastos** | createExpense, listExpenses, getExpense, updateExpense, deleteExpense | CRUD completo de gastos |
| **Clientes** | createClient, listClients, getClient, updateClient, deleteClient | CRUD completo de clientes |
| **Productos** | createProduct, listProducts, getProduct, updateProduct, deleteProduct | CRUD completo de productos |
| **Presupuestos** | createQuote, listQuotes, getQuote, updateQuote, deleteQuote | CRUD completo de presupuestos |
| **Recurrentes** | createRecurring, listRecurring, cancelRecurring | Facturas recurrentes |
| **Pagos** | recordPayment, listPayments | Registrar y consultar cobros |
| **Exportación** | exportToCSV, exportToPDF | Exportar datos a CSV o PDF |
| **Impuestos** | calculateModelo303, calculateModelo130, getTaxCalendar | Cálculos fiscales y calendario |
| **Banca** | reconcileTransactions, getUnreconciledTransactions | Conciliación bancaria |
| **Operaciones masivas** | bulkUpdateInvoices, bulkUpdateExpenses, bulkDeleteDrafts | Actualización y eliminación en lote |
| **Análisis** | getSummary, getKPIs, getProjections | Resúmenes y métricas |
| **Documentos** | scanDocument, extractData | OCR y extracción de datos |

## Límites por plan

El asistente IA tiene límites de mensajes según tu plan:

| Plan | Mensajes/mes | Análisis de documentos | Histórico |
|------|--------------|------------------------|-----------|
| **Free** | 20 | Sí | 7 días |
| **Pro** | 100 | Sí | 90 días |
| **Premium** | 500 | Sí | Sin límite |

Los límites se reinician el primer día de cada mes.

## Historial persistente

El asistente mantiene **historial de conversaciones**:

- Accede a cualquier momento desde la barra lateral
- El contexto se preserva entre sesiones
- Puedes volver a referencias anteriores
- Los datos se sincronizan en todos tus dispositivos

## Privacidad y seguridad

- **Tus datos nunca se usan para entrenar modelos** — Solo procesamos con Gemini en tiempo real
- Encriptación end-to-end para uploads de documentos
- Las conversaciones se almacenan localmente en tu cuenta
- Puedes eliminar historial en cualquier momento

## Limitaciones actuales

El asistente **no puede**:

- Modificar clientes existentes (solo puede sugerir)
- Crear campañas de email masivas

## Extender las capacidades con la API

:::info Para desarrolladores
Puedes ampliar las capacidades del asistente IA de Frihet con herramientas programáticas:

- **Servidor MCP** — Conecta Claude, Cursor o Windsurf directamente a tu ERP via [@frihet/mcp-server](https://www.npmjs.com/package/@frihet/mcp-server). 157 herramientas para crear facturas, registrar gastos y consultar datos en lenguaje natural desde tu IDE.
- **API REST** — Construye flujos de IA personalizados usando los [endpoints de la API](/desarrolladores/api-rest). Ideal para pipelines de procesamiento, integraciones con LLMs propios o automatizaciones a medida.
- **Webhooks** — Dispara acciones cuando ocurren eventos como `invoice.created` o `expense.created`. Conecta con modelos de IA externos para clasificación automática, detección de anomalías o alertas inteligentes. Ver [documentación de webhooks](/desarrolladores/webhooks).

Consulta la [sección de desarrolladores](/desarrolladores) para la referencia completa.
:::

---

**Siguiente paso:** [Crear facturas por texto](./crear-facturas-por-texto)

---

## Subir documentos al chat
> Path: /ia/subir-documentos

# Subir documentos al chat

Sube fotografías o PDFs de recibos, facturas e invoices. El asistente extrae datos automáticamente con OCR.

## Formatos soportados

| Formato | Tamaño máx | Casos de uso |
|---------|-----------|--------------|
| **PDF** | 25 MB | Facturas, presupuestos, nóminas |
| **JPG** | 10 MB | Fotografías de recibos, tickets |
| **PNG** | 10 MB | Screenshots, documentos escaneados |

## Cómo subir un documento

### Desde el chat

1. Haz clic en el **icono de clip** (📎) en la barra de entrada
2. Selecciona tu archivo (PDF, JPG, PNG)
3. El asistente procesa la imagen
4. Te muestra los datos extraídos

### Opción: Arrastrar y soltar

Arrastra directamente tu archivo al chat:

1. Abre el chat del asistente
2. Arrastra la imagen o PDF desde tu carpeta
3. Suéltalo en la ventana del chat
4. Se carga automáticamente

## Qué extrae el asistente

El OCR reconoce automáticamente:

### De recibos/facturas

- **Concepto**: qué compraste
- **Importe**: cuánto costó
- **IVA**: si está desglosado
- **Fecha**: cuándo
- **Proveedor**: a quién se lo compraste
- **Categoría**: Material, Servicios, Viajes, etc.

### Ejemplo 1: Recibo de oficina

Subes una foto del recibo de Staples:

> "3 paquetes de papel A4 - €18,50"

El asistente:
- Extrae concepto: "Papel A4"
- Cantidad: 3
- Importe: €18,50
- Categoría: Material de oficina
- Fecha: 8 feb 2025

Te pregunta: **"¿Creo un gasto?"**

### Ejemplo 2: Factura de un cliente

Subes una factura que recibiste de tu proveedor:

**Factura:**
```
Electricidad - Febrero 2025
Total: €145,30 + 21% IVA = €175,81
```

El asistente:
- Detecta: Gasto de servicios (electricidad)
- Importe: €175,81 (con IVA)
- Categoría: Servicios
- Fecha: Febrero 2025

### Ejemplo 3: Factura de cliente

Subes un PDF de factura que emitiste y el cliente pagó:

El asistente:
- Extrae datos de factura
- Número de documento
- Concepto y monto
- Te sugiere marcarla como "Pagada"

## Flujo después de subir

1. **El asistente procesa** el documento (1-3 segundos)
2. **Muestra los datos extraídos** en formato editable
3. **Preguntas**: "¿Creo un gasto de €45,00 en Material?"
4. **Confirmas o corriges** los datos
5. **Se crea automáticamente** en Frihet

Si algo no es exacto, **edita directamente antes de confirmar**:

- Cambiar concepto
- Ajustar importe
- Cambiar fecha
- Reasignar categoría

## Casos especiales

### Factura con múltiples líneas

Si subes una factura con 5 conceptos diferentes:

El asistente:
- Extrae cada línea
- Te pregunta si crear un gasto con total
- O si crear 5 gastos separados (si son diferentes categorías)

Recomendación: **Responde naturalmente**
- "Crea un solo gasto con todo" → €185,30 total
- "Separa Material y Servicios" → 2 gastos

### Recibo sin datos claros

Si la foto es borrosa o está inclinada:

- El asistente intenta extraer de todas formas
- Marca los datos dudosos como **"Requiere revisión"**
- Te deja editarlos manualmente

### Documento en inglés o idioma diferente

El asistente entiende:

- Español ✅
- Inglés ✅
- Francés ✅
- Alemán ✅
- Portugués ✅

Si está en otro idioma, lo traduce automáticamente.

### Documento incompleto

Si falta información crítica (fecha o importe):

El asistente te pregunta:
- "¿Cuándo fue este gasto?" → Tú introduces la fecha
- "¿Cuál es el importe total?" → Tú editas el monto

## Consejos para mejores extracciones

### Fotos de calidad

✅ **Buena iluminación** — sin sombras
✅ **Documento completo** — entra todo en la foto
✅ **Ángulo recto** — evita fotos inclinadas
✅ **Resolución decente** — no pixelado

❌ Foto muy oscura
❌ Documento cortado
❌ Foto muy inclinada
❌ Foto borrosa

### Orden de información

Si es posible:
- Pon el **concepto visible**
- Asegura que el **importe está claro**
- Incluye la **fecha**
- Muestra el **proveedor/empresa**

### Casos donde el OCR falla

**Recibos de tickets de caja:**
- Letras muy pequeñas
- Papel térmico degradado
- Números entrelazados

**Solución:** Edita manualmente después. El asistente te lo permitirá.

## Crear gastos vs facturas

El asistente sugiere automáticamente:

| Tipo | Cuándo |
|------|--------|
| **Gasto** | Es un recibo de algo que compraste tú |
| **Factura** | Es un documento que emitiste a un cliente |
| **Factura recibida** | Es una factura de un proveedor |

Si no está seguro, **pregunta:**
- "¿Es un gasto o factura?"
- Tú respondes y procesa correctamente

## Privacidad de documentos

- Los documentos se procesan con OCR local
- No se guardan en servidores de terceros
- Los datos extraídos sí se guardan en tu cuenta Frihet (encriptados)
- Puedes eliminar el documento original después

Desde Ajustes → Privacidad puedes:
- Eliminar uploads antiguos
- Deshabilitar OCR si lo prefieres

## Limitaciones

El asistente **no puede**:

- Procesar archivos de Word o Excel (solo PDF/JPG/PNG)
- Extraer de imágenes muy deterioradas (< 100px de ancho)
- Reconocer manuscrita (escritura manual)
- Leer QR codes o códigos de barras

---

**Próxima sección:** [Integraciones](../integraciones/stripe)

---

## Documentación de Frihet
> Path: /index

# Documentación de Frihet

**Frihet** es un ERP moderno diseñado para empresas que valoran la velocidad. Keyboard-first, potenciado por IA, y listo para trabajar offline cuando lo necesites.

## ¿Qué es Frihet?

Una herramienta de gestión empresarial que te permite:

- **Facturación en segundos** — Desde presupuesto a factura con unos pocos atajos
- **Gestión de gastos y clientes** — Todo integrado en un mismo lugar
- **Asistente IA** — Que aprende cómo trabajas y te sugiere acciones
- **Offline-ready** — Tus datos siempre disponibles, con o sin conexión
- **Keyboard-centric** — Diseñado para quien no quiere dejar el teclado
- **Cumplimiento fiscal** — VeriFactu, IVA, IRPF, todo automatizado

Consulta todas las [funcionalidades de Frihet](https://www.frihet.io/es/features) o compara [planes y precios](https://www.frihet.io/es/pricing).

## Acceso rápido

### Tareas comunes

- [Crear una factura en 30 segundos](./primeros-pasos/primera-factura)
- [Atajos de teclado imprescindibles](./primeros-pasos/atajos-teclado)
- [Configurar el asistente IA](./ia/que-puede-hacer)
- [Conectar tus integraciones](./integraciones/stripe)
- [Documentación para desarrolladores](./desarrolladores/resumen.md)

### Primeros pasos

Eres nuevo aquí? Empieza por:

1. [Crear una cuenta](./primeros-pasos/crear-cuenta)
2. [Configurar tu negocio](./primeros-pasos/configurar-negocio)
3. [Hacer tu primera factura](./primeros-pasos/primera-factura)
4. [Aprender los atajos de teclado](./primeros-pasos/atajos-teclado)

### Funcionalidades principales

| Sección | Qué encontrarás |
|---------|-----------------|
| [Facturación](./facturacion/facturas) | Crear facturas, presupuestos, notas de crédito |
| [Clientes](./clientes/gestion-clientes) | Gestión de contactos y datos fiscales |
| [Gastos](./gastos/registrar-gastos) | Registro y categorización de gastos |
| [Productos](./productos/catalogo) | Catálogo de artículos y servicios |
| [IA](./ia/que-puede-hacer) | Asistente con 50+ herramientas: documentos, impuestos, exportación, conciliación |
| [Integraciones](./integraciones/stripe) | Bancos, contabilidad, email y [40+ servicios](https://www.frihet.io/es/integrations) |
| [Configuración](./configuracion/datos-empresa) | Preferencias, empresa, seguridad |
| [Desarrolladores](./desarrolladores/resumen.md) | API REST, webhooks, integraciones programáticas |

### Para desarrolladores

| Recurso | Descripcion |
|---------|-------------|
| [API REST](./desarrolladores/api-rest) | 5 recursos, autenticacion por API key, paginacion y filtros |
| [Webhooks](./desarrolladores/webhooks) | 14 eventos en tiempo real con firma HMAC-SHA256 |
| [Servidor MCP](./desarrolladores/mcp-server) | 157 herramientas para conectar Claude, Cursor o Windsurf a tu ERP |
| [Skill Claude Code](./desarrolladores/skill-claude-code) | 8 comandos de gestion fiscal directamente desde tu terminal |

### Informacion legal

- [Cumplimiento fiscal en Frihet](./legal/ticketbai)
- [Privacidad y proteccion de datos](./legal/privacidad)

---

## Principios de diseño

Frihet está construido alrededor de tres ideas:

1. **Velocidad** — Lo que antes tardaba 5 minutos ahora cabe en 5 atajos
2. **Inteligencia** — El ERP aprende de ti. Menos clics, más contexto
3. **Libertad** — Funciona offline. Funciona sin JavaScript. Funciona para ti

---

¿Preguntas? Abre el asistente IA con `Cmd+K` y pregunta directamente. O consulta la [sección de IA](./ia/que-puede-hacer) para aprender más. También puedes visitar el [blog de Frihet](https://www.frihet.io/es/blog) para tutoriales y novedades.

---

## Centro de informes
> Path: /informes/centro-informes

# Centro de informes

El **Centro de informes** (`/reports`) reune en un solo lugar todos los informes de tu negocio. Desde el resumen ejecutivo hasta el detalle por proveedor, puedes analizar cualquier dimension financiera sin salir de Frihet.

Todos los informes son en tiempo real y reflejan los datos actuales de tu cuenta. La mayoria admiten filtros por fecha y exportacion a CSV o PDF.

---

## Vista general del hub

Al acceder a `/reports` ves el **AnalyticsDashboard**: un resumen ejecutivo con las metricas mas importantes del negocio, graficas de evolucion de ingresos y gastos, y acceso rapido a todos los sub-informes desde el menu de pestanas.

---

## Informes generales

Estos informes ofrecen una vision amplia del estado financiero del negocio.

### Panel general

**Ruta:** `/reports`

Panel ejecutivo con:

- Ingresos, gastos y beneficio neto del periodo seleccionado
- Evolucion mensual de facturacion y cobros
- Alertas de facturas vencidas y pagos proximos
- Acceso directo al resto de informes

### Prevision de tesoreria (Cash Flow Forecast)

**Ruta:** `/reports/cashflow`

Proyeccion del flujo de caja para los proximos 30, 60 y 90 dias basada en:

- Facturas pendientes de cobro y sus fechas de vencimiento
- Gastos recurrentes y pagos programados
- Tendencias historicas de cobro por cliente

Permite anticipar tensiones de liquidez antes de que ocurran.

### Evolucion de gastos (Expense Trends)

**Ruta:** `/reports/trends`

Visualiza como evolucionan los gastos en el tiempo, agrupados por:

- Categoria de gasto
- Proveedor
- Periodo (mensual, trimestral, anual)

Util para identificar incrementos inesperados y optimizar partidas de coste.

### Objetivos de ventas (Revenue Goals)

**Ruta:** `/reports/goals`

Seguimiento del progreso hacia los objetivos de facturacion:

| Columna | Descripcion |
|---------|-------------|
| Objetivo | Meta de facturacion configurada |
| Conseguido | Facturacion real hasta la fecha |
| Progreso | Porcentaje de cumplimiento |
| Restante | Importe que falta para alcanzar el objetivo |

Configura los objetivos desde la seccion de ajustes del informe.

---

## Informes fiscales

Informes orientados al cumplimiento fiscal y la preparacion de declaraciones tributarias.

### Informe de periodo fiscal (Tax Period Report)

**Ruta:** `/reports/tax-period`

Resumen de la actividad fiscal de un periodo concreto (trimestre o ejercicio):

- Base imponible total
- IVA repercutido por tipo (21%, 10%, 4%, 0%)
- IVA soportado (de gastos deducibles)
- Diferencia IVA a ingresar / a compensar
- Retenciones IRPF practicadas

Compatible con los modelos 303, 130 y 420. Ver [Modelos fiscales](/cumplimiento/modelos-fiscales).

### Pasivo por impuesto sobre ventas (Sales Tax Liability)

**Ruta:** `/reports/tax-liability`

Detalle del IVA devengado pendiente de liquidar:

- Desglose por tipo impositivo
- Facturas incluidas en cada base imponible
- Comparativa con el periodo anterior
- Exportacion para tu gestoria

---

## Informes de facturacion

Informes sobre facturas emitidas, cobros y aging de deuda.

### Informe de facturas (Invoice Report)

**Ruta:** `/reports/invoices`

Exportacion masiva de facturas con filtros avanzados:

| Filtro | Opciones |
|--------|----------|
| Estado | Borrador, Enviada, Cobrada, Vencida, Anulada |
| Cliente | Busqueda por nombre o NIF |
| Fecha | Rango personalizado o periodos predefinidos |
| Serie | Por serie de numeracion |
| Importe | Mayor o menor que un valor |

Exporta a CSV para importacion en contabilidad externa o a PDF para archivo.

### Informe de pagos (Payment Report)

**Ruta:** `/reports/payments`

Registro de todos los cobros recibidos:

- Fecha y metodo de pago
- Importe cobrado
- Factura asociada
- Cliente
- Diferencia entre importe facturado y cobrado (pagos parciales)

### Antigüedad de deuda (Invoice Aging)

**Ruta:** `/reports/aging`

Clasifica las facturas pendientes de cobro por antiguedad:

| Tramo | Descripcion |
|-------|-------------|
| 0-30 dias | Vencimiento reciente o proximos a vencer |
| 31-60 dias | Atraso moderado |
| 61-90 dias | Riesgo de impago |
| +90 dias | Deuda critica |

Util para priorizar la gestion de cobros y activar el proceso de reclamacion.

### Beneficio por cliente (Profit by Client)

**Ruta:** `/reports/profit`

Rentabilidad de cada cliente: ingresos facturados menos gastos directamente imputados:

- Margen bruto por cliente
- Ranking de clientes mas y menos rentables
- Evolucion trimestral del margen

---

## Informes de clientes

Analisis de la actividad y el saldo de tus clientes.

### Ventas por cliente (Client Sales)

**Ruta:** `/reports/client-sales`

Facturacion desglosada por cliente en el periodo seleccionado:

- Numero de facturas emitidas
- Importe total facturado
- Importe cobrado vs pendiente
- Ticket medio por cliente

### Saldo de clientes (Client Balance)

**Ruta:** `/reports/client-balance`

Posicion financiera actual de cada cliente:

- Deuda total pendiente
- Creditos emitidos (facturas rectificativas)
- Saldo neto

### Resumen de cuentas por cobrar (AR Summary)

**Ruta:** `/reports/ar-summary`

Vista agregada de cuentas por cobrar (Accounts Receivable):

- Total pendiente de cobro
- Distribucion por estado (corriente, vencida, critica)
- Comparativa con el mes anterior

### Detalle de cuentas por cobrar (AR Detail)

**Ruta:** `/reports/ar-detail`

Listado transaction a transaction de todas las partidas pendientes de cobro con referencia a la factura original.

---

## Informes de proveedores y gastos

Analisis de la deuda con proveedores y los gastos de la empresa.

### Informe de gastos (Expense Report)

**Ruta:** `/reports/expenses`

Exportacion masiva de gastos con los mismos filtros que el informe de facturas: categoria, proveedor, fecha, importe. Exportable a CSV o PDF.

### Informe de proveedores (Vendor Report)

**Ruta:** `/reports/vendors`

Actividad y saldo con cada proveedor:

- Gastos totales por proveedor en el periodo
- Pagos realizados vs pendientes
- Historial de facturas recibidas

### Detalle de cuentas por pagar (AP Detail)

**Ruta:** `/reports/ap-detail`

Detalle transaction a transaction de todas las partidas pendientes de pago a proveedores (Accounts Payable).

---

## Informes de ventas por usuario y producto

### Ventas por producto (Product Sales)

**Ruta:** `/reports/product-sales`

Ranking de productos y servicios por volumen de facturacion:

- Unidades vendidas
- Importe total facturado por producto
- Precio medio de venta
- Evolucion mensual

### Ventas por usuario (User Sales Report)

**Ruta:** `/reports/user-sales`

Rendimiento de cada miembro del equipo:

- Facturas creadas o enviadas por usuario
- Importe total gestionado
- Tasa de cobro
- Comparativa entre periodos

Util para equipos comerciales con responsabilidades individuales de facturacion.

---

## Exportacion

Todos los informes del Centro de informes soportan exportacion:

| Formato | Uso |
|---------|-----|
| **CSV** | Importacion en Excel, Google Sheets o software contable |
| **PDF** | Archivo, entrega a gestoria o auditoria |

Para exportar:

1. Abre el informe deseado
2. Aplica los filtros de fecha y/o entidad
3. Haz clic en **Exportar** en la esquina superior derecha
4. Selecciona el formato

Algunos informes como **Invoice Report** y **Expense Report** permiten seleccionar columnas especificas antes de exportar.

---

## Filtros comunes

La mayoria de informes comparten estos filtros:

| Filtro | Descripcion |
|--------|-------------|
| **Periodo** | Este mes, ultimo mes, este trimestre, este anio, rango personalizado |
| **Comparar con** | Periodo anterior o mismo periodo del anio pasado |
| **Moneda** | Si tienes facturas en varias monedas |

---

:::tip Informes fiscales trimestrales
Para preparar las declaraciones de IVA e IRPF, usa el **Informe de periodo fiscal** junto con los [Modelos fiscales](/cumplimiento/modelos-fiscales). Frihet te indica exactamente que cifras trasladar a cada casilla.
:::

---

**Siguiente paso:** [Modelos fiscales](/cumplimiento/modelos-fiscales) o [Dashboard](/dashboard)

---

## Informes de cumplimiento
> Path: /informes/informes-cumplimiento

# Informes de cumplimiento

> Todos los informes que necesitas para auditorias, Hacienda y gestores en un solo lugar.

## Overview

El centro de informes de cumplimiento de Frihet agrupa 25+ informes especializados listos para exportar: desglose de IVA por trimestre, retenciones IRPF, saldo por cliente, antiguedad de cobros (aging AR/AP), ventas por producto, directorio de proveedores, auditoria de actividad y previsiones de tesoreria. Cada informe soporta filtros por periodo, cliente, categoria y estado, y se exporta en CSV con la estructura esperada por asesores contables.

## Quick start

1. Ve a Informes → selecciona el informe del catalogo
2. Ajusta los filtros de periodo y entidad
3. Pulsa **Exportar CSV** — el archivo se descarga inmediatamente

## Reference

- API: `GET /v1/reports/:reportType` — parametros varían por informe; ver [referencia API](/desarrolladores/api-rest)
- MCP tool: `generate_report` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Informes → Centro de informes

---

## Prevision de tesoreria
> Path: /informes/prevision-tesoreria

# Prevision de tesoreria

> Anticipa tensiones de liquidez antes de que ocurran: Frihet proyecta tu caja a 90 dias.

## Overview

La prevision de tesoreria combina el historial de cobros y pagos con las facturas pendientes de cobro y los gastos recurrentes para proyectar el saldo de caja a 3 meses. El motor de IA detecta patrones estacionales y ajusta la proyeccion segun la probabilidad de cobro por cliente (basada en historial de retrasos). Las alertas de liquidez se muestran en el dashboard fiscal cuando el saldo proyectado cae por debajo del umbral configurado.

## Quick start

1. Ve a Informes → **Prevision de tesoreria**
2. Revisa la curva de caja a 30, 60 y 90 dias
3. Haz clic en cualquier semana para ver que facturas o pagos impactan ese saldo

## Reference

- API: `GET /v1/reports/cash-flow-forecast` — parametros: `horizon` (30/60/90), `includeExpenses`
- MCP tool: `get_cash_flow_forecast` — ver [referencia MCP](/desarrolladores/mcp-server)
- Settings: Dashboard Fiscal → Prevision de tesoreria

---

## ActiveCampaign
> Path: /integraciones/activecampaign

# ActiveCampaign

> Conecta ActiveCampaign con Frihet para sincronizar contactos y automatizar facturación.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre ActiveCampaign y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **ActiveCampaign**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → ActiveCampaign
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Adyen
> Path: /integraciones/adyen

# Adyen

> Conecta Adyen con Frihet para registrar pagos y conciliar ingresos automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Adyen y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Adyen**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Adyen
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Amazon Seller Central
> Path: /integraciones/amazon-seller

# Amazon Seller Central

:::info Próximamente
Esta integración está en desarrollo. Puedes ver su estado en **Ajustes → Integraciones**.
:::

Amazon Seller Central es la plataforma para vendedores del marketplace de Amazon, que permite gestionar productos, pedidos, inventario y logística en uno de los mayores marketplaces del mundo.

## ¿Para qué sirve?

Con Amazon Seller Central integrado en Frihet:

- **Importar pedidos de Amazon** — Los pedidos del marketplace se importan automáticamente a Frihet como registros de venta
- **Sincronizar datos de ventas** — Mantén un registro centralizado de tus ventas en Amazon junto con el resto de tu facturación
- **Generación automática de facturas** — Cada venta en Amazon genera su factura correspondiente en Frihet para tu contabilidad

## Estado

Esta integración aparece en la sección de integraciones de Frihet. La funcionalidad completa está en desarrollo.

---

## Asana
> Path: /integraciones/asana

# Asana

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu workspace de Asana a Frihet. Consulta proyectos y tareas directamente desde tu ERP para tener visibilidad del trabajo realizado al momento de facturar.

## ¿Para qué sirve?

Con Asana integrado:

- **Ver proyectos** — Consulta todos tus proyectos de Asana desde Frihet
- **Ver tareas** — Navega las tareas de cada proyecto con su estado
- **Contexto al facturar** — Revisa tareas completadas antes de crear facturas
- **Detección automática de workspace** — Frihet detecta tu workspace principal automáticamente

## Requisitos

- **Cuenta Asana activa** — [asana.com](https://asana.com)
- **Personal Access Token** — Se genera desde la configuración de Asana
- **Frihet Pro o superior**

## Conectar Asana con Frihet

### Paso 1: Obtener tu Personal Access Token

1. Ve a [app.asana.com/0/developer-console](https://app.asana.com/0/developer-console)
2. Inicia sesión con tu cuenta de Asana
3. En la sección **Personal access tokens**, haz clic en **Create new token**
4. Ponle un nombre (ej: "Frihet ERP")
5. Acepta los términos de la API
6. Copia el token generado

:::caution Guarda el token
El Personal Access Token solo se muestra una vez. Cópialo antes de cerrar la ventana.
:::

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Asana**
3. Haz clic en **Conectar**
4. Pega tu **Personal Access Token**
5. Haz clic en **Verificar conexión**
6. Frihet detectará automáticamente tu primer workspace

### Paso 3: Verificar conexión

Si la conexión es correcta, Frihet mostrará:

- Nombre de tu workspace en Asana
- Número de proyectos accesibles
- Tu nombre de usuario en Asana

## Cómo funciona

Frihet usa la **API REST v1 de Asana** con Bearer authentication:

1. Proporcionas tu Personal Access Token
2. Frihet envía el token en la cabecera `Authorization: Bearer <token>`
3. Al conectar, Frihet consulta tus workspaces y selecciona el primero automáticamente
4. Los proyectos y tareas se consultan bajo demanda
5. El token se almacena cifrado (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Proyectos | Asana → Frihet | Bajo demanda |
| Tareas | Asana → Frihet | Bajo demanda |
| Estado de tareas | Asana → Frihet | Con cada consulta |
| Asignados | Asana → Frihet | Con cada consulta |

## Casos de uso

### Consultor que factura por proyecto

Gestionas los entregables de cada cliente en Asana. Antes de facturar, consultas desde Frihet las tareas completadas del proyecto para incluir el desglose correcto en la factura.

### Agencia creativa con sprints

Tu equipo trabaja en sprints organizados en proyectos de Asana. A final de cada sprint, consultas las tareas completadas desde Frihet y generas las facturas correspondientes.

### Verificar alcance antes de facturar

Tienes un proyecto con alcance definido en Asana. Antes de emitir la factura final, verificas desde Frihet que todas las tareas del alcance están marcadas como completadas.

## Funcionalidades

### Ver proyectos

1. Desde Frihet, accede a la sección de Asana
2. Verás todos los proyectos de tu workspace
3. Cada proyecto muestra nombre, estado y número de tareas

### Ver tareas de un proyecto

1. Selecciona un proyecto
2. Frihet muestra las tareas con:
   - Nombre de la tarea
   - Estado (completada / pendiente)
   - Persona asignada
   - Fecha de vencimiento
3. Filtra por estado para ver solo las completadas

### Detección automática de workspace

Al conectar, Frihet detecta tu primer workspace automáticamente. Si tienes varios workspaces en Asana, se usa el principal. No necesitas configurar nada adicional.

### Manejo de errores

Todas las llamadas a la API de Asana tienen un timeout de 30 segundos. Si una peticion falla, Frihet registra el error automaticamente para diagnostico. Verifica tu conexion a internet si las consultas fallan repetidamente.

## Solución de problemas

### "Error de autenticación"

- Verifica que el Personal Access Token es correcto
- Comprueba que no ha sido revocado en la consola de desarrollador de Asana
- Si regeneraste el token, actualízalo en Frihet

### "No veo mis proyectos"

- Frihet usa el primer workspace de tu cuenta. Si tienes varios, el que quieres puede estar en otro
- Verifica que tienes acceso a los proyectos desde tu cuenta de Asana
- Los proyectos privados de otros usuarios no serán visibles

### "Las tareas no se actualizan"

- Las consultas son en tiempo real (bajo demanda)
- Recarga la vista en Frihet para ver cambios recientes
- Verifica que las tareas están asignadas al proyecto correcto en Asana

### "Quiero usar otro workspace"

- Actualmente, Frihet auto-detecta el primer workspace
- Si necesitas cambiar, desconecta y reconecta la integración
- El workspace seleccionado depende del orden devuelto por la API de Asana

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Asana**
2. Haz clic en **Desconectar**
3. Opcionalmente, revoca el token en [app.asana.com/0/developer-console](https://app.asana.com/0/developer-console)

## Próximos pasos

- [Conecta Trello como alternativa de gestión de proyectos](./trello)
- [Conecta Notion para documentación y bases de datos](./notion)
- [Automatiza flujos con n8n](./n8n)

---

## BambooHR
> Path: /integraciones/bamboohr

# BambooHR

> Importa empleados y costes de nómina de BambooHR en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre BambooHR y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **BambooHR**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → BambooHR
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Beehiiv
> Path: /integraciones/beehiiv

# Beehiiv

> Sincroniza suscripciones y pagos de Beehiiv con Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Beehiiv y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Beehiiv**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Beehiiv
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Bexio
> Path: /integraciones/bexio

# Bexio

> Conecta Frihet con Bexio para exportar facturas y gastos a tu contabilidad suiza.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Bexio y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Bexio**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Bexio
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## BigCommerce
> Path: /integraciones/bigcommerce

# BigCommerce

> Sincroniza pedidos, productos y clientes de tu tienda BigCommerce con Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre BigCommerce y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **BigCommerce**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → BigCommerce
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Braintree (PayPal)
> Path: /integraciones/braintree

# Braintree (PayPal)

> Importa pagos de Braintree en Frihet y marca facturas como cobradas.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Braintree (PayPal) y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Braintree (PayPal)**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Braintree (PayPal)
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Brevo
> Path: /integraciones/brevo

# Brevo

> Sincroniza contactos y campañas de Brevo con Frihet para trackear ingresos por email marketing.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Brevo y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Brevo**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Brevo
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Brex
> Path: /integraciones/brex

# Brex

> Importa gastos y transacciones de Brex en Frihet para contabilidad automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Brex y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Brex**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Brex
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Bunq
> Path: /integraciones/bunq

# Bunq

> Conecta tu cuenta Bunq Business con Frihet para conciliación bancaria automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Bunq y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Bunq**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Bunq
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Checkout.com
> Path: /integraciones/checkout-com

# Checkout.com

> Sincroniza pagos procesados por Checkout.com con Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Checkout.com y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Checkout.com**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Checkout.com
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Clockify
> Path: /integraciones/clockify

# Clockify

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

Conecta Clockify a Frihet. Importa tus horas registradas y convierte tiempo en facturas.

## ¿Para qué sirve?

Con Clockify integrado:

- **Importar horas** — Trae tus registros de tiempo a Frihet
- **Crear facturas automáticas** — Convierte tiempo en dinero
- **Por proyecto o cliente** — Agrupa como necesites
- **Tarifas flexibles** — Define precio/hora por cliente o proyecto

## Requisitos

- **Cuenta Clockify activa** — Con horas registradas
- **API Key de Clockify** — Para autenticar
- **Frihet Pro o superior**

## Obtener tu API Key de Clockify

### Paso 1: Abre Clockify

1. Ve a [app.clockify.me](https://app.clockify.me)
2. Inicia sesión
3. En la esquina superior derecha, haz clic en el **engranaje** (Configuración)

### Paso 2: Encuentra tu API Key

1. En **Settings**, ve a **Account**
2. Busca sección **"API"**
3. Verás tu **API Key** (un token largo)
4. Haz clic en **"Copy"** para copiar
5. **Guarda este token en lugar seguro** (no lo compartas)

## Conectar Clockify a Frihet

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Clockify**
3. Haz clic en **Conectar**

### Paso 2: Ingresa API Key

1. Pega el token de Clockify
2. Haz clic en **Verificar conexión**
3. Si es correcto: "✅ Conectado"

### Paso 3: Configura proyectos

1. Elige **qué proyectos importar**:
   - Todos los proyectos ✅
   - Solo proyectos específicos ⚪

2. Establece **tarifa por defecto**:
   - Ejemplo: €55/hora
   - Cambiable por cliente después

3. Guarda

## Importar horas

### Importación manual

1. Ve a **Facturación** → **Importar desde Clockify**
2. Selecciona rango de fechas:
   - "Este mes"
   - "Últimas 2 semanas"
   - "Personalizado"
3. Elige proyectos
4. Haz clic en **"Importar"**
5. Se crean facturas en estado **"Borrador"**

### Sincronización automática

Si la activas:

1. Cada noche, Frihet importa automáticamente tus horas
2. Agrupa por cliente/proyecto
3. Crea borradores de factura
4. Confirmas cuando esté listo

## Ejemplo práctico

### En Clockify

```
Proyecto: Sitio Web
Cliente: Empresa ABC
- Lunes 3 feb: 6 horas (Desarrollo frontend)
- Miércoles 5 feb: 4 horas (Backend)
Total: 10 horas

Proyecto: Consultoría
Cliente: Juan Martínez
- Jueves 6 feb: 3 horas (Auditoría)
Total: 3 horas
```

### En Frihet (después de importar)

**Factura #1001 - Empresa ABC**
```
Concepto: Desarrollo Sitio Web
- 6h (frontend) @ €55 = €330
- 4h (backend) @ €55 = €220
Subtotal: €550
IVA (21%): €115,50
Total: €665,50

Detalle:
- 3 feb: 6h Desarrollo frontend
- 5 feb: 4h Backend
```

**Factura #1002 - Juan Martínez**
```
Concepto: Auditoría Técnica
- 3h @ €55 = €165
Subtotal: €165
IVA (21%): €34,65
Total: €199,65

Detalle:
- 6 feb: 3h Auditoría
```

## Tarifas personalizadas

### Por cliente

1. Ve a **Clientes** → abre cliente
2. En **"Tarifa Clockify"**, ingresa tu tarifa
3. Próximas importaciones usan esa tarifa

**Ejemplo:**
```
Empresa ABC: €75/h (cliente importante)
Juan Martínez: €55/h (tarifa estándar)
```

### Por proyecto

Edita la factura antes de confirmar:

1. Se importa con tarifa por defecto
2. Cambias la tarifa manualmente
3. Se recalcula automáticamente

## Agrupar horas

### Por proyecto

Si tienes múltiples proyectos del mismo cliente:

1. Importas "Proyecto A" → Factura separada
2. Importas "Proyecto B" → Factura separada
3. O combinas ambas en una factura

### Por período

```
Semana 1 (1-7 feb) → Factura semanal
Semana 2 (8-14 feb) → Otra factura
```

O agrupar todo el mes en una factura grande.

## Descripción de tareas

Si usas **descripciones de tareas** en Clockify:

```
Clockify:
- 09:00-11:00 "Diseño mockups" (2h)
- 13:00-15:30 "Integración API" (2.5h)
```

Frihet importa:
```
Factura:
- Diseño mockups: 2h @ €55 = €110
- Integración API: 2.5h @ €55 = €137.50
Total: €247.50
```

Cada línea editable antes de confirmar.

## Mapeo de proyectos y clientes

### Automático

Clockify: "Cliente XYZ" → Frihet: Cliente "Cliente XYZ"

Si no existe, Frihet lo crea.

### Manual

Para mapear un proyecto a otro cliente:

1. **Ajustes** → **Integraciones** → **Clockify** → **Mapeo**
2. Para cada proyecto, asigna cliente Frihet
3. Guarda

**Ejemplo:**
```
Proyecto Clockify "App Q1"
→ Asignar a cliente Frihet "Startup Tech"
```

## Configurar sincronización automática

Si quieres que se importe automáticamente cada noche:

1. Ve a **Ajustes** → **Integraciones** → **Clockify**
2. Activa **"Sincronización automática"**
3. Elige hora de sincronización (recomendado: 11pm)
4. Guarda

Cada noche:
- Frihet importa tus horas
- Crea borradores de factura
- Tú confirmas cuando quieras

## Prueba la integración

### Test import

1. En Clockify, registra una entrada: "Test entry" (1h)
2. En Frihet, **Facturación** → **Importar desde Clockify**
3. Elige **"Últimas 24 horas"**
4. Haz clic en **"Importar"**
5. Deberías ver un borrador de factura

Si no funciona:

- Verifica que Clockify está conectado ✅
- Las horas deben estar en "completadas" (no en pausa)
- Espera 5 minutos
- Recarga Frihet (F5)

## Ediciones después de importar

La factura llega en estado **"Borrador"**. Puedes:

- ✏️ Editar concepto
- ✏️ Cambiar tarifa/hora
- ✏️ Agregar/quitar líneas
- ✏️ Cambiar cliente
- ✏️ Ajustar IVA

Los cambios en Clockify **no afectan** la factura de Frihet.

### Importar registros de tiempo

Frihet puede convertir tus registros de tiempo en lineas de factura automaticamente:

1. Conecta tu cuenta de Clockify
2. Ve a la pestaña **Datos** de la integracion
3. Haz clic en **Importar registros de tiempo**
4. Introduce tu tarifa por hora
5. Frihet agrupa las entradas por proyecto y crea un borrador de factura

Las entradas se agrupan por proyecto, sumando las horas totales y aplicando la tarifa indicada.

## Comparación: Clockify vs Toggl

| Característica | Clockify | Toggl |
|---|---|---|
| **API** | Sí ✅ | Sí ✅ |
| **Tarifa/hora** | €55 recomendado | €60 recomendado |
| **Descripción tareas** | Sí | Sí |
| **Equipos** | Sí | Sí |
| **Costo** | Gratuito o €99/año | Gratuito o €108/año |

**Recomendación:** Usa la que ya tengas. Ambas funcionan igual de bien con Frihet.

## Límites

- **Máximo 90 días por importación** (para no sobrecargar)
- **Sin sincronización bidireccional** — Solo Clockify → Frihet
- **API Key válida indefinidamente** — Hasta que la revoques

## Troubleshooting

### "No conecta con Clockify"

- Verifica que el token es correcto (cópialo de nuevo)
- Confirma que tu cuenta Clockify está activa
- Intenta desconectar y reconectar

### "Veo horas en Clockify pero no en Frihet"

- Las horas deben estar "completadas", no en pausa
- Clockify actualiza datos cada 24h, Frihet sincroniza cada 15 minutos
- Recarga Frihet

### "¿Puedo cambiar de Toggl a Clockify?"

Sí. Los pasos:

1. Desconecta Toggl: **Ajustes** → **Integraciones** → **Toggl** → **Desconectar**
2. Conecta Clockify: **Ajustes** → **Integraciones** → **Clockify** → **Conectar**
3. Las facturas ya creadas quedan igual

### "¿Importo histórico de 6 meses?"

Sí, pero en múltiples importaciones:

1. Importa 3 meses (ej: enero-marzo)
2. Confirma las facturas
3. Importa otros 3 meses
4. Así no se mezcla el histórico

## Próximos pasos

- [Automatiza con n8n](./n8n)
- [Conecta tu banco para reconciliación](./revolut)

---

**Anterior:** [Toggl Track](./toggl)

---

## Close CRM
> Path: /integraciones/close-crm

# Close CRM

> Sincroniza leads y clientes de Close CRM con Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Close CRM y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Close CRM**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Close CRM
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## ConvertKit
> Path: /integraciones/convertkit

# ConvertKit

> Importa suscriptores y ventas de ConvertKit en Frihet para facturación automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre ConvertKit y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **ConvertKit**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → ConvertKit
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Copper CRM
> Path: /integraciones/copper-crm

# Copper CRM

> Conecta Copper CRM (nativo Google Workspace) con Frihet para sincronizar clientes y proyectos.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Copper CRM y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Copper CRM**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Copper CRM
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Correos Spain
> Path: /integraciones/correos-spain

# Correos Spain

> Conecta con la API de Correos España para gestionar envíos nacionales desde Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Correos Spain y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Correos Spain**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Correos Spain
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## DHL Express
> Path: /integraciones/dhl-express

# DHL Express

> Crea envíos DHL Express directamente desde Frihet y registra costes automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre DHL Express y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **DHL Express**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → DHL Express
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Discord Webhooks
> Path: /integraciones/discord-webhooks

# Discord Webhooks

> Envía notificaciones y alertas de Frihet directamente a canales de Discord de tu equipo.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Discord Webhooks y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Discord Webhooks**
2. Click **Conectar** → copia la Webhook URL y pégala en tu cuenta
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Discord Webhooks
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## DocuSign
> Path: /integraciones/docusign

# DocuSign

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → DocuSign**.
:::

Conecta tu cuenta de DocuSign a Frihet para enviar documentos a firmar electrónicamente y hacer seguimiento del proceso de firma directamente desde tu ERP. DocuSign es la plataforma líder mundial en firma electrónica, utilizada por más de un millón de empresas para firmar contratos, acuerdos y documentos legales con validez jurídica. Con esta integración, puedes enviar presupuestos, contratos y facturas para firma digital desde Frihet, y automatizar la creación de facturas cuando un contrato se firma.

## ¿Para qué sirve?

- **Enviar documentos a firmar** — Envía presupuestos, contratos y facturas de Frihet a DocuSign para firma electrónica con un clic
- **Seguimiento de estado** — Consulta el estado de cada documento (enviado, visto, firmado, rechazado) directamente desde Frihet
- **Contrato a factura** — Cuando un documento se firma en DocuSign, genera automáticamente la factura correspondiente en Frihet
- **Documentos vinculados** — Los documentos firmados quedan vinculados a la ficha del cliente en Frihet
- **Listar envelopes** — Consulta todos tus documentos de DocuSign desde la interfaz de Frihet

## Requisitos

- Cuenta activa en [DocuSign](https://www.docusign.com) (plan Personal o superior)
- Plan Frihet Pro o Premium
- Integration Key de DocuSign (se obtiene desde DocuSign Admin)

## Cómo conectar

### Paso 1: Obtener tu Integration Key en DocuSign

1. Inicia sesión en [admin.docusign.com](https://admin.docusign.com)
2. Ve a **Settings → Integrations → API and Keys**
3. Haz clic en **Add App / Integration Key**
4. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
5. Configura el **Redirect URI** con la URL que Frihet te proporciona
6. Copia la **Integration Key** generada

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **DocuSign** y haz clic en el card
3. Pega tu **Integration Key** en el campo correspondiente
4. Haz clic en **Conectar con DocuSign** para completar la autorización OAuth
5. Acepta los permisos solicitados en la ventana de DocuSign
6. Haz clic en **Guardar**

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Documentos para firma | Frihet → DocuSign | PDFs de presupuestos, contratos o facturas enviados para firma |
| Estado de firma | DocuSign → Frihet | Enviado, entregado, visto, firmado, rechazado, expirado |
| Documento firmado | DocuSign → Frihet | PDF firmado vinculado al registro original en Frihet |
| Datos del firmante | DocuSign → Frihet | Nombre, email, fecha y hora de firma |
| Envelopes | DocuSign → Frihet | Lista de todos los envelopes con su estado actual |

## Casos de uso

### Consultor que envía propuestas

Creas un presupuesto en Frihet y lo envías al cliente para firma a través de DocuSign. El cliente firma desde su email o móvil. Cuando la firma se completa, Frihet te notifica y puedes convertir el presupuesto en factura con un clic. Todo el flujo propuesta-firma-factura queda trazado.

### Agencia con contratos de servicio

Gestionas contratos de colaboración con clientes. Envías el contrato desde Frihet a DocuSign, haces seguimiento del estado de firma desde tu dashboard, y cuando se firma, generas la primera factura automáticamente. El contrato firmado queda vinculado a la ficha del cliente.

### Freelancer con acuerdos recurrentes

Envías acuerdos de confidencialidad (NDA) o contratos de servicio a nuevos clientes. Desde Frihet puedes consultar qué documentos están pendientes de firma y enviar recordatorios. Una vez firmados, procedes con la facturación sabiendo que la relación contractual está formalizada.

## Solución de problemas

### Error de conexión

- Verifica que la Integration Key es correcta y que la aplicación está activa en DocuSign Admin
- Comprueba que el Redirect URI configurado en DocuSign coincide con el de Frihet
- Si la autorización OAuth expiró, reconecta desde **Settings → Integraciones → DocuSign → Reconectar**

### El documento no se envía

- Asegúrate de que el documento tiene al menos un destinatario con email válido
- Verifica que tu plan de DocuSign incluye envíos disponibles (algunos planes tienen límite mensual)
- El PDF debe generarse correctamente en Frihet antes de enviarse — verifica que la factura o presupuesto tiene datos completos

### Estado no se actualiza

- Frihet consulta el estado de los documentos periódicamente. Si no se actualiza, usa el botón **Actualizar estado** en el detalle del documento
- Los cambios de estado en DocuSign pueden tardar unos segundos en reflejarse en Frihet
- Si el destinatario no ha recibido el email, verifica que la dirección es correcta y revisa la carpeta de spam

### Documento firmado no aparece vinculado

- El documento firmado se descarga automáticamente cuando el estado cambia a "firmado"
- Si no aparece, verifica la conexión con DocuSign y haz clic en **Descargar documento firmado** manualmente
- Los documentos firmados se almacenan en Frihet y se pueden ver desde la ficha del cliente o del presupuesto

## Siguientes pasos

- [Conecta PandaDoc como alternativa de firma](./pandadoc)
- [Conecta Dropbox Sign (HelloSign) para firma](./hellosign)
- [Crea presupuestos en Frihet](../facturacion/presupuestos)

---

## Dropbox
> Path: /integraciones/dropbox

# Dropbox

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Dropbox**.
:::

Conecta tu cuenta de Dropbox a Frihet para adjuntar documentos, recibos y archivos directamente a tus facturas, gastos y clientes. Dropbox es una plataforma de almacenamiento en la nube con más de 700 millones de usuarios. Con esta integración, puedes vincular archivos almacenados en Dropbox con tus registros contables en Frihet y configurar el guardado automático de las facturas PDF que generas.

## ¿Para qué sirve?

- **Adjuntar documentos** — Selecciona archivos de Dropbox y vincúlalos a facturas, gastos o fichas de clientes en Frihet
- **Backup automático de PDFs** — Las facturas PDF generadas en Frihet se guardan automáticamente en una carpeta de Dropbox
- **Recibos digitales** — Vincula fotos de recibos almacenados en Dropbox con gastos registrados en Frihet
- **Organización automática** — Estructura de carpetas automática por año, mes y tipo de documento
- **Acceso centralizado** — Todos los documentos asociados a una factura o gasto se acceden desde un solo lugar

## Requisitos

- Cuenta activa en [Dropbox](https://www.dropbox.com) (gratuita o de pago)
- Plan Frihet Pro o Premium
- Autorización OAuth de Dropbox (se gestiona directamente desde Frihet)

## Cómo conectar

### Paso 1: Autorizar Dropbox desde Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Dropbox** y haz clic en el card
3. Haz clic en **Conectar con Dropbox**
4. Se abrirá una ventana de autorización de Dropbox — inicia sesión si no lo has hecho
5. Acepta los permisos solicitados (Frihet solo accede a la carpeta designada, no a todo tu Dropbox)

### Paso 2: Configurar la carpeta de destino

1. Una vez autorizado, selecciona o crea la **carpeta base** donde Frihet almacenará documentos (p.ej., `/Frihet/`)
2. Activa el **backup automático de PDFs** si quieres que cada factura generada se guarde en Dropbox
3. Haz clic en **Guardar**

### Paso 3: Adjuntar archivos

1. Al editar una factura o gasto, haz clic en el botón **Adjuntar desde Dropbox**
2. Navega por tus carpetas y selecciona el archivo
3. El archivo queda vinculado al registro en Frihet

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Facturas PDF | Frihet → Dropbox | Copia automática de cada factura PDF generada |
| Archivos adjuntos | Dropbox → Frihet | Vínculo al archivo en Dropbox asociado a factura/gasto |
| Estructura de carpetas | Frihet → Dropbox | Carpetas creadas automáticamente: `/Frihet/2026/03/Facturas/` |
| Recibos | Dropbox → Frihet | Imágenes o PDFs de recibos vinculados a gastos |
| Contratos | Dropbox → Frihet | Documentos vinculados a fichas de clientes |

## Casos de uso

### Autónomo que necesita guardar recibos

Recibes recibos en papel y los fotografías con el móvil, subiéndolos automáticamente a Dropbox. Desde Frihet, vinculas cada foto de recibo con el gasto correspondiente. Cuando tu gestor te pide justificantes, los tiene todos accesibles desde Frihet.

### Agencia con documentación por cliente

Gestionas contratos, briefings y entregables en Dropbox para cada cliente. Puedes vincular estos documentos a la ficha del cliente en Frihet, teniendo una vista completa: facturas emitidas + documentación del proyecto, todo desde un solo lugar.

### Freelancer con backup automático

Generas facturas en Frihet y quieres tener una copia de seguridad organizada. Con el backup automático, cada factura PDF se guarda en Dropbox bajo una estructura de carpetas por año y mes. Si alguna vez necesitas buscar una factura antigua, la encuentras tanto en Frihet como en Dropbox.

## Solución de problemas

### Error de autorización

- La sesión de Dropbox puede expirar — reconecta desde **Settings → Integraciones → Dropbox → Reconectar**
- Verifica que no has revocado los permisos de Frihet desde la configuración de seguridad de Dropbox
- Si cambiaste la contraseña de Dropbox, necesitas volver a autorizar la conexión

### Los PDFs no se guardan en Dropbox

- Verifica que el **backup automático** está activado en la configuración de la integración
- Comprueba que la carpeta de destino existe y no ha sido eliminada o movida en Dropbox
- Si tu cuenta de Dropbox está llena, los archivos no se subirán — libera espacio o actualiza tu plan

### No puedo adjuntar archivos

- Asegúrate de que el archivo no supera el límite de tamaño (50 MB por archivo)
- Verifica que el formato del archivo es compatible (PDF, JPG, PNG, XLSX, DOCX)
- Comprueba que la conexión con Dropbox sigue activa en Settings

### Carpetas no se crean automáticamente

- La estructura automática se crea solo cuando se genera un nuevo PDF — no se crean carpetas vacías
- Si la carpeta base fue eliminada en Dropbox, Frihet la recreará en la próxima sincronización

## Siguientes pasos

- [Conecta Google Drive como alternativa de almacenamiento](./google-drive)
- [Escanea recibos con OCR en Frihet](../gastos/escaneo-ocr)
- [Gestiona documentos adjuntos en facturas](../facturacion/facturas)

---

## eBay
> Path: /integraciones/ebay

# eBay

> Importa pedidos de eBay en Frihet y genera facturas automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre eBay y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **eBay**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → eBay
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Etsy
> Path: /integraciones/etsy

# Etsy

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Etsy**.
:::

Conecta tu tienda de Etsy a Frihet para importar automáticamente pedidos, productos y datos de compradores. Etsy es el marketplace líder para productos artesanales, vintage y creativos, con más de 90 millones de compradores activos. Con esta integración, cada venta en tu tienda Etsy se registra como ingreso en Frihet, las comisiones de Etsy se contabilizan como gastos, y las ventas internacionales se gestionan con conversión automática de divisa.

## ¿Para qué sirve?

- **Importar pedidos** — Cada venta en Etsy se convierte automáticamente en un ingreso registrado en Frihet con todos los detalles del pedido
- **Comisiones y fees como gastos** — Las comisiones de listado, transacción y procesamiento de Etsy se registran automáticamente como gastos
- **Catálogo sincronizado** — Tus productos de Etsy se reflejan en el catálogo de Frihet
- **Multidivisa** — Las ventas internacionales se importan con su divisa original y tipo de cambio
- **Clientes importados** — Los compradores de Etsy se añaden como clientes en Frihet con sus datos de envío

## Requisitos

- Cuenta de vendedor activa en [Etsy](https://www.etsy.com)
- Plan Frihet Pro o Premium
- API Key de Etsy (se obtiene desde el Etsy Developer Portal)

## Cómo conectar

### Paso 1: Crear una aplicación en Etsy

1. Ve al [Etsy Developer Portal](https://www.etsy.com/developers)
2. Inicia sesión con tu cuenta de vendedor
3. Haz clic en **Create a New App**
4. Rellena el nombre ("Frihet ERP") y la descripción
5. Una vez aprobada la aplicación, copia la **API Key** (Keystring)

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Etsy** y haz clic en el card
3. Pega tu **API Key** en el campo correspondiente
4. Haz clic en **Conectar con Etsy** para autorizar el acceso mediante OAuth
5. Acepta los permisos solicitados en la ventana de Etsy
6. Haz clic en **Guardar**

### Paso 3: Importación inicial

1. Una vez conectado, haz clic en **Importar pedidos** para traer el historial de ventas
2. Selecciona el rango de fechas que quieres importar
3. Revisa los pedidos importados y verifica que los datos son correctos

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Pedidos | Etsy → Frihet | ID, importe, fecha, productos, dirección de envío |
| Productos | Etsy → Frihet | Nombre, precio, cantidad, variantes |
| Clientes | Etsy → Frihet | Nombre del comprador, email (si disponible), dirección |
| Comisiones | Etsy → Frihet | Listing fees, transaction fees, payment processing fees como gastos |
| Divisa | Etsy → Frihet | Divisa original de la venta con tipo de cambio |
| Estado del pedido | Etsy → Frihet | Pagado, enviado, completado, reembolsado |

## Casos de uso

### Artesano con ventas internacionales

Vendes joyería artesanal en Etsy a compradores de todo el mundo. Cada venta se importa a Frihet con la divisa original (USD, GBP, EUR) y el tipo de cambio real. Las comisiones de Etsy se registran automáticamente como gastos, dándote una visión clara del margen real de cada venta. Al final del trimestre, tienes todos los datos para tu declaración fiscal.

### Vendedor de productos vintage

Gestionas un catálogo grande de productos vintage en Etsy. Cada venta actualiza tu catálogo en Frihet y registra el ingreso. Puedes generar informes de rentabilidad por producto y ver qué categorías de productos tienen mejor margen una vez descontadas las comisiones de Etsy.

### Creador digital con descargas

Vendes plantillas, ilustraciones o recursos digitales en Etsy. Las ventas se importan automáticamente sin intervención manual. Como no hay costes de envío en productos digitales, puedes hacer seguimiento preciso del margen neto: precio de venta menos comisiones de Etsy.

## Solución de problemas

### Error de conexión

- Verifica que la API Key es correcta y que la aplicación está activa en el Etsy Developer Portal
- Comprueba que la autorización OAuth no ha expirado — reconecta desde Settings si es necesario
- Asegúrate de que tu cuenta de Etsy está en buen estado (no suspendida o restringida)

### No se importan pedidos

- Confirma que tienes ventas en el rango de fechas seleccionado
- Solo se importan pedidos con pago completado — los pendientes de pago se excluyen
- Si tienes muchos pedidos, la importación puede tardar unos minutos — espera a que complete

### Comisiones no registradas

- Las comisiones se importan como gastos separados, asociados al pedido correspondiente
- Verifica que la importación de comisiones está activada en la configuración de la integración
- Las comisiones de publicidad de Etsy (Etsy Ads) se importan por separado

### Divisa incorrecta

- Frihet usa la divisa de la transacción original en Etsy
- Si tu contabilidad es en EUR y la venta fue en USD, Frihet aplica el tipo de cambio del día de la transacción
- Puedes ajustar manualmente el tipo de cambio desde el detalle del gasto/ingreso

## Siguientes pasos

- [Conecta Squarespace para ventas desde tu web](./squarespace)
- [Conecta Shopify si vendes en múltiples plataformas](./shopify)
- [Gestiona tu catálogo de productos en Frihet](../productos/catalogo)

---

## Expensify
> Path: /integraciones/expensify

# Expensify

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Expensify**.
:::

Conecta tu cuenta de Expensify a Frihet para importar automáticamente informes de gastos, recibos escaneados y categorías. Expensify es una plataforma de gestión de gastos empresariales con escaneo inteligente de recibos, flujos de aprobación y conciliación de tarjetas corporativas. Con esta integración, los gastos aprobados en Expensify se registran directamente en Frihet, eliminando la doble entrada de datos y manteniendo tu contabilidad sincronizada con los gastos reales de tu equipo.

## ¿Para qué sirve?

- **Importar informes de gastos** — Los informes aprobados en Expensify se importan como gastos individuales en Frihet con todos los detalles
- **Recibos sincronizados** — Los recibos escaneados en Expensify se vinculan automáticamente a los gastos importados en Frihet
- **Categorías preservadas** — Los gastos mantienen las categorías asignadas en Expensify, mapeadas a las categorías de Frihet
- **Datos del empleado** — Cada gasto importado incluye quién lo generó, para control interno
- **Importación selectiva** — Elige qué informes o rangos de fechas importar, sin traer todo el historial

## Requisitos

- Cuenta activa en [Expensify](https://www.expensify.com)
- Plan Frihet Pro o Premium
- Partner User ID y Partner User Secret de Expensify (se obtienen desde la configuración de integraciones)

## Cómo conectar

### Paso 1: Obtener credenciales en Expensify

1. Inicia sesión en [expensify.com](https://www.expensify.com)
2. Ve a **Settings → Account → Integrations**
3. En la sección de **API**, solicita acceso a la API de integraciones
4. Copia tu **Partner User ID** y **Partner User Secret**
5. Estas credenciales son únicas para tu cuenta y no expiran

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Expensify** y haz clic en el card
3. Introduce tu **Partner User ID** y **Partner User Secret**
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Configura el **mapeo de categorías** entre Expensify y Frihet
6. Haz clic en **Guardar**

### Paso 3: Importar gastos

1. Haz clic en **Importar informes** para traer los informes de gastos aprobados
2. Selecciona los informes o el rango de fechas que quieres importar
3. Revisa los gastos importados y verifica categorías y datos

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Informes de gastos | Expensify → Frihet | Nombre del informe, estado, fecha de aprobación |
| Gastos individuales | Expensify → Frihet | Importe, fecha, comercio, categoría, descripción |
| Recibos | Expensify → Frihet | Imagen del recibo vinculada al gasto |
| Categorías | Expensify → Frihet | Mapeadas a categorías de gastos de Frihet |
| Empleado/usuario | Expensify → Frihet | Nombre del empleado que generó el gasto |
| Divisa | Expensify → Frihet | Divisa original del gasto con tipo de cambio |

## Casos de uso

### Startup con equipo remoto

Tu equipo usa Expensify para registrar gastos de viaje, software y comidas. Cada semana, los informes aprobados se importan a Frihet automáticamente. Tu contabilidad refleja todos los gastos del equipo sin que tengas que pedirle a nadie que envíe recibos por email.

### Autónomo que usa SmartScan

Fotografías recibos con Expensify SmartScan mientras viajas o comes con clientes. Cuando vuelves a la oficina, importas los gastos a Frihet de una vez. Los recibos escaneados quedan vinculados para justificación fiscal.

### Empresa con tarjetas corporativas

Tu empresa tiene tarjetas Expensify o tarjetas corporativas conciliadas en Expensify. Los gastos de tarjeta se sincronizan con Frihet para tener una visión consolidada de todos los gastos: tanto los de tarjeta como los pagados en efectivo o por transferencia.

## Solución de problemas

### Error de conexión

- Verifica que el Partner User ID y Partner User Secret son correctos
- Comprueba que tu cuenta de Expensify tiene acceso a la API de integraciones (no todos los planes lo incluyen)
- Las credenciales de API de Expensify no expiran, pero pueden ser revocadas — verifica en tu cuenta

### No se importan informes

- Solo se importan informes con estado **aprobado** — los borradores y los pendientes de aprobación se excluyen
- Verifica que tienes informes en el rango de fechas seleccionado
- Si usas políticas de grupo en Expensify, asegúrate de que tus credenciales tienen acceso a los informes del grupo

### Categorías no coinciden

- Al configurar la integración, mapea las categorías de Expensify con las de Frihet
- Los gastos con categorías no mapeadas se importan con la categoría "General"
- Puedes editar la categoría de un gasto importado directamente en Frihet

### Recibos no se muestran

- Los recibos se importan como imágenes adjuntas al gasto. Si no aparecen, verifica que el informe en Expensify tiene recibos adjuntos
- Formatos soportados: JPG, PNG, PDF
- Recibos de gran tamaño (más de 10 MB) pueden no importarse — redúcelos en Expensify antes de importar

## Siguientes pasos

- [Conecta Pleo para gestión de tarjetas corporativas](./pleo)
- [Categoriza y gestiona tus gastos en Frihet](../gastos/categorias)
- [Escanea recibos directamente en Frihet con OCR](../gastos/escaneo-ocr)

---

## Exportacion a Software Contable
> Path: /integraciones/exportacion-contable

# Exportacion a Software Contable

:::note Funcionalidad nativa de Frihet
La exportación contable es una función integrada en Frihet — no requiere conectar ninguna integración de terceros. Está disponible en todos los planes desde **Facturación** o desde el **Dashboard Gestoría**.
:::

Frihet exporta los datos de facturacion en 5 formatos que los principales programas de contabilidad pueden importar directamente. Esto permite a gestores y asesores fiscales trabajar con sus herramientas habituales sin introducir datos manualmente.

## Formatos disponibles

| Formato               | Software destino                      | Delimitador                 | Codificacion     | Formato de fechas |
| --------------------- | ------------------------------------- | --------------------------- | ---------------- | ----------------- |
| ContaPlus xDiario.txt | Sage 50, ContaSol, A3                 | Ancho fijo (129 caracteres) | latin-1          | AAAAMMDD          |
| DATEV EXTF            | Gestorías alemanas (~90% del mercado) | `;` (punto y coma)          | latin-1 / CP1252 | DDMM              |
| Xero CSV              | Xero (global)                         | `,` (coma)                  | UTF-8            | DD/MM/YYYY        |
| QuickBooks CSV        | QuickBooks (global)                   | `,` (coma)                  | UTF-8            | MM/DD/YYYY        |
| CSV Generico          | Universal                             | `,` (coma)                  | UTF-8 con BOM    | ISO 8601          |

## ContaPlus (xDiario.txt)

El formato ContaPlus xDiario es el estandar historico de la contabilidad en Espana. Genera un archivo de texto con registros de ancho fijo de 129 caracteres por linea.

### Estructura del registro

Cada factura genera entre 2 y 3 lineas de asiento contable:

| Posicion | Longitud | Campo            | Ejemplo              |
| -------- | -------- | ---------------- | -------------------- |
| 1-2      | 2        | Tipo asiento     | `A1`                 |
| 3-10     | 8        | Fecha            | `20260215`           |
| 11-22    | 12       | Cuenta contable  | `430001000000`       |
| 23-34    | 12       | Contrapartida    | `700000000000`       |
| 35-49    | 15       | Importe          | `000000121000.00`    |
| 50       | 1        | D/H (Debe/Haber) | `D`                  |
| 51-90    | 40       | Concepto         | `Fra. FRI-2026-0001` |

### Cuentas contables por defecto

| Cuenta | Concepto                                        |
| ------ | ----------------------------------------------- |
| 430XXX | Clientes (XXX = codigo cliente)                 |
| 477000 | Hacienda Publica, IVA repercutido               |
| 700000 | Ventas de mercaderías / prestacion de servicios |
| 472000 | Hacienda Publica, IVA soportado                 |
| 600000 | Compras / gastos                                |

### Importar en Sage 50

1. Abre Sage 50 y ve a **Contabilidad** > **Diario** > **Importar**
2. Selecciona el formato **xDiario ContaPlus**
3. Carga el archivo `.txt` exportado desde Frihet
4. Revisa los asientos y confirma la importacion

## DATEV EXTF

El formato DATEV EXTF es el estandar de facto en gestorías alemanas y se usa tambien en Austria y Suiza. Frihet genera archivos compatibles con DATEV Unternehmen Online y similares.

### Cabecera EXTF

La primera linea del archivo contiene los metadatos del lote:

```
EXTF;700;21;Buchungsstapel;12;...
```

### Campos principales

| Campo               | Descripcion                          |
| ------------------- | ------------------------------------ |
| Umsatz (Soll/Haben) | Importe en Debe o Haber              |
| Gegenkonto          | Cuenta contrapartida                 |
| BU-Schlüssel        | Codigo de impuesto (8 = 19%, 9 = 7%) |
| Belegdatum          | Fecha del documento (DDMM)           |
| Buchungstext        | Texto del apunte                     |
| Belegfeld 1         | Numero de factura                    |

### Codificacion

DATEV requiere codificacion latin-1 (CP1252). Frihet convierte automaticamente los caracteres especiales (tildes, ene) al exportar.

## Xero CSV

Xero es el software contable mas utilizado en mercados anglosajones. El CSV de Xero contiene 43 columnas que cubren todos los campos de una factura de venta.

### Campos principales

| Campo           | Descripcion                             |
| --------------- | --------------------------------------- |
| \*ContactName   | Nombre del cliente (obligatorio)        |
| \*InvoiceNumber | Numero de factura                       |
| \*InvoiceDate   | Fecha de emision (DD/MM/YYYY)           |
| \*DueDate       | Fecha de vencimiento                    |
| \*UnitAmount    | Precio unitario                         |
| \*Quantity      | Cantidad                                |
| \*AccountCode   | Codigo de cuenta contable               |
| TaxType         | Tipo de impuesto (OUTPUT, INPUT, NONE)  |
| Description     | Descripcion del concepto                |
| Currency        | Codigo ISO de moneda (EUR, USD, GBP...) |

### Importar en Xero

1. En Xero, ve a **Business** > **Invoices** > **Import**
2. Selecciona **CSV** como formato
3. Carga el archivo exportado desde Frihet
4. Mapea las columnas (el CSV de Frihet usa los nombres exactos de Xero)
5. Confirma la importacion

## QuickBooks CSV

El formato QuickBooks CSV es compatible con QuickBooks Online y QuickBooks Desktop.

### Campos del CSV

| Campo       | Descripcion                   |
| ----------- | ----------------------------- |
| InvoiceNo   | Numero de factura             |
| Customer    | Nombre del cliente            |
| InvoiceDate | Fecha de emision (MM/DD/YYYY) |
| DueDate     | Fecha de vencimiento          |
| Item        | Descripcion del concepto      |
| Quantity    | Cantidad                      |
| Rate        | Precio unitario               |
| Amount      | Importe total de la linea     |
| TaxCode     | Codigo de impuesto            |
| TaxAmount   | Importe del impuesto          |
| Memo        | Notas adicionales             |

:::info Formato de fecha
QuickBooks usa el formato MM/DD/YYYY (mes/dia/ano). Frihet convierte automaticamente las fechas al exportar.
:::

## CSV Generico

El formato CSV generico es la opcion universal cuando ningun otro formato se ajusta al software destino. Incluye todos los campos disponibles con la mayor compatibilidad posible.

### Caracteristicas

- **Codificacion**: UTF-8 con BOM (compatible con Excel en todos los idiomas)
- **Delimitador**: coma
- **Fechas**: formato ISO 8601 (`YYYY-MM-DD`)
- **Importes**: notacion decimal con punto (`1234.56`)

### Campos incluidos

El CSV generico exporta todos los campos de la factura: numero, fecha, cliente (nombre, NIF, direccion), conceptos (descripcion, cantidad, precio, impuesto), totales, estado de pago y metadatos VeriFactu.

## Como exportar

### Exportacion individual

1. Ve a **Facturacion** > **Facturas**
2. Abre la factura que quieres exportar
3. En el menu de acciones, selecciona **Exportar** > formato deseado
4. Se descarga el archivo

### Exportacion por periodo (Dashboard Gestoria)

Si tienes acceso al Dashboard de Gestoria:

1. Ve a **Dashboard Gestoria** > pestana **Exportar**
2. Selecciona el **formato** de exportacion
3. Selecciona el **periodo** (mes, trimestre o rango personalizado)
4. Si gestionas varios clientes, selecciona el **cliente**
5. Haz clic en **Descargar**

El archivo contiene todas las facturas del periodo seleccionado en el formato elegido.

## Batch Modelo 303

El Dashboard de Gestoria permite generar el borrador del Modelo 303 para multiples clientes de forma simultanea:

1. Ve a **Dashboard Gestoria** > pestana **Lote**
2. Selecciona el **trimestre** y **ano**
3. Marca los clientes para los que quieres generar el modelo
4. Haz clic en **Generar lote**
5. Se descarga un archivo ZIP con un borrador de Modelo 303 por cada cliente seleccionado

:::tip
La exportacion por lotes ahorra tiempo significativo al cierre trimestral cuando gestionas multiples clientes desde un mismo workspace de gestoria.
:::

## Notas sobre codificacion

Los formatos ContaPlus y DATEV requieren codificacion **latin-1** (ISO 8859-1 / CP1252). Frihet realiza la conversion automaticamente al exportar:

- Los caracteres compatibles se convierten directamente
- Los caracteres sin equivalente en latin-1 se transliteran (por ejemplo, caracteres asiáticos se reemplazan por su representacion ASCII mas cercana)

Los formatos Xero, QuickBooks y CSV generico usan **UTF-8** y no tienen restricciones de caracteres.

---

**Relacionado:** [Libro Registro](/cumplimiento/libro-registro) | [Modelos Fiscales](/cumplimiento/modelos-fiscales) | [Todas las integraciones](https://www.frihet.io/es/integrations)

---

## Factorial
> Path: /integraciones/factorial

# Factorial

> Sincroniza empleados y nóminas de Factorial con Frihet para contabilización automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Factorial y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Factorial**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Factorial
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## FedEx
> Path: /integraciones/fedex

# FedEx

> Conecta FedEx con Frihet para gestionar envíos internacionales y costes de transporte.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre FedEx y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **FedEx**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → FedEx
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## FreshBooks
> Path: /integraciones/freshbooks

# FreshBooks

> Exporta datos de facturación de Frihet a FreshBooks para contabilidad unificada.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre FreshBooks y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **FreshBooks**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → FreshBooks
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Freshsales
> Path: /integraciones/freshsales

# Freshsales

> Importa contactos y deals de Freshsales en Frihet para facturación ágil.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Freshsales y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Freshsales**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Freshsales
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## GoCardless
> Path: /integraciones/gocardless

# GoCardless

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta GoCardless a Frihet para gestionar cobros por domiciliación bancaria SEPA. Consulta mandatos, pagos y clientes directamente desde tu ERP. Ideal para suscripciones y cobros recurrentes con comisiones bajas.

## ¿Para qué sirve?

Con GoCardless integrado:

- **Importar pagos** — Importa cobros de GoCardless como facturas en Frihet con un clic
- **Deduplicación automática** — Los pagos ya importados no se duplican (prefijo `GC-`)
- **Ver pagos** — Consulta todos tus cobros por domiciliación desde Frihet
- **Gestionar clientes** — Accede a la información de clientes con mandatos activos
- **Consultar mandatos** — Ve el estado de cada mandato SEPA (activo, pendiente, cancelado)
- **Reconciliar cobros** — Asocia pagos de GoCardless con facturas en Frihet
- **Modo sandbox** — Prueba la integración con datos ficticios

## Requisitos

- **Cuenta GoCardless activa** — [gocardless.com](https://gocardless.com)
- **Access Token de la API** — Se genera desde el dashboard
- **Frihet Pro o superior**

## Conectar GoCardless con Frihet

### Paso 1: Obtener tu Access Token

1. Ve a [manage.gocardless.com](https://manage.gocardless.com) (o [manage-sandbox.gocardless.com](https://manage-sandbox.gocardless.com) para pruebas)
2. Inicia sesión en tu cuenta
3. Ve a **Developers** en el menú lateral
4. Haz clic en **Create** → **Access Token**
5. Selecciona el scope **Read-only** (suficiente para consultar datos) o **Read-write** si necesitas gestionar cobros
6. Ponle un nombre (ej: "Frihet ERP")
7. Copia el token generado

:::caution Guarda el token
El Access Token solo se muestra una vez al crearlo. Cópialo antes de cerrar la ventana.
:::

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **GoCardless**
3. Haz clic en **Conectar**
4. Pega tu **Access Token**
5. Selecciona el entorno:
   - **Live** — Para datos reales
   - **Sandbox** — Para pruebas
6. Haz clic en **Verificar conexión**

### Paso 3: Verificar conexión

Si la conexión es correcta, Frihet mostrará:

- Nombre de tu organización en GoCardless
- Número de mandatos activos
- Número de clientes registrados

## Cómo funciona

Frihet se conecta a la **API v2 de GoCardless** (versión 2015-07-06) usando Bearer authentication:

1. Proporcionas tu Access Token
2. Frihet envía el token en la cabecera `Authorization: Bearer <token>` de cada petición
3. Los datos de pagos, clientes y mandatos se consultan bajo demanda
4. El token se almacena cifrado (AES-256-GCM) en Frihet
5. Toda la comunicación se realiza sobre HTTPS

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Pagos (cobros) | GoCardless → Frihet | Bajo demanda |
| Clientes | GoCardless → Frihet | Bajo demanda |
| Mandatos SEPA | GoCardless → Frihet | Bajo demanda |
| Estado de pagos | GoCardless → Frihet | Bajo demanda |

## Casos de uso

### Asesoría con cuotas mensuales

Cobras una cuota mensual a tus clientes por domiciliación bancaria. Desde Frihet puedes ver qué pagos se han cobrado correctamente, cuáles están pendientes y cuáles han fallado, sin salir de tu ERP.

### SaaS con suscripciones SEPA

Tus clientes europeos prefieren pagar por domiciliación en lugar de tarjeta. GoCardless gestiona los cobros recurrentes y Frihet te muestra el estado de cada pago junto a las facturas emitidas.

### Verificar mandatos antes de facturar

Antes de emitir una factura recurrente, consulta desde Frihet si el mandato del cliente sigue activo. Evita facturar a clientes cuyo mandato haya expirado o sido cancelado.

## Importar pagos a Frihet

Puedes importar los pagos de GoCardless como facturas en Frihet:

1. Ve a **Ajustes** → **Integraciones** → **GoCardless**
2. En la pestaña **Datos**, haz clic en **Importar pagos**
3. Frihet descargará todos los pagos y creará facturas por cada uno
4. Los pagos ya importados previamente se saltan automáticamente (deduplicación por `GC-{id}`)
5. Al terminar, verás el número exacto de pagos importados

Los pagos importados incluyen: importe, divisa, fecha, referencia y estado.

## Modo Sandbox

GoCardless ofrece un entorno sandbox completamente separado:

1. Regístrate en [manage-sandbox.gocardless.com](https://manage-sandbox.gocardless.com)
2. Crea un Access Token en el entorno sandbox
3. Configura Frihet en modo "Sandbox"
4. Crea mandatos y pagos de prueba desde el dashboard sandbox
5. Verifica que los datos aparecen correctamente en Frihet

## Estados de pago en GoCardless

| Estado GoCardless | Significado |
|-------------------|-------------|
| `pending_submission` | Pago creado, pendiente de enviar al banco |
| `submitted` | Enviado al banco, en proceso |
| `confirmed` | Cobro realizado con éxito |
| `paid_out` | Fondos transferidos a tu cuenta |
| `failed` | El cobro falló (fondos insuficientes, mandato cancelado, etc.) |
| `cancelled` | Cancelado antes de procesarse |

## Solución de problemas

### "Error de autenticación"

- Verifica que el Access Token es correcto y no ha expirado
- Asegúrate de usar un token **Live** en modo Live y **Sandbox** en modo Sandbox
- Si regeneraste el token en GoCardless, actualízalo en Frihet

### "No veo mis pagos"

- Comprueba que tienes pagos registrados en tu cuenta GoCardless
- Verifica que el token tiene permisos de lectura
- En sandbox, crea pagos de prueba primero

### "Error de versión de API"

- Frihet usa la versión de API 2015-07-06 de GoCardless, que es estable y compatible
- Si GoCardless notifica cambios de API, actualizaremos la integración

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **GoCardless**
2. Haz clic en **Desconectar**
3. Opcionalmente, revoca el Access Token desde el dashboard de GoCardless

## Próximos pasos

- [Conecta Stripe para cobros con tarjeta](./stripe)
- [Conecta PayPal para cobros internacionales](./paypal)
- [Configura Plaid para conexión bancaria directa](./plaid)

---

## Google Ads API
> Path: /integraciones/google-ads-api

# Google Ads API

> Importa costes de Google Ads en Frihet para comparar gasto publicitario vs ingresos.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Google Ads API y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Google Ads API**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Google Ads API
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Google Calendar
> Path: /integraciones/google-calendar

# Google Calendar

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

Conecta Google Calendar a Frihet. Las fechas importantes se sincronizan automáticamente: vencimientos de facturas, fechas fiscales, deadlines.

## ¿Para qué sirve?

Con Google Calendar integrado:

- **Vencimientos de facturas** — Se crean automáticamente en tu calendario
- **Fechas fiscales** — IVA, IRPF, declaraciones se sincronizan
- **Deadlines de pagos** — Recibos de electricidad, alquiler, etc.
- **Recordatorios automáticos** — Notificaciones antes de cada vencimiento
- **Vista unificada** — Todo junto en Google Calendar

## Requisitos

- **Cuenta Google** — Gmail, workspace, etc.
- **Google Calendar activo** — Ya deberías tenerlo
- **Frihet Pro o superior**

## Conectar Google Calendar

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Google Calendar**
3. Haz clic en **"Conectar"**

### Paso 2: Autoriza en Google

1. Serás redirigido a Google
2. Inicia sesión con tu cuenta Google
3. Verás permisos necesarios:
   - Crear eventos en tu calendario
   - Ver tus calendarios
   - Acceso a información de cuenta básica
4. Haz clic en **"Permitir"**

### Paso 3: Configura qué sincronizar

En Frihet, elige qué eventos crear en Google Calendar:

- ✅ **Vencimientos de facturas** — Recomendado
- ✅ **Fechas fiscales** — Muy útil
- ⚪ **Fechas de pago de gastos recurrentes** — Opcional
- ⚪ **Hitos personalizados** — Si tienes

Guarda.

## Qué eventos se sincronizan

### Vencimientos de facturas

Cuando creas una factura con fecha de vencimiento:

```
Frihet:
Factura #1042
Concepto: Diseño web
Cliente: Empresa ABC
Vencimiento: 20 febrero 2025

↓

Google Calendar:
20 febrero - Vencimiento factura #1042 (Empresa ABC - €2.500)
Recordatorio: 3 días antes (17 febrero)
Ubicación: Frihet App
```

### Fechas fiscales

Según tu país (España):

```
17 de febrero - IVA enero (vencimiento)
25 de marzo - IRPF 2024 (declaración)
10 de diciembre - IVA noviembre (vencimiento)
```

Todos estos se crean **automáticamente** en Google Calendar.

### Pago de gastos recurrentes

Si tienes gastos recurrentes (alquiler, luz, etc.):

```
1 de cada mes - Pago alquiler (€1.200)
15 de cada mes - Pago nómina
20 de cada mes - Pago seguros (€150)
```

Se crean como eventos recurrentes.

### Ejemplo real

**Tu calendario Google después de conectar Frihet:**

```
Febrero 2025:
5 feb → Vencimiento factura #1038 (Juan García €800) - Color naranja
10 feb → Vencimiento factura #1040 (Empresa SL €2.100) - Color naranja
17 feb → IVA enero - Vencimiento - Color rojo
17 feb → Recordatorio: vencimiento factura #1042 - Color naranja
20 feb → Vencimiento factura #1042 (Empresa ABC €2.500) - Color naranja
25 mar → IRPF 2024 - Declaración - Color rojo
```

## Recordatorios automáticos

Para cada evento creado, Frihet configura recordatorios:

| Evento | Recordatorios |
|--------|---------------|
| **Vencimiento factura** | 3 días antes, 1 día antes |
| **Fecha fiscal** | 7 días antes, 3 días antes |
| **Pago recurrente** | 1 día antes, 2 horas antes |

Puedes cambiar estos en Google Calendar per evento.

## Colores y categorías

Frihet agrupa los eventos con colores:

| Color | Tipo |
|-------|------|
| 🟠 Naranja | Vencimientos de facturas |
| 🔴 Rojo | Fechas fiscales importantes |
| 🔵 Azul | Pagos recurrentes |
| 🟢 Verde | Hitos personalizados |

Así identificas rápidamente en tu calendario.

## Calendario dedicado a Frihet

Puedes crear un **calendario separado** para Frihet:

1. En Google Calendar, crea nuevo calendario: "Frihet Finanzas"
2. En **Frihet** → **Ajustes** → **Google Calendar**, selecciona ese calendario
3. Todos los eventos de Frihet van allí
4. Mantiene tu calendario personal limpio

### Ventajas:

- ✅ No contamina calendario personal
- ✅ Fácil de compartir con contador/gestoría
- ✅ Puedes ocultarlo cuando no lo necesites

## Compartir con contador

Si tienes gestoría o contador:

1. Crea calendario "Frihet Finanzas" (paso anterior)
2. Comparte ese calendario con tu contador:
   - Ve a **Google Calendar** → calendario
   - **Compartir** → añade email del contador
   - Permisos: "Leer" (solo pueden ver)
3. Tu contador ve:
   - Vencimientos de declaraciones
   - Fechas límite de documentos
   - Fechas fiscales críticas

## Editar eventos en Google Calendar

Si cambias una fecha en Google Calendar:

❌ **NO se sincroniza a Frihet**

La sincronización es **Frihet → Google Calendar** (una dirección).

Si necesitas cambiar una fecha:

1. Edita en **Frihet** (la fuente de verdad)
2. Google Calendar se actualiza automáticamente
3. No edites directamente en Google Calendar

## Remover un evento

Si eliminas una factura en Frihet:

```
Frihet: Eliminas factura #1042
↓
Google Calendar: El evento se elimina automáticamente
```

No necesitas hacer nada en Google Calendar.

## Desconectar Google Calendar

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Google Calendar**
3. Haz clic en **"Desconectar"**
4. Los eventos existentes **quedan en Google Calendar** (no se borran)

Después:
- Los nuevos eventos de Frihet no se sincronizan
- Los eventos existentes permanecen
- Puedes reconectar después si quieres

## Privacidad

- **Solo escritura** — Frihet solo crea eventos, no lee tu calendario personal
- **Sin acceso a eventos personales** — No ve tus citas privadas
- **Datos sincronizados** — Vencimientos y fechas (sin detalles sensibles de clientes)
- **Revocable instantáneamente** — Desconecta cuando quieras

## Configuración avanzada

### Formato de evento

El formato por defecto es:

```
Vencimiento factura #1042 (Empresa ABC - €2.500)
```

Puedes personalizar en **Ajustes** → **Google Calendar** → **Formato de evento**:

```
[FACTURA] #1042 - Empresa ABC (€2.500)
```

O más simple:

```
Vencimiento: Empresa ABC €2.500
```

### Excluir clientes específicos

Si tienes un cliente que no quieres en calendario:

1. **Ajustes** → **Google Calendar** → **Excluir clientes**
2. Selecciona clientes (ej: "Cliente interno")
3. Sus vencimientos no se sincronizan

Útil si tienes clientes internos o filiales.

### Zona horaria

Frihet detecta automáticamente tu zona horaria. Si es incorrecta:

1. **Ajustes** → **Integraciones** → **Google Calendar**
2. Cambia zona horaria
3. Guarda

Los eventos se crean a las 09:00 tu hora local.

## Troubleshooting

### "No veo los eventos en Google Calendar"

- Verifica que Google Calendar está conectado ✅
- En **Configurar**, activa **"Vencimientos de facturas"**
- Espera 2 minutos
- Recarga Google Calendar (F5)

### "¿Por qué no aparecen fechas fiscales?"

- Verifica que activaste **"Fechas fiscales"** en Ajustes
- Tu país debe estar configurado como España
- Próximas fechas fiscales de 2025 deberían aparecer
- Si es fin de año, algunas fechas de 2026 aparecerán después

### "Quiero ver todos los eventos en un solo calendario"

Excelente idea:

1. **Google Calendar**, crea calendario "Finanzas Frihet"
2. **Frihet** → **Ajustes** → **Google Calendar**
3. Selecciona ese calendario
4. Todos los eventos van allí (vencimientos + fechas fiscales)

### "¿Puedo editar eventos directamente en Google Calendar?"

Técnicamente puedes, pero:

- ❌ No se sincroniza a Frihet
- ❌ Próxima sincronización sobrescribe tu cambio
- ✅ Mejor: edita en Frihet, Google Calendar se actualiza

### "¿Cómo comparto con mi equipo?"

1. Crea calendario separado "Frihet Finanzas"
2. En Google Calendar, comparte con tu equipo
3. Permisos **"Leer"** (solo ven, no editan)
4. Tu equipo ve vencimientos y fechas críticas

## Próximos pasos

- [Automatiza con n8n](./n8n)
- [Recibe notificaciones en Slack](./slack)

---

**Anterior:** [Slack](./slack)

---

## Google Drive
> Path: /integraciones/google-drive

# Google Drive

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu Google Drive a Frihet. Lista, busca, sube y descarga archivos directamente desde tu ERP. Guarda facturas y documentos en carpetas organizadas sin salir de Frihet.

## ¿Para qué sirve?

Con Google Drive integrado:

- **Listar archivos** — Ve tus archivos y carpetas de Drive desde Frihet
- **Buscar documentos** — Encuentra archivos por nombre o contenido
- **Subir archivos** — Guarda facturas, presupuestos y documentos en Drive
- **Descargar archivos** — Accede a documentos guardados en Drive desde Frihet
- **Organización automática** — Guarda documentos en carpetas por cliente o año

## Requisitos

- **Cuenta Google** — Gmail, Google Workspace o Google One
- **Frihet Pro o superior**

:::info Sin credenciales que introducir
Esta integración usa OAuth con Google. No necesitas copiar ninguna API key o token. Simplemente autorizas a Frihet a acceder a tu Google Drive mediante una ventana de inicio de sesión de Google.
:::

:::note Configuración técnica
Esta integración requiere que la variable de entorno `VITE_GOOGLE_CLIENT_ID` esté configurada en el servidor de Frihet. Si eres usuario de Frihet Cloud, ya está configurado. Si usas Frihet self-hosted, consulta la [documentación de la API REST](../desarrolladores/api-rest).
:::

## Conectar Google Drive con Frihet

### Paso 1: Iniciar la conexión

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Google Drive**
3. Haz clic en **Conectar con Google**

### Paso 2: Autorizar en Google

1. Se abrirá la ventana de inicio de sesión de Google
2. Selecciona tu cuenta de Google
3. Revisa los permisos solicitados:
   - Ver, crear y eliminar archivos en Google Drive
   - Ver información de tu cuenta
4. Haz clic en **Permitir**

### Paso 3: Verificar conexión

1. De vuelta en Frihet, verás "Conectado" con tu cuenta de Google
2. Frihet mostrará tus archivos recientes de Drive
3. La integración está lista para usar

## Cómo funciona

Frihet usa la **API de Google Drive** con flujo de autorización OAuth 2.0 (redirect):

1. Haces clic en "Conectar con Google" y autorizas en la ventana de Google
2. Google genera tokens de acceso y refresco
3. Frihet almacena ambos tokens cifrados (AES-256-GCM)
4. Con el token de acceso, Frihet puede listar, buscar, subir y descargar archivos
5. El token se refresca automáticamente cuando expira
6. En ningún momento introduces credenciales de Google en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Listado de archivos | Google Drive → Frihet | Bajo demanda |
| Búsqueda de archivos | Google Drive → Frihet | Bajo demanda |
| Subir archivos | Frihet → Google Drive | Bajo demanda |
| Descargar archivos | Google Drive → Frihet | Bajo demanda |

## Funcionalidades

### Listar archivos

1. Desde Frihet, accede a la sección de Google Drive
2. Verás tus archivos y carpetas recientes
3. Navega por carpetas para encontrar documentos

Cada archivo muestra:
- Nombre
- Tipo (documento, hoja de cálculo, PDF, imagen, etc.)
- Fecha de modificación
- Tamaño

### Buscar archivos

1. Usa la barra de búsqueda de Google Drive en Frihet
2. Busca por nombre de archivo o contenido
3. Los resultados incluyen archivos de todo tu Drive

### Subir archivos

Sube documentos desde Frihet directamente a Google Drive:

1. Selecciona el archivo a subir (factura PDF, presupuesto, documento)
2. Elige la carpeta de destino en Drive
3. El archivo se sube y queda disponible en tu Drive

### Descargar archivos

1. Navega o busca el archivo en Drive desde Frihet
2. Haz clic en **Descargar**
3. El archivo se descarga a tu dispositivo

### Exportar documentos a Drive

Puedes exportar facturas y otros documentos directamente a Google Drive:

1. Conecta tu cuenta de Google Drive
2. Selecciona la carpeta de destino (o usa la carpeta raiz)
3. Usa la funcion de exportar para guardar documentos en Drive

Frihet puede listar tus carpetas para que elijas donde guardar los archivos.

## Casos de uso

### Backup automático de facturas

Cada vez que generas una factura en PDF, la subes a una carpeta de Google Drive organizada por año y mes. Tu gestoría tiene acceso a la carpeta compartida y puede consultar las facturas sin pedírtelas.

### Documentación de proyectos centralizada

Guardas contratos, propuestas y documentos de proyecto en Google Drive. Desde Frihet, accedes a esos documentos al trabajar en la facturación del proyecto sin cambiar de aplicación.

### Compartir con la gestoría

Creas una carpeta "Frihet - Facturas 2026" en Drive y la compartes con tu gestoría. Subes facturas y documentos desde Frihet directamente a esa carpeta.

### Importar documentos para gastos

Tienes facturas de proveedores guardadas en Drive. Desde Frihet, las descargas para adjuntarlas como justificantes al registrar gastos.

## Solución de problemas

### "Error al conectar con Google"

- Verifica que tu cuenta de Google está activa
- Si usas Google Workspace corporativo, tu administrador puede haber restringido las aplicaciones de terceros
- Comprueba que no tienes bloqueadores de ventanas emergentes que impidan la ventana de Google

### "No veo mis archivos"

- Verifica que has autorizado acceso a Google Drive (no solo a Gmail)
- Los archivos compartidos contigo aparecen en la sección "Compartidos conmigo"
- Recarga la vista en Frihet

### "No puedo subir archivos"

- Comprueba que tienes espacio disponible en tu Google Drive
- El archivo no debe superar el límite de tamaño de Google Drive
- Verifica que la sesión no ha expirado

### "La sesión ha expirado"

- Google puede solicitar re-autorización periódicamente
- Ve a **Ajustes** → **Integraciones** → **Google Drive** y haz clic en **Reconectar**
- Volverás a la ventana de Google para autorizar de nuevo

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Google Drive**
2. Haz clic en **Desconectar**
3. Los tokens se eliminan de Frihet
4. Opcionalmente, revoca el acceso en [myaccount.google.com/permissions](https://myaccount.google.com/permissions)

## Próximos pasos

- [Conecta Google Calendar para vencimientos](./google-calendar)
- [Automatiza backups con n8n](./n8n)
- [Consulta la API REST para acceso programático](../desarrolladores/api-rest)

---

## Google Sheets
> Path: /integraciones/google-sheets

# Google Sheets

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Exporta tus facturas, gastos y resumen fiscal a hojas de cálculo profesionales en Google Sheets. Comparte informes con tu gestoría con un enlace. Importa datos desde cualquier spreadsheet con detección automática de columnas.

## ¿Para qué sirve?

Con Google Sheets integrado:

- **Exportar facturas** — Libro de facturas con formato profesional, fórmulas y totales
- **Exportar gastos** — Registro de gastos con categorías y resumen por categoría
- **Resumen fiscal** — Resumen trimestral listo para compartir con tu contable
- **Importar datos** — Lee cualquier hoja de cálculo (facturas, gastos, clientes, productos)
- **Detección automática** — Reconoce columnas en español e inglés con coincidencia difusa
- **Control de duplicados** — Detecta registros duplicados antes de importar

## Requisitos

- **Cuenta Google** — Gmail, Google Workspace o Google One
- **Frihet Pro o superior**
- **Google Sheets API habilitada** en Google Cloud Console (la configura el administrador)

:::info Sin credenciales que introducir
Esta integración usa OAuth con Google. No necesitas copiar ninguna API key o token. Simplemente autorizas a Frihet a acceder a Google Sheets mediante una ventana de inicio de sesión de Google.
:::

## Conectar Google Sheets con Frihet

### Paso 1: Iniciar la conexión

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Google Sheets**
3. Haz clic en **Conectar con Google**

### Paso 2: Autorizar en Google

1. Se abrirá la ventana de inicio de sesión de Google
2. Selecciona tu cuenta de Google
3. Revisa los permisos solicitados:
   - Crear y editar hojas de cálculo en Google Sheets
   - Ver y gestionar archivos creados por la aplicación en Google Drive
4. Haz clic en **Permitir**

### Paso 3: Verificar conexión

1. De vuelta en Frihet, verás "Conectado" junto a Google Sheets
2. Las acciones de exportar e importar estarán disponibles
3. La integración está lista para usar

## Cómo funciona

Frihet usa la **API de Google Sheets v4** con flujo de autorización OAuth 2.0:

1. Haces clic en "Conectar con Google" y autorizas en la ventana de Google
2. Google genera tokens de acceso y refresco
3. Frihet almacena ambos tokens cifrados (AES-256-GCM)
4. Con el token de acceso, Frihet puede crear hojas de cálculo y leer las existentes
5. El token se refresca automáticamente cuando expira
6. En ningún momento introduces credenciales de Google en Frihet

## Datos sincronizados

| Dato                    | Dirección              | Frecuencia   |
| ----------------------- | ---------------------- | ------------ |
| Exportar facturas       | Frihet → Google Sheets | Bajo demanda |
| Exportar gastos         | Frihet → Google Sheets | Bajo demanda |
| Exportar resumen fiscal | Frihet → Google Sheets | Bajo demanda |
| Importar datos          | Google Sheets → Frihet | Bajo demanda |

## Exportar a Google Sheets

### Exportar facturas

Crea un libro de cálculo profesional con 3 hojas:

**Hoja 1: Facturas**

| Columna        | Descripción                         |
| -------------- | ----------------------------------- |
| N. Factura     | Número de factura                   |
| Cliente        | Nombre del cliente                  |
| NIF            | NIF/CIF del cliente                 |
| Fecha          | Fecha de emisión                    |
| Vencimiento    | Fecha de vencimiento                |
| Base Imponible | Subtotal sin impuestos              |
| IVA %          | Tipo de IVA aplicado                |
| IVA            | Importe de IVA                      |
| IRPF %         | Retención de IRPF                   |
| IRPF           | Importe de IRPF                     |
| Total          | Importe total                       |
| Estado         | Borrador, enviada, cobrada, vencida |

Incluye:

- Fila de totales con fórmulas `SUM()`
- Formato de moneda EUR
- Formato condicional: cobrada (verde), vencida (rojo), borrador (gris)
- Filtro automático en todas las columnas
- Cabecera fija (frozen)

**Hoja 2: Resumen Fiscal**

Desglose por trimestres (Q1-Q4):

- Base imponible por trimestre
- IVA repercutido
- IRPF retenido
- Totales anuales

**Hoja 3: Detalle de Líneas**

Una fila por línea de factura (expandida):

- N. Factura, Descripción, Cantidad, Precio Unitario, Subtotal, IVA

### Exportar gastos

Crea un libro de cálculo con 2 hojas:

**Hoja 1: Gastos**

- N. Factura, Proveedor, Fecha, Descripción, Categoría, Base, IVA, IRPF, Total, Tipo IVA
- Formato condicional por categoría
- Filtro automático y fila de totales

**Hoja 2: Resumen por Categoría**

- Desglose de gastos por categoría con totales

### Exportar resumen fiscal

Crea un libro de cálculo completo para tu contable con 3 hojas:

- Resumen fiscal (ingresos + gastos + estimación M303)
- Facturas emitidas
- Facturas recibidas (gastos)

### Cómo exportar

1. Ve a **Ajustes** → **Integraciones** → **Google Sheets**
2. En la pestaña **Datos**, elige la acción de exportación
3. Frihet crea la hoja de cálculo en tu Google Drive
4. Se abre automáticamente en una nueva pestaña
5. El enlace se copia al portapapeles para compartir

## Importar desde Google Sheets

### Tipos de datos soportados

| Tipo      | Columnas detectadas automáticamente                    |
| --------- | ------------------------------------------------------ |
| Facturas  | factura, cliente, NIF, fecha, total, IVA, estado       |
| Gastos    | proveedor, fecha, descripción, categoría, importe, IVA |
| Clientes  | nombre, NIF, email, teléfono, dirección                |
| Productos | nombre, descripción, precio, IVA                       |

### Detección automática de columnas

Frihet reconoce cabeceras en español e inglés con coincidencia difusa. Ejemplos:

| Frihet espera | Cabeceras reconocidas                           |
| ------------- | ----------------------------------------------- |
| Fecha         | fecha, date, fecha emisión, issue date          |
| Cliente       | cliente, client, customer, nombre, razón social |
| NIF           | nif, cif, tax id, vat, dni                      |
| Total         | total, importe, amount, monto                   |

Si no se detecta automáticamente, puedes ajustar el mapeo manualmente.

### Flujo de importación

1. **Seleccionar hoja** — Elige una de tus hojas de cálculo de Google Drive o pega una URL
2. **Seleccionar pestaña** — Si la hoja tiene varias pestañas, elige la correcta
3. **Mapeo de columnas** — Frihet detecta automáticamente el tipo de datos y las columnas. Puedes ajustar
4. **Vista previa** — Revisa los datos parseados con avisos de validación
5. **Importar** — Los registros se crean en Frihet

### Detección de duplicados

Antes de importar, Frihet compara los datos con tus registros existentes:

- Compara por número de factura o documento
- Muestra avisos para posibles duplicados
- Puedes omitir duplicados o sobrescribir

## Casos de uso

### Compartir con la gestoría

Exportas el resumen fiscal trimestral a Google Sheets. Compartes el enlace con tu gestoría. Tienen acceso instantáneo a facturas, gastos y estimaciones fiscales en un formato que conocen.

### Migrar desde otro sistema

Tienes tus facturas en un Excel exportado de Billin o cualquier otro programa. Lo subes a Google Sheets, conectas con Frihet, y el importador reconoce las columnas automáticamente. En minutos tienes todos tus datos en Frihet.

### Análisis personalizado

Exportas tus datos a Google Sheets y creas gráficos, tablas dinámicas o fórmulas personalizadas que no están (todavía) en Frihet. Lo mejor de ambos mundos.

## Solución de problemas

### "Error al conectar con Google"

- Verifica que tu cuenta de Google está activa
- Si usas Google Workspace corporativo, tu administrador puede haber restringido las aplicaciones de terceros
- Comprueba que no tienes bloqueadores de ventanas emergentes

### "No se exportaron datos"

- Verifica que tienes facturas o gastos creados en Frihet
- Comprueba que la sesión de Google no ha expirado
- Si el error persiste, desconecta y reconecta Google Sheets

### "No veo mis hojas de cálculo al importar"

- Solo se listan hojas de cálculo de Google Sheets (no Excel ni CSV)
- Verifica que la hoja está en tu Google Drive (no solo compartida)
- Para hojas compartidas, primero añádelas a "Mi unidad"

### "El importador no detecta las columnas"

- Verifica que la primera fila contiene los nombres de columna (cabeceras)
- Las cabeceras deben estar en la fila 1 de la hoja
- Prueba con cabeceras más descriptivas (ej: "Fecha" en vez de "F")
- Puedes ajustar el mapeo manualmente si la detección automática falla

### "La sesión ha expirado"

- Google puede solicitar re-autorización periódicamente
- Ve a **Ajustes** → **Integraciones** → **Google Sheets** y haz clic en **Reconectar**

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Google Sheets**
2. Haz clic en **Desconectar**
3. Los tokens se eliminan de Frihet
4. Opcionalmente, revoca el acceso en [myaccount.google.com/permissions](https://myaccount.google.com/permissions)

:::tip Integraciones programaticas
Para exportaciones automatizadas o integraciones a medida, consulta la [API REST](/desarrolladores/api-rest) y los [webhooks](/desarrolladores/webhooks) de Frihet. Puedes disparar exportaciones cuando se crea una factura o sincronizar datos con scripts propios.
:::

## Proximos pasos

- [Conecta Google Drive para gestionar archivos](./google-drive)
- [Conecta Google Calendar para vencimientos](./google-calendar)
- [Automatiza exportaciones con n8n](./n8n)
- [Consulta la API REST para acceso programatico](../desarrolladores/api-rest)

---

## Gumroad
> Path: /integraciones/gumroad

# Gumroad

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu cuenta de Gumroad a Frihet. Importa productos y ventas de tu tienda digital, genera facturas automáticas y consolida tus ingresos de creador con el resto de tu facturación.

## ¿Para qué sirve?

Con Gumroad integrado:

- **Importar productos** — Trae tu catálogo de Gumroad a Frihet
- **Importar ventas** — Cada venta se convierte en un registro de ingreso
- **Facturas automáticas** — Genera facturas por cada venta con datos del comprador
- **Deduplicación** — Las ventas ya importadas no se duplican
- **Prefijo GR-** — Las ventas importadas se identifican con el prefijo GR- para fácil rastreo
- **Estado de reembolsos** — Los reembolsos en Gumroad se reflejan automáticamente

## Requisitos

- **Cuenta Gumroad activa** — [gumroad.com](https://gumroad.com)
- **Access Token de la API** — Se genera desde la configuración de Gumroad
- **Frihet Pro o superior**

## Conectar Gumroad con Frihet

### Paso 1: Obtener tu Access Token

1. Ve a [app.gumroad.com/settings/advanced](https://app.gumroad.com/settings/advanced)
2. Inicia sesión en tu cuenta de Gumroad
3. En la sección **Applications**, busca **Access Token**
4. Si no tienes uno, haz clic en **Create application**:
   - Nombre: "Frihet ERP"
   - Redirect URI: `https://app.frihet.io` (no se usa, pero es obligatorio)
5. Copia el **Access Token** generado

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Gumroad**
3. Haz clic en **Conectar**
4. Pega tu **Access Token**
5. Haz clic en **Verificar conexión**
6. Si es correcto, verás el nombre de tu perfil de Gumroad

### Paso 3: Verificar conexión

1. Frihet mostrará un resumen de tu cuenta:
   - Número de productos activos
   - Ventas recientes
2. Haz una importación de prueba para verificar que todo funciona

## Cómo funciona

Frihet usa la API de Gumroad con autenticación Bearer:

1. Proporcionas tu Access Token
2. Frihet envía el token en la cabecera `Authorization: Bearer <token>`
3. Los productos y ventas se importan bajo demanda
4. Cada venta importada recibe un identificador con prefijo **GR-** (ej: `GR-abc123`)
5. La deduplicación se basa en el ID de venta de Gumroad: si una venta ya fue importada, no se duplica
6. El token se almacena cifrado (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Productos | Gumroad → Frihet | Bajo demanda |
| Ventas | Gumroad → Frihet | Bajo demanda |
| Datos del comprador | Gumroad → Frihet | Con cada venta |
| Estado de reembolso | Gumroad → Frihet | Con cada importación |
| Precio y divisa | Gumroad → Frihet | Con cada venta |

## Mapeo de estados

| Estado Gumroad | Estado Frihet |
|----------------|---------------|
| Venta completada | Ingreso registrado |
| Reembolso parcial | Ingreso ajustado |
| Reembolso completo | Ingreso anulado / nota de crédito |

## Casos de uso

### Creador digital con ebooks y cursos

Vendes ebooks, plantillas y cursos en Gumroad. Cada venta se importa a Frihet automáticamente con los datos del comprador, generando un registro de ingreso que puedes facturar y declarar.

### Freelancer que vende templates

Además de tus servicios de consultoría, vendes plantillas en Gumroad. Frihet consolida tus ingresos de servicios (facturas manuales) con los de productos digitales (importados de Gumroad) en un solo panel.

### Control de reembolsos

Un comprador solicita un reembolso en Gumroad. Al importar de nuevo las ventas, Frihet detecta el cambio de estado y ajusta el registro de ingreso para reflejar el reembolso.

## Importar productos

1. Ve a **Ajustes** → **Integraciones** → **Gumroad**
2. Haz clic en **Importar productos**
3. Frihet traerá todos tus productos activos de Gumroad
4. Los productos aparecerán en tu catálogo de Frihet

Datos importados por producto:
- Nombre del producto
- Precio
- Descripción
- Estado (activo/inactivo)

## Importar ventas

1. Ve a **Ajustes** → **Integraciones** → **Gumroad**
2. Haz clic en **Importar ventas**
3. Selecciona el rango de fechas
4. Frihet importará las ventas y creará registros de ingreso

Cada venta importada incluye:
- ID de venta con prefijo GR- (ej: `GR-xYz123`)
- Nombre y email del comprador
- Producto vendido
- Importe y divisa
- Fecha de la venta
- Estado (completada / reembolsada)

### Reintentos automaticos

Si una importacion falla por un error temporal (timeout, error del servidor), Frihet reintenta automaticamente hasta 3 veces con esperas exponenciales (1s, 2s, 4s). No necesitas hacer nada — los reintentos son transparentes.

## Solución de problemas

### "Error de autenticación"

- Verifica que el Access Token es correcto
- Comprueba que tu cuenta de Gumroad está activa
- Si regeneraste el token, actualízalo en Frihet

### "No se importan mis ventas"

- Comprueba que tienes ventas en el rango de fechas seleccionado
- Las ventas muy antiguas pueden tardar más en importarse
- Verifica que el Access Token tiene permisos de lectura

### "Veo ventas duplicadas"

- No debería ocurrir: Frihet deduplica por ID de venta de Gumroad
- Si ocurre, desconecta y reconecta la integración
- Las ventas ya registradas en Frihet no se verán afectadas

### "Un reembolso no se refleja"

- Importa las ventas de nuevo para que Frihet detecte el cambio de estado
- El reembolso debe estar procesado en Gumroad (no solo solicitado)

## Próximos pasos

- [Conecta Lemon Squeezy para más ventas digitales](./lemon-squeezy)
- [Conecta Shopify para e-commerce completo](./shopify)
- [Automatiza importaciones con n8n](./n8n)

---

## Gusto
> Path: /integraciones/gusto

# Gusto

> Sincroniza nóminas procesadas con Gusto en Frihet para contabilidad de personal.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Gusto y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Gusto**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Gusto
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Harvest
> Path: /integraciones/harvest

# Harvest

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta Harvest a Frihet. Importa registros de tiempo y convierte horas trabajadas en líneas de factura automáticamente. Define tarifas por cliente o proyecto y factura directamente desde tu ERP.

## ¿Para qué sirve?

Con Harvest integrado:

- **Importar registros de tiempo** — Trae tus horas registradas en Harvest a Frihet
- **Crear facturas desde horas** — Convierte tiempo en facturas con tarifas configurables
- **Proyectos y clientes** — Agrupa horas por proyecto para facturas detalladas
- **Tarifas personalizadas** — Define precio/hora por cliente o proyecto
- **Sin duplicados** — Las horas ya importadas no se re-importan

## Requisitos

- **Cuenta Harvest activa** — [getharvest.com](https://www.getharvest.com)
- **Personal Access Token** — Se genera desde la configuración de Harvest
- **Account ID** — Se obtiene junto al token
- **Frihet Pro o superior**

## Conectar Harvest con Frihet

### Paso 1: Obtener tu Personal Access Token

1. Ve a [id.getharvest.com/developers](https://id.getharvest.com/developers)
2. Inicia sesión con tu cuenta de Harvest
3. Haz clic en **Create New Personal Access Token**
4. Ponle un nombre (ej: "Frihet ERP")
5. Haz clic en **Create Personal Access Token**
6. Verás dos datos:
   - **Token** — Tu clave de acceso (ej: `123456.pt.abcdefg...`)
   - **Account ID** — El identificador numérico de tu cuenta (ej: `987654`)
7. Copia ambos valores

:::caution Guarda ambos valores
El Token solo se muestra una vez. El Account ID lo puedes consultar después, pero copia ambos ahora.
:::

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Harvest**
3. Haz clic en **Conectar**
4. Introduce tu **Personal Access Token**
5. Introduce tu **Account ID**
6. Haz clic en **Verificar conexión**
7. Si es correcto, verás el nombre de tu empresa en Harvest

### Paso 3: Verificar conexión

1. Frihet mostrará un resumen:
   - Nombre de la empresa en Harvest
   - Número de proyectos activos
   - Horas registradas recientes
2. Puedes hacer una importación de prueba

## Cómo funciona

Frihet usa la **API v2 de Harvest** con dos cabeceras de autenticación:

```
Authorization: Bearer <token>
Harvest-Account-Id: <account-id>
```

1. Proporcionas tu Personal Access Token y Account ID
2. Frihet envía ambos en las cabeceras de cada petición
3. Los registros de tiempo se importan bajo demanda o periódicamente
4. Cada registro incluye proyecto, tarea, cliente y horas
5. Las credenciales se almacenan cifradas (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Registros de tiempo | Harvest → Frihet | Bajo demanda / periódica |
| Proyectos | Harvest → Frihet | Bajo demanda |
| Clientes de Harvest | Harvest → Frihet | Bajo demanda |
| Tareas | Harvest → Frihet | Con cada registro |

## Ejemplo: Convertir horas a factura

### En Harvest

```
Proyecto: Rediseño Web - ClienteXYZ
  Lun 3 feb: 4h — Diseño de wireframes
  Mar 4 feb: 3h — Maquetación responsive
  Jue 6 feb: 5h — Desarrollo frontend
  Total: 12 horas
```

### En Frihet (después de importar)

```
Factura #1047 - ClienteXYZ
Concepto: Rediseño Web

  Diseño de wireframes:     4h × 75 EUR = 300,00 EUR
  Maquetación responsive:   3h × 75 EUR = 225,00 EUR
  Desarrollo frontend:      5h × 75 EUR = 375,00 EUR

Total: 900,00 EUR
```

## Tarifas personalizadas

### Tarifa por defecto

Al configurar la integración, defines una tarifa base (ej: 60 EUR/h). Todas las importaciones usan esta tarifa por defecto.

### Tarifa por cliente

1. Ve a **Clientes** → abre el cliente
2. En **"Tarifa Harvest"**, introduce la tarifa específica (ej: 80 EUR/h)
3. Las próximas importaciones de este cliente usarán esa tarifa

### Editar en la factura

Después de importar, la factura está en estado **Borrador**. Puedes:
- Cambiar la tarifa por hora de cualquier línea
- Añadir o quitar líneas
- Ajustar el concepto
- Confirmar cuando esté listo

### Importar registros de tiempo

Frihet puede convertir tus registros de tiempo en lineas de factura automaticamente:

1. Conecta tu cuenta de Harvest
2. Ve a la pestaña **Datos** de la integracion
3. Haz clic en **Importar registros de tiempo**
4. Introduce tu tarifa por hora
5. Frihet agrupa las entradas por proyecto y crea un borrador de factura

Las entradas de Harvest incluyen nombre de proyecto y tarea directamente, por lo que cada linea de factura refleja la tarea realizada.

## Casos de uso

### Agencia de desarrollo

Tu equipo registra horas en Harvest por proyecto y tarea. A final de mes, importas las horas a Frihet y generas facturas detalladas para cada cliente con el desglose de tareas.

### Consultor independiente

Registras tus horas de consultoría en Harvest. Semanalmente o mensualmente, importas a Frihet y creas facturas por cliente. Cada factura muestra el desglose exacto de qué hiciste y cuánto tiempo dedicaste.

### Facturación por proyecto

Tienes un proyecto grande con presupuesto cerrado. Usas Harvest para rastrear las horas reales y Frihet para facturar los hitos del proyecto. Las horas importadas te dan visibilidad de rentabilidad.

## Solución de problemas

### "Error de autenticación"

- Verifica que el Personal Access Token es correcto
- Comprueba que el Account ID corresponde a tu cuenta activa
- Si regeneraste el token, actualízalo en Frihet

### "No veo mis registros de tiempo"

- Verifica que has registrado horas en Harvest (no borradores)
- Comprueba que seleccionas el rango de fechas correcto
- Las entradas de tiempo deben tener un proyecto asignado

### "Las tarifas no son correctas"

- Revisa la tarifa por defecto en **Ajustes** → **Harvest**
- Comprueba si el cliente tiene una tarifa personalizada configurada
- Puedes editar la tarifa directamente en el borrador de factura antes de confirmar

### "Quiero cambiar el Account ID"

1. Ve a **Ajustes** → **Integraciones** → **Harvest**
2. Haz clic en **Desconectar**
3. Vuelve a conectar con el nuevo Account ID y token

## Próximos pasos

- [Conecta Toggl como alternativa de time tracking](./toggl)
- [Conecta Clockify para otra opción de time tracking](./clockify)
- [Automatiza la facturación con n8n](./n8n)

---

## Dropbox Sign (HelloSign)
> Path: /integraciones/hellosign

# Dropbox Sign (HelloSign)

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Dropbox Sign**.
:::

Conecta tu cuenta de Dropbox Sign (anteriormente HelloSign) a Frihet para gestionar tus firmas electrónicas desde tu ERP. Dropbox Sign ofrece una interfaz sencilla para enviar documentos a firma y, con esta integración, puedes consultar el estado de todas tus solicitudes de firma directamente desde Frihet.

## ¿Para qué sirve?

- **Listar solicitudes de firma** — Consulta todas tus signature requests de Dropbox Sign desde Frihet con su estado actualizado
- **Seguimiento de estado** — Visualiza si cada solicitud está pendiente, firmada, rechazada o caducada
- **Visibilidad centralizada** — No necesitas alternar entre Dropbox Sign y Frihet para saber el estado de tus documentos
- **Flujo de trabajo unificado** — Complementa la facturación de Frihet con el seguimiento de firmas de tus contratos y acuerdos

## Requisitos

- Cuenta activa en [Dropbox Sign](https://sign.dropbox.com) (anteriormente HelloSign)
- Plan Frihet Pro o Premium
- API Key de Dropbox Sign

## Cómo conectar

### Paso 1: Obtener tu API Key en Dropbox Sign

1. Inicia sesión en [app.hellosign.com](https://app.hellosign.com) o [sign.dropbox.com](https://sign.dropbox.com)
2. Ve a **Settings** (Configuración)
3. Navega a **Integrations** o **API**
4. Busca tu **API Key** en la sección de desarrolladores
5. Si no tienes una, genera una nueva clave API
6. Copia la **API Key**

:::info Autenticación
Dropbox Sign utiliza Basic Auth para su API. Frihet envía tu API Key como nombre de usuario (con contraseña vacía). No necesitas configurar nada adicional — Frihet gestiona esto automáticamente.
:::

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Dropbox Sign** (o HelloSign) y haz clic en el card
3. Pega tu **API Key** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Dropbox Sign utilizando tu API Key con autenticación Basic (la API Key se envía como username, sin password). Cuando consultas tus solicitudes de firma, Frihet obtiene la lista actualizada desde Dropbox Sign con el estado de cada una.

Al igual que PandaDoc, esta integración no importa datos a Frihet (no crea clientes ni gastos). Es una herramienta de seguimiento de firmas que complementa tu flujo de facturación y documentación.

### Información disponible por solicitud

| Dato | Descripción |
|------|-------------|
| Título del documento | Nombre del documento enviado a firma |
| Estado | Pendiente, firmado, rechazado, caducado |
| Firmantes | Lista de personas que deben firmar |
| Fecha de creación | Cuándo se creó la solicitud |
| Fecha de firma | Cuándo se completó la firma (si aplica) |

## Casos de uso

### Agencia con contratos de servicio

Envías contratos a tus clientes a través de Dropbox Sign. Desde Frihet puedes ver de un vistazo qué contratos están firmados y cuáles siguen pendientes, y crear facturas para los proyectos con contrato firmado.

### Freelancer con acuerdos de confidencialidad

Antes de empezar un proyecto, envías un NDA a tu cliente vía Dropbox Sign. Desde Frihet consultas si ya fue firmado y, cuando lo está, procedes a crear la primera factura del proyecto.

### Empresa con documentación legal

Gestionas múltiples documentos que requieren firma (contratos, addendums, acuerdos). En Frihet tienes un panel centralizado donde puedes verificar el estado de cada solicitud sin abrir otra aplicación.

## Solución de problemas

### Error de conexión

- Verifica que la API Key es correcta
- Comprueba que tu plan de Dropbox Sign incluye acceso a la API (los planes gratuitos pueden tener limitaciones)
- Si generaste una nueva API Key, la anterior se invalida — actualízala en Frihet

### No se muestran solicitudes de firma

- Asegúrate de que tienes signature requests creadas en Dropbox Sign
- Las solicitudes eliminadas o archivadas pueden no aparecer
- Verifica que la API Key pertenece a la cuenta correcta

### Estado desactualizado

- Frihet consulta el estado en tiempo real desde la API de Dropbox Sign
- Si el estado no se actualiza, verifica la conexión (puede haber un problema temporal con la API de Dropbox Sign)
- Prueba a desconectar y reconectar la integración si el problema persiste

## Siguientes pasos

- [Conecta PandaDoc como alternativa de firma con creación de documentos](./pandadoc)
- [Gestiona tus facturas en Frihet](../facturacion/facturas)
- [Crea presupuestos en Frihet](../facturacion/presupuestos)

---

## HubSpot CRM
> Path: /integraciones/hubspot

# HubSpot CRM

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → HubSpot CRM**.
:::

Conecta tu cuenta de HubSpot CRM a Frihet para importar tus contactos como clientes. Si usas HubSpot para gestionar tu pipeline de ventas y relaciones comerciales, esta integración te permite traer esos contactos a Frihet para facturarles directamente, sin duplicar datos ni escribir nada a mano.

## ¿Para qué sirve?

- **Importar contactos como clientes** — Los contactos de HubSpot se convierten en clientes de Frihet con nombre, email, teléfono, empresa y dirección
- **Eliminación de doble entrada** — No necesitas volver a crear en Frihet los clientes que ya tienes en HubSpot
- **Base de clientes unificada** — Mantén una única fuente de datos de clientes que fluye desde tu CRM a tu ERP
- **Facturación inmediata** — Una vez importados, puedes crear facturas para esos clientes directamente desde Frihet

## Requisitos

- Cuenta activa en [HubSpot](https://www.hubspot.com)
- Plan Frihet Pro o Premium
- Private App con access token en HubSpot (necesita el scope `crm.objects.contacts.read`)

## Cómo conectar

### Paso 1: Crear una Private App en HubSpot

1. Inicia sesión en [app.hubspot.com](https://app.hubspot.com)
2. Ve a **Settings** (icono de engranaje en la barra superior)
3. En el menú lateral, navega a **Integrations → Private Apps**
4. Haz clic en **Create a private app**
5. En la pestaña **Basic Info**:
   - Nombre: "Frihet ERP"
   - Descripción (opcional): "Importar contactos a Frihet"
6. En la pestaña **Scopes**, busca y activa:
   - `crm.objects.contacts.read` — Lectura de contactos
7. Haz clic en **Create app** y confirma
8. Copia el **Access Token** que se muestra. Este es el token que usarás en Frihet.

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **HubSpot CRM** y haz clic en el card
3. Pega tu **Access Token** (Private App token) en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de HubSpot utilizando el access token de tu Private App. Cuando lanzas una importación, Frihet consulta los contactos de tu cuenta de HubSpot y los crea como clientes en Frihet.

La importación es bajo demanda. Los contactos ya importados se identifican por su ID de HubSpot y no se duplican en importaciones posteriores.

### Mapeo de datos

| Dato en HubSpot | Campo en Frihet |
|-----------------|-----------------|
| First name + Last name | Nombre del cliente |
| Email | Email del cliente |
| Phone | Teléfono del cliente |
| Company | Empresa del cliente |
| Address, City, State, Zip, Country | Dirección del cliente |

## Casos de uso

### Agencia que cierra deals en HubSpot

Tu equipo comercial gestiona el pipeline en HubSpot. Cuando un deal se cierra, importas el contacto a Frihet para crear la factura. No necesitas pedirle los datos al cliente de nuevo ni copiarlos a mano.

### Consultora con base de clientes en HubSpot

Tienes cientos de contactos en HubSpot acumulados durante años. En lugar de crear cada cliente manualmente en Frihet, haces una importación masiva y tu base de datos de facturación queda lista al instante.

### Freelancer con HubSpot Free

Usas el CRM gratuito de HubSpot para gestionar contactos. Cuando necesitas facturar a un contacto, lo importas a Frihet con un clic y creas la factura con todos los datos ya completados.

## Solución de problemas

### Error de conexión

- Verifica que el access token de la Private App es correcto
- Comprueba que la Private App tiene el scope `crm.objects.contacts.read` activado
- Si eliminaste y recreaste la Private App, el token anterior deja de funcionar — actualízalo en Frihet

### No se importan contactos

- Asegúrate de que tienes contactos en tu cuenta de HubSpot
- Verifica que los contactos tienen al menos nombre o email (los contactos sin datos se omiten)
- Comprueba que la Private App no ha sido desactivada en HubSpot

### Datos incompletos en clientes importados

- Solo se importan los campos que tienen datos en HubSpot
- Si un contacto no tiene teléfono o dirección en HubSpot, esos campos quedarán vacíos en Frihet
- Puedes completar los datos directamente en Frihet después de la importación

## Siguientes pasos

- [Conecta Pipedrive como alternativa de CRM](./pipedrive)
- [Gestiona tus clientes en Frihet](../clientes/gestion-clientes)
- [Importa y exporta clientes en lote](../clientes/importar-exportar)

---

## Intercom
> Path: /integraciones/intercom

# Intercom

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Intercom**.
:::

Conecta tu cuenta de Intercom a Frihet para importar tus contactos como clientes. Si usas Intercom para comunicarte con tus usuarios y gestionar soporte, esta integración te permite traer esos contactos a Frihet para facturarles, sin tener que duplicar datos entre tu plataforma de comunicación y tu ERP.

## ¿Para qué sirve?

- **Importar contactos como clientes** — Los contactos de Intercom se convierten en clientes de Frihet con nombre, email, teléfono y empresa
- **Puente entre soporte y facturación** — Pasa de una conversación de soporte a crear una factura sin reescribir datos
- **Base de clientes actualizada** — Trae a Frihet los contactos que ya tienes registrados en Intercom
- **Deduplicación automática** — Los contactos ya importados no se duplican en importaciones posteriores

## Requisitos

- Cuenta activa en [Intercom](https://www.intercom.com)
- Plan Frihet Pro o Premium
- Access Token de Intercom (se genera desde Developer Hub)

## Cómo conectar

### Paso 1: Obtener tu Access Token en Intercom

1. Inicia sesión en [app.intercom.com](https://app.intercom.com)
2. Ve a **Settings** (icono de engranaje)
3. Navega a **Integrations → Developer Hub**
4. Si no tienes una app creada, haz clic en **New app** y dale un nombre como "Frihet ERP"
5. Dentro de la app, ve a la sección **Authentication**
6. Copia el **Access Token** que se muestra

:::caution Nota
El Access Token da acceso a los datos de tu workspace de Intercom. Guárdalo de forma segura y no lo compartas.
:::

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Intercom** y haz clic en el card
3. Pega tu **Access Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Intercom utilizando tu Access Token con autenticación Bearer. Cuando lanzas una importación, Frihet consulta los contactos registrados en tu workspace de Intercom y los crea como clientes en Frihet.

La importación es bajo demanda. Se importan tanto leads como usuarios registrados en Intercom. Los contactos ya importados se identifican por su ID de Intercom y no se duplican.

### Mapeo de datos

| Dato en Intercom | Campo en Frihet |
|------------------|-----------------|
| Name | Nombre del cliente |
| Email | Email del cliente |
| Phone | Teléfono del cliente |
| Company name | Empresa del cliente |

## Casos de uso

### SaaS con soporte en Intercom

Tus usuarios se comunican contigo a través del chat de Intercom. Cuando un usuario quiere pasar a un plan de pago o necesita una factura, importas su contacto a Frihet y creas la factura con los datos correctos sin pedírselos de nuevo.

### Agencia con clientes en Intercom

Usas Intercom para gestionar la comunicación con tus clientes. En lugar de mantener dos bases de datos separadas (una en Intercom y otra en Frihet), importas los contactos y mantienes una sola fuente de verdad para facturación.

### Empresa que migra a Frihet

Ya tienes una base de contactos consolidada en Intercom. Al conectar la integración, puedes traer todos esos contactos a Frihet de una vez y empezar a facturar sin perder tiempo en entrada manual de datos.

## Solución de problemas

### Error de conexión

- Verifica que el Access Token es correcto y corresponde a tu workspace
- Comprueba que la app en Developer Hub no ha sido eliminada o desactivada
- Si regeneraste el token, actualízalo en Frihet — el anterior deja de funcionar

### No se importan contactos

- Asegúrate de que tienes contactos registrados en Intercom (leads o usuarios)
- Los contactos sin nombre ni email se omiten durante la importación
- Verifica que el Access Token tiene permisos de lectura sobre contactos

### Datos incompletos

- Solo se importan los campos que tienen datos en Intercom
- Si un contacto no tiene teléfono o empresa asociada, esos campos quedarán vacíos en Frihet
- Puedes completar los datos manualmente en Frihet después de la importación

## Siguientes pasos

- [Conecta HubSpot como alternativa de CRM](./hubspot)
- [Conecta Pipedrive para gestión de pipeline](./pipedrive)
- [Gestiona tus clientes en Frihet](../clientes/gestion-clientes)

---

## Lemlist
> Path: /integraciones/lemlist

# Lemlist

> Importa leads y deals cerrados de Lemlist en Frihet para facturación ágil.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Lemlist y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Lemlist**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Lemlist
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Lemon Squeezy
> Path: /integraciones/lemon-squeezy

# Lemon Squeezy

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu tienda de Lemon Squeezy a Frihet. Importa productos y pedidos de software digital, registra ingresos automáticamente y mantén toda tu facturación centralizada. Lemon Squeezy actúa como Merchant of Record (gestiona impuestos por ti) y Frihet registra las transacciones para tu contabilidad.

## ¿Para qué sirve?

Con Lemon Squeezy integrado:

- **Importar productos** — Trae tu catálogo de software y productos digitales a Frihet
- **Importar pedidos** — Cada venta se registra como ingreso en tu ERP
- **Deduplicación automática** — Los pedidos ya importados no se duplican (prefijo `LS-`)
- **Multi-tienda** — Si tienes varias tiendas, selecciona cuál importar o importa de todas
- **Gestión de impuestos simplificada** — Lemon Squeezy maneja los impuestos como MoR; Frihet registra los importes netos
- **Suscripciones** — Seguimiento de pagos recurrentes de SaaS

## Requisitos

- **Cuenta Lemon Squeezy activa** — [lemonsqueezy.com](https://www.lemonsqueezy.com)
- **API Key** — Se genera desde el dashboard
- **Frihet Pro o superior**

## Conectar Lemon Squeezy con Frihet

### Paso 1: Obtener tu API Key

1. Ve a [app.lemonsqueezy.com/settings/api](https://app.lemonsqueezy.com/settings/api)
2. Inicia sesión en tu cuenta
3. Haz clic en **Create API key** (o el botón "+")
4. Ponle un nombre (ej: "Frihet ERP")
5. Copia la API Key generada

:::caution Guarda la clave
La API Key solo se muestra una vez al crearla. Cópiala antes de cerrar la ventana.
:::

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Lemon Squeezy**
3. Haz clic en **Conectar**
4. Pega tu **API Key**
5. Haz clic en **Verificar conexión**
6. Si es correcto, Frihet cargará tus tiendas disponibles
7. **(Opcional)** Selecciona una **tienda específica** del desplegable — si no seleccionas ninguna, se importarán productos y pedidos de todas tus tiendas
8. Haz clic en **Guardar conexión**

### Paso 3: Verificar conexión

1. Frihet mostrará un resumen de tu tienda:
   - Nombre de la tienda
   - Número de productos
   - Pedidos recientes
2. Realiza una importación de prueba

## Cómo funciona

Frihet usa la API de Lemon Squeezy con formato **JSON:API**:

1. Proporcionas tu API Key
2. Frihet envía la clave en la cabecera `Authorization: Bearer <api-key>`
3. Las respuestas siguen el formato JSON:API (con `data`, `attributes`, `relationships`)
4. Los productos y pedidos se importan bajo demanda
5. La deduplicación se basa en el ID de pedido de Lemon Squeezy (prefijo `LS-{id}`)
6. La API Key se almacena cifrada (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Productos | Lemon Squeezy → Frihet | Bajo demanda |
| Pedidos (orders) | Lemon Squeezy → Frihet | Bajo demanda |
| Datos del comprador | Lemon Squeezy → Frihet | Con cada pedido |
| Importe y divisa | Lemon Squeezy → Frihet | Con cada pedido |
| Estado del pedido | Lemon Squeezy → Frihet | Con cada importación |

## Merchant of Record

Lemon Squeezy actúa como **Merchant of Record**, lo que significa que:

- **Lemon Squeezy** cobra al cliente, gestiona IVA/Sales Tax y emite la factura al comprador
- **Tú recibes** el importe neto (después de impuestos y comisiones)
- **Frihet registra** el ingreso neto que recibes para tu contabilidad interna

Esto simplifica tu contabilidad: no necesitas calcular impuestos internacionales por cada venta digital.

## Casos de uso

### Desarrollador indie con SaaS

Vendes licencias de tu software a través de Lemon Squeezy. Cada pago se importa a Frihet como ingreso, tanto los pagos únicos como las renovaciones de suscripción.

### Creador de plugins o themes

Vendes plugins de WordPress, themes de Shopify o extensiones. Frihet consolida estos ingresos con el resto de tu facturación (servicios de consultoría, otros clientes).

### Seguimiento de suscripciones

Tienes un producto SaaS con plan mensual y anual. Desde Frihet puedes ver el desglose de ingresos recurrentes importados de Lemon Squeezy junto con el resto de tu negocio.

## Importar productos

1. Ve a **Ajustes** → **Integraciones** → **Lemon Squeezy**
2. Haz clic en **Importar productos**
3. Frihet traerá los productos de tu tienda

Datos importados por producto:
- Nombre
- Precio
- Tipo (pago único, suscripción)
- Estado (publicado, borrador)

## Importar pedidos

1. Ve a **Ajustes** → **Integraciones** → **Lemon Squeezy**
2. Haz clic en **Importar pedidos**
3. Selecciona el rango de fechas
4. Frihet creará registros de ingreso por cada pedido

Cada pedido importado incluye:
- ID del pedido
- Nombre y email del comprador
- Producto adquirido
- Importe total y neto
- Divisa
- Fecha del pedido
- Estado (completado, reembolsado, pendiente)

### Reintentos automaticos

Si una importacion falla por un error temporal (timeout, error del servidor), Frihet reintenta automaticamente hasta 3 veces con esperas exponenciales (1s, 2s, 4s). No necesitas hacer nada — los reintentos son transparentes.

## Solución de problemas

### "Error de autenticación"

- Verifica que la API Key es correcta y no ha sido revocada
- Comprueba que tu cuenta de Lemon Squeezy está activa
- Si creaste una nueva API Key, actualízala en Frihet

### "No se importan pedidos"

- Comprueba que tienes pedidos en el rango de fechas seleccionado
- Verifica que la API Key no está restringida a ciertos scopes
- Si tu tienda es nueva, asegúrate de que hay al menos un pedido completado

### "Los importes no coinciden con lo que veo en Lemon Squeezy"

- Frihet importa el importe que tú recibes (neto de impuestos y comisiones de Lemon Squeezy)
- El importe bruto que ve el comprador incluye impuestos gestionados por el MoR
- Consulta el desglose en tu dashboard de Lemon Squeezy para confirmar

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Lemon Squeezy**
2. Haz clic en **Desconectar**
3. Opcionalmente, revoca la API Key desde tu dashboard de Lemon Squeezy

## Próximos pasos

- [Conecta Gumroad para más ventas digitales](./gumroad)
- [Conecta Stripe para cobros con tarjeta](./stripe)
- [Automatiza importaciones con n8n](./n8n)

---

## Lexoffice
> Path: /integraciones/lexoffice

# Lexoffice

> Exporta facturas y gastos de Frihet a Lexoffice (popular en DACH).

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Lexoffice y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Lexoffice**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Lexoffice
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Lightspeed Restaurant
> Path: /integraciones/lightspeed-restaurant

# Lightspeed Restaurant

> Conecta Lightspeed Restaurant con Frihet para sincronizar ventas diarias automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Lightspeed Restaurant y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Lightspeed Restaurant**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Lightspeed Restaurant
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Lightspeed X-Series
> Path: /integraciones/lightspeed-x-series

# Lightspeed X-Series

> Integra Lightspeed X-Series (retail) con Frihet para sincronizar ventas y stock.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Lightspeed X-Series y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Lightspeed X-Series**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Lightspeed X-Series
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Adobe Commerce (Magento)
> Path: /integraciones/magento-adobe-commerce

# Adobe Commerce (Magento)

> Conecta tu tienda Magento / Adobe Commerce con Frihet para sincronizar pedidos y facturas.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Adobe Commerce (Magento) y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Adobe Commerce (Magento)**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Adobe Commerce (Magento)
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Mailchimp
> Path: /integraciones/mailchimp

# Mailchimp

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Mailchimp**.
:::

Conecta tu cuenta de Mailchimp a Frihet para sincronizar automáticamente tus clientes con audiencias y listas de correo. Mailchimp es una de las plataformas de email marketing más utilizadas del mundo, con herramientas de campañas automatizadas, segmentación avanzada y analítica de engagement. Con esta integración, cada cliente que añades o actualizas en Frihet se refleja en tus listas de Mailchimp sin intervención manual.

## ¿Para qué sirve?

- **Sincronización automática de contactos** — Tus clientes de Frihet se añaden automáticamente como suscriptores en las audiencias de Mailchimp que elijas
- **Segmentación por actividad comercial** — Crea segmentos en Mailchimp basados en datos reales de facturación: clientes activos, nuevos, con facturas pendientes o inactivos
- **Tags inteligentes** — Los contactos exportados incluyen tags con información de Frihet como plan, volumen de facturación y antigüedad
- **Datos siempre actualizados** — Cuando actualizas el email o nombre de un cliente en Frihet, se actualiza en Mailchimp automáticamente
- **Campañas basadas en eventos** — Utiliza los datos sincronizados para disparar campañas cuando un cliente recibe una factura, completa un pago o lleva tiempo inactivo

## Requisitos

- Cuenta activa en [Mailchimp](https://mailchimp.com)
- Plan Frihet Pro o Premium
- API Key de Mailchimp
- Al menos una audiencia (lista) creada en Mailchimp

## Cómo conectar

### Paso 1: Obtener tu API Key en Mailchimp

1. Inicia sesión en [mailchimp.com](https://mailchimp.com)
2. Haz clic en tu avatar y selecciona **Account & billing**
3. Navega a **Extras → API keys**
4. Haz clic en **Create A Key**
5. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
6. Copia la API Key generada (tiene el formato `xxxxxxxxxxxxxxxx-usXX`, donde `usXX` indica el datacenter)

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Mailchimp** y haz clic en el card
3. Pega tu **API Key** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Selecciona la **audiencia** (lista) donde quieres sincronizar tus clientes
6. Haz clic en **Guardar**

### Paso 3: Sincronización inicial

1. Una vez conectado, haz clic en **Sincronizar ahora** para exportar tus clientes existentes a Mailchimp
2. Verifica en Mailchimp que los contactos aparecen en la audiencia seleccionada

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Email del cliente | Frihet → Mailchimp | Se usa como identificador único del suscriptor |
| Nombre y apellido | Frihet → Mailchimp | Campos FNAME y LNAME del suscriptor |
| Empresa | Frihet → Mailchimp | Merge field COMPANY |
| Tags | Frihet → Mailchimp | Tags basados en actividad: plan, estado, antigüedad |
| Estado de suscripción | Mailchimp → Frihet | Si un contacto se desuscribe en Mailchimp, se marca en Frihet |

## Casos de uso

### Freelancer que envía newsletters a clientes

Tienes una lista de clientes en Frihet y quieres enviarles una newsletter mensual con novedades. Con la integración, cada nuevo cliente que añades en Frihet aparece automáticamente en tu lista de Mailchimp. No necesitas exportar CSV ni copiar datos a mano.

### Agencia con campañas segmentadas

Gestionas decenas de clientes en Frihet. Quieres enviar una campaña solo a los clientes activos que han pagado en los últimos 3 meses. Los tags sincronizados desde Frihet te permiten crear ese segmento directamente en Mailchimp sin manipular datos manualmente.

### E-commerce con seguimiento post-compra

Vendes productos y generas facturas en Frihet. Quieres enviar un email de agradecimiento después de cada compra y un recordatorio a clientes que llevan 30 días sin comprar. Los datos de Mailchimp se mantienen actualizados con la actividad real de Frihet.

## Solución de problemas

### Error de conexión

- Verifica que la API Key es correcta y no ha sido revocada
- Comprueba que el sufijo de la API Key coincide con tu datacenter (p.ej., `us21`)
- Si regeneraste la API Key en Mailchimp, actualízala en Frihet

### Los contactos no aparecen en Mailchimp

- Asegúrate de que los clientes en Frihet tienen email registrado — sin email no se pueden sincronizar
- Verifica que la audiencia seleccionada en Frihet existe y no ha sido archivada en Mailchimp
- Comprueba que no has alcanzado el límite de contactos de tu plan de Mailchimp

### Contacto marcado como desuscrito

- Si un contacto se desuscribe desde un email de Mailchimp, no se puede volver a añadir automáticamente (cumplimiento CAN-SPAM)
- El contacto permanece en Frihet pero aparece como desuscrito en Mailchimp
- Para re-suscribirlo, el contacto debe confirmar manualmente desde Mailchimp

### Datos desactualizados

- La sincronización se ejecuta cuando creas o editas un cliente en Frihet
- Si modificaste datos directamente en Mailchimp, esos cambios no se reflejan en Frihet (sincronización unidireccional de contactos)

## Siguientes pasos

- [Conecta Slack para recibir notificaciones de pagos](./slack)
- [Gestiona tus clientes en Frihet](../clientes/gestion-clientes)
- [Importa clientes desde CSV](../clientes/importar-exportar)

---

## Make
> Path: /integraciones/make

# Make

:::tip Disponible
Make funciona a través del sistema de webhooks de Frihet, disponible en todos los planes Pro.
:::

Conecta Frihet con Make (anteriormente Integromat). Crea automatizaciones visuales potentes sin código.

## ¿Para qué sirve?

Con Make integrado:

- **Automatizaciones visuales** — Diseña flujos con drag & drop
- **Cientos de apps** — Conecta Frihet con las herramientas que ya usas
- **Lógica avanzada** — Filtros, condiciones, iteradores y routers
- **Webhooks en tiempo real** — Frihet envía datos al instante cuando ocurre un evento

## Cómo conectar

Make se conecta a Frihet a través del sistema de **Webhooks**:

1. En Make, crea un nuevo escenario con un módulo "Webhook"
2. Copia la URL del webhook de Make
3. En Frihet, ve a **Ajustes → Integraciones → Webhooks**
4. Crea un webhook con la URL de Make
5. Selecciona los eventos que quieres enviar

Consulta la guía de [n8n](/integraciones/n8n) para ver un ejemplo similar, o la [documentación de webhooks](/desarrolladores/webhooks) para detalles sobre eventos, firma HMAC y reintentos.

---

## Mercury
> Path: /integraciones/mercury

# Mercury

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Mercury**.
:::

Conecta tu cuenta de Mercury a Frihet para importar automáticamente las transacciones de tu cuenta bancaria como gastos. Mercury es la banca preferida por startups y empresas tecnológicas, y con esta integración puedes mantener tus gastos actualizados en Frihet sin entrada manual.

## ¿Para qué sirve?

- **Importar transacciones como gastos** — Los pagos y cargos realizados desde Mercury se importan como gastos en Frihet con descripción, importe, fecha y divisa
- **Solo débitos** — Se importan únicamente las transacciones de débito (dinero que sale), no los ingresos
- **Control de burn rate** — Combinado con tus facturas en Frihet, tienes visibilidad completa de ingresos vs gastos para controlar tu runway
- **Deduplicación automática** — Las transacciones ya importadas se identifican por su ID y no se duplican

## Requisitos

- Cuenta activa en [Mercury](https://mercury.com)
- Plan Frihet Pro o Premium
- API Token de Mercury

## Cómo conectar

### Paso 1: Obtener tu API Token en Mercury

1. Inicia sesión en [app.mercury.com](https://app.mercury.com)
2. Ve a **Settings** en el menú lateral
3. Selecciona **Developers** o **API**
4. Haz clic en **Generate Token** (Generar token)
5. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
6. Selecciona los permisos de solo lectura (Read) para transacciones
7. Copia el token generado. Guárdalo en un lugar seguro ya que solo se muestra una vez.

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Mercury** y haz clic en el card
3. Pega tu **API Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Si la conexión es exitosa, verás la confirmación con los datos de tu cuenta
6. Haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Mercury utilizando tu API Token con autenticación Bearer. Cuando lanzas una importación, Frihet consulta las transacciones de tus cuentas en Mercury y registra las transacciones de débito como gastos en Frihet.

La importación es bajo demanda. Solo se importan transacciones de débito completadas — pagos a proveedores, transferencias salientes, suscripciones, etc. Los depósitos e ingresos no se importan.

### Mapeo de datos

| Dato en Mercury | Campo en Frihet |
|-----------------|-----------------|
| Descripción de la transacción | Descripción del gasto |
| Importe (débito) | Importe del gasto |
| Fecha de la transacción | Fecha del gasto |
| Divisa | Divisa del gasto |
| Contrapartida / beneficiario | Notas del gasto |

## Casos de uso

### Startup en fase seed

Acabas de cerrar una ronda y necesitas controlar el burn rate. Importas las transacciones de Mercury a Frihet cada semana para ver exactamente cuánto estás gastando y en qué. Combinado con tus ingresos facturados en Frihet, tienes una foto clara de tu runway.

### SaaS con gastos recurrentes

Pagas infraestructura (AWS, Vercel, Cloudflare), herramientas SaaS y servicios profesionales desde Mercury. En lugar de registrar cada cargo manualmente, importas todo a Frihet y lo categorizas para saber cuánto cuesta operar tu producto.

### Founder con múltiples cuentas

Tienes cuenta operativa y cuenta de reserva en Mercury. Puedes importar transacciones de ambas cuentas a Frihet para tener un registro unificado de todos tus gastos.

## Solución de problemas

### Error de conexión

- Verifica que el API Token es correcto y no ha sido revocado
- Comprueba que el token tiene permisos de lectura sobre transacciones
- Si regeneraste el token en Mercury, actualízalo en Frihet

### No se importan transacciones

- Solo se importan transacciones de débito completadas
- Las transacciones pendientes o en proceso no aparecen hasta que Mercury las confirma
- Verifica el rango de fechas seleccionado

### Algunas transacciones no aparecen

- Las transferencias internas entre cuentas Mercury pueden tener un tratamiento distinto
- Verifica que la cuenta específica tiene movimientos en el período seleccionado

## Siguientes pasos

- [Conecta Wise para transferencias internacionales](./wise)
- [Conecta Qonto si usas banca empresarial europea](./qonto)
- [Aprende a categorizar gastos importados](../gastos/categorias)

---

## Meta Marketing API
> Path: /integraciones/meta-marketing-api

# Meta Marketing API

> Conecta tus campañas de Meta Ads con Frihet para trackear ROI y costes publicitarios.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Meta Marketing API y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Meta Marketing API**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Meta Marketing API
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Microsoft Teams Webhooks
> Path: /integraciones/microsoft-teams-webhooks

# Microsoft Teams Webhooks

> Recibe notificaciones de Frihet en canales de Microsoft Teams.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Microsoft Teams Webhooks y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Microsoft Teams Webhooks**
2. Click **Conectar** → copia la Webhook URL y pégala en tu cuenta
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Microsoft Teams Webhooks
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Mollie
> Path: /integraciones/mollie

# Mollie

> Acepta pagos con Mollie y sincroniza cobros automáticamente en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Mollie y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Mollie**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Mollie
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Monzo Premium
> Path: /integraciones/monzo-business

# Monzo Premium

> Sincroniza transacciones de Monzo Premium con Frihet para conciliación automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Monzo Premium y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Monzo Premium**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Monzo Premium
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## N26 Business
> Path: /integraciones/n26

# N26 Business

:::caution No disponible
N26 Business no ofrece una API publica. Para sincronizar cuentas N26, recomendamos usar la integracion de Plaid.
:::

N26 Business es la cuenta bancaria empresarial de N26, un neobanco móvil europeo con gestión de finanzas en tiempo real y sin comisiones de mantenimiento.

## ¿Para qué sirve?

Con N26 Business integrado en Frihet:

- **Sincronizar transacciones** — Importa automáticamente los movimientos de tu cuenta N26 Business a Frihet
- **Categorizar gastos empresariales** — Clasifica los pagos y gastos de N26 en las categorías de tu ERP
- **Seguimiento de saldo en tiempo real** — Consulta el estado de tu cuenta sin salir de Frihet

## Estado

Esta integración aparece en la sección de integraciones de Frihet. La funcionalidad completa está en desarrollo.

---

## n8n
> Path: /integraciones/n8n

# n8n

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

Conecta Frihet a n8n para automatizar flujos de trabajo: recordatorios automáticos, sincronización con CRM, notificaciones personalizadas, y más.

## ¿Para qué sirve?

Con n8n integrado:

- **Recordatorios automáticos** — Envía emails cuando una factura vence
- **Sincronización CRM** — Nuevos clientes se crean en Salesforce, Pipedrive, etc.
- **Notificaciones personalizadas** — Slack, email, Telegram, webhook personalizado
- **Flujos complejos** — Condicionales, loops, ramificaciones lógicas
- **Webhook endpoints** — Otros sistemas disparan acciones en Frihet

## Nodo de comunidad oficial

Frihet publica un nodo de comunidad oficial en npm: **`n8n-nodes-frihet`**.

Instálalo directamente desde n8n sin configurar HTTP requests manuales:

1. En n8n: **Settings → Community Nodes → Install**
2. Introduce: `n8n-nodes-frihet`
3. Confirma la instalación

O vía CLI en instancias self-hosted:

```bash
npm install n8n-nodes-frihet
```

El nodo aparece en tu paleta con acceso nativo a todos los recursos de Frihet:

| Recurso | Operaciones |
|---------|-------------|
| Invoice | Create, Get, List, Update, Delete, Send, Mark Paid |
| Quote | Create, Get, List, Update, Delete, Send |
| Expense | Create, Get, List, Update, Delete |
| Client | Create, Get, List, Update, Delete |
| Product | Create, Get, List, Update, Delete |
| Vendor | Create, Get, List, Update, Delete |

Paginación cursor-based en todas las operaciones List. Campos fiscales completos: IVA, IGIC, IRPF.

- [npm](https://www.npmjs.com/package/n8n-nodes-frihet)
- [GitHub](https://github.com/Frihet-io/n8n-nodes-frihet)

## Requisitos

- **Cuenta n8n** — [Crea una en n8n.io](https://n8n.io)
- **Conocimiento básico de n8n** — O usa templates preconfigurados
- **API endpoint de Frihet** — Consulta la [documentación de la API REST](/desarrolladores/api-rest)
- **Frihet Pro o superior**

## Obtener credenciales de Frihet

### En Frihet

1. Ve a **Ajustes** → **Integraciones** → **n8n**
2. Haz clic en **"Generar API Key"**
3. Copia la clave (algo como: `fh_live_XXXXXXXXXXXXXXXXX`)
4. Haz clic en **"Crear Webhook"**
5. Copia el webhook URL (para recibir eventos)

Guarda ambos en lugar seguro.

## Conectar Frihet a n8n

### Paso 1: Crea workflow en n8n

1. Ve a [n8n.io](https://n8n.io)
2. **Nuevo workflow**
3. Añade nodo: **Frihet** (búscalo)

### Paso 2: Configura credenciales

1. En el nodo de Frihet, ve a **Credenciales**
2. Haz clic en **"Crear nueva credencial"**
3. Pega la **API Key** de Frihet
4. Guarda

### Paso 3: Elige acción

En el nodo, elige qué hacer:

- Crear factura
- Crear gasto
- Crear cliente
- Obtener listado de clientes
- Obtener listado de facturas
- Marcar factura como pagada

## Casos de uso común

### Recordatorio de vencimiento

**Cuando:** Cada mañana a las 9am
**Qué hace:** Busca facturas vencidas y envía email al cliente

```
n8n workflow:
1. Trigger: Cada día a las 09:00
2. Nodo Frihet: Obtener facturas vencidas
3. Loop: Para cada factura
4. Nodo Email: Enviar email de recordatorio
5. Actualizar en Frihet: Marcar "Recordatorio enviado"
```

### Nuevo cliente → CRM

**Cuando:** Se crea cliente en Frihet
**Qué hace:** Automáticamente lo añade a Salesforce/Pipedrive

```
n8n workflow:
1. Trigger: Webhook de Frihet (nuevo cliente)
2. Nodo Frihet: Obtener datos del cliente
3. Nodo Salesforce: Crear contacto
4. Nodo Email: Notificar al equipo
```

### Factura pagada → Notificación Slack

**Cuando:** Se marca una factura como pagada
**Qué hace:** Envía notificación a Slack con detalles

```
n8n workflow:
1. Trigger: Webhook de Frihet (factura pagada)
2. Nodo Frihet: Obtener detalles de factura
3. Nodo Slack: Enviar mensaje formateado
4. Nodo Sheet: Registrar en Google Sheets (opcional)
```

### Crear factura desde form

**Cuando:** Alguien completa un formulario
**Qué hace:** Automáticamente crea factura en Frihet

```
n8n workflow:
1. Trigger: Webhook de formulario (TypeForm, Typebot, etc.)
2. Node: Procesar datos del formulario
3. Nodo Frihet: Crear factura
4. Nodo Email: Confirmar al cliente
```

## Templates preconfigurados

n8n y Frihet ofrecen templates listos:

1. En n8n, ve a **Community** → **Templates**
2. Busca **"Frihet"**
3. Elige un template
4. Haz clic en **"Use this template"**
5. Solo configura credenciales

### Templates disponibles

- "Recordatorio de facturas vencidas"
- "Sincronizar clientes a Airtable"
- "Notificaciones de pagos en Slack"
- "Crear facturas desde Typeform"
- "Backup diario a Google Drive"

Úsalos como base y personaliza.

## Webhook de Frihet

Frihet envía eventos automáticamente a n8n. Consulta la [documentación completa de webhooks](/desarrolladores/webhooks) para detalles sobre firma HMAC-SHA256, reintentos y todos los tipos de evento.

### Eventos que disparan webhook

| Evento | Datos enviados |
|--------|----------------|
| **Factura creada** | ID, cliente, monto, vencimiento |
| **Factura pagada** | ID, cliente, monto, fecha pago |
| **Factura vencida** | ID, cliente, monto, días vencida |
| **Cliente creado** | ID, nombre, email, teléfono |
| **Gasto creado** | ID, categoría, monto, fecha |
| **Pago recibido** | ID factura, cliente, monto |

### Configurar webhook en Frihet

1. **Ajustes** → **Integraciones** → **n8n**
2. Haz clic en **"Crear Webhook"**
3. Elige qué eventos disparar (recomendado: todos)
4. Copia la URL del webhook
5. En n8n, configura un nodo **"Webhook"** como trigger con esa URL

## Acciones disponibles en Frihet

### Crear factura

```javascript
Entrada:
- Cliente ID (o crear nuevo)
- Concepto
- Monto
- Vencimiento
- IVA

Salida:
- ID de factura creada
- Número de documento
- Estado
```

### Crear gasto

```javascript
Entrada:
- Categoría
- Monto
- Fecha
- Proveedor (opcional)

Salida:
- ID de gasto
- Confirmación
```

### Obtener listado

```javascript
Entrada:
- Filtro (fecha, cliente, estado)
- Límite de resultados

Salida:
- Array de facturas/gastos/clientes
```

### Marcar como pagada

```javascript
Entrada:
- ID factura
- Monto (opcional)
- Método de pago (opcional)

Salida:
- Confirmación
- Fecha de actualización
```

## Ejemplo completo: Recordatorio diario

### Objetivo

Cada mañana a las 8am, si hay facturas vencidas, envía email al cliente.

### Workflow en n8n

**Paso 1: Trigger**
```
Scheduler: Todos los días a las 08:00
Timezone: Europe/Madrid
```

**Paso 2: Obtener facturas vencidas**
```
Nodo: Frihet
Acción: Get Invoices
Filtro: State = "unpaid" AND Due Date < Today
```

**Paso 3: Loop sobre cada factura**
```
Loop Node: Para cada factura en el resultado
  - Obtener email del cliente
  - Calcular días vencida
```

**Paso 4: Enviar email**
```
Nodo: Gmail / SendGrid
Para: email del cliente
Asunto: "Factura #{{$node.Frihet.data.number}} por cobrar"
Cuerpo:
  "Tu factura {{id}} de {{monto}} euros
   está vencida desde hace {{días_vencida}} días.
   Por favor, realiza el pago cuanto antes.
   [Enlace de pago]"
```

**Paso 5: Actualizar en Frihet**
```
Nodo: Frihet
Acción: Update Invoice
Actualizar: reminder_sent = true
Actualizar: reminder_date = today
```

## Sincronización bidireccional con CRM

### Crear cliente en Frihet → Salesforce

```
1. Trigger: Webhook Frihet (cliente creado)
2. Frihet: Obtener datos del cliente
3. Salesforce: Crear Account
4. Salesforce: Crear Contact
5. Frihet: Guardar Salesforce ID en cliente
```

### Crear deal en Salesforce → Factura en Frihet

```
1. Trigger: Webhook Salesforce (deal ganado)
2. Salesforce: Obtener datos del deal
3. Frihet: Crear cliente (si es nuevo)
4. Frihet: Crear factura con monto del deal
5. Salesforce: Actualizar deal con link a Frihet
```

## Notificaciones personalizadas

### Opción 1: Email

```
Nodo: Gmail / SendGrid
Plantilla personalizada con:
  - Logo de tu empresa
  - Detalles de factura
  - Enlace de pago
```

### Opción 2: Slack

```
Nodo: Slack
Mensaje:
  ":moneybag: Factura pagada
   Cliente: {{cliente}}
   Monto: €{{monto}}
   Estado: Pagada ✅"
```

### Opción 3: WhatsApp/Telegram

```
Nodo: Telegram / WhatsApp (vía Twilio)
Mensaje:
  "Hola {{nombre}},
   Tu factura #{{id}} vence en 3 días.
   [Paga aquí]"
```

### Opción 4: Webhook personalizado

Si tienes tu propio sistema:

```
Nodo: HTTP POST
URL: https://tu-sistema.com/frihet-webhook
Body:
  {
    "event": "invoice_paid",
    "invoice_id": "...",
    "amount": 1200,
    "client": "..."
  }
```

Tu sistema procesa como necesite.

## Condiciones y lógica

Puedes agregar condiciones:

```
IF factura vencida MÁS DE 7 DÍAS
  THEN enviar email + crear tarea
ELSE IF vencida MENOS DE 7 DÍAS
  THEN solo enviar email
ELSE
  THEN no hacer nada
```

O ramificaciones más complejas:

```
IF cliente es "Premium"
  THEN llamar por teléfono
ELSE IF cliente es "Regular"
  THEN enviar email
ELSE
  THEN ignorar
```

## Testing y debugging

### Ejecutar workflow manualmente

1. En n8n, haz clic en **"Execute"**
2. Ves resultados paso a paso
3. Si hay error, lo muestra con detalles
4. Ajusta y vuelve a ejecutar

### Logs y historial

1. Ve a **Executions** en tu workflow
2. Ves cada ejecución:
   - Cuándo se ejecutó
   - Si fue exitosa
   - Tiempo de ejecución
   - Resultados de cada nodo

### Test con datos de prueba

Antes de activar (schedule), prueba:

1. Edita el trigger a **Manual**
2. Haz clic en **"Execute"** varias veces
3. Verifica que cada nodo funciona
4. Luego cambia a **Trigger automático** (scheduler)

## Límites y costos

### En n8n

- **Workflow automáticos:** Depende de tu plan
- **Ejecuciones:** Gratuito hasta cierto límite
- **Nodos:** Ilimitados
- **Integraciones:** Cientos disponibles

### En Frihet

- **API calls:** Incluidos en Pro (no hay límite adicional)
- **Webhooks:** Ilimitados
- **Datos:** Sin límite especial para n8n

## Troubleshooting

### "Webhook no dispara"

- Verifica que el webhook está **activo** en Frihet
- El evento debe coincidir con la configuración
- Comprueba logs de n8n: **Executions** → historial
- Si hay error HTTP, revisa estado del webhook

### "Error: No credentials found"

- En n8n, verifica que las credenciales están guardadas
- Copia nuevamente la API Key de Frihet
- Recrea la credencial

### "¿Cómo debug si algo no funciona?"

1. Añade nodo **"Log"** entre pasos para ver datos intermedios
2. Ejecuta manualmente paso a paso
3. Ve **Executions** → historial completo
4. Busca el error en los logs

### "¿Puedo usar múltiples workflows?"

Sí. Puedes tener:

- Workflow 1: Recordatorios diarios
- Workflow 2: Sincronización CRM
- Workflow 3: Backups automáticos
- Todos corriendo en paralelo

## Próximos pasos

- Explora [plantillas de n8n](https://n8n.io/workflows)
- Lee la [documentación de la API REST](/desarrolladores/api-rest) y los [webhooks](/desarrolladores/webhooks)
- Crea tu primer automation personalizado

---

**Anterior:** [Revolut Business](./revolut)

---

## Notion
> Path: /integraciones/notion

# Notion

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu workspace de Notion a Frihet. Busca páginas, consulta bases de datos y accede a información de proyectos y clientes directamente desde tu ERP sin cambiar de aplicación.

## ¿Para qué sirve?

Con Notion integrado:

- **Buscar páginas** — Encuentra cualquier página de tu workspace desde Frihet
- **Listar bases de datos** — Ve todas tus bases de datos de Notion
- **Consultar registros** — Haz queries a bases de datos con filtros
- **Contexto de proyecto** — Accede a información de proyectos vinculados a facturas
- **Documentación accesible** — Consulta SOPs, contratos o briefs sin salir del ERP

## Requisitos

- **Cuenta Notion activa** — [notion.so](https://www.notion.so)
- **Internal Integration Token** — Se crea desde la configuración de integraciones de Notion
- **Frihet Pro o superior**

## Conectar Notion con Frihet

### Paso 1: Crear una integración interna en Notion

1. Ve a [notion.so/my-integrations](https://www.notion.so/my-integrations)
2. Inicia sesión con tu cuenta de Notion
3. Haz clic en **New integration**
4. Configura la integración:
   - **Name**: "Frihet ERP"
   - **Associated workspace**: Selecciona tu workspace
   - **Capabilities**: Marca al menos "Read content" y "Read user information"
5. Haz clic en **Submit**
6. Copia el **Internal Integration Token** (empieza por `ntn_...`)

:::caution Guarda el token
El token se puede consultar después, pero cópialo ahora para no tener que volver.
:::

### Paso 2: Compartir páginas con la integración

Notion requiere que compartas explícitamente las páginas o bases de datos con tu integración:

1. Abre la página o base de datos que quieres que Frihet pueda ver
2. Haz clic en **...** (menú de la página) → **Connections**
3. Busca **"Frihet ERP"** (el nombre de tu integración)
4. Haz clic para añadirla
5. Repite para cada página o base de datos que necesites

:::info Solo lo que compartas
La integración solo puede acceder a las páginas y bases de datos que compartas explícitamente. No tiene acceso a todo tu workspace.
:::

### Paso 3: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Notion**
3. Haz clic en **Conectar**
4. Pega tu **Internal Integration Token** (`ntn_...`)
5. Haz clic en **Verificar conexión**
6. Si es correcto, verás el nombre de tu workspace

## Cómo funciona

Frihet usa la **API de Notion** (versión 2022-06-28):

1. Proporcionas tu Internal Integration Token
2. Frihet envía el token en la cabecera `Authorization: Bearer ntn_...`
3. Además, incluye la cabecera `Notion-Version: 2022-06-28` en cada petición
4. Las búsquedas y consultas se realizan bajo demanda
5. El token se almacena cifrado (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Páginas (búsqueda) | Notion → Frihet | Bajo demanda |
| Bases de datos (listado) | Notion → Frihet | Bajo demanda |
| Registros de base de datos | Notion → Frihet | Bajo demanda (query) |
| Propiedades de página | Notion → Frihet | Con cada consulta |

## Funcionalidades

### Buscar páginas

Busca cualquier página compartida con la integración por título o contenido:

1. Desde Frihet, usa la función de búsqueda de Notion
2. Escribe el término de búsqueda
3. Frihet devuelve las páginas que coincidan
4. Haz clic en un resultado para ver los detalles o abrir en Notion

### Listar bases de datos

Ve todas las bases de datos compartidas con la integración:

1. Frihet consulta todas las bases de datos accesibles
2. Muestra nombre, descripción y número de registros
3. Selecciona una para consultar sus registros

### Consultar bases de datos

Haz queries a una base de datos con filtros:

1. Selecciona la base de datos
2. Aplica filtros (por propiedad, estado, fecha, etc.)
3. Frihet muestra los registros que coincidan
4. Útil para consultar, por ejemplo, una base de datos de clientes o proyectos

### Importar contactos

Puedes importar contactos desde cualquier base de datos de Notion:

1. Conecta tu cuenta de Notion
2. Selecciona la base de datos que contiene tus contactos
3. Frihet detecta automaticamente los campos: nombre, email, direccion e identificacion fiscal
4. Los contactos se importan como clientes en Frihet
5. Los duplicados se detectan por nombre (no se importan dos veces)

Frihet busca campos con nombres como "Name", "Email", "Address", "Tax ID", "NIF" tanto en ingles como en español.

## Casos de uso

### Base de datos de clientes en Notion

Mantienes una base de datos de clientes en Notion con campos como empresa, contacto y notas. Desde Frihet, consultas esa base de datos para obtener contexto al crear una factura.

### Documentación de proyectos

Tienes la documentación de cada proyecto en Notion (briefs, contratos, alcance). Al facturar un proyecto, consultas la página de Notion directamente desde Frihet para verificar el alcance acordado.

### CRM ligero

Usas Notion como CRM informal con una base de datos de deals. Desde Frihet, consultas el estado de cada deal para saber cuándo es momento de enviar una factura.

## Solución de problemas

### "Error de autenticación"

- Verifica que el token es correcto y empieza por `ntn_`
- Comprueba que la integración no ha sido desactivada en Notion
- Si regeneraste el token, actualízalo en Frihet

### "No encuentro mis páginas"

- La integración solo ve las páginas que compartes explícitamente con ella
- Abre la página en Notion → **...** → **Connections** → Añade tu integración
- Las páginas hijo de una página compartida son accesibles automáticamente

### "No puedo acceder a una base de datos"

- Comparte la base de datos con la integración (mismo proceso que con páginas)
- Verifica que la integración tiene capability "Read content" activada

### "Los datos están desactualizados"

- Las consultas a Notion son en tiempo real (bajo demanda)
- Si no ves cambios recientes, recarga la vista en Frihet
- Notion puede tardar unos segundos en reflejar cambios muy recientes

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Notion**
2. Haz clic en **Desconectar**
3. Opcionalmente, desactiva o elimina la integración en [notion.so/my-integrations](https://www.notion.so/my-integrations)

## Próximos pasos

- [Conecta Trello para gestión de proyectos](./trello)
- [Conecta Asana para tareas y proyectos](./asana)
- [Automatiza con n8n](./n8n)

---

## Open Banking
> Path: /integraciones/open-banking

# Open Banking

:::caution Próximamente
Esta integración está en desarrollo. Backend implementado con Salt Edge. Disponibilidad sujeta a viabilidad comercial.
:::

Conecta tus cuentas bancarias españolas y europeas a Frihet mediante Open Banking (PSD2). Transacciones y saldos se sincronizan automáticamente.

## ¿Para qué servirá?

Con Open Banking integrado podrás:

- **Bancos españoles** — Conecta CaixaBank, Santander, BBVA, Sabadell y más
- **Transacciones automáticas** — Movimientos llegan a Frihet sin intervención
- **Reconciliación inteligente** — Pagos se cotejan con facturas y gastos
- **Categorización** — Gastos se clasifican automáticamente por categoría
- **Seguridad PSD2** — Regulado por la directiva europea de servicios de pago

## ¿Quieres que lo implementemos antes?

Si Open Banking es crítico para tu negocio, escríbenos a [soporte@frihet.io](mailto:soporte@frihet.io). Priorizamos integraciones según la demanda de nuestros usuarios.

---

## Outlook Calendar
> Path: /integraciones/outlook-calendar

# Outlook Calendar

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu Outlook Calendar a Frihet a través de Microsoft Graph API. Consulta tus calendarios, ve eventos próximos y crea o elimina eventos directamente desde tu ERP. Ideal para sincronizar vencimientos de facturas y fechas fiscales con tu calendario de Microsoft.

## ¿Para qué sirve?

Con Outlook Calendar integrado:

- **Ver calendarios** — Consulta todos tus calendarios de Outlook desde Frihet
- **Ver eventos** — Revisa tus próximos eventos sin salir del ERP
- **Crear eventos** — Añade vencimientos de facturas y recordatorios fiscales a tu calendario
- **Eliminar eventos** — Gestiona eventos creados desde Frihet
- **Sincronización de vencimientos** — Los vencimientos de facturas pueden crear eventos automáticamente

## Requisitos

- **Cuenta Microsoft** — Outlook.com, Microsoft 365 u Office 365
- **Frihet Pro o superior**

:::info Sin credenciales que introducir
Esta integración usa OAuth con Microsoft Azure AD. No necesitas copiar ninguna clave o token manualmente. Simplemente autorizas a Frihet a acceder a tu calendario mediante una ventana de inicio de sesión de Microsoft.
:::

## Conectar Outlook Calendar con Frihet

### Paso 1: Iniciar la conexión

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Outlook Calendar**
3. Haz clic en **Conectar con Microsoft**

### Paso 2: Autorizar en Microsoft

1. Se abrirá la ventana de inicio de sesión de Microsoft
2. Inicia sesión con tu cuenta de Microsoft
3. Revisa los permisos solicitados:
   - Leer tus calendarios
   - Leer y escribir eventos
   - Acceder a tu información básica de perfil
4. Haz clic en **Aceptar**

### Paso 3: Verificar conexión

1. De vuelta en Frihet, verás "Conectado" con tu cuenta de Microsoft
2. Frihet mostrará tus calendarios disponibles
3. Selecciona el calendario donde quieres crear eventos (normalmente "Calendar" o tu calendario principal)

## Cómo funciona

Frihet usa la **Microsoft Graph API** con flujo de autorización OAuth 2.0:

1. Haces clic en "Conectar con Microsoft" y autorizas en la ventana de Microsoft
2. Microsoft genera tokens de acceso y refresco
3. Frihet almacena los tokens cifrados (AES-256-GCM)
4. Con el token de acceso, Frihet consulta y crea eventos en tu calendario
5. El token se refresca automáticamente cuando expira
6. En ningún momento introduces credenciales de Microsoft en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Calendarios (listado) | Outlook → Frihet | Al conectar / bajo demanda |
| Eventos | Outlook → Frihet | Bajo demanda |
| Crear eventos | Frihet → Outlook | Al crear vencimiento |
| Eliminar eventos | Frihet → Outlook | Bajo demanda |

## Funcionalidades

### Ver calendarios

1. Desde Frihet, accede a la sección de Outlook Calendar
2. Verás todos los calendarios de tu cuenta (personal, trabajo, compartidos)
3. Selecciona un calendario para ver sus eventos

### Ver eventos próximos

1. Selecciona un calendario
2. Frihet muestra los eventos próximos con:
   - Título del evento
   - Fecha y hora
   - Ubicación
   - Organizador
3. Filtra por rango de fechas

### Crear eventos

Crea eventos directamente en tu Outlook Calendar desde Frihet:

1. Haz clic en **Crear evento**
2. Rellena los campos:
   - Título (ej: "Vencimiento factura #1042 - Cliente SL")
   - Fecha y hora
   - Descripción (opcional)
   - Calendario destino
3. El evento aparecerá inmediatamente en Outlook

### Eventos automáticos de vencimiento

Cuando activas esta opción, Frihet crea automáticamente un evento en tu calendario cada vez que:

- Se emite una factura con fecha de vencimiento
- Se acerca una fecha fiscal (IVA trimestral, IRPF)
- Se programa un recordatorio de cobro

### Eliminar eventos

1. Desde la lista de eventos en Frihet, selecciona un evento creado por Frihet
2. Haz clic en **Eliminar**
3. El evento se elimina tanto en Frihet como en tu Outlook Calendar

## Casos de uso

### Control de vencimientos de facturas

Emites facturas con vencimiento a 30 días. Frihet crea automáticamente un evento en tu Outlook Calendar para el día de vencimiento, recordándote hacer seguimiento del cobro.

### Recordatorios fiscales

Frihet añade eventos automáticos para las fechas fiscales importantes: presentación del IVA trimestral (Modelo 303), IRPF, y cierre de trimestre.

### Planificación de cobros

Consultas tu calendario desde Frihet para ver qué facturas vencen esta semana. Planificas tus llamadas y recordatorios de cobro en base a los eventos del calendario.

## Solución de problemas

### "Error al conectar con Microsoft"

- Verifica que tu cuenta de Microsoft está activa
- Si usas Microsoft 365 corporativo, tu administrador puede haber restringido las aplicaciones de terceros
- Prueba con otra cuenta de Microsoft si el error persiste

### "No veo mis calendarios"

- Verifica que tu cuenta tiene calendarios creados
- Los calendarios compartidos por otros usuarios pueden no aparecer si no tienes permisos suficientes
- Recarga la integración desde **Ajustes** → **Outlook Calendar**

### "Los eventos creados no aparecen en Outlook"

- Verifica que seleccionaste el calendario correcto en Frihet
- Los eventos pueden tardar unos segundos en sincronizarse con Outlook
- Comprueba que la sesión no ha expirado (reconecta si es necesario)

### "La sesión ha expirado"

- Microsoft puede solicitar re-autorización periódicamente por seguridad
- Ve a **Ajustes** → **Integraciones** → **Outlook Calendar** y haz clic en **Reconectar**
- Volverás a la ventana de Microsoft para autorizar de nuevo

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Outlook Calendar**
2. Haz clic en **Desconectar**
3. Los tokens se eliminan de Frihet
4. Opcionalmente, revoca el acceso en [myaccount.microsoft.com/permissions](https://myaccount.microsoft.com/permissions)

## Próximos pasos

- [Conecta Google Calendar como alternativa](./google-calendar)
- [Configura notificaciones por Slack](./slack)
- [Automatiza recordatorios con n8n](./n8n)

---

## PandaDoc
> Path: /integraciones/pandadoc

# PandaDoc

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → PandaDoc**.
:::

Conecta tu cuenta de PandaDoc a Frihet para gestionar tus documentos y firmas electrónicas directamente desde tu ERP. PandaDoc es una plataforma de automatización documental con creación de propuestas, contratos y firma electrónica. Con esta integración, puedes consultar tus documentos y enviarlos para firma sin salir de Frihet.

## ¿Para qué sirve?

- **Listar documentos** — Consulta todos tus documentos de PandaDoc (propuestas, contratos, presupuestos) desde Frihet
- **Enviar para firma** — Envía documentos de PandaDoc para firma electrónica directamente desde la interfaz de Frihet
- **Estado de documentos** — Visualiza el estado de cada documento (borrador, enviado, visto, firmado, rechazado)
- **Flujo unificado** — Gestiona tu documentación y tu facturación desde un mismo lugar

## Requisitos

- Cuenta activa en [PandaDoc](https://www.pandadoc.com)
- Plan Frihet Pro o Premium
- API Key de PandaDoc

## Cómo conectar

### Paso 1: Obtener tu API Key en PandaDoc

1. Inicia sesión en [app.pandadoc.com](https://app.pandadoc.com)
2. Ve a **Settings** (Configuración) haciendo clic en tu avatar
3. Navega a **Integrations → API**
4. En la sección de API Keys, haz clic en generar una nueva clave
5. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
6. Copia la **API Key** generada

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **PandaDoc** y haz clic en el card
3. Pega tu **API Key** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de PandaDoc utilizando tu API Key para autenticarse. La integración te permite consultar la lista de documentos en tu cuenta de PandaDoc y gestionar el envío de documentos para firma electrónica.

A diferencia de las integraciones de banca o CRM, PandaDoc no importa datos a Frihet (no crea clientes ni gastos). Es una herramienta de gestión documental y firma que complementa tu flujo de trabajo en el ERP.

### Funcionalidades disponibles

| Funcionalidad | Descripción |
|---------------|-------------|
| Listar documentos | Ver todos los documentos de tu cuenta con su estado |
| Ver estado | Consultar si un documento está en borrador, enviado, visto o firmado |
| Enviar para firma | Lanzar el flujo de firma electrónica de un documento |
| Filtrar por estado | Buscar documentos por su estado actual |

## Casos de uso

### Consultor que envía propuestas

Creas propuestas en PandaDoc y facturas en Frihet. Con la integración, puedes ver el estado de tus propuestas directamente desde Frihet. Cuando una propuesta se firma, creas la factura correspondiente sin cambiar de aplicación.

### Agencia con contratos de servicio

Gestionas contratos con tus clientes en PandaDoc. Desde Frihet puedes consultar qué contratos están pendientes de firma y enviar recordatorios, manteniendo el flujo documental y de facturación en un solo lugar.

### Freelancer con acuerdos recurrentes

Envías acuerdos de servicio a nuevos clientes a través de PandaDoc. Desde Frihet puedes verificar el estado de cada acuerdo y, una vez firmado, proceder a crear la primera factura con los datos del cliente.

## Solución de problemas

### Error de conexión

- Verifica que la API Key es correcta y no ha sido revocada
- Comprueba que tu plan de PandaDoc incluye acceso a la API (no todos los planes lo incluyen)
- Si generaste una nueva API Key, la anterior deja de funcionar — actualízala en Frihet

### No se muestran documentos

- Asegúrate de que tienes documentos creados en PandaDoc
- Verifica que la API Key pertenece a la cuenta correcta (si tienes múltiples workspaces)
- Los documentos eliminados en PandaDoc no aparecen en Frihet

### Error al enviar para firma

- Verifica que el documento en PandaDoc está completo y listo para enviar (no en estado borrador incompleto)
- Comprueba que los destinatarios del documento tienen email válido configurado en PandaDoc
- La API Key necesita permisos de escritura para enviar documentos a firma

## Siguientes pasos

- [Conecta Dropbox Sign como alternativa de firma](./hellosign)
- [Gestiona tus facturas en Frihet](../facturacion/facturas)
- [Crea presupuestos en Frihet](../facturacion/presupuestos)

---

## PayFit
> Path: /integraciones/payfit

# PayFit

> Conecta PayFit con Frihet para importar nóminas y costes de personal automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre PayFit y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **PayFit**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → PayFit
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## PayPal
> Path: /integraciones/paypal

# PayPal

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tu cuenta PayPal Business a Frihet. Importa transacciones, consulta saldos y reconcilia cobros internacionales con tus facturas de forma automática. Soporta modo sandbox para pruebas.

## ¿Para qué sirve?

Con PayPal integrado:

- **Importar transacciones** — Trae automáticamente los cobros de PayPal a Frihet como facturas
- **Paginación completa** — Importa todas las transacciones sin límite (paginación automática)
- **Historial inteligente** — Primera importación: 1 año de historial. Después: solo transacciones nuevas desde la última sincronización
- **Reembolsos** — Los refunds se importan con prefijo `[Refund]` y monto negativo para contabilidad clara
- **Consultar saldos** — Ve tu saldo PayPal directamente desde el panel de Frihet
- **Reconciliar cobros** — Asocia transacciones PayPal con facturas existentes
- **Multi-divisa** — Maneja cobros en EUR, USD, GBP y otras divisas
- **Deduplicación** — Las transacciones ya importadas no se duplican (prefijo `PP-`)
- **Modo sandbox** — Prueba la integración sin afectar datos reales

## Requisitos

- **Cuenta PayPal Business** — Las cuentas personales no tienen acceso a la API
- **Aplicación en PayPal Developer** — Para obtener Client ID y Client Secret
- **Frihet Pro o superior**

## Conectar PayPal con Frihet

### Paso 1: Crear una aplicación en PayPal Developer

1. Ve a [developer.paypal.com](https://developer.paypal.com)
2. Inicia sesión con tu cuenta PayPal Business
3. En el dashboard, ve a **Apps & Credentials**
4. Selecciona el modo **Live** (o **Sandbox** para pruebas)
5. Haz clic en **Create App**
6. Ponle un nombre (ej: "Frihet ERP")
7. Haz clic en **Create App**

Una vez creada, verás:

- **Client ID** — Un identificador público (ej: `AaBbCcDdEe...`)
- **Client Secret** — Una clave privada (haz clic en "Show" para verla)

:::caution Guarda el Secret
El Client Secret solo se muestra una vez. Cópialo y guárdalo en un lugar seguro antes de continuar.
:::

### Paso 2: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **PayPal**
3. Haz clic en **Conectar**
4. Introduce tu **Client ID** y **Client Secret**
5. Selecciona el modo:
   - **Live** — Para transacciones reales
   - **Sandbox** — Para pruebas con datos ficticios
6. Haz clic en **Verificar conexión**
7. Si es correcto, verás "Conectado"

### Paso 3: Verificar conexión

1. Frihet obtiene automáticamente un token OAuth2 usando tus credenciales
2. Si la verificación es exitosa, verás tu saldo PayPal en el panel
3. Puedes hacer una importación de prueba con las últimas transacciones

## Cómo funciona

Frihet usa la **API REST v2 de PayPal** con autenticación OAuth2 (client credentials flow):

1. Tú proporcionas Client ID y Client Secret
2. Frihet solicita un token de acceso a PayPal automáticamente
3. Con ese token, Frihet consulta transacciones y saldos
4. Las credenciales se almacenan cifradas (AES-256-GCM) en Frihet
5. El token se renueva automáticamente cuando expira

En ningún momento necesitas gestionar tokens manualmente.

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Transacciones recibidas | PayPal → Frihet | Bajo demanda / periódica |
| Saldo de cuenta | PayPal → Frihet | En cada consulta |
| Datos del pagador | PayPal → Frihet | Con cada transacción |
| Divisa y tipo de cambio | PayPal → Frihet | Con cada transacción |

## Casos de uso

### Freelancer con clientes internacionales

Cobras a clientes en USD y EUR a través de PayPal. Frihet importa cada pago, lo asocia con la factura correspondiente y convierte el importe a tu divisa base.

### Tienda online con PayPal como método de pago

Recibes pagos de clientes vía PayPal Checkout. Las transacciones se importan a Frihet y puedes reconciliarlas con los pedidos facturados.

### Verificar saldo antes de pagar proveedores

Consulta tu saldo PayPal desde el panel de Frihet sin salir de la aplicación. Decide si tienes fondos disponibles antes de emitir transferencias.

## Modo Sandbox

Para probar la integración sin afectar datos reales:

1. En [developer.paypal.com](https://developer.paypal.com), crea una app en modo **Sandbox**
2. Usa las credenciales Sandbox en Frihet (selecciona modo "Sandbox")
3. PayPal proporciona cuentas de prueba con saldo ficticio
4. Verifica que las transacciones se importan correctamente
5. Cuando estés listo, cambia a modo **Live** con credenciales de producción

## Solución de problemas

### "Error de autenticación"

- Verifica que el Client ID y Client Secret son correctos
- Asegúrate de usar credenciales **Live** en modo Live y **Sandbox** en modo Sandbox
- Comprueba que tu cuenta PayPal Business está activa y verificada

### "No se importan transacciones"

- Verifica que hay transacciones en el periodo consultado (1 año en primera importación, desde última sincronización en siguientes)
- En modo Sandbox, genera transacciones de prueba desde el dashboard de PayPal Developer
- Comprueba que tu aplicación en PayPal tiene los permisos necesarios activados
- Si el toast muestra "No new transactions to import", todas las transacciones ya están en Frihet

### "Error de permisos en la API"

- Al crear la app en PayPal Developer, asegúrate de que incluya el scope de transacciones
- Si cambiaste permisos, genera un nuevo Client Secret y actualízalo en Frihet

### "Quiero cambiar de Sandbox a Live"

1. Ve a **Ajustes** → **Integraciones** → **PayPal**
2. Haz clic en **Desconectar**
3. Vuelve a conectar con las credenciales de producción (Live)

## Próximos pasos

- [Conecta Stripe para cobros con tarjeta](./stripe)
- [Conecta GoCardless para domiciliaciones SEPA](./gocardless)
- [Automatiza flujos con n8n](./n8n)

---

## Personio
> Path: /integraciones/personio

# Personio

> Conecta Personio con Frihet para importar datos de empleados y costes de personal.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Personio y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Personio**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Personio
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Pipedrive
> Path: /integraciones/pipedrive

# Pipedrive

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Pipedrive**.
:::

Conecta tu cuenta de Pipedrive a Frihet para importar tus contactos (personas) como clientes. Pipedrive es un CRM centrado en el pipeline de ventas, y con esta integración puedes traer los datos de tus contactos a Frihet para facturarles sin necesidad de duplicar información entre sistemas.

## ¿Para qué sirve?

- **Importar personas como clientes** — Los contactos (persons) de Pipedrive se convierten en clientes de Frihet con nombre, email, teléfono y empresa
- **Datos primarios automáticos** — Se importa el email y teléfono principal de cada contacto
- **Sin doble entrada** — Evita crear manualmente en Frihet los clientes que ya existen en tu CRM
- **Facturación directa** — Una vez importados, crea facturas para esos clientes con todos los datos ya completados

## Requisitos

- Cuenta activa en [Pipedrive](https://www.pipedrive.com)
- Plan Frihet Pro o Premium
- API Token de Pipedrive

## Cómo conectar

### Paso 1: Obtener tu API Token en Pipedrive

1. Inicia sesión en [app.pipedrive.com](https://app.pipedrive.com)
2. Haz clic en tu avatar o iniciales en la esquina superior derecha
3. Selecciona **Personal preferences** (Preferencias personales)
4. Ve a la pestaña **API**
5. Copia tu **API Token** personal que se muestra en pantalla

:::caution Nota
El API Token de Pipedrive es personal y tiene acceso a todos los datos de tu cuenta. No lo compartas y guárdalo de forma segura.
:::

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Pipedrive** y haz clic en el card
3. Pega tu **API Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Pipedrive utilizando tu API Token como parámetro de autenticación. Cuando lanzas una importación, Frihet consulta las personas (persons) registradas en Pipedrive y las crea como clientes en Frihet.

La importación es bajo demanda. Se importa el email y teléfono principal de cada persona. Los contactos ya importados se identifican por su ID de Pipedrive y no se duplican.

### Mapeo de datos

| Dato en Pipedrive | Campo en Frihet |
|-------------------|-----------------|
| Name | Nombre del cliente |
| Email (primary) | Email del cliente |
| Phone (primary) | Teléfono del cliente |
| Organization name | Empresa del cliente |

## Casos de uso

### Equipo comercial con pipeline en Pipedrive

Tu equipo gestiona oportunidades en Pipedrive. Cuando un deal se cierra, importas la persona asociada a Frihet como cliente y creas la factura directamente. El flujo va de CRM a ERP sin fricciones.

### Migración de base de contactos

Tienes años de contactos acumulados en Pipedrive. En lugar de exportar un CSV y reimportarlo, conectas Pipedrive a Frihet y traes todos tus contactos con un clic.

### Freelancer o consultor

Usas Pipedrive para gestionar tus leads y oportunidades. Cuando un prospecto se convierte en cliente, lo importas a Frihet para empezar a facturarle con los datos correctos desde el principio.

## Solución de problemas

### Error de conexión

- Verifica que el API Token es correcto y corresponde a tu cuenta
- Comprueba que tu cuenta de Pipedrive está activa y no ha expirado
- Si cambiaste tu contraseña en Pipedrive, el API Token puede haberse regenerado — verifica en Personal preferences > API

### No se importan contactos

- Asegúrate de que tienes personas (persons) creadas en Pipedrive, no solo organizaciones
- Los contactos sin nombre se omiten durante la importación
- Verifica que tu plan de Pipedrive permite acceso a la API

### Falta el email o teléfono

- Pipedrive permite múltiples emails y teléfonos por persona. Frihet importa solo el marcado como **primary**
- Si un contacto no tiene email o teléfono primary, esos campos quedarán vacíos en Frihet

## Siguientes pasos

- [Conecta HubSpot como alternativa de CRM](./hubspot)
- [Gestiona tus clientes en Frihet](../clientes/gestion-clientes)
- [Importa y exporta clientes en lote](../clientes/importar-exportar)

---

## Plaid
> Path: /integraciones/plaid

# Plaid

:::caution Próximamente
Esta integración está en desarrollo. La arquitectura frontend está completa; backend pendiente de implementar. Disponibilidad estimada: Q2 2026.
:::

Conecta tus cuentas bancarias directamente a Frihet a través de Plaid. Importa transacciones y saldos en tiempo real para reconciliar facturas con movimientos bancarios de forma automática.

## ¿Para qué sirve?

Con Plaid integrado:

- **Conectar cuentas bancarias** — Vincula tus cuentas de cualquier banco soportado por Plaid
- **Importar transacciones** — Trae movimientos bancarios a Frihet automáticamente
- **Reconciliar facturas** — Asocia cobros bancarios con facturas emitidas
- **Consultar saldos** — Ve el saldo de tus cuentas desde el panel de Frihet
- **Multi-banco** — Conecta varias cuentas de distintos bancos

## Requisitos

- **Cuenta bancaria compatible con Plaid** — La mayoría de bancos europeos y americanos están soportados
- **Frihet Pro o superior**
- **Configuración adicional del servidor** — Esta integración requiere servicios de servidor activos (incluidos en tu plan)

:::info Configuración del servidor
A diferencia de otras integraciones donde introduces una API key directamente, Plaid utiliza un flujo seguro a través de Plaid Link SDK. La conexión bancaria se realiza mediante una ventana segura del propio Plaid, sin que Frihet tenga acceso a tus credenciales bancarias.
:::

## Conectar tu banco con Frihet

### Paso 1: Iniciar la conexión

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Plaid**
3. Haz clic en **Conectar banco**

### Paso 2: Seleccionar tu banco en Plaid Link

1. Se abrirá la ventana segura de **Plaid Link**
2. Busca tu banco por nombre
3. Inicia sesión con tus credenciales bancarias (directamente en la ventana de Plaid, Frihet no las ve)
4. Completa la verificación de seguridad si tu banco lo requiere (SMS, app del banco, etc.)
5. Selecciona las cuentas que quieres vincular

### Paso 3: Verificar conexión

1. De vuelta en Frihet, verás las cuentas conectadas
2. Frihet importará las transacciones recientes automáticamente
3. Comprueba que los movimientos aparecen en tu panel

## Cómo funciona

La integración con Plaid sigue un flujo seguro en varias capas:

1. **Plaid Link SDK** abre una ventana segura donde introduces tus credenciales bancarias
2. Plaid autentica directamente con tu banco (Frihet nunca ve tus credenciales)
3. Plaid genera un **access token** que permite a Frihet consultar transacciones y saldos
4. Este token se almacena cifrado (AES-256-GCM) en los servidores de Frihet
5. El backend de Frihet usa el token para consultar datos a Plaid de forma periódica
6. Las transacciones se importan y están disponibles para reconciliación

## Datos sincronizados

| Dato                     | Dirección              | Frecuencia           |
| ------------------------ | ---------------------- | -------------------- |
| Transacciones            | Banco → Plaid → Frihet | Periódica (diaria)   |
| Saldos de cuenta         | Banco → Plaid → Frihet | Bajo demanda         |
| Nombre de cuenta         | Banco → Plaid → Frihet | Al conectar          |
| Categoría de transacción | Plaid → Frihet         | Con cada transacción |

## Casos de uso

### Reconciliación automática de cobros

Emites una factura por 2.500 EUR a un cliente. Cuando el pago llega a tu cuenta bancaria, Frihet detecta la transacción importada por Plaid y sugiere asociarla con la factura pendiente.

### Control de tesorería

Conecta tus cuentas de negocio y consulta los saldos desde Frihet sin entrar en la banca online. Ten una visión unificada de tu liquidez junto con tus facturas pendientes de cobro.

### Categorización de gastos

Las transacciones importadas incluyen la categorización automática de Plaid. Frihet puede sugerir registros de gasto basados en los movimientos bancarios para que no se te escape ninguno.

## Seguridad

La integración con Plaid está diseñada para máxima seguridad:

- **Credenciales bancarias** — Frihet nunca las ve. Se introducen directamente en la ventana segura de Plaid
- **Cifrado de tokens** — El access token se almacena cifrado con AES-256-GCM
- **Comunicación segura** — Todo el tráfico entre Frihet, Plaid y tu banco va por HTTPS
- **Plaid certificado** — Plaid cumple con SOC 2 Type II, PCI DSS y está regulado como proveedor fintech
- **Revocable** — Puedes desconectar tu cuenta en cualquier momento desde Frihet o desde tu banca online

## Bancos soportados

Plaid soporta miles de instituciones financieras. Algunos ejemplos en Europa:

- Bancos principales de España, Alemania, Francia, Italia, Países Bajos, Reino Unido
- Neobancos: Revolut, N26, Wise

La lista completa está disponible directamente en Plaid Link al iniciar la conexión.

## Solución de problemas

### "Mi banco no aparece en Plaid Link"

- Plaid no soporta todos los bancos. Consulta la cobertura en [plaid.com/institutions](https://plaid.com/institutions)
- Algunos bancos pequeños o cajas de ahorros pueden no estar disponibles
- Alternativa: usa la [integración con Revolut](./revolut) o importación manual de transacciones

### "La conexión se desconecta tras un tiempo"

- Algunos bancos requieren re-autenticación periódica por seguridad
- Cuando esto ocurre, Frihet te notificará para que vuelvas a conectar mediante Plaid Link
- Es un requisito del banco, no un error de Frihet

### "No se importan las transacciones más recientes"

- Las transacciones pueden tardar 24-48 horas en estar disponibles a través de Plaid
- Plaid depende de la velocidad de cada banco para reportar movimientos
- Las transacciones pendientes (no confirmadas) pueden no aparecer

### "Quiero desconectar mi banco"

1. Ve a **Ajustes** → **Integraciones** → **Plaid**
2. Haz clic en **Desconectar**
3. El access token se elimina de Frihet
4. Opcionalmente, revoca el acceso desde tu banca online

## Próximos pasos

- [Conecta Revolut Business para transacciones](./revolut)
- [Automatiza reconciliación con n8n](./n8n)
- [Consulta la API REST para acceso programático](../desarrolladores/api-rest)

---

## Pleo
> Path: /integraciones/pleo

# Pleo

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Pleo**.
:::

Conecta tu cuenta de Pleo a Frihet para importar automáticamente los gastos realizados con tarjetas corporativas Pleo. Si tu equipo usa tarjetas Pleo para gastos del día a día, esta integración te permite tener todos esos gastos registrados en Frihet sin intervención manual, con datos del comercio, importe y categoría.

## ¿Para qué sirve?

- **Importar gastos de tarjeta** — Cada pago realizado con una tarjeta Pleo se importa como gasto en Frihet con el nombre del comercio, importe y categoría
- **Categorización automática** — Pleo categoriza los gastos y esa categoría se traslada a Frihet como sugerencia
- **Visibilidad del gasto del equipo** — Consolida los gastos de todas las tarjetas Pleo de tu equipo en Frihet
- **Deduplicación inteligente** — Los gastos ya importados no se duplican en importaciones posteriores

## Requisitos

- Cuenta activa en [Pleo](https://pleo.io)
- Plan Frihet Pro o Premium
- API Token de Pleo

## Cómo conectar

### Paso 1: Obtener tu API Token en Pleo

1. Inicia sesión en [app.pleo.io](https://app.pleo.io) con una cuenta de administrador
2. Ve a **Settings** (Configuración)
3. Selecciona **Integrations** (Integraciones)
4. Busca la sección **API** o **Developer**
5. Haz clic en generar un nuevo token de API
6. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
7. Copia el token generado

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Pleo** y haz clic en el card
3. Pega tu **API Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar
5. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Pleo utilizando tu API Token para autenticarse. Cuando lanzas una importación, Frihet consulta los gastos registrados en las tarjetas corporativas Pleo y los importa como gastos en tu cuenta de Frihet.

La importación es bajo demanda. Se importan los gastos completados con toda la información disponible: comercio, importe, categoría y fecha.

### Mapeo de datos

| Dato en Pleo | Campo en Frihet |
|--------------|-----------------|
| Nombre del comercio (merchant) | Descripción del gasto |
| Importe | Importe del gasto |
| Fecha del cargo | Fecha del gasto |
| Divisa | Divisa del gasto |
| Categoría Pleo | Categoría del gasto |
| Titular de la tarjeta | Notas del gasto |

## Casos de uso

### Equipo con tarjetas de empresa

Cada miembro de tu equipo tiene una tarjeta Pleo con límite configurado. En lugar de que cada persona registre sus gastos en Frihet manualmente, importas todos los gastos de Pleo de una vez. Cada gasto llega con el nombre del comercio y la categoría asignada.

### Control de gastos de viaje

Tu equipo viaja para reuniones con clientes. Los gastos de hotel, transporte y comidas se pagan con Pleo. Al importarlos a Frihet, tienes un registro completo del coste de cada viaje que puedes asociar a un cliente o proyecto.

### Suscripciones y gastos recurrentes

Pagas herramientas SaaS y servicios con Pleo. Al importar los gastos mensualmente, puedes rastrear el coste de cada suscripción y detectar cargos inesperados o duplicados.

## Solución de problemas

### Error de conexión

- Verifica que el API Token es correcto y que se generó con una cuenta de administrador
- Comprueba que tu plan de Pleo incluye acceso a la API
- Si el token fue revocado o regenerado, actualízalo en Frihet

### No se importan gastos

- Solo se importan gastos completados y confirmados
- Los gastos pendientes de aprobación en Pleo no aparecen hasta que se aprueban
- Verifica el rango de fechas de la importación

### Faltan datos del comercio

- Algunos gastos pueden no tener nombre de comercio si Pleo no pudo identificarlo
- En esos casos, aparecerá la referencia de la transacción en su lugar

## Siguientes pasos

- [Conecta Qonto para importar transacciones bancarias](./qonto)
- [Aprende a categorizar gastos importados](../gastos/categorias)
- [Gestiona gastos recurrentes en Frihet](../gastos/gastos-recurrentes)

---

## PrestaShop
> Path: /integraciones/prestashop

# PrestaShop

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

Conecta tu tienda PrestaShop a Frihet. Importa productos y pedidos directamente desde la API Webservice.

## ¿Para qué sirve?

Con PrestaShop integrado:

- **Importar pedidos** — Los pedidos de tu tienda se convierten en facturas en Frihet
- **Importar productos** — Trae tu catálogo de PrestaShop para unificar la gestión
- **Datos sincronizados** — Precios, cantidades, referencias y estados se importan automáticamente

## Requisitos

- **PrestaShop 1.7 o superior** — Con el Servicio Web habilitado
- **Clave API** — Generada desde el panel de administración
- **HTTPS obligatorio** — Tu tienda debe tener certificado SSL
- **Frihet Pro o superior**

## Configurar la conexión

### Paso 1: Genera una clave API en PrestaShop

1. En tu panel de administración de PrestaShop, ve a **Parámetros Avanzados** → **Servicio Web**
2. Haz clic en **Añadir nueva clave**
3. Activa los permisos de lectura (GET) para:
   - `products` — Para importar productos
   - `orders` — Para importar pedidos
   - `customers` — Para datos de cliente
4. Copia la clave generada

### Paso 2: Conecta en Frihet

1. En Frihet, ve a **Ajustes** → **Integraciones**
2. Busca **PrestaShop** y haz clic
3. Introduce la **URL de tu tienda** (ej: `https://mitienda.com`)
4. Pega la **Clave API**
5. Haz clic en **Probar Conexión** para verificar
6. Si es correcto, haz clic en **Guardar**

## Importar datos

### Importar productos

1. Ve a **Ajustes** → **Integraciones** → **PrestaShop** → pestaña **Datos**
2. Haz clic en **Importar productos**
3. Frihet importa todos los productos activos de tu tienda
4. Los productos duplicados (mismo SKU o nombre) se omiten automáticamente

### Importar pedidos

1. En la misma pestaña **Datos**, haz clic en **Importar pedidos**
2. La primera importación trae los pedidos de los últimos 30 días
3. Las siguientes importaciones traen solo los pedidos nuevos desde la última sincronización
4. Cada pedido genera una factura con el formato `PS-{id}`

## Datos importados

### Productos

| Dato PrestaShop | Dato Frihet |
|-----------------|-------------|
| Nombre | Nombre del producto |
| Referencia | SKU |
| Precio (sin impuestos) | Precio unitario |
| Descripción corta | Descripción |
| Activo (sí/no) | Estado activo/inactivo |

### Pedidos

| Dato PrestaShop | Dato Frihet |
|-----------------|-------------|
| ID del pedido | Número de factura (`PS-{id}`) |
| Fecha del pedido | Fecha de emisión |
| Productos del pedido | Líneas de factura |
| Cantidad | Cantidad |
| Precio unitario (sin IVA) | Precio unitario |
| Referencia del pedido | Notas de la factura |

## Ejemplo real

### Pedido en PrestaShop

```
Pedido #4521 - 18 feb 2026
- 3x Camiseta Básica (ref: CAM-001) @ €15 = €45
- 1x Sudadera Premium (ref: SUD-010) @ €45 = €45
Total: €90 + €18,90 IVA (21%) = €108,90
```

### En Frihet tras importar

```
Factura PS-4521
Fecha: 18 feb 2026
- 3x Camiseta Básica @ €15 = €45
- 1x Sudadera Premium @ €45 = €45
Subtotal: €90,00
IVA (21%): €18,90
Total: €108,90
Estado: Pagada
```

## Diferencias con WooCommerce

| Característica | PrestaShop | WooCommerce |
|---------------|------------|-------------|
| Tipo de conexión | Clave API (Webservice) | Consumer Key + Secret |
| Sync en tiempo real | No (importación manual) | Sí (webhooks) |
| Dirección | PrestaShop → Frihet | WooCommerce → Frihet |
| Formato factura | `PS-{id}` | `WC-{number}` |

## Limitaciones

- **Importación manual** — Los pedidos no se sincronizan en tiempo real. Debes hacer clic en "Importar pedidos" periódicamente
- **Solo lectura** — Frihet importa datos de PrestaShop pero no escribe de vuelta
- **Sin datos de dirección en facturas** — Los datos de envío del pedido no se trasladan al cliente (próximamente)

## Troubleshooting

### "Error de conexión al probar"

- Verifica que la URL es correcta y usa `https://`
- Comprueba que el Servicio Web está habilitado en PrestaShop
- Verifica que la clave API tiene permisos de lectura para `products`, `orders` y `customers`
- Si usas un firewall o `.htaccess`, asegúrate de que no bloquea `/api/`

### "No se importan todos los productos"

- Solo se importan productos **activos** (estado = 1)
- Productos con el mismo SKU o nombre ya existentes se omiten (deduplicación)

### "Los pedidos no aparecen"

- La primera importación trae solo los últimos 30 días
- Verifica que los pedidos tienen estado "procesando" o superior
- Haz clic en "Importar pedidos" de nuevo si han llegado nuevos

### "¿Puedo desconectar sin perder datos?"

Sí. Los productos y facturas ya importados quedan en Frihet. Desconectar solo impide nuevas importaciones.

Para desconectar:

1. Ve a **Ajustes** → **Integraciones** → **PrestaShop** → pestaña **Configuración**
2. Haz clic en **Desconectar**
3. Confirma

## Próximos pasos

- [Conecta WooCommerce si también tienes tienda WordPress](./woocommerce)
- [Importa ventas de Gumroad](./gumroad)
- [Automatiza flujos con n8n](./n8n)

---

## Printful
> Path: /integraciones/printful

# Printful

> Importa pedidos y costes de producción de Printful en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Printful y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Printful**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Printful
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Qonto
> Path: /integraciones/qonto

# Qonto

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Qonto**.
:::

Conecta tu cuenta de Qonto a Frihet para importar automáticamente las transacciones de tu banca empresarial como gastos. Si usas Qonto como tu banco principal, esta integración elimina la necesidad de registrar manualmente cada pago y te da visibilidad completa de tus gastos operativos dentro de Frihet.

## ¿Para qué sirve?

- **Importar transacciones como gastos** — Los pagos y cargos completados en Qonto se importan como gastos en Frihet con todos los detalles
- **Solo débitos** — Se importan únicamente las transacciones de débito (pagos realizados), no los ingresos, para evitar mezclar flujos
- **Deduplicación automática** — Las transacciones ya importadas no se duplican en importaciones posteriores
- **Consolidación de gastos** — Unifica tus gastos de Qonto con el resto de gastos registrados en Frihet para tener una visión financiera completa

## Requisitos

- Cuenta activa en [Qonto](https://qonto.com)
- Plan Frihet Pro o Premium
- Organization slug y Secret key de la API de Qonto

## Cómo conectar

### Paso 1: Obtener tus credenciales de API en Qonto

1. Inicia sesión en [app.qonto.com](https://app.qonto.com)
2. Ve a **Settings** (Configuración) en el menú lateral
3. Selecciona la sección **API** o **Integraciones > API**
4. Aquí encontrarás dos datos que necesitas:
   - **Organization slug** — El identificador único de tu organización (algo como `mi-empresa-abc123`)
   - **Secret key** — La clave secreta de la API
5. Copia ambos valores

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Qonto** y haz clic en el card
3. Introduce tu **Organization slug** en el primer campo
4. Introduce tu **Secret key** en el segundo campo
5. Haz clic en **Probar conexión** para verificar
6. Si la conexión es exitosa, haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Qonto utilizando tu Organization slug y Secret key para autenticarse. Cuando lanzas una importación, Frihet consulta las transacciones completadas de tipo débito en tu cuenta Qonto y las registra como gastos.

La importación es bajo demanda. Solo se importan transacciones de débito completadas (pagos a proveedores, suscripciones, compras con tarjeta, etc.). Los ingresos y transferencias entrantes no se importan.

### Mapeo de datos

| Dato en Qonto | Campo en Frihet |
|----------------|-----------------|
| Etiqueta / concepto | Descripción del gasto |
| Importe (débito) | Importe del gasto |
| Fecha de la operación | Fecha del gasto |
| Divisa | Divisa del gasto |
| Nombre del beneficiario | Notas del gasto |
| Categoría Qonto | Categoría sugerida |

## Casos de uso

### Pyme europea con cuenta Qonto

Usas Qonto como tu banco principal. Cada mes importas todas las transacciones a Frihet para tener un registro completo de gastos sin teclear nada. Combinas estos gastos importados con las facturas emitidas en Frihet para tener una visión completa de tu rentabilidad.

### Equipo con tarjetas corporativas Qonto

Tu equipo tiene tarjetas Qonto para gastos del día a día. En lugar de perseguir a cada persona para que registre sus gastos, importas todas las transacciones de tarjeta a Frihet y las categorizas de una vez.

## Solución de problemas

### Error de conexión

- Verifica que el Organization slug y la Secret key son correctos
- Comprueba que has copiado los valores completos, sin espacios extra
- Si Qonto regeneró tu Secret key, actualízala en Frihet

### No se importan transacciones

- Solo se importan transacciones de tipo débito y en estado completado
- Confirma que tienes transacciones en el período seleccionado
- Las transacciones pendientes o en proceso no aparecen hasta que se completan

### Faltan algunas transacciones

- Verifica el rango de fechas de la importación
- Las transferencias internas entre cuentas Qonto pueden no importarse según la configuración

## Siguientes pasos

- [Conecta Wise para transferencias internacionales](./wise)
- [Conecta Pleo si usas tarjetas corporativas adicionales](./pleo)
- [Aprende a categorizar gastos importados](../gastos/categorias)

---

## QuickBooks Online
> Path: /integraciones/quickbooks-online

# QuickBooks Online

> Sincroniza facturas y gastos entre Frihet y QuickBooks Online.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre QuickBooks Online y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **QuickBooks Online**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → QuickBooks Online
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Revolut Business
> Path: /integraciones/revolut

# Revolut Business

:::caution Próximamente
Esta integración está en desarrollo. El backend está implementado, pendiente de adaptar el flujo de autenticación a API key por usuario. Disponibilidad estimada: Q2 2026.
:::

Conecta tu cuenta Revolut Business a Frihet. Los movimientos bancarios se sincronizan automáticamente y se reconcilian con facturas y gastos.

## ¿Para qué sirve?

Con Revolut integrado:

- **Transacciones automáticas** — Tus movimientos bancarios llegan a Frihet
- **Reconciliación automática** — Pagos se cotejan con facturas
- **Categorización** — Gastos se categorizan automáticamente
- **Vista de caja** — Sabes siempre cuánto tienes
- **Reportes sincronizados** — Cash flow real vs proyectado

## Requisitos

- **Cuenta Revolut Business** — No funciona con Revolut personal
- **API Key de Revolut** — Para conectar
- **Acceso a transacciones** — Permisos en Revolut
- **Frihet Pro o superior**

## Obtener API Key de Revolut

### Paso 1: Abre Revolut Business

1. Ve a [business.revolut.com](https://business.revolut.com)
2. Inicia sesión
3. En el menú principal, ve a **Ajustes** → **API**

### Paso 2: Genera token

1. Haz clic en **"Crear nuevo token"**
2. Dale un nombre: "Frihet Integration"
3. Elige **permisos**:
   - ✅ Leer transacciones
   - ✅ Leer datos de cuenta
   - ❌ Enviar dinero (no necesario)
   - ❌ Crear pagos (no necesario)
4. Haz clic en **"Crear"**
5. **Copia el token** (lo necesitarás inmediatamente)

⚠️ **Importante:** Revolut solo muestra el token una vez. Cópialo y guárdalo en un lugar seguro.

## Conectar Revolut a Frihet

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Revolut Business**
3. Haz clic en **"Conectar"**

### Paso 2: Ingresa API Key

1. Pega el token de Revolut
2. Haz clic en **"Verificar conexión"**
3. Si es correcto: "✅ Conectado"

### Paso 3: Configura sincronización

1. Elige **qué cuentas sincronizar**:
   - Todas las cuentas ✅
   - Solo cuenta principal ⚪
   - Cuentas específicas ⚪

2. Elige **frecuencia**:
   - Tiempo real (cada 5 minutos)
   - Cada hora
   - Cada día

3. Activa **"Categorizar gastos automáticamente"**

4. Guarda

## Cómo funciona la sincronización

### Flujo automático

```
1. Alguien paga una factura en Revolut
   ↓
2. Frihet detecta la transacción (en 5 minutos)
   ↓
3. Busca una factura coincidente (monto + cliente)
   ↓
4. Si encuentra: marca factura como "Pagada"
   ↓
5. Si no encuentra: crea "Movimiento bancario pendiente"
   ↓
6. Tú confirmas la coincidencia manualmente
```

### Ejemplo: Cliente paga

**En Revolut:**
```
10 feb 2025, 14:30
Transferencia recibida
Juan García
€1.200,00
Referencia: Factura #1042
```

**En Frihet automáticamente:**
```
Factura #1042 - Juan García
Estado: Pagada ✅
Pagado por: Transferencia Revolut
Monto: €1.200,00
Fecha: 10 feb 2025, 14:30
```

### Ejemplo: Gasto desde Revolut

**En Revolut:**
```
11 feb 2025, 09:15
Pago con tarjeta
Amazon
€45,99
```

**En Frihet:**
```
Nuevo movimiento:
- Categoría: Electrónica (detectada automáticamente)
- Monto: €45,99
- Proveedor: Amazon
- Fecha: 11 feb 2025
- Estado: Requiere revisión
```

Tú lo editas si necesario o lo confirmas.

## Movimientos bancarios

### Ver transacciones

1. Ve a **Finanzas** → **Movimientos bancarios**
2. Ves todos los movimientos de Revolut
3. Filtra por:
   - Estado (Reconciliado, Pendiente, Rechazado)
   - Fecha
   - Tipo (Ingreso, Egreso)
   - Categoría

### Estados de movimiento

| Estado | Significado |
|--------|------------|
| **Reconciliado** | ✅ Coincide con factura/gasto |
| **Pendiente** | ⏳ En espera de tu revisión |
| **Rechazado** | ❌ No coincide con ningún documento |
| **Manual** | 📝 Lo registraste tú mismo |

### Reconciliar movimientos

Si un pago no se reconcilia automáticamente:

1. Ve a **Movimientos bancarios**
2. Abre el movimiento pendiente
3. Haz clic en **"Reconciliar"**
4. Elige:
   - ✅ **Factura pagada** → selecciona la factura
   - ✅ **Gasto** → crea o selecciona gasto
   - ✅ **Transferencia a otra cuenta** → ignora
   - ✅ **Otro** → comentario personalizado
5. Confirma

La factura se marca automáticamente como pagada.

## Categorización automática

Revolut / Frihet detecta automáticamente:

| Transacción | Categoría detectada |
|------------|-------------------|
| Amazon, eBay | Electrónica |
| Gasolina, Parkings | Transporte |
| Restaurante, Cafés | Comidas |
| Oficina Depot | Material de oficina |
| Telecom, Internet | Servicios |
| Depósito | Entrada de dinero |

Puedes cambiar la categoría al reconciliar.

## Cash Flow y proyecciones

### Ver balance actual

1. Ve a **Dashboard** → **Caja**
2. Ves:
   - Saldo actual en Revolut
   - Ingresos esperados (facturas no cobradas)
   - Gastos esperados (facturas sin pagar)
   - Proyección a fin de mes

**Ejemplo:**
```
Saldo actual: €5.340
+ Facturas pendientes: €8.500 (dentro de 15 días)
- Gastos por pagar: €2.100 (próximos 7 días)
= Proyección mes: €11.740
```

### Alertas de saldo bajo

Puedes configurar:

1. **Ajustes** → **Revolut** → **Alertas**
2. **"Alertarme si saldo < €X"**
3. Recibirás notificación cuando baje de ese límite

Útil para no quedarte sin dinero.

## Cuentas múltiples

Si tienes múltiples cuentas Revolut:

1. En Frihet, puedes sincronizar todas
2. Cada cuenta tiene su código
3. Los movimientos se agrupan por cuenta
4. Ves el balance total de todas

**En reportes, distingue entre:**
- Cuenta principal (EUR)
- Cuenta de ahorros (EUR)
- Cuenta de otra moneda (GBP, USD, etc.)

## Divisas múltiples

Si tienes cuentas en otras divisas (USD, GBP, etc.):

1. Frihet detecta automáticamente
2. Convierte a tu moneda principal (EUR)
3. Los movimientos aparecen con tasa de cambio
4. En reportes ves tanto en divisa original como en EUR

**Ejemplo:**
```
Movimiento: $500 USD (Pago de cliente USA)
Conversión: €460,75 EUR (a tasa de cambio 11 feb 2025)
Aparece en reportes como: €460,75
```

## Sincronización histórica

La primera vez que conectas:

1. Frihet importa transacciones de los **últimos 90 días**
2. Intenta reconciliar con facturas/gastos existentes
3. Lo que no coincide queda como "Pendiente"
4. Tú confirmas manualmente si quieres

Este proceso toma **2-5 minutos**.

## Impuestos y reportes

Con Revolut sincronizado:

1. **Reportes de ingresos** → Muestran dinero real cobrado
2. **Reportes de gastos** → Gastos reales registrados
3. **IVA calculado** → Más preciso (no estimado)
4. **Declaración fiscal** → Datos reales de Revolut

Ejemplo:
```
En Frihet facturaste: €50.000
En Revolut cobraste: €48.500 (2 facturas aún impagadas)
Reportes muestran realidad: €48.500 cobrado
```

## Desconectar Revolut

1. Ve a **Ajustes** → **Integraciones** → **Revolut**
2. Haz clic en **"Desconectar"**
3. Los movimientos que ya importaste quedan en Frihet

Después:
- No se sincronizan nuevas transacciones
- Puedes reconectar después
- En Revolut, ve a **Ajustes** → **API** y revoca el token si quieres

## Revocación de token

Si pierdes el token o quieres reset:

1. En Revolut, ve a **Ajustes** → **API**
2. Busca el token "Frihet Integration"
3. Haz clic en **"Revocar"**
4. Genera uno nuevo
5. En Frihet, actualiza el token

## Privacidad y seguridad

- **No vemos tu dinero** — Solo leemos transacciones
- **Tokens encriptados** — Se guardan encriptados en Frihet
- **Sin acceso a movimientos futuros** — Solo datos autorizados
- **Revocable inmediatamente** — Borra acceso cuando quieras

## Troubleshooting

### "No aparecen mis transacciones"

- Verifica que Revolut está conectado ✅
- Las transacciones deben ser de los últimos 90 días
- Espera 5-10 minutos para primera sincronización
- Recarga Frihet (F5)

### "¿Por qué no reconcilia automáticamente?"

- El monto debe coincidir exactamente
- La referencia ayuda (si incluyes número de factura)
- Diferentes monedas pueden no coincidir
- La fecha del cobro debe estar cerca de la factura

**Solución:** Reconcilia manualmente haciendo clic en **"Reconciliar"**.

### "Tengo cuentas en múltiples divisas"

Todo funciona:

1. Revolut soporta GBP, USD, EUR, JPY, etc.
2. Frihet convierte automáticamente a tu moneda principal
3. En reportes ves ambas (divisa original + EUR)

### "¿Afecta el token si cambio contraseña en Revolut?"

No. El token sigue válido. Solo se revoca si:

- Tú lo haces manualmente
- Tu cuenta Revolut se cierra
- Permisos del token se revocan

### "¿Qué pasa con pagos entre mis propias cuentas?"

Si haces transferencia interna (Revolut → otra cuenta):

1. Frihet detecta como "Movimiento interno"
2. No lo reconcilia con factura
3. No lo cuenta como gasto/ingreso
4. Lo puedes ignorar o marcar como "Transferencia"

## Próximos pasos

- [Automatiza todo con n8n](./n8n)
- [Sincroniza también Google Calendar](./google-calendar)

---

**Anterior:** [Google Calendar](./google-calendar)

---

## Sage Business Cloud Accounting
> Path: /integraciones/sage-business-cloud

# Sage Business Cloud Accounting

> Exporta datos contables de Frihet a Sage Business Cloud.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Sage Business Cloud Accounting y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Sage Business Cloud Accounting**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Sage Business Cloud Accounting
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Salesforce
> Path: /integraciones/salesforce

# Salesforce

> Sincroniza clientes y oportunidades de Salesforce con Frihet para facturación directa desde tu CRM.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Salesforce y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Salesforce**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Salesforce
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Sendcloud
> Path: /integraciones/sendcloud

# Sendcloud

> Sincroniza envíos de Sendcloud con Frihet para facturar costes logísticos automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Sendcloud y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Sendcloud**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Sendcloud
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## SEUR
> Path: /integraciones/seur

# SEUR

> Integra SEUR con Frihet para crear envíos y registrar costes de logística.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre SEUR y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **SEUR**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → SEUR
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Shippo
> Path: /integraciones/shippo

# Shippo

> Gestiona envíos multi-carrier desde Frihet vía Shippo y registra costes automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Shippo y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Shippo**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Shippo
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## ShipStation
> Path: /integraciones/shipstation

# ShipStation

> Importa pedidos enviados desde ShipStation en Frihet para facturación y seguimiento.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre ShipStation y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **ShipStation**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → ShipStation
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Shopify
> Path: /integraciones/shopify

# Shopify

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

Conecta tu tienda Shopify a Frihet. Los pedidos se importan automáticamente y generan facturas.

## ¿Para qué sirve?

Con Shopify integrado:

- **Importar pedidos** — Importa pedidos de Shopify como facturas en Frihet (prefijo `SHOP-`)
- **Importar productos** — Trae tu catálogo de Shopify a Frihet
- **Deduplicación automática** — Los pedidos ya importados no se duplican
- **Datos de cliente** — Email, dirección y teléfono se sincronizan automáticamente
- **Pagos automáticos** — Si Shopify procesó el pago, Frihet marca la factura como pagada

## Requisitos

- **Tienda Shopify activa** — Con productos listados
- **Acceso de administrador** — Para autorizar la app
- **Frihet Pro o superior**

## Conectar Shopify

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Shopify**
3. Haz clic en **Conectar**

### Paso 2: Autoriza en Shopify

1. Introduce el **nombre de tu tienda** (ej: `mitienda` o `mitienda.myshopify.com`)
2. Haz clic en **Conectar a Shopify**
3. Serás redirigido a la página de autorización de Shopify
4. Inicia sesión con tu cuenta Shopify si no lo has hecho
5. Verás los permisos que necesita Frihet:
   - Leer pedidos
   - Leer clientes
   - Leer productos
6. Haz clic en **Instalar app**
7. Volverás automáticamente a Frihet con la conexión activada

### Paso 3: Configura sincronización

En Frihet, después de autorizar:

1. Elige qué sincronizar:
   - ✅ **Pedidos nuevos** — Automático
   - ✅ **Crear facturas automáticas** — Automático
   - ⚪ **Sincronizar clientes** — Opcional
   - ⚪ **Sincronizar productos** — Opcional
   - ⚪ **Actualizar inventario** — Opcional

2. Guarda cambios

## Primera sincronización

La primera vez:

1. Frihet importa tus **últimos 100 pedidos** (los más recientes)
2. Crea clientes (si no existen)
3. Crea facturas para cada pedido
4. **Esto tarda 2-5 minutos** dependiendo de cantidad

Vuelve a **Facturación** → **Facturas** en 5 minutos y verás tus pedidos de Shopify como facturas.

## Cómo funciona el sync

### Nuevo pedido en Shopify

```
1. Cliente compra en tu tienda Shopify
   ↓
2. Shopify procesa el pedido
   ↓
3. Frihet detecta el nuevo pedido (cada 15 minutos)
   ↓
4. Sincroniza a Frihet automáticamente:
   - Cliente (si es nuevo, lo crea)
   - Productos
   - Factura con estado "Pagada" (si pagó en Shopify)
   ↓
5. Aparece en tu listado de Frihet
```

### Datos sincronizados

| Dato | De Shopify a Frihet |
|------|-------------------|
| ID pedido | Número de factura |
| Productos | Líneas de factura |
| Precio Shopify | Precio unitario |
| Cantidad | Cantidad |
| Cliente | Nombre, email, dirección de envío |
| Fecha pedido | Fecha de factura |
| Pago | Método (tarjeta, PayPal, etc.) |
| Envío | Se incluye como línea si aplica |
| Impuestos | Se calcula según jurisdicción |

## Estados de pedido

### Shopify → Frihet

| Estado Shopify | Estado Frihet |
|---------------|---------------|
| Pendiente | Pendiente |
| Confirmado | Pendiente |
| Completado | Pagada ✅ |
| Cancelado | Cancelada |
| Devuelto | Parcialmente reembolsado |

## Ejemplo real

### Cliente compra en tu tienda Shopify

```
Pedido #1009 en Shopify
Cliente: María García
Email: maria@example.com
Dirección: Calle Principal 42, Madrid 28001

Productos:
- 1x Camiseta azul S = €25,00
- 2x Gafas de sol = €40,00 c/u = €80,00

Subtotal: €105,00
Envío: €5,95
Impuestos: €23,19 (21%)
Total pagado: €134,14

Método pago: Tarjeta de crédito
```

### En Frihet automáticamente

```
Factura #1009
Fecha: 10 feb 2025
Cliente: María García

Líneas:
- 1x Camiseta azul S = €25,00
- 2x Gafas de sol = €80,00
- Envío = €5,95

Subtotal: €110,95
IVA (21%): €23,29 (si está configurado en Frihet)
Total: €134,24

Estado: Pagada ✅ (Shopify procesó pago)
```

**Creado automáticamente. Sin hacer nada.**

## Configuraciones avanzadas

### Mapeo de productos

Por defecto, Frihet importa productos como **descripción de línea**. Puedes:

1. Ir a **Ajustes** → **Shopify**
2. Activar **"Sincronizar catálogo de productos"**
3. Frihet crea productos en tu catálogo
4. Futuros pedidos usan esos productos (con actualización de precio)

Útil si quieres reutilizar productos en presupuestos.

### Incluir/excluir órdenes específicas

Puedes decirle a Frihet:

- **"No sincronices pedidos cancelados"** — Excluye automáticamente
- **"Solo sincroniza después del 1 enero"** — Solo pedidos recientes
- **"Excluye cliente específico"** — No crees factura para ese cliente

Configura en **Ajustes** → **Integraciones** → **Shopify** → **Filtros avanzados**

### Impuestos y comisiones

Shopify puede incluir:

- **Taxes (impuestos)** — Se sincronizan como línea separada
- **Tarifas de app** — Puedes excluirlas de la factura
- **Descuentos** — Se restan en línea aparte

En Frihet puedes ajustar qué incluir en la factura final.

## Sincronización de clientes

Si activas **"Sincronizar clientes"**:

- Cada cliente nuevo en Shopify se importa a Frihet
- Email, teléfono, dirección se sincronizan
- Si el cliente ya existe, se actualiza su info

Útil para tener una **vista unificada** de tus clientes.

## Página de productos

Con **"Sincronizar productos"** activo:

1. Frihet importa tu catálogo de Shopify
2. Ves todos los productos con:
   - Nombre
   - Precio
   - SKU
   - Descripción

3. Puedes usarlos en nuevas facturas manuales (no solo pedidos)

Si cambias precio en Shopify, se actualiza automáticamente.

## Prueba la integración

### Test pedido

1. Ve a tu tienda Shopify
2. Haz un pedido de prueba (como cliente)
3. En Frihet, espera **hasta 15 minutos**
4. Ve a **Facturación** → **Facturas**
5. Deberías ver la factura creada

Si no aparece:

- Verifica que Shopify está conectado ✅
- El pedido en Shopify debe tener estado "Completado"
- Recarga Frihet (F5)
- Revisa **Ajustes** → **Integraciones** → **Logs** de Shopify

## Reembolsos y cancelaciones

### Cliente cancela pedido en Shopify

1. Cambias estado a "Cancelado" en Shopify
2. Frihet lo detecta en próxima sincronización
3. La factura se marca como "Cancelada"

### Procesas reembolso en Shopify

Si reembolsas parcialmente:

1. Shopify registra el reembolso
2. Frihet lo detecta
3. Puedes crear **nota de crédito** automáticamente en Frihet
4. O crear manualmente si lo prefieres

## Limitaciones

- **Shopify → Frihet (síncronización de una dirección)**
  - Los cambios en Frihet no se sincronizan a Shopify
  - Si editas una factura en Frihet, Shopify no se actualiza

- **No sincroniza borradores de pedido** — Solo pedidos completados

- **Sin acceso a facturas Shopify** — Si Shopify generó factura, Frihet no puede verla

- **Inventario** — Solo lectura, no actualización automática

## Troubleshooting

### "No veo mis pedidos de Shopify"

- Espera hasta 15 minutos para primera sincronización
- Los pedidos deben estar en estado "Completado" o "Procesando"
- Recarga Frihet (F5 o Cmd+Shift+R)
- Verifica que Shopify está conectado en Ajustes

### "Duplicadas facturas"

- Puede pasar si sincronizaste dos veces
- Elimina duplicadas desde **Facturación** (selecciona varias y "Eliminar")
- Luego desconecta y reconecta

### "¿Desconectar borra mis facturas?"

No. Las facturas ya creadas en Frihet quedan. Desconectar solo:

- Detiene nuevas sincronizaciones
- Nuevos pedidos de Shopify no se sincronizan

Para desconectar:

1. **Ajustes** → **Integraciones** → **Shopify**
2. **Desconectar**
3. Confirma

### "¿Puedo conectar múltiples tiendas Shopify?"

Actualmente, Frihet soporta **una tienda Shopify** por cuenta. Si tienes múltiples:

- Opción 1: Crea cuentas Frihet separadas (una por tienda)
- Opción 2: Contacta soporte para consultar opciones avanzadas

## Próximos pasos

- [Automatiza flujos con n8n](./n8n)
- [Conecta también WooCommerce](./woocommerce)
- [Sincroniza pagos con Stripe](./stripe)
- [Ver todas las integraciones de Frihet](https://www.frihet.io/es/integrations)

---

**Anterior:** [WooCommerce](./woocommerce)

---

## Slack
> Path: /integraciones/slack

# Slack

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

Conecta Slack a Frihet. Recibe notificaciones de eventos financieros importantes directamente en tu workspace.

## ¿Para qué sirve?

Con Slack integrado:

- **Notificaciones de facturas** — Cuando se paga una factura
- **Alertas de vencimientos** — Facturas por vencer en próximos días
- **Recordatorios de cobros** — Clientes con facturas vencidas
- **Resúmenes diarios** — KPI de ese día
- **Hitos alcanzados** — Objetivo de facturación mensual

## Requisitos

- **Workspace Slack activo** — Donde trabajas
- **Permisos de administrador en Slack** — Para instalar app
- **Frihet Pro o superior**

## Instalar app de Frihet en Slack

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Slack**
3. Haz clic en **"Conectar con Slack"**

### Paso 2: Autoriza en Slack

1. Serás redirigido a Slack
2. Inicia sesión con tu workspace
3. Verás permisos necesarios:
   - Enviar mensajes
   - Acceder a información básica
   - Crear conexiones
4. Haz clic en **"Autorizar"**

### Paso 3: Elige canal de notificaciones

1. De vuelta en Frihet, elige **dónde recibir notificaciones**:
   - Canal **#finanzas** (si existe)
   - Canal **#general**
   - Mensaje directo contigo
   - Canal personalizado

2. Guarda

## Notificaciones disponibles

### Pagos recibidos

```
✅ Factura pagada
Empresa ABC pagó €2.500
Factura #1042 - 100% cobrada
Total cobrado este mes: €15.340
```

Se envía **instantáneamente** cuando se detecta pago.

### Facturas vencidas

```
⚠️ Factura vencida
Juan García debe €1.200
Factura #1038 - Vencida hace 5 días
Enviar recordatorio: Sí / No
```

Se envía **cada mañana** con resumen de vencidas.

### Próximos vencimientos

```
📅 Próximos vencimientos (7 días)
- Empresa SL: €3.500 (vence 15 feb)
- María García: €800 (vence 18 feb)
Total: €4.300
```

Se envía **cada lunes** o cada mañana (configurable).

### Objetivos alcanzados

```
🎯 ¡Objetivo alcanzado!
Facturación febrero: €12.000
Objetivo: €10.000 ✅ (20% superado)
```

Se envía cuando alcanzas tu objetivo mensual.

### Resumen diario

```
📊 Resumen Frihet - 9 feb 2025
Facturas nuevas: 2 (€1.500)
Facturas pagadas: 1 (€2.000)
Gastos registrados: 3 (€340)
Balance neto: +€3.160
```

Se envía **cada mañana a la hora que configures**.

### Gastos registrados

```
💰 Gasto registrado
Juan García gastó €45 en Material de oficina
(Tú mismo gastaste esto hace poco)
```

Opcional, para mantenerte al día.

## Configurar notificaciones

### Abre el panel de notificaciones

1. **Ajustes** → **Integraciones** → **Slack**
2. Haz clic en **"Configurar notificaciones"**

### Qué activar/desactivar

| Evento | Recomendación |
|--------|-------------|
| **Pagos recibidos** | ✅ Siempre sí |
| **Vencimientos próximos** | ✅ Muy útil |
| **Facturas vencidas** | ✅ Crítico |
| **Objetivos alcanzados** | ✅ Motivador |
| **Resumen diario** | ✅ Recomendado |
| **Nuevas facturas creadas** | ⚪ Opcional |
| **Gastos registrados** | ⚪ Solo si trabajas en equipo |

### Configurar frecuencia

```
Resumen diario:
- A las 08:30 (mañana)
- A las 18:00 (tarde)
- Ambas (recomendado)

Alertas de vencimiento:
- Cada mañana
- Solo los lunes
- Manual (bajo demanda)
```

## Menciones en equipo

Si trabajas en equipo en Slack, puedes:

1. Mencionar a alguien en una notificación
2. Ej: "⚠️ @juan_manager: Factura vencida de €2.500"

Configura en **Ajustes** → **Slack** → **Menciones automáticas**.

## Comandos rápidos en Slack

Con Frihet en Slack puedes escribir comandos:

### Resumen rápido

```
/frihet resumen
```

**Respuesta:**
```
Facturación total: €15.340
Gastos totales: €2.100
Margen: €13.240 (86%)
Facturas pendientes: 3 (€4.500)
```

### Últimos pagos

```
/frihet pagos
```

**Respuesta:**
```
Últimos 5 pagos:
1. Empresa ABC - €2.500 (8 feb)
2. Juan García - €800 (6 feb)
3. Startup XYZ - €1.200 (4 feb)
...
```

### Clientes con deuda

```
/frihet vencidas
```

**Respuesta:**
```
Facturas vencidas:
- Juan García: €800 (5 días)
- Empresa SL: €2.100 (12 días)
Total: €2.900
```

### Ver objetivo

```
/frihet objetivo
```

**Respuesta:**
```
Objetivo febrero: €10.000
Facturado hasta hoy: €8.340 (83%)
Falta: €1.660 (7 días)
```

## Recordatorios automáticos

### Enviar cobro

Cuando hay una factura vencida, Frihet pregunta:

```
⚠️ Factura vencida: Juan García €1.200

Acciones:
[Enviar recordatorio] [Marcar como pagada] [Ignorar]
```

Haz clic en **"Enviar recordatorio"** y Slack:

1. Crea un email de recordatorio
2. Te pregunta si enviarlo
3. Lo envía al cliente

### Confirmación de pago

Cuando marcas una factura como pagada desde Slack:

```
✅ Factura #1042 marcada como pagada
Empresa ABC - €2.500
Actualizado en Frihet hace 2 segundos
```

## Desconectar Slack

1. Ve a **Ajustes** → **Integraciones** → **Slack**
2. Haz clic en **"Desconectar"**
3. Confirma

Después:
- No recibís más notificaciones
- Comandos `/frihet` dejan de funcionar
- Puedes reconectar en cualquier momento

## Privacidad

- **Sin acceso a conversaciones** — Frihet solo envía notificaciones
- **Datos encriptados** — Entre Frihet y Slack
- **Sin historial de mensajes** — Los mensajes no se guardan en Frihet
- **Revocable en cualquier momento** — Desconecta cuando quieras

## Troubleshooting

### "No recibo notificaciones"

- Verifica que Slack está conectado ✅
- En **Configurar notificaciones**, activa los eventos que quieres
- Comprueba que elegiste el canal correcto
- Recarga Frihet (F5)

### "¿Puedo recibir notificaciones en otro canal?"

Sí. En **Ajustes** → **Slack** → **Canal de notificaciones**, cambia a otro.

Opciones:
- Canal público (#finanzas)
- Canal privado (#proyectos-secretos)
- Mensaje directo contigo
- Subcanal (@frihet-bot)

### "Los comandos `/frihet` no funcionan"

- La app debe estar instalada en tu workspace ✅
- En Slack, busca en el canal de notificaciones y menciona a @frihet
- Luego debería responder con opciones de comandos

### "¿Trabaj en equipo y todos reciben notificaciones?"

Sí. Si es un problema, puedes:

1. Usar un canal privado solo para ti
2. O desactivar ciertas notificaciones que parecen spam
3. Mencionar a personas específicas en **Ajustes** → **Menciones automáticas**

## Próximos pasos

- [Automatiza con n8n](./n8n)
- [Conecta Google Calendar para fechas importantes](./google-calendar)

---

**Anterior:** [Clockify](./clockify)

---

## Square
> Path: /integraciones/square

# Square

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Square**.
:::

Conecta tu cuenta de Square a Frihet para importar automáticamente las transacciones y pagos de tu punto de venta. Square es una plataforma de cobros que incluye terminales POS, pagos online y gestión de inventario. Con esta integración, cada venta registrada en Square se importa a Frihet como ingreso, eliminando la entrada manual y manteniendo tu contabilidad sincronizada con las ventas presenciales y online.

## ¿Para qué sirve?

- **Importar transacciones** — Cada pago procesado en Square (TPV, online, factura) se importa como ingreso en Frihet con todos los detalles
- **Reconciliación automática** — Cruza los pagos de Square con tus facturas en Frihet sin esfuerzo manual
- **Clientes sincronizados** — Los clientes registrados en Square se importan a tu base de datos de contactos en Frihet
- **Comisiones como gastos** — Las comisiones que cobra Square por cada transacción se registran automáticamente como gastos en Frihet
- **Historial completo** — Importa transacciones pasadas para tener una vista completa de tu actividad comercial

## Requisitos

- Cuenta activa en [Square](https://squareup.com)
- Plan Frihet Pro o Premium
- Access Token de la API de Square (se obtiene desde el Square Developer Dashboard)

## Cómo conectar

### Paso 1: Obtener tu Access Token en Square

1. Inicia sesión en [developer.squareup.com](https://developer.squareup.com)
2. Crea una nueva aplicación o selecciona una existente
3. En el panel de la aplicación, navega a **Credentials**
4. Copia el **Production Access Token** (no uses el de sandbox para datos reales)
5. Asegúrate de que el token tiene permisos de lectura para **Payments**, **Orders** y **Customers**

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Square** y haz clic en el card
3. Pega tu **Access Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Selecciona la **ubicación** (location) de Square que quieres sincronizar
6. Haz clic en **Guardar**

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Transacciones/pagos | Square → Frihet | Importe, fecha, método de pago, referencia |
| Clientes | Square → Frihet | Nombre, email, teléfono del comprador |
| Comisiones | Square → Frihet | Comisiones de Square registradas como gastos |
| Productos vendidos | Square → Frihet | Líneas de detalle de cada transacción |
| Estado de pago | Square → Frihet | Completado, reembolsado, pendiente |

## Casos de uso

### Tienda física con contabilidad digital

Tienes una tienda y cobras con el terminal de Square. Cada venta del día se importa automáticamente a Frihet por la noche. Tu contabilidad refleja todas las ventas presenciales sin que tengas que copiar nada a mano. Las comisiones de Square aparecen como gastos para que veas tu margen real.

### Negocio con ventas presenciales y online

Vendes tanto en tienda con Square como por tu web. Frihet consolida las transacciones de Square con tus facturas online para darte una vista unificada de todos tus ingresos. Puedes generar informes fiscales con todas las fuentes de ingreso centralizadas.

### Autónomo con cobros por móvil

Eres autónomo y cobras a tus clientes con Square en el móvil (eventos, servicios a domicilio, mercados). Cada cobro se registra automáticamente en Frihet con el detalle del servicio, para que tengas tu contabilidad al día sin dedicar tiempo extra.

## Solución de problemas

### Error de conexión

- Verifica que estás usando el **Production Access Token**, no el de sandbox
- Comprueba que el token no ha expirado o sido revocado desde el Developer Dashboard
- Asegúrate de que la aplicación de Square tiene los permisos necesarios (Payments Read, Orders Read, Customers Read)

### No se importan transacciones

- Confirma que tienes transacciones en el rango de fechas seleccionado
- Solo se importan transacciones con estado **completado** — las pendientes o canceladas se excluyen
- Verifica que has seleccionado la ubicación (location) correcta de Square

### Transacciones duplicadas

- Frihet deduplica por ID de transacción de Square. No debería ocurrir duplicados
- Si ves duplicados, desconecta y reconecta la integración
- Las transacciones ya importadas en Frihet no se ven afectadas por la reconexión

### Comisiones no registradas

- Las comisiones se registran como gastos separados, no se descuentan del importe de la transacción
- Verifica que la importación de comisiones está activada en la configuración de la integración

## Siguientes pasos

- [Conecta Stripe para pagos online](./stripe)
- [Gestiona tus gastos importados](../gastos/registrar-gastos)
- [Reconcilia transacciones con facturas](../facturacion/cobros-pagos)

---

## Squarespace
> Path: /integraciones/squarespace

# Squarespace

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Squarespace**.
:::

Conecta tu tienda de Squarespace Commerce a Frihet para importar automáticamente pedidos, productos y datos de clientes. Squarespace es una plataforma de creación web con funcionalidades de e-commerce integradas. Con esta integración, cada venta realizada en tu tienda Squarespace se registra en Frihet como ingreso, manteniendo tu contabilidad sincronizada con tu actividad de ventas online sin intervención manual.

## ¿Para qué sirve?

- **Importar pedidos** — Las ventas de Squarespace Commerce se importan automáticamente como ingresos/facturas en Frihet
- **Productos sincronizados** — Tu catálogo de productos de Squarespace se refleja en el catálogo de Frihet
- **Clientes unificados** — Los compradores de tu tienda Squarespace se añaden como clientes en Frihet con sus datos de contacto
- **Informes consolidados** — Ve todas tus ventas de Squarespace junto con otros canales en los informes de Frihet
- **Comisiones como gastos** — Las comisiones de procesamiento de pago se registran automáticamente como gastos

## Requisitos

- Cuenta de Squarespace con un plan Commerce (Basic o Advanced)
- Plan Frihet Pro o Premium
- API Key de Squarespace

## Cómo conectar

### Paso 1: Obtener tu API Key en Squarespace

1. Inicia sesión en tu sitio de [Squarespace](https://www.squarespace.com)
2. Ve a **Settings → Advanced → Developer API Keys**
3. Haz clic en **Generate API Key**
4. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
5. Selecciona los permisos de **Orders** (lectura) y **Inventory** (lectura)
6. Copia la API Key generada

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Squarespace** y haz clic en el card
3. Pega tu **API Key** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Confirma el sitio web de Squarespace que quieres conectar
6. Haz clic en **Guardar**

## Datos que se sincronizan

| Dato | Dirección | Detalles |
|------|-----------|----------|
| Pedidos | Squarespace → Frihet | ID de pedido, importe total, fecha, estado, líneas de producto |
| Productos | Squarespace → Frihet | Nombre, precio, SKU, variantes |
| Clientes | Squarespace → Frihet | Nombre, email, dirección de envío |
| Estado de pedido | Squarespace → Frihet | Pendiente, completado, reembolsado, cancelado |
| Comisiones de pago | Squarespace → Frihet | Registradas como gastos automáticamente |

## Casos de uso

### Diseñador con tienda online

Vendes prints, plantillas o productos digitales desde tu web de Squarespace. Cada venta se importa a Frihet automáticamente, y puedes generar facturas profesionales para tus clientes sin copiar datos manualmente. Al final del trimestre, tienes todos tus ingresos registrados para la declaración fiscal.

### Tienda de artesanía o productos handmade

Gestionas tu tienda de productos hechos a mano en Squarespace Commerce. Los pedidos se sincronizan con Frihet para que tengas un registro contable limpio. Las comisiones de procesamiento de pago aparecen como gastos, dándote visibilidad del margen real de cada venta.

### Consultor con venta de cursos online

Ofreces cursos o recursos descargables desde tu web de Squarespace. Cada compra genera un registro en Frihet con los datos del comprador, permitiéndote hacer seguimiento de ingresos por producto y emitir facturas cuando el cliente las solicite.

## Solución de problemas

### Error de conexión

- Verifica que la API Key es correcta y no ha expirado
- Comprueba que tu plan de Squarespace incluye Commerce (los planes Personal no incluyen API de Commerce)
- Si regeneraste la API Key, actualízala en Frihet

### No se importan pedidos

- Asegúrate de que tienes pedidos en Squarespace con estado **completado** o **pagado**
- Los pedidos en estado borrador o cancelado no se importan
- Verifica que la API Key tiene permisos de lectura de Orders

### Productos no aparecen en el catálogo

- Solo se importan productos que forman parte de pedidos importados
- Los productos archivados o eliminados en Squarespace no se sincronizan
- Ejecuta una sincronización manual desde la configuración de la integración

### Importes no coinciden

- Squarespace muestra precios con impuestos incluidos o excluidos según tu configuración — verifica que coincide con la configuración fiscal de Frihet
- Los descuentos aplicados en Squarespace se reflejan en el importe neto del pedido importado

## Siguientes pasos

- [Conecta Shopify si vendes en múltiples plataformas](./shopify)
- [Conecta Etsy para ventas en marketplace](./etsy)
- [Gestiona tu catálogo de productos en Frihet](../productos/catalogo)

---

## Starling Bank
> Path: /integraciones/starling-bank

# Starling Bank

> Conecta Starling Bank con Frihet para importar movimientos y conciliar cobros.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Starling Bank y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Starling Bank**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Starling Bank
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Stripe Connect
> Path: /integraciones/stripe-connect

# Stripe Connect

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

Con Stripe Connect, tus clientes pagan directamente desde el link que les envías. El pago se sincroniza automáticamente en Frihet.

## ¿Para qué sirve?

Stripe Connect permite:

- **Links de pago en facturas** — Clientes pagan con tarjeta, Apple Pay, Google Pay
- **Métodos múltiples** — Tarjeta, transferencia bancaria, móvil
- **Sincronización automática** — Frihet marca como pagada al instante
- **Sin complicaciones** — No necesitas cargar números de tarjeta

## Requisitos

- **Plan Pro o superior**
- **Cuenta bancaria verificada en Stripe** — Para recibir transferencias

## Dos formas de conectar

### Si ya tienes cuenta Stripe (recomendado)

1. Ve a **Ajustes** → **Integraciones** → **Stripe Connect**
2. Haz clic en **"Conectar cuenta Stripe existente"**
3. Stripe te pedirá iniciar sesión y autorizar a Frihet
4. Una vez autorizado, ya puedes generar links de pago

Esto usa Stripe Connect **Standard** — mantienes el control total de tu cuenta Stripe.

### Si no tienes cuenta Stripe

1. Ve a **Ajustes** → **Integraciones** → **Stripe Connect**
2. Selecciona tu **país** y haz clic en **"Crear cuenta nueva"**
3. Stripe te guiará por la verificación (datos personales, cuenta bancaria)
4. Una vez verificado, ya puedes generar links de pago

Esto usa Stripe Connect **Express** — Stripe gestiona la verificación por ti.

## Cómo generar un link de pago

### Desde una factura

#### Opción 1: Botón rápido

1. Abre tu factura desde **Facturación** → **Facturas**
2. Haz clic en **"Generar link de pago"** (botón azul)
3. Automáticamente Frihet genera link
4. El link aparece en la factura con un código QR

#### Opción 2: Al enviar factura

Cuando envías una factura por email:

1. Antes de enviar, activa **"Incluir link de pago"**
2. Frihet genera automáticamente el link
3. Se incluye en el email al cliente
4. Cliente ve un botón "Pagar ahora" en el email

#### Opción 3: Compartir manualmente

```
Link de pago (copiable):
https://frihet.link/pay/inv_XXXXXXXX

O escaneando QR
```

Puedes:

- Copiar el link
- Compartirlo por Whatsapp, Slack, SMS
- Incrustar en tu web
- Escanear con móvil

## Experiencia del cliente

### Flujo de pago

1. Cliente abre el link
2. Ve el resumen: concepto, importe, vencimiento
3. Elige método:
   - **Tarjeta** → Visa, Mastercard, etc.
   - **Transferencia** → IBAN (si está disponible)
   - **Google Pay** / **Apple Pay** — Si está en móvil
4. Confirma datos
5. Paga
6. Recibe confirmación por email

### Métodos de pago disponibles

Según tu configuración de Stripe:

| Método                 | Disponible         |
| ---------------------- | ------------------ |
| Tarjeta crédito/débito | Siempre ✅         |
| Google Pay             | Móvil ✅           |
| Apple Pay              | Móvil/Mac ✅       |
| Transferencia SEPA     | Según país         |
| PayPal                 | Si está habilitado |

## Qué pasa después del pago

### En Frihet

1. Cliente paga usando el link
2. Stripe procesa el pago (~2 segundos)
3. Frihet recibe confirmación (en tiempo real)
4. **La factura se marca automáticamente como "Pagada"** ✅
5. El pago aparece en **Movimientos bancarios**

### En tu cuenta bancaria

1. Los pagos se depositan en tu cuenta bancaria
2. Stripe retiene su comisión (2,4% + €0,20)
3. En 1-2 días ves el monto neto en tu banco

**Ejemplo:**

- Cliente paga €100
- Comisión Stripe: €2,60 (2,4% + €0,20)
- Recibes en el banco: €97,40

## Personalización

### Cambiar branding del link

Stripe Connect muestra tu nombre automáticamente, pero puedes personalizar:

1. Ve a **Ajustes** → **Integraciones** → **Stripe**
2. Configura:
   - Logo de tu empresa
   - Color principal
   - Mensaje personalizado

### Cambiar texto del botón

En tu email de factura puedes cambiar:

❌ "Pagar ahora"
✅ "Abonar factura"
✅ "Completar pago"

Edita en **Ajustes** → **Email templates**

## Comisiones y precios

Stripe cobra:

- **2,4% + €0,20** por transacción con tarjeta
- **0,2% + €0,02** por transferencia bancaria (si está habilitada)

**No hay comisiones mensuales** en Stripe (usas gratis si no tienes transacciones).

## Seguridad

- **PCI compliance** — Tus datos y los de clientes están protegidos
- **Encriptación SSL** — Toda comunicación encriptada
- **Verificación de identidad** — Stripe verifica al cliente
- **Protección de fraude** — Stripe detecta transacciones sospechosas

## Reconciliación manual

Si por algún motivo Frihet no detecta un pago:

1. Abre la factura
2. Haz clic en **"Marcar como pagada"**
3. Selecciona método: **"Pago Stripe"**
4. Confirma el monto
5. Se registra manualmente

## Múltiples links para la misma factura

Puedes regenerar links:

1. Abre la factura
2. **"Generar nuevo link"** — Invalida el anterior
3. El nuevo link funciona con los mismos datos

**Caso de uso:** Cliente perdió el primer link, generas uno nuevo.

## Límites y restricciones

| Restricción            | Detalle                                 |
| ---------------------- | --------------------------------------- |
| **Importe máximo**     | €50.000 por transacción                 |
| **Clientes repetidos** | Sin límite                              |
| **Links activos**      | Sin límite temporal (siempre funcionan) |
| **Intentos fallidos**  | Unlimited (cliente puede reintentar)    |

## Troubleshooting

### "El link no funciona"

- Verifica que Stripe está conectado (estado "Conectado")
- Recarga la página del link
- Intenta en navegador privado
- Si persiste, regenera el link

### "Cliente recibió error al pagar"

- Posible bloqueo del banco — Pide que intente de nuevo
- Limite de transacción — Cliente contacta a su banco
- Problema de Stripe — Espera y reintenta (Stripe también puede estar en mantenimiento)

### "¿Puedo aceptar PayPal?"

Actualmente Frihet + Stripe solo soporta métodos de Stripe. Para PayPal tendrías que usar integraciones adicionales.

### "¿Qué comisiones pagué?"

1. Ve a **Movimientos bancarios**
2. Filtra por **"Comisiones Stripe"**
3. Ves todas las que pagaste este mes

## Próximos pasos

- [Automatiza cobros con n8n](./n8n)
- [Conecta también WooCommerce](./woocommerce)
- [Sincroniza con tu banco](./revolut)

---

**Anterior:** [Stripe — Resumen y conexión OAuth](./stripe)

---

## Stripe Revenue Sync
> Path: /integraciones/stripe-revenue

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

---

## Stripe — Resumen y conexión OAuth
> Path: /integraciones/stripe

# Stripe

:::tip Disponible
Ambas integraciones Stripe están disponibles en todos los planes Pro.
:::

Frihet tiene dos integraciones Stripe complementarias — elige la que se adapta a tu flujo:

| Integración                                 | Caso de uso                                                                                    | Conexión            |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------- |
| **[Stripe Connect](./stripe-connect)**      | Genera links de pago en tus facturas. Clientes pagan con tarjeta, Apple Pay o Google Pay.      | OAuth (un clic)     |
| **[Stripe Revenue Sync](./stripe-revenue)** | Importa tus cobros de Stripe como facturas en Frihet. Sincronización incremental cada 6 horas. | API Key restringida |

## ¿Cuál usar?

- **Cobras desde Frihet y quieres que tus clientes paguen online** → usa [Stripe Connect](./stripe-connect)
- **Ya cobras desde el Dashboard de Stripe y quieres esos cobros como facturas en Frihet** → usa [Stripe Revenue Sync](./stripe-revenue)
- **Tienes suscripciones en Stripe Billing** → usa [Stripe Revenue Sync](./stripe-revenue) para importar cada cobro automáticamente

Puedes activar las dos a la vez.

## Conectar Stripe (OAuth)

La conexión OAuth de Stripe es la base para Stripe Connect. Se hace una sola vez:

### Paso 1: Abre integraciones

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Stripe Connect**
3. Haz clic en **Conectar**

### Paso 2: Autenticación

1. Serás redirigido a Stripe
2. Inicia sesión con tu cuenta Stripe
3. Autoriza a Frihet para acceder a tu cuenta
4. Frihet redirige automáticamente

### Paso 3: Confirma la conexión

Una vez autorizado:

```
✅ Stripe conectado
ID de cuenta: acct_XXXXXXXXX
Último sincronizado: Hace 2 minutos
```

## Datos que se sincronizan (OAuth)

### De Stripe a Frihet

| Dato                  | Sincronización  |
| --------------------- | --------------- |
| Clientes              | Cada 15 minutos |
| Suscripciones activas | Cada 15 minutos |
| Pagos                 | En tiempo real  |
| Reembolsos            | En tiempo real  |
| Facturas              | Cada 15 minutos |

### De Frihet a Stripe

| Dato                 | Sincronización       |
| -------------------- | -------------------- |
| Datos de cliente     | Manual (al crear)    |
| Metadatos de factura | Manual (al vincular) |

**Nota:** La sincronización es principalmente de Stripe → Frihet. No edites clientes en Frihet que existan en Stripe para evitar conflictos.

## Seguridad

- **Conexión OAuth** — No compartimos contraseña de Stripe
- **API restringida** — Solo acceso a lectura de pagos, sin acceso a dinero
- **Desconexión instantánea** — Revoca acceso en Ajustes cuando quieras
- **Encriptación** — Tokens almacenados encriptados en Frihet

## Desconectar Stripe

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

Después de desconectar, las suscripciones activas en Stripe siguen funcionando pero Frihet no las ve. Puedes reconectar en cualquier momento.

## Próximos pasos

- [Genera links de pago con Stripe Connect](./stripe-connect)
- [Importa cobros de Stripe con Revenue Sync](./stripe-revenue)
- [Automatiza con n8n](./n8n)
- [Ver todas las integraciones de Frihet](https://www.frihet.io/es/integrations)

---

## SumUp Invoices
> Path: /integraciones/sumup-invoices

# SumUp Invoices

> Sincroniza facturas emitidas con SumUp Invoices en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre SumUp Invoices y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **SumUp Invoices**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → SumUp Invoices
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## SumUp Payments
> Path: /integraciones/sumup-payments

# SumUp Payments

> Sincroniza cobros de tarjeta procesados con SumUp en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre SumUp Payments y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **SumUp Payments**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → SumUp Payments
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## SumUp POS
> Path: /integraciones/sumup-pos

# SumUp POS

> Sincroniza ventas en punto de venta SumUp con Frihet para facturación y contabilidad.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre SumUp POS y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **SumUp POS**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → SumUp POS
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Telegram Bot API
> Path: /integraciones/telegram-bot-api

# Telegram Bot API

> Envía alertas y resúmenes de actividad de Frihet vía bot de Telegram.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Telegram Bot API y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Telegram Bot API**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Telegram Bot API
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## TikTok Shop
> Path: /integraciones/tiktok-shop

# TikTok Shop

> Sincroniza pedidos de TikTok Shop con Frihet para facturación automática.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre TikTok Shop y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **TikTok Shop**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → TikTok Shop
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Toggl Track
> Path: /integraciones/toggl

# Toggl Track

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

Conecta Toggl Track a Frihet. Importa tus horas registradas y convierte tiempo en facturas.

## ¿Para qué sirve?

Con Toggl integrado:

- **Importar horas** — Traes tus registros de tiempo a Frihet
- **Crear facturas desde horas** — Convierte horas en facturas por cliente
- **Tarifa configurable** — Define precio/hora por cliente
- **Proyectos y tareas** — Agrupa por proyecto para facturas detalladas

## Requisitos

- **Cuenta Toggl Track activa** — Necesitas tener registrado tiempo
- **API Key de Toggl** — Para conectar
- **Frihet Pro o superior**

## Obtener tu API Key de Toggl

### Paso 1: Abre Toggl

1. Ve a [track.toggl.com](https://track.toggl.com)
2. Inicia sesión
3. En la esquina inferior izquierda, haz clic en tu nombre
4. Selecciona **Configuración** (engranaje)

### Paso 2: Encuentra tu API Key

1. En **Configuración**, ve a **API Token**
2. Verás un token largo (ej: `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`)
3. **Cópialo** (importante: guárdalo seguro, no lo compartas)

## Conectar Toggl a Frihet

### Paso 1: Abre Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Toggl Track**
3. Haz clic en **Conectar**

### Paso 2: Ingresa tu API Key

1. Pega el token de Toggl
2. Haz clic en **Verificar conexión**
3. Si es correcto, verás "✅ Conectado"

### Paso 3: Configura la sincronización

1. Elige **qué proyectos sincronizar**:
   - Todos los proyectos ✅
   - Solo proyectos específicos ⚪

2. Define **tarifa por defecto**:
   - Ejemplo: €60/hora
   - Puedes cambiarla por cliente después

3. Guarda

## Importar horas registradas

### Opción 1: Importación manual

1. En Frihet, ve a **Facturación** → **Importar desde Toggl**
2. Elige rango de fechas:
   - "Este mes"
   - "Últimos 7 días"
   - "Fechas personalizadas"
3. Selecciona qué proyectos importar
4. Haz clic en **"Importar"**
5. Se crean **borradores de factura** (puedes revisar antes de guardar)

### Opción 2: Sincronización automática

Si lo activas en Ajustes:

1. Cada día, Frihet importa automáticamente tus horas de Toggl
2. Las agrupa por cliente
3. Crea borradores de factura
4. Tú las revises y confirmes

## Ejemplo: Convertir horas a factura

### En Toggl

```
Proyecto: Diseño Web - Cliente XYZ
- Lunes 3 feb: 5 horas (Diseño UI)
- Miércoles 5 feb: 3 horas (Desarrollo)
- Total: 8 horas

Proyecto: Consultoría - Juan García
- Jueves 6 feb: 2 horas (Reunión)
- Total: 2 horas
```

### En Frihet (después de importar)

**Factura #1 - Cliente XYZ**
```
Concepto: Diseño Web
- 5 horas @ €60 = €300
- 3 horas @ €60 = €180
Total: €480

Desglose:
- 3 feb: 5h Diseño UI
- 5 feb: 3h Desarrollo
```

**Factura #2 - Juan García**
```
Concepto: Consultoría
- 2 horas @ €60 = €120

Desglose:
- 6 feb: 2h Reunión
```

## Tarifas personalizadas por cliente

Por defecto, todos usan la tarifa de €60/h. Puedes cambiar:

### Opción 1: Editar en la factura

1. Se crea la factura
2. Antes de confirmar, cambias la tarifa manualmente
3. Las horas se recalculan automáticamente

### Opción 2: Tarifa fija por cliente

1. Ve a **Clientes** → abre un cliente
2. En **"Tarifa Toggl"**, ingresa €80/hora
3. La próxima importación usa esa tarifa para ese cliente

## Desglose detallado de tareas

Si en Toggl usas **descripción de tareas**, Frihet las incluye:

```
En Toggl:
- 10:00-12:00 "Reunión con cliente" (2h)
- 14:00-16:30 "Correcciones de diseño" (2.5h)
```

En Frihet aparece como:
```
Factura:
- Reunión con cliente: 2h @ €60 = €120
- Correcciones de diseño: 2.5h @ €60 = €150
Total: €270
```

Puedes editar cada línea antes de confirmar.

## Proyectos y clientes

### Mapeo automático

Frihet intenta mapear:

```
Proyecto Toggl "Cliente A"
→ Cliente Frihet "Cliente A"

Si el cliente no existe:
→ Frihet lo crea automáticamente
```

### Mapeo manual

Si quieres que un proyecto Toggl vaya a otro cliente:

1. Ve a **Ajustes** → **Toggl** → **Mapeo de proyectos**
2. Para cada proyecto, elige cliente Frihet
3. Guarda

**Ejemplo:**
```
Proyecto Toggl "Diseño Q1"
→ Asignar a cliente Frihet "Empresa SL"
```

## Prueba la integración

### Test import

1. En Toggl, registra una hora: "Tarea de prueba" (1 hora)
2. En Frihet, ve a **Facturación** → **Importar desde Toggl**
3. Elige **"Últimas 24 horas"**
4. Haz clic en **"Importar"**
5. Deberías ver una factura borrador

Si no aparece:

- Verifica que Toggl está conectado ✅
- Las horas tienen que ser de hoy o ayer (Toggl puede estar en UTC)
- Recarga Frihet (F5)

### Importar registros de tiempo

Frihet puede convertir tus registros de tiempo en lineas de factura automaticamente:

1. Conecta tu cuenta de Toggl
2. Ve a la pestaña **Datos** de la integracion
3. Haz clic en **Importar registros de tiempo**
4. Introduce tu tarifa por hora
5. Frihet agrupa las entradas por proyecto y crea un borrador de factura

Las entradas se agrupan por proyecto, sumando las horas totales y aplicando la tarifa indicada.

## Cosas que puedes hacer

### Agrupar por proyecto

Importas un proyecto completo del mes:

```
Proyecto "App iOS":
- Semana 1: 20 horas
- Semana 2: 25 horas
Total: 45 horas @ €70/h = €3.150
```

Creas una factura única: "Desarrollo App iOS - Febrero 2025"

### Facturar por sprint

Si trabajas en sprints:

1. En Toggl, cada sprint en un proyecto separado
2. Cada mes, importas y creas factura por sprint
3. Desglose claro para el cliente

### Tarifas por tipo de trabajo

```
Toggl: Tag "Diseño" → €80/h
Toggl: Tag "Desarrollo" → €100/h
Toggl: Tag "Consultoría" → €60/h
```

Puedes mapear estas tarifas diferentes en Frihet.

## Sincronización en tiempo real

El trabajo que registres en Toggl **hoy**:

- Aparecerá disponible para importar en Frihet **mañana**
- Si activas sincronización automática, se importa automáticamente

Toggl envía datos una vez al día (normalmente a las 3am UTC).

## Editar después de importar

Después de importar las horas:

1. La factura está en estado **"Borrador"**
2. Puedes editar:
   - Concepto
   - Tarifa por hora
   - Agregar/quitar líneas
   - Cambiar cliente
3. Cuando esté bien, confirma la factura

Las horas originales en Toggl **no se afectan** — puedes editar la factura libremente.

## Eliminar una importación

Si importaste por error:

1. Busca la factura en **Facturación** → **Facturas**
2. Si aún es **"Borrador"**, puedes **Eliminar**
3. Las horas en Toggl siguen ahí, sin cambios

Si ya la confirmaste como factura, puedes:
- Marcarla como "Cancelada"
- O crear una nota de crédito

## Límites y restricciones

- **Máximo 90 días de historial** en una importación
- **10 importaciones simultáneas** (no debería afectarte)
- **Sin sincronización de eliminaciones** — Si borras una hora en Toggl, la factura en Frihet permanece

## Troubleshooting

### "No veo mis horas en Toggl"

- Verifica que está conectado ✅
- Las horas deben estar registradas (no borradores)
- Espera 24h después de registrar en Toggl

### "¿Puedo cambiar la tarifa después de facturar?"

Sí. Edita la factura:

1. **Facturación** → abre la factura
2. Cambia tarifa por hora
3. Se recalcula automáticamente
4. Guarda cambios

### "¿Qué pasa si cambio la API Key?"

Desconecta y reconecta:

1. **Ajustes** → **Integraciones** → **Toggl**
2. **Desconectar**
3. Ingresa nueva API Key
4. **Conectar**

Las facturas ya creadas quedan igual.

## Próximos pasos

- [Usa Clockify como alternativa a Toggl](./clockify)
- [Automatiza facturas con n8n](./n8n)

---

**Anterior:** [Shopify](./shopify)

---

## Trello
> Path: /integraciones/trello

# Trello

:::tip Disponible
Esta integración está activa y lista para usar en Frihet.
:::

Conecta tus tableros de Trello a Frihet. Consulta tableros, listas y tarjetas directamente desde tu ERP para tener contexto de proyecto al facturar.

## ¿Para qué sirve?

Con Trello integrado:

- **Ver tableros** — Consulta todos tus tableros de Trello desde Frihet
- **Ver listas y tarjetas** — Navega la estructura de tus proyectos
- **Contexto al facturar** — Consulta tareas completadas antes de crear una factura
- **Visibilidad centralizada** — Sin cambiar entre aplicaciones

## Requisitos

- **Cuenta Trello activa** — [trello.com](https://trello.com)
- **API Key de Trello** — Se obtiene desde el portal de desarrolladores
- **Token de autorización** — Se genera al autorizar tu aplicación
- **Frihet Pro o superior**

## Conectar Trello con Frihet

### Paso 1: Obtener tu API Key

1. Ve a [trello.com/power-ups/admin](https://trello.com/power-ups/admin)
2. Inicia sesión en tu cuenta de Trello
3. Haz clic en **New** para crear un nuevo Power-Up o integración
4. Rellena los campos:
   - **Name**: "Frihet ERP"
   - **Workspace**: Selecciona tu workspace
5. Una vez creado, ve a la pestaña **API Key**
6. Copia tu **API Key**

### Paso 2: Generar un Token

1. En la misma página, junto a la API Key, haz clic en el enlace **Token**
2. Se abrirá una página de autorización de Trello
3. Revisa los permisos solicitados y haz clic en **Allow**
4. Copia el **Token** generado

:::caution Dos credenciales
Necesitas ambas: la **API Key** y el **Token**. Cópialos antes de continuar.
:::

### Paso 3: Configurar en Frihet

1. Ve a **Ajustes** → **Integraciones**
2. Busca **Trello**
3. Haz clic en **Conectar**
4. Introduce tu **API Key**
5. Introduce tu **Token**
6. Haz clic en **Verificar conexión**
7. Si es correcto, verás tus tableros listados

## Cómo funciona

Frihet usa la **API REST de Trello** con autenticación por query params:

1. Proporcionas API Key y Token
2. Frihet añade ambos como parámetros de query en cada petición: `?key=<api-key>&token=<token>`
3. Los tableros, listas y tarjetas se consultan bajo demanda
4. Ambas credenciales se almacenan cifradas (AES-256-GCM) en Frihet

## Datos sincronizados

| Dato | Dirección | Frecuencia |
|------|-----------|------------|
| Tableros | Trello → Frihet | Bajo demanda |
| Listas | Trello → Frihet | Bajo demanda |
| Tarjetas | Trello → Frihet | Bajo demanda |
| Miembros | Trello → Frihet | Con cada consulta |

## Casos de uso

### Freelancer que gestiona proyectos en Trello

Tienes un tablero por cliente con columnas como "Por hacer", "En progreso" y "Completado". Antes de facturar, consultas las tarjetas completadas desde Frihet para verificar qué trabajo incluir.

### Agencia con tableros de cliente

Tu equipo trabaja con tableros compartidos por cliente. Desde Frihet puedes ver el estado de cada tablero para saber cuándo un proyecto está listo para facturar.

### Verificar entregables antes de facturar

Antes de emitir una factura de un proyecto, consultas desde Frihet las tarjetas del tablero correspondiente en Trello. Confirmas que todos los entregables están completados.

## Funcionalidades

### Ver tableros

1. Desde Frihet, accede a la sección de Trello
2. Verás todos los tableros a los que tiene acceso tu cuenta
3. Selecciona un tablero para ver sus listas y tarjetas

### Ver listas y tarjetas

1. Selecciona un tablero
2. Frihet muestra las listas (columnas) con sus tarjetas
3. Cada tarjeta muestra título, miembros asignados y etiquetas

### Navegar tarjetas

1. Haz clic en una tarjeta para ver más detalles
2. Ve la descripción, checklist, comentarios y adjuntos
3. Usa esta información como referencia al crear facturas

### Limites de API

Frihet implementa throttling automatico (100ms entre peticiones) para respetar los limites de la API de Trello. Las consultas a tableros grandes pueden tardar unos segundos adicionales.

## Solución de problemas

### "Error de autenticación"

- Verifica que la API Key y el Token son correctos
- El Token debe corresponder a la misma cuenta que la API Key
- Si revocaste el Token, genera uno nuevo y actualízalo en Frihet

### "No veo todos mis tableros"

- Verifica que tu cuenta tiene acceso a esos tableros en Trello
- Los tableros privados de otros miembros no serán visibles
- Si eres invitado a un tablero, el acceso depende de los permisos del tablero

### "El Token ha expirado"

- Los tokens de Trello no expiran por defecto a menos que los configures así
- Si el token fue revocado manualmente, genera uno nuevo
- Ve a [trello.com/power-ups/admin](https://trello.com/power-ups/admin) para gestionar tokens

### "Quiero desconectar"

1. Ve a **Ajustes** → **Integraciones** → **Trello**
2. Haz clic en **Desconectar**
3. Opcionalmente, revoca el Token desde Trello en **Settings** → **Applications**

## Próximos pasos

- [Conecta Asana como alternativa de gestión de proyectos](./asana)
- [Conecta Notion para documentación](./notion)
- [Automatiza flujos con n8n](./n8n)

---

## UPS
> Path: /integraciones/ups

# UPS

> Integra UPS con Frihet para crear envíos y sincronizar tarifas de transporte.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre UPS y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **UPS**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → UPS
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Upwork
> Path: /integraciones/upwork

# Upwork

> Importa contratos y pagos de Upwork como facturas o gastos en Frihet.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Upwork y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Upwork**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Entrada   | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Upwork
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Wave
> Path: /integraciones/wave-accounting

# Wave

> Conecta Frihet con Wave para exportar facturas y gastos automáticamente.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Wave y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Wave**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección | Frecuencia                    |
| ----- | --------- | ----------------------------- |
| Stub  | Salida    | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Wave
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## WhatsApp Business
> Path: /integraciones/whatsapp

# WhatsApp Business

:::info Próximamente
Esta integración está en desarrollo. Puedes ver su estado en **Ajustes → Integraciones**.
:::

WhatsApp Business es la versión empresarial de WhatsApp, diseñada para que negocios se comuniquen con sus clientes a través del canal de mensajería más utilizado en Europa y Latinoamérica.

## ¿Para qué sirve?

Con WhatsApp Business integrado en Frihet:

- **Enviar facturas por WhatsApp** — Comparte facturas en PDF directamente al WhatsApp de tu cliente desde Frihet
- **Recordatorios de pago** — Envía avisos de facturas pendientes o vencidas por WhatsApp de forma automatizada
- **Comunicación con clientes desde Frihet** — Contacta a tus clientes sin salir de tu ERP, manteniendo el historial centralizado

## Estado

Esta integración aparece en la sección de integraciones de Frihet. La funcionalidad completa está en desarrollo.

---

## Wise
> Path: /integraciones/wise

# Wise

:::tip Disponible
Esta integración está disponible en Frihet. Configúrala en **Settings → Integraciones → Wise**.
:::

Conecta tu cuenta de Wise (anteriormente TransferWise) a Frihet para importar automáticamente tus transferencias y transacciones como gastos. Si trabajas con clientes internacionales o proveedores en distintas divisas, esta integración te ahorra la entrada manual de cada movimiento y mantiene tus gastos actualizados con los tipos de cambio reales que aplicó Wise.

## ¿Para qué sirve?

- **Importar transacciones como gastos** — Cada transferencia y pago realizado desde Wise se importa como un gasto en Frihet con todos los detalles: descripción, importe, fecha y divisa
- **Gestión multidivisa** — Las transacciones en USD, GBP, EUR u otras divisas se registran con su divisa original y el tipo de cambio aplicado
- **Eliminación de entrada manual** — No necesitas copiar datos de Wise a Frihet: importa todo de una vez
- **Visibilidad completa de gastos** — Consolida tus gastos bancarios de Wise con el resto de gastos en Frihet para tener una foto financiera completa

## Requisitos

- Cuenta activa en [Wise](https://wise.com)
- Plan Frihet Pro o Premium
- API Token de Wise (se genera desde la configuración de tu cuenta)

## Cómo conectar

### Paso 1: Obtener tu API Token en Wise

1. Inicia sesión en [wise.com](https://wise.com)
2. Ve a tu perfil y selecciona **Settings** (Configuración)
3. Busca la sección **API tokens**
4. Haz clic en **Add new token** (Añadir nuevo token)
5. Dale un nombre descriptivo, por ejemplo "Frihet ERP"
6. Selecciona los permisos de **Read only** (solo lectura) — es suficiente para importar transacciones
7. Completa la verificación de seguridad (Wise puede pedir confirmación por SMS o email)
8. Copia el token generado. Solo se muestra una vez.

### Paso 2: Configurar en Frihet

1. En Frihet, ve a **Settings → Integraciones**
2. Busca **Wise** y haz clic en el card
3. Pega tu **API Token** en el campo correspondiente
4. Haz clic en **Probar conexión** para verificar que las credenciales son correctas
5. Si la conexión es exitosa, verás la confirmación con los datos de tu cuenta
6. Haz clic en **Guardar**

## Cómo funciona

Frihet se conecta a la API de Wise utilizando tu API Token con autenticación Bearer. Cuando lanzas una importación, Frihet consulta las transacciones de tus cuentas en Wise y las registra como gastos en tu cuenta de Frihet.

La importación es bajo demanda: tú decides cuándo importar. Las transacciones ya importadas se identifican por su ID de Wise y no se duplican en importaciones posteriores.

### Mapeo de datos

| Dato en Wise | Campo en Frihet |
|--------------|-----------------|
| Descripción de la transferencia | Descripción del gasto |
| Importe | Importe del gasto |
| Fecha de la transacción | Fecha del gasto |
| Divisa | Divisa del gasto |
| Referencia | Notas del gasto |

## Casos de uso

### Freelancer con clientes internacionales

Cobras en USD y GBP pero tu contabilidad es en EUR. Cada vez que recibes un pago y haces una conversión en Wise, la comisión y el tipo de cambio se registran automáticamente como gasto en Frihet. Tienes visibilidad total del coste real de tus operaciones internacionales.

### Startup con proveedores en múltiples países

Pagas a proveedores de software, hosting y servicios en distintas divisas a través de Wise. En lugar de registrar cada pago manualmente, importas todas las transacciones a Frihet de una vez y las categorizas.

### Nómada digital

Viajas y pagas con tu tarjeta Wise en distintas divisas. Importas todos los gastos a Frihet para tener un control real de tus costes operativos, sin importar en qué moneda pagaste.

## Solución de problemas

### Error de conexión

- Verifica que el API Token es correcto y no ha caducado
- Comprueba que el token tiene permisos de lectura (Read only)
- Si regeneraste el token en Wise, actualízalo en Frihet — el anterior deja de funcionar

### No se importan transacciones

- Confirma que tienes transacciones en el rango de fechas seleccionado
- Asegúrate de que la cuenta de Wise está activa y verificada
- Solo se importan transacciones completadas, no las pendientes

### Transacciones duplicadas

- No debería ocurrir: Frihet deduplica por ID de transacción de Wise
- Si ocurre, desconecta y reconecta la integración
- Los gastos ya registrados en Frihet no se ven afectados

## Siguientes pasos

- [Conecta Qonto para importar transacciones bancarias europeas](./qonto)
- [Conecta Mercury si usas banca para startups](./mercury)
- [Aprende a categorizar gastos importados](../gastos/categorias)

---

## WooCommerce
> Path: /integraciones/woocommerce

# WooCommerce

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

Conecta tu tienda WooCommerce a Frihet. Los pedidos se sincronizan automáticamente y generan facturas.

## ¿Para qué sirve?

Con WooCommerce integrado:

- **Sync de pedidos** — Nuevos pedidos aparecen en Frihet automáticamente
- **Facturas automáticas** — Se crean sin que hagas nada
- **Datos de cliente** — Nombre, email, dirección del pedido se importan
- **Control de inventario** — Productos sincronizados entre ambas plataformas (opcional)

## Requisitos

- **WordPress con WooCommerce instalado** — Tu tienda online
- **Acceso a WordPress** — Usuario admin o con permisos de plugins
- **Frihet Pro o superior**

## Instalar plugin de conexión

### Paso 1: Descarga el plugin

1. En WordPress, ve a **Plugins** → **Añadir nuevo**
2. Busca **"Frihet WooCommerce"**
3. Haz clic en **Instalar**
4. Luego **Activar**

O descárgalo manualmente desde: `frihet.io/plugins/woocommerce`

### Paso 2: Autoriza la conexión

1. En WordPress, ve a **Ajustes** → **Frihet WooCommerce**
2. Haz clic en **"Conectar con Frihet"**
3. Serás redirigido a Frihet
4. Autoriza el acceso
5. Redirige automáticamente a WordPress

### Paso 3: Configura qué sincronizar

En **Ajustes** → **Frihet WooCommerce**, elige:

- ✅ **Sincronizar pedidos** — Recomendado
- ✅ **Crear facturas automáticas** — Recomendado
- ⚪ **Sincronizar clientes** — Opcional
- ⚪ **Sincronizar inventario** — Solo si lo necesitas

Guarda cambios.

## Cómo funciona el sync

### Nuevo pedido en WooCommerce

```
1. Cliente compra en tu tienda
   ↓
2. WooCommerce recibe el pedido
   ↓
3. Plugin detecta cambio
   ↓
4. Envía datos a Frihet (en tiempo real)
   ↓
5. Frihet crea automáticamente:
   - Cliente (si es nuevo)
   - Factura con los productos del pedido
   ↓
6. La factura aparece en tu listado de Frihet
```

### Datos sincronizados

| Dato | De WooCommerce a Frihet |
|------|-------------------------|
| Número de pedido | Número de factura |
| Productos | Líneas de factura |
| Cantidad | Cantidad |
| Precio | Precio unitario |
| Cliente | Nombre, email, dirección |
| Fecha pedido | Fecha de factura |
| Estado del pedido | Estado de pago |
| IVA (si está configurado) | IVA desglosado |

## Estados de pedido y factura

### WooCommerce → Frihet

| Estado WooCommerce | Estado Frihet |
|-------------------|---------------|
| Pendiente de pago | Pendiente |
| Procesando | Pendiente |
| Completado | Pagada ✅ |
| Cancelado | Cancelada |
| Reembolso | Reembolso parcial |

Si el cliente marca el pedido como "Completado", la factura se marca como pagada automáticamente.

## Ejemplo real

### Cliente compra en tu tienda

Pedido en WooCommerce:
```
Pedido #1234 - 10 feb 2025
- 2x Producto A @ €50 = €100
- 1x Producto B @ €30 = €30
Total: €130 + €27,30 IVA (21%) = €157,30

Cliente: Juan García
Email: juan@example.com
```

### En Frihet automáticamente

Factura creada:
```
Factura #1234
Fecha: 10 feb 2025
Cliente: Juan García
- 2x Producto A @ €50 = €100
- 1x Producto B @ €30 = €30
Subtotal: €130,00
IVA (21%): €27,30
Total: €157,30
Estado: Pagada ✅
```

La factura aparece en tu listado. **Sin hacer nada.**

## Configuraciones avanzadas

### Mapeo de categorías de producto

Si quieres que los productos de WooCommerce se creen como productos en Frihet:

1. Ve a **Ajustes** → **Frihet WooCommerce**
2. Activa **"Sincronizar productos"**
3. Elige si sincronizar inventario (stock)

Esto es útil si quieres reutilizar esos productos en presupuestos futuros.

### Formato de factura personalizado

Por defecto, Frihet usa su formato. Puedes personalizar:

1. En **Frihet**, ve a **Ajustes** → **Facturación**
2. Modifica el template de factura
3. Los nuevos pedidos de WooCommerce usan ese template

### Correo al cliente

Cuando se crea una factura desde WooCommerce:

- ✅ WooCommerce envía email de confirmación del pedido
- ✅ Frihet puede enviar email de factura (si lo activas)

Ambos emails irán al cliente. Puedes desactivar uno en Ajustes para evitar duplicados.

## Prueba la integración

### Test pedido

1. Ve a tu tienda WooCommerce
2. Haz un pedido de prueba (como cliente)
3. En Frihet, ve a **Facturación** → **Facturas**
4. Deberías ver la factura creada automáticamente en los últimos 30 segundos

Si no aparece:

- Espera 1 minuto (a veces tarda)
- Verifica que WooCommerce → Frihet muestra "Conectado"
- Revisa logs de error en **Ajustes** → **Integraciones** → **Logs**

## Reembolsos y cancelaciones

### Cliente cancela pedido en WooCommerce

1. El estado cambia a "Cancelado"
2. Frihet detecta el cambio
3. La factura se marca como "Cancelada"

### Cliente solicita reembolso

Si procesas un reembolso en WooCommerce:

1. Se registra en el pedido
2. Frihet crea automáticamente una **nota de crédito** (si lo activas en Ajustes)
3. O puedes crear manualmente la nota de crédito en Frihet

## Limitaciones

Frihet → WooCommerce:

- **No sincroniza facturas de Frihet a WooCommerce** — Solo WooCommerce → Frihet
- **Ediciones en Frihet no afectan WooCommerce** — Si cambias el precio de una factura en Frihet, WooCommerce no se actualiza
- **Productos nuevos en Frihet no van a WooCommerce** — Solo se sincronizan existentes

## Troubleshooting

### "No veo las facturas de WooCommerce en Frihet"

- Verifica que la integración está conectada ✅
- El pedido debe estar en estado "Procesando" o superior
- Espera 1-2 minutos después de crear el pedido
- Recarga Frihet (F5)

### "¿Por qué se duplican emails?"

- WooCommerce envía email de pedido
- Frihet también puede enviar email de factura
- Solución: Desactiva emails de Frihet para pedidos de WooCommerce en **Ajustes** → **Email**

### "El cliente no coincide entre WooCommerce y Frihet"

- WooCommerce creó un cliente nuevo en Frihet
- Si el cliente ya existía, podrían haber quedado duplicados
- Solución: Fusiona clientes manualmente en Frihet

### "¿Puedo desconectar sin perder facturas?"

Sí. Las facturas ya creadas quedan en Frihet. La desconexión solo:

- Detiene nuevos syncs
- Los pedidos nuevos en WooCommerce no se sincronizan más

Para desconectar:

1. Ve a **Ajustes** → **Integraciones**
2. Busca **WooCommerce**
3. Haz clic en **Desconectar**
4. Confirma

:::tip Webhooks para e-commerce
Frihet emite [webhooks](/desarrolladores/webhooks) en eventos como `invoice.created` y `invoice.paid`. Usalo para sincronizar tu tienda WooCommerce con sistemas externos o disparar automatizaciones cuando se generan facturas desde pedidos.
:::

## Proximos pasos

- [Conecta Shopify si tienes tienda alli tambien](./shopify)
- [Automatiza flujos con n8n](./n8n)

---

**Anterior:** [Stripe Connect](./stripe-connect)

---

## Xero
> Path: /integraciones/xero

# Xero

> Exporta facturas, gastos y pagos de Frihet a Xero para mantener tu contabilidad sincronizada.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Xero y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Xero**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Xero
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Zapier
> Path: /integraciones/zapier

# Zapier

:::info Beta pública — disponible ahora
La app nativa de Frihet está disponible en Zapier como **Beta pública** desde el 26 de junio de 2026. Puedes usarla hoy en todos los planes Pro.
[Ver en Zapier →](https://zapier.com/apps/frihet/integrations)
:::

Frihet tiene una integración nativa oficial en Zapier. Sin webhooks manuales, sin HTTP requests: conecta Frihet con más de **7.000+ apps** desde la interfaz de Zapier con autenticación por API key.

## ¿Para qué sirve?

Con la app de Frihet en Zapier puedes:

- **Reaccionar a eventos en tiempo real** — Factura pagada, nuevo cliente, presupuesto aceptado...
- **Crear y actualizar datos** — Facturas, presupuestos, clientes, gastos, productos desde cualquier trigger externo
- **Buscar antes de crear** — Encuentra un cliente o factura existente antes de duplicar
- **Conectar con 7.000+ apps** — Slack, HubSpot, Google Sheets, Gmail, Notion, Airtable...
- **Sin código** — Configura desde la interfaz visual de Zapier

---

## Autenticación — API Key

Frihet en Zapier usa autenticación por **API Key** (cabecera `X-API-Key`). Necesitas generar una clave en la app antes de conectar.

### Generar tu API Key en Frihet

1. Accede a [app.frihet.io](https://app.frihet.io)
2. Ve a **Configuración → Desarrolladores → API Keys**
3. Haz clic en **"Nueva clave de API"**
4. Asigna un nombre descriptivo (p. ej. `zapier-produccion`)
5. Copia la clave — **solo se muestra una vez**; guárdala en lugar seguro

:::warning La clave solo se muestra una vez
Si la pierdes, deberás revocarla y crear una nueva. Consulta [Claves de API](/configuracion/api-keys) para gestión completa.
:::

### Conectar en Zapier

1. En Zapier, al añadir Frihet a un Zap, haz clic en **"Sign in"**
2. Pega tu API Key cuando te la pidan
3. Zapier verificará la conexión automáticamente

---

## Operaciones disponibles (43)

La app de Frihet en Zapier registra **43 operaciones**: 14 triggers, 21 acciones y 8 búsquedas.

### Triggers (14)

Se activan automáticamente cuando ocurren eventos en tu cuenta de Frihet.

| Trigger             | Cuándo dispara                              |
| ------------------- | ------------------------------------------- |
| **New Invoice**     | Se crea una nueva factura                   |
| **Invoice Paid**    | Una factura se marca como pagada            |
| **Invoice Updated** | Se actualiza cualquier campo de una factura |
| **Invoice Overdue** | Una factura supera su fecha de vencimiento  |
| **New Expense**     | Se registra un nuevo gasto                  |
| **Expense Updated** | Se actualiza un gasto existente             |
| **New Quote**       | Se crea un nuevo presupuesto                |
| **Quote Updated**   | Se actualiza un presupuesto                 |
| **Quote Accepted**  | Un cliente acepta un presupuesto            |
| **Quote Rejected**  | Un cliente rechaza un presupuesto           |
| **New Client**      | Se crea un nuevo cliente                    |
| **Client Updated**  | Se actualizan los datos de un cliente       |
| **New Product**     | Se añade un producto al catálogo            |
| **Product Updated** | Se actualiza un producto                    |

### Acciones (21)

Crean o modifican datos en Frihet desde cualquier trigger de Zapier.

| Acción                  | Qué hace                                           |
| ----------------------- | -------------------------------------------------- |
| **Create Invoice**      | Crea una nueva factura                             |
| **Update Invoice**      | Actualiza una factura existente                    |
| **Mark Invoice Paid**   | Marca una factura como pagada                      |
| **Send Invoice Email**  | Envía la factura por email al cliente              |
| **Create Credit Note**  | Genera una nota de crédito (rectificativa)         |
| **Apply Late Fee**      | Aplica un recargo por mora                         |
| **Create Quote**        | Crea un nuevo presupuesto                          |
| **Send Quote Email**    | Envía el presupuesto por email al cliente          |
| **Create Deposit**      | Registra un depósito o anticipo                    |
| **Apply Deposit**       | Aplica un depósito a una factura                   |
| **Refund Deposit**      | Devuelve un depósito                               |
| **Create Client**       | Crea un nuevo cliente                              |
| **Update Client**       | Actualiza los datos de un cliente                  |
| **Add Client Activity** | Registra una actividad en el historial del cliente |
| **Add Client Contact**  | Añade un contacto al cliente                       |
| **Add Client Note**     | Añade una nota al cliente                          |
| **Create Expense**      | Registra un nuevo gasto                            |
| **Update Expense**      | Actualiza un gasto existente                       |
| **Create Product**      | Añade un producto al catálogo                      |
| **Update Product**      | Actualiza un producto                              |
| **Create Vendor**       | Crea un nuevo proveedor                            |

### Búsquedas (8)

Encuentran registros existentes en Frihet para usarlos en pasos siguientes.

| Búsqueda                  | Qué encuentra                                  |
| ------------------------- | ---------------------------------------------- |
| **Find Invoice**          | Busca una factura por número, cliente o estado |
| **Find Expense**          | Busca un gasto por categoría o proveedor       |
| **Find Client**           | Busca un cliente por nombre, email o NIF       |
| **Find Product**          | Busca un producto por nombre o referencia      |
| **Find Quote**            | Busca un presupuesto por número o cliente      |
| **Find Vendor**           | Busca un proveedor por nombre o NIF            |
| **Find Deposit**          | Busca un depósito por cliente o estado         |
| **Get Financial Summary** | Obtiene un resumen financiero del periodo      |

---

## Configurar tu primer Zap

### Paso 1 — Encuentra Frihet en Zapier

1. Abre [zapier.com/apps/frihet/integrations](https://zapier.com/apps/frihet/integrations)
2. O desde cualquier Zap: busca **"Frihet"** en el selector de app

### Paso 2 — Conecta tu cuenta

1. Selecciona un trigger o acción de Frihet
2. Haz clic en **"Sign in to Frihet"**
3. Pega tu API Key ([Cómo generarla ↑](#autenticación--api-key))
4. Confirma con **"Yes, Continue"**

### Paso 3 — Configura el trigger

1. Selecciona el evento (p. ej. **Invoice Paid**)
2. Haz clic en **"Test trigger"** — Zapier carga un ejemplo real de tu cuenta
3. Confirma los datos y continúa

### Paso 4 — Añade una acción

1. Selecciona la app destino (Slack, Google Sheets, HubSpot...)
2. Mapea los campos de Frihet a los campos de la app
3. Prueba la acción
4. Activa el Zap

---

## Ejemplos de Zaps

### Factura pagada → Notificación en Slack

Cuando un cliente paga, notifica al equipo con el detalle.

```
Trigger:  Frihet — Invoice Paid
Acción:   Slack — Send Channel Message
Mensaje:  "Cobrado: {{invoice_number}} · {{client_name}} · {{amount}} EUR"
```

[Empezar este Zap →](https://zapier.com/webintent/create-zap?steps[0][app]=App237629CLIAPI@2.1.0&steps[0][action]=invoice_paid)

---

### Nuevo cliente → Crear contacto en HubSpot

Sincroniza automáticamente nuevos clientes a tu CRM.

```
Trigger:  Frihet — New Client
Acción:   HubSpot — Create Contact
Campos:   email, nombre, teléfono, NIF
```

[Empezar este Zap →](https://zapier.com/webintent/create-zap?steps[0][app]=App237629CLIAPI@2.1.0&steps[0][action]=client_created)

---

### Nueva factura → Fila en Google Sheets

Lleva un registro de todas tus facturas en una hoja de cálculo.

```
Trigger:  Frihet — New Invoice
Acción:   Google Sheets — Create Spreadsheet Row
Columnas: número, cliente, importe, IVA, vencimiento, estado
```

[Empezar este Zap →](https://zapier.com/webintent/create-zap?steps[0][app]=App237629CLIAPI@2.1.0&steps[0][action]=invoice_created)

---

### Presupuesto aceptado → Crear factura automáticamente

Convierte presupuestos aceptados en facturas sin intervención manual.

```
Trigger:  Frihet — Quote Accepted
Búsqueda: Frihet — Find Quote (para obtener líneas de detalle)
Acción:   Frihet — Create Invoice
Campos:   cliente, líneas, vencimiento desde presupuesto aceptado
```

[Empezar este Zap →](https://zapier.com/webintent/create-zap?steps[0][app]=App237629CLIAPI@2.1.0&steps[0][action]=quote_accepted)

---

### Nuevo gasto → Tarea de revisión en Notion

Crea una tarea para revisar gastos por encima de un umbral.

```
Trigger:  Frihet — New Expense
Filtro:   amount > 500
Acción:   Notion — Create Page en base de datos "Gastos a revisar"
```

[Empezar este Zap →](https://zapier.com/webintent/create-zap?steps[0][app]=App237629CLIAPI@2.1.0&steps[0][action]=expense_created)

---

## Empieza ahora

Explora todas las integraciones disponibles y crea tu primer Zap:

**[Ver Frihet en Zapier →](https://zapier.com/apps/frihet/integrations)**

---

## Ver también

- [Claves de API](/configuracion/api-keys) — Crea y gestiona tus claves de acceso
- [API REST](/desarrolladores/api-rest) — Acceso programático completo
- [Webhooks](/desarrolladores/webhooks) — 27 eventos con firma HMAC-SHA256
- [n8n](/integraciones/n8n) — Alternativa self-hosted con nodo oficial

---

**Anterior:** [Revolut Business](./revolut)

---

## Zoho Books
> Path: /integraciones/zoho-books

# Zoho Books

> Sincroniza facturas y gastos entre Frihet y Zoho Books.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Zoho Books y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Zoho Books**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Zoho Books
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Zoho CRM
> Path: /integraciones/zoho-crm

# Zoho CRM

> Conecta Zoho CRM con Frihet para sincronizar contactos y convertir negocios en facturas.

<!-- AUTO-STUB-INT 2026-05-06 -->

## Qué hace esta integración

Stub: explica los flujos de datos principales entre Zoho CRM y Frihet — qué información entra, qué información sale, y cómo se mantiene sincronizada.

## Conectar

1. Settings → Integraciones → buscar **Zoho CRM**
2. Click **Conectar** → pega tu API key
3. Selecciona qué se sincroniza (productos, clientes, facturas, pagos, etc.)

## Qué se sincroniza

| Datos | Dirección     | Frecuencia                    |
| ----- | ------------- | ----------------------------- |
| Stub  | Bidireccional | Tiempo real / Diaria / Manual |

## Limitaciones

Stub: límites conocidos, requisitos de plan, límites de tasa de la API si aplica.

## Solución de problemas

- **Error de conexión**: revisa las credenciales en Settings → Integraciones → Zoho CRM
- **Datos no se sincronizan**: verifica los permisos concedidos
- Más ayuda: [contacta soporte](mailto:soporte@frihet.io)

## Recursos

- [API reference](/desarrolladores/api-rest)
- [API reference](/desarrolladores/api-rest)

---

## Consentimiento de cookies
> Path: /legal/consentimiento-cookies

# Consentimiento de cookies

Frihet muestra un banner de consentimiento de cookies conforme al RGPD la primera vez que entras a la aplicación o al sitio web. El banner permite aceptar, rechazar o configurar cada categoría de cookies por separado, y registra la versión de la política aceptada para auditoría.

## Cómo funciona

Cuando un visitante o usuario abre `app.frihet.io` por primera vez, aparece un banner con tres acciones: **Aceptar todas**, **Rechazar todas** y **Configurar**. La opción de configuración despliega las categorías disponibles, cada una con un selector individual que se puede activar o desactivar de forma independiente.

Las categorías típicas incluyen cookies estrictamente necesarias (siempre activas, sin opción de desactivar), analítica y producto. Las cookies estrictamente necesarias mantienen tu sesión activa y no requieren consentimiento. El resto solo se cargan después de aceptar la categoría correspondiente.

La elección se guarda en tu navegador junto con la versión de la política de cookies vigente en ese momento. Si la política cambia y se publica una versión nueva, el banner vuelve a aparecer para pedirte un consentimiento actualizado, sin perder tus preferencias previas.

Puedes revisar y modificar tu consentimiento en cualquier momento desde el enlace **Cookies** del pie de página o desde **Configuración → Privacidad**. Cambiar las preferencias toma efecto de forma inmediata: las cookies de categorías rechazadas se eliminan y las herramientas asociadas dejan de cargarse.

## Configuración

El banner está activo por defecto en todas las cuentas y no requiere configuración por parte del usuario. El equipo de Frihet gestiona las categorías disponibles, los textos legales y la versión vigente desde la configuración global del producto.

Para auditar el consentimiento de tu propia cuenta, accede a **Configuración → Privacidad** donde encontrarás la fecha de tu último consentimiento, la versión aceptada y un botón para revocar o reconfigurar.

## Ver también

- [Política de privacidad](./privacidad)
- [Términos del servicio](./terminos)
- [Seguridad de la cuenta](../configuracion/seguridad)

---

## Política de privacidad
> Path: /legal/privacidad

# Política de Privacidad

**Última actualización**: febrero 2026

## 1. Responsable del Tratamiento

El responsable del tratamiento de tus datos personales es **Victor Berthelius**, con NIF **54052380B**, actuando como profesional autónomo bajo la marca comercial **Frihet**, con domicilio fiscal en C/ Cervera n9, Radazul 38109, S/C de Tenerife.

Puedes contactar en materia de protección de datos a través del correo electrónico **support@frihet.io**.

## 2. Datos que Recopilamos

Recopilamos los siguientes tipos de datos:

- **Datos de cuenta**: nombre, dirección de correo electrónico, contraseña (cifrada), nombre de empresa y datos fiscales que proporcionas al registrarte.
- **Datos de uso**: información sobre cómo utilizas el Servicio, incluyendo páginas visitadas, funcionalidades utilizadas, frecuencia de uso y preferencias de configuración.
- **Datos de pago**: los datos de tu tarjeta de crédito o débito son procesados directamente por Stripe; Frihet no almacena los números completos de tarjeta en sus servidores.
- **Datos técnicos**: dirección IP, tipo de navegador, sistema operativo, identificadores de dispositivo y datos de conexión.

## 3. Base Legal del Tratamiento

Tratamos tus datos personales en base a las siguientes bases jurídicas:

- **Ejecución contractual** (art. 6.1.b RGPD): el tratamiento es necesario para prestar el Servicio que has contratado.
- **Consentimiento** (art. 6.1.a RGPD): para el envío de comunicaciones comerciales y newsletters, que puedes retirar en cualquier momento.
- **Interés legítimo** (art. 6.1.f RGPD): para la mejora del Servicio, la prevención del fraude y la seguridad de la plataforma.
- **Obligación legal** (art. 6.1.c RGPD): para el cumplimiento de obligaciones fiscales y legales aplicables.

## 4. Finalidades del Tratamiento

Utilizamos tus datos para las siguientes finalidades:

- Prestación y gestión del Servicio contratado
- Procesamiento de pagos y facturación
- Comunicación contigo sobre tu cuenta, actualizaciones del Servicio y soporte técnico
- Envío de comunicaciones comerciales (previo consentimiento)
- Mejora y personalización de la experiencia de usuario
- Análisis estadístico y agregado del uso del Servicio
- Cumplimiento de obligaciones legales y fiscales
- Detección y prevención de fraude y abusos

## 5. Destinatarios de los Datos

Compartimos tus datos únicamente con los siguientes proveedores de servicios, necesarios para la prestación del Servicio:

| Servicio | Propósito | Sede | Garantía |
|----------|-----------|------|----------|
| **Stripe** | Procesamiento de pagos | EE.UU. | DPF |
| **Firebase / Google Cloud** | Infraestructura y autenticación | EE.UU. | DPF |
| **Resend** | Correos electrónicos transaccionales | EE.UU. | DPA |
| **Google Analytics 4** | Analítica web (solo con consentimiento) | EE.UU. | DPF |
| **Vercel Inc.** | Alojamiento web y analítica sin cookies | EE.UU. | DPA |
| **PostHog** | Analítica de producto (solo con consentimiento) | EE.UU. | DPA |
| **Umami** | Analítica web (autoalojado en la UE, sin cookies) | UE | — |
| **Cloudflare** | CDN y seguridad | Global | DPA |

Todos los proveedores han sido seleccionados garantizando que ofrecen medidas de seguridad adecuadas y cumplen con la normativa de protección de datos aplicable.

**No vendemos ni compartimos tus datos** con agencias publicitarias, brokers de datos ni terceros comerciales.

## 6. Transferencias Internacionales

Algunos de nuestros proveedores de servicios se encuentran fuera del Espacio Económico Europeo, concretamente en Estados Unidos. Estas transferencias se realizan al amparo de:

- El Marco de Privacidad de Datos UE-EE.UU. (Data Privacy Framework) para proveedores adheridos
- Cláusulas contractuales tipo aprobadas por la Comisión Europea
- Decisiones de adecuación de la Comisión Europea, cuando existan

Puedes solicitar información adicional sobre las garantías aplicables a estas transferencias escribiendo a **support@frihet.io**.

## 7. Plazo de Conservación

| Dato | Retención | Razón |
|------|-----------|-------|
| Datos de cuenta y contenido | Vigencia de la cuenta + 30 días | Permitir exportación |
| Datos de facturación | 4 años | Ley General Tributaria |
| Datos de uso y analítica | Sin límite (anonimizados y agregados) | Mejora del servicio |
| Comunicaciones comerciales | Hasta retirada del consentimiento | RGPD art. 6.1.a |

Cuando canceles tu cuenta:
- Tus datos se conservan 30 días para permitir la exportación
- Datos fiscales se retienen el período legalmente exigido
- Eliminación física tras el período de conservación

## 8. Tus Derechos (ARCO-POL)

De conformidad con el RGPD y la LOPDGDD, tienes los siguientes derechos:

- **Acceso**: conocer qué datos personales tratamos sobre ti.
- **Rectificación**: corregir datos inexactos o incompletos.
- **Supresión** (derecho al olvido): solicitar la eliminación de tus datos cuando ya no sean necesarios.
- **Oposición**: oponerte al tratamiento de tus datos en determinadas circunstancias.
- **Portabilidad**: recibir tus datos en un formato estructurado y de uso común (CSV, JSON).
- **Limitación**: solicitar la limitación del tratamiento en ciertos supuestos.

Puedes ejercer estos derechos enviando un correo a **support@frihet.io**, acompañando copia de tu documento de identidad. Respondemos en un plazo máximo de 30 días.

También tienes derecho a presentar una reclamación ante la [Agencia Española de Protección de Datos](https://www.aepd.es) (AEPD).

## 9. Cookies y Analítica

En **frihet.io** utilizamos las siguientes herramientas de analítica:

- **Umami** (autoalojado en la UE, sin cookies, sin datos personales identificables, conforme al RGPD sin necesidad de consentimiento)
- **Google Analytics 4** (utiliza cookies de seguimiento, activado únicamente tras el consentimiento explícito del usuario a través de nuestro banner de cookies)
- **PostHog** (analítica de producto, activado únicamente tras consentimiento)
- **Vercel Analytics y SpeedInsights** (sin cookies, métricas de rendimiento anónimas)

Al visitar nuestro sitio web por primera vez, se muestra un banner de consentimiento de cookies. Las herramientas que utilizan cookies (GA4, PostHog) solo se activan si el usuario acepta expresamente. Puedes retirar tu consentimiento en cualquier momento desde la configuración de cookies.

En nuestra aplicación web (**app.frihet.io**), utilizamos almacenamiento local (localStorage) para guardar tus preferencias de idioma y sesión, lo cual es estrictamente necesario para el funcionamiento del Servicio.

## 10. Seguridad

Implementamos las siguientes medidas de seguridad:

- Encriptación en tránsito (TLS/SSL)
- Encriptación en reposo (AES-256)
- Acceso limitado basado en roles
- Auditoría de cambios (registro inmutable)
- Backups cifrados diarios
- Monitoreo de seguridad 24/7
- Validación con Cloudflare Turnstile en login

Ningún sistema es perfecto. Si detectas una vulnerabilidad, repórtala a **support@frihet.io**.

## 11. Contacto del Responsable del Tratamiento

Para cualquier cuestión relacionada con el tratamiento de tus datos personales o el ejercicio de tus derechos:

**Victor Berthelius**
C/ Cervera n9, Radazul 38109, S/C de Tenerife
**support@frihet.io**

Nos comprometemos a atender tus solicitudes con la mayor diligencia y transparencia.

---

**Versión**: 2.0
**Fecha de efectividad**: febrero 2026

---

## Términos de uso
> Path: /legal/terminos

# Términos y Condiciones

**Última actualización**: febrero 2026

## 1. Definiciones

A los efectos de estos Términos y Condiciones:

- **"Frihet" o "el Servicio"**: la plataforma de software de gestión empresarial (ERP) proporcionada como servicio (SaaS) por Victor Berthelius, profesional autónomo, bajo la marca comercial Frihet.
- **"Usuario"**: toda persona física o jurídica que acceda, se registre o utilice el Servicio.
- **"Cuenta"**: el espacio personal del Usuario dentro de la plataforma.
- **"Plan"**: la modalidad de suscripción contratada (Free, Pro, Premium o Enterprise).
- **"Contenido del Usuario"**: todos los datos, documentos, facturas y demás información introducida por el Usuario en la plataforma.

## 2. Descripción del Servicio

Frihet es una plataforma de gestión empresarial en la nube diseñada para autónomos, freelancers y pequeñas y medianas empresas. El Servicio incluye, entre otras funcionalidades:

- Creación y gestión de facturas y presupuestos
- Gestión de gastos con reconocimiento óptico de caracteres (OCR)
- Panel de control financiero
- CRM básico
- Conciliación bancaria
- Exportación contable
- Automatizaciones
- Asistente de inteligencia artificial

Las funcionalidades disponibles dependen del Plan contratado por el Usuario.

## 3. Registro y Cuenta de Usuario

Para utilizar el Servicio es necesario crear una Cuenta proporcionando información veraz, completa y actualizada. El Usuario es el único responsable de mantener la confidencialidad de sus credenciales de acceso y de todas las actividades que se realicen bajo su Cuenta.

El Usuario se compromete a notificar inmediatamente a Frihet cualquier uso no autorizado de su Cuenta. Frihet se reserva el derecho de suspender o cancelar Cuentas que contengan información falsa o que infrinjan estos Términos.

## 4. Planes y Precios

Frihet ofrece los siguientes planes:

| Plan | Precio mensual | Precio anual |
|------|---------------|-------------|
| **Free** | Gratuito (con limitaciones) | — |
| **Pro** | 9 EUR/mes | 90 EUR/año |
| **Premium** | 29 EUR/mes | 290 EUR/año |
| **Enterprise** | Precio personalizado | Precio personalizado |

Los precios indicados no incluyen impuestos aplicables (IVA). Frihet se reserva el derecho de modificar los precios previa notificación al Usuario con al menos 30 días de antelación. Los cambios de precio se aplicarán en el siguiente periodo de facturación.

## 5. Facturación y Pagos

Los pagos se procesan de forma segura a través de **Stripe**. Las suscripciones se facturan de forma recurrente (mensual o anualmente) según el Plan seleccionado.

El Usuario autoriza a Frihet a realizar los cargos correspondientes en el método de pago registrado. En caso de impago, Frihet podrá suspender el acceso al Servicio tras un periodo de gracia de 7 días naturales.

Existe un plan gratuito con uso limitado disponible de forma indefinida.

## 6. Uso Aceptable

El Usuario se compromete a utilizar el Servicio de conformidad con la legislación vigente, estos Términos y la buena fe. Queda prohibido:

- Utilizar el Servicio para actividades ilegales o fraudulentas
- Intentar acceder a datos de otros usuarios sin autorización
- Realizar ingeniería inversa, descompilar o desensamblar cualquier parte del Servicio
- Utilizar el Servicio para enviar spam o contenido malicioso
- Sobrecargar intencionadamente la infraestructura del Servicio
- Revender o redistribuir el Servicio sin autorización expresa de Frihet

## 7. Propiedad Intelectual

El Servicio, incluyendo su código fuente, diseño, interfaz, logotipos, textos y demás elementos, es propiedad exclusiva de Victor Berthelius o de sus licenciantes, y está protegido por las leyes de propiedad intelectual e industrial aplicables.

El Usuario conserva todos los derechos sobre el Contenido del Usuario. Al utilizar el Servicio, el Usuario otorga a Frihet una licencia limitada, no exclusiva y revocable para procesar dicho contenido únicamente con el fin de prestar el Servicio.

## 8. Limitación de Responsabilidad

Frihet proporciona el Servicio "tal cual" y "según disponibilidad". En la máxima medida permitida por la ley, Frihet no será responsable de:

- Daños indirectos, incidentales, especiales, consecuentes o punitivos
- Pérdida de beneficios, datos o ingresos
- Interrupciones del servicio causadas por factores fuera de su control razonable

La responsabilidad total acumulada de Frihet no excederá, en ningún caso, el importe total pagado por el Usuario durante los 12 meses anteriores al evento que genere la reclamación.

Frihet no sustituye el asesoramiento fiscal o contable profesional.

## 9. Cancelación y Reembolsos

El Usuario puede cancelar su suscripción en cualquier momento desde el panel de facturación de su Cuenta. La cancelación será efectiva al final del periodo de facturación en curso, manteniendo el acceso al Servicio hasta dicha fecha.

No se realizarán reembolsos por periodos parciales ya facturados.

Tras la cancelación, el Usuario dispondrá de 30 días para exportar sus datos antes de que estos sean eliminados de nuestros sistemas. En el plan Free, la Cuenta permanecerá activa con las limitaciones propias de dicho plan.

## 10. Modificaciones de los Términos

Frihet se reserva el derecho de modificar estos Términos y Condiciones. Cualquier modificación sustancial será notificada al Usuario con al menos 30 días de antelación a través del correo electrónico asociado a su Cuenta.

El uso continuado del Servicio tras la entrada en vigor de las modificaciones implicará la aceptación de los nuevos Términos. Si el Usuario no está de acuerdo con las modificaciones, podrá cancelar su suscripción antes de que entren en vigor.

## 11. Ley Aplicable y Jurisdicción

Estos Términos y Condiciones se regirán e interpretarán de acuerdo con la legislación española. Para la resolución de cualquier controversia derivada de la interpretación o el cumplimiento de estos Términos, las partes se someten a los Juzgados y Tribunales de la ciudad de Madrid, sin perjuicio de los derechos que asistan al Usuario como consumidor conforme a la normativa vigente.

## Contacto

Para cualquier cuestión relacionada con estos Términos:

**Victor Berthelius**
C/ Cervera n9, Radazul 38109, S/C de Tenerife
**support@frihet.io**

---

**Versión**: 2.0
**Fecha de efectividad**: febrero 2026

---

## TicketBAI
> Path: /legal/ticketbai

# TicketBAI

TicketBAI es el sistema de facturación electrónica obligatorio en la Comunidad Autónoma de Euskadi (Álava, Bizkaia, Gipuzkoa).

:::info Relación con VeriFactu
TicketBAI es un sistema **distinto** de [VeriFactu](/cumplimiento/verifactu). VeriFactu aplica en territorio común (toda España excepto País Vasco y Navarra). Son mutuamente excluyentes: si operas en Euskadi usas TicketBAI, si operas en territorio común usas VeriFactu. Frihet implementa VeriFactu de forma completa. El soporte nativo de TicketBAI está pendiente.
:::

## Qué es TicketBAI

TicketBAI obliga a los contribuyentes de Euskadi a:

- Emitir facturas con registro inmediato
- Firmar cada factura con certificado digital (XAdES)
- Remitir los datos a la Hacienda Foral correspondiente
- Mantener un registro auditado e inmutable de todas las operaciones

### Obligados

- Empresas y profesionales radicados en Euskadi
- Que realizan operaciones sujetas a IVA
- Facturación de cualquier importe (sin límite mínimo)

### Plazos

| Territorio | Obligatorio desde |
|-----------|-------------------|
| Álava | Diciembre 2022 |
| Gipuzkoa | Junio 2023 |
| Bizkaia | Enero 2026 |

## Diferencias con VeriFactu

| Aspecto | VeriFactu | TicketBAI |
|---------|-----------|-----------|
| Ámbito territorial | Territorio común (toda España) | Solo País Vasco |
| Cadena de hash | Una por contribuyente | Flexible (por POS, tienda o contribuyente) |
| Firma digital | En el envío a AEAT | XAdES obligatoria en cada XML |
| Esquemas XML | Único nacional | Uno por cada Diputación Foral |
| Modo incidencia | Envío posterior al recuperar conexión | Notificación por email a Hacienda |
| Normativa | RD 1007/2023 | Decreto 305/2022 y equivalentes forales |

## Estado en Frihet

Frihet comparte con TicketBAI la base técnica de [inmutabilidad y registro](/cumplimiento/inmutabilidad) que ya está implementada:

- ✓ Cadena de hash SHA-256 inmutable
- ✓ Numeración secuencial sin saltos (server-side)
- ✓ Registro de auditoría automático
- ✓ Campos bloqueados tras emisión
- ✓ Soft delete (cancelación en lugar de eliminación)
- ✓ Facturas rectificativas con tipos R1-R5

Lo que falta para soporte nativo de TicketBAI:

- Firma XAdES por factura (requiere certificado de dispositivo)
- Generación de XML según esquemas de cada Diputación Foral
- Envío a las APIs de cada Hacienda Foral
- Adaptación del QR al formato TicketBAI

### Alternativa actual

Si operas en Euskadi, puedes usar Frihet para la gestión de facturas y exportar los datos mediante el [libro registro](/cumplimiento/libro-registro) para remitirlos a través de herramientas certificadas por tu Hacienda Foral.

## Preguntas frecuentes

### ¿Tengo que usar TicketBAI?

Si estás en Euskadi y realizas operaciones sujetas a IVA, sí. Consulta con tu asesor para confirmar si te aplica.

### ¿Puedo modificar una factura emitida?

No. El registro es inmutable por ley. Si necesitas corregir una factura, crea una [factura rectificativa](/facturacion/abonos).

### ¿TicketBAI y VeriFactu son compatibles?

No se aplican simultáneamente. Depende de dónde esté radicada tu empresa. Si operas en territorio común, se aplica VeriFactu. Si operas en Euskadi, se aplica TicketBAI.

## Recursos externos

- [Portal TicketBAI Gipuzkoa](https://ticketbai.gipuzkoailan.eus)
- [Portal TicketBAI Bizkaia (Batuz)](https://www.batuz.eus)
- [Portal TicketBAI Álava](https://web.araba.eus/es/hacienda/ticketbai)

---

**Referencia normativa:** Decreto 305/2022 de Hacienda Vasca y equivalentes forales

---

## Atajos de teclado
> Path: /primeros-pasos/atajos-teclado

# Atajos de teclado

Frihet está diseñado para quien no quiere dejar el teclado. Memoriza estos atajos y ganarás horas de productividad cada mes.

## Atajos universales

| Atajo | Acción |
|-------|--------|
| `Cmd+K` | Abre la **Paleta de Comandos** — busca cualquier acción o documento |
| `Cmd+/` | Muestra esta página de **Ayuda de atajos** |
| `Esc` | Cierra diálogos, modales, y paletas |

---

## Navegación por secciones (G-sequences)

Frihet usa un sistema de **G-sequences**: presiona `G`, luego dentro de **800ms** presiona una segunda tecla.

### Cómo funcionan

1. Presiona `G` (aparecerá un indicador visual)
2. Dentro de 800ms, presiona la segunda tecla
3. Frihet te lleva a esa sección

Ejemplo: para ir a Dashboard, presiona `G` y luego `D` rápidamente.

### Lista de atajos G-sequences

| Atajo | Sección |
|-------|---------|
| `G` → `D` | **Dashboard** — resumen de ingresos, gastos, próximas facturas |
| `G` → `F` | **Facturas** — todas tus facturas, presupuestos emitidos |
| `G` → `Q` | **Presupuestos** — presupuestos no convertidos a factura |
| `G` → `E` | **Gastos** — registro y categorización de gastos |
| `G` → `P` | **Productos** — catálogo de artículos y servicios |
| `G` → `T` | **Calendario Fiscal** — fechas límite de impuestos (trimestral, anual) |
| `G` → `C` | **Contactos** — gestión de clientes, proveedores, personal |
| `G` → `S` | **Ajustes** — configuración de empresa, impuestos, integraciones |

---

## Dentro de la Paleta de Comandos (`Cmd+K`)

Abre `Cmd+K` y empieza a escribir:

- `new invoice` — Crea una factura nueva
- `new budget` — Crea un presupuesto
- `new expense` — Registra un gasto
- `new product` — Añade artículo al catálogo
- `new contact` — Crea un cliente o proveedor
- `search invoices` — Busca una factura por número, cliente, fecha
- `search expenses` — Busca gastos
- `search products` — Busca en tu catálogo
- `settings` — Abre configuración

También puedes escribir en lenguaje natural (si tienes el asistente IA activo):
- `crea factura para juan por 500` — Entiende intención, busca cliente, crea documento
- `gasto de transporte hoy 50 euros` — Registra un gasto categorizado
- `nuevo cliente acme corp` — Crea contacto

---

## Dentro de un documento (factura, presupuesto, etc.)

| Atajo | Acción |
|-------|--------|
| `Cmd+S` | **Guardar** — guarda los cambios sin cerrar |
| `Cmd+Enter` | **Enviar** — abre diálogo para enviar por email |
| `Cmd+P` | **Vista previa** — genera y muestra PDF |
| `Tab` | Siguiente campo — navega por el formulario |
| `Shift+Tab` | Campo anterior — vuelve atrás |

---

## En listas (facturas, gastos, contactos)

| Atajo | Acción |
|-------|--------|
| `/` | Abre filtro rápido — escribe para buscar |
| `Cmd+A` | Selecciona todos los resultados |
| `↑` / `↓` | Navega entre filas (si está activo el filtro) |
| `Enter` | Abre el elemento seleccionado |
| `Delete` | Elimina el elemento seleccionado (pide confirmación) |

---

## Notas importantes

### ⚠️ Los atajos no funcionan mientras escribes

Si estás dentro de un campo de texto (nombre de cliente, descripción, etc.), los atajos están **deshabilitados**:

- `Cmd+K` dentro de un input abre Cmd+K y sigue escribiendo — no reabre la paleta
- `G` sequences no responden dentro de campos

**Solución:** Presiona `Esc` para salir del campo, luego usa el atajo.

### ⚠️ `G` sequences tienen timeout

Tienes **800ms** desde que presionas `G` para presionar la segunda tecla. Si pasas de ese tiempo, `G` se cancela.

Esto es intencional: deja que escribas "Google Analytics" sin accidentes — solo "Ga" rápido abre Analytics.

### Personalizar atajos

Algunos atajos son estándar (Cmd+K, Cmd+S). Los atajos de navegación (`G`-sequences) se pueden personalizar desde `Ajustes > Atajos de teclado`.

---

## Flujo típico de uso

Así es cómo un usuario de Frihet experimentado factura en 30 segundos:

```
Cmd+K                          # Abre paleta
new invoice                    # Escribe y presiona Enter
[Escribe nombre de cliente]    # Frihet autocompleta
Tab Tab                        # Va a campo de líneas
[Escribe descripción + precio] # Añade línea
Cmd+S                          # Guarda
Cmd+K send                      # Paleta de comandos: enviar
```

---

## Referencia visual

Para una referencia visual de todos los atajos, presiona `Cmd+/` en cualquier momento. Frihet mostrará una tarjeta interactiva con todos los disponibles en tu contexto actual.

---

**Tip:** Imprime esta página o añádela a favoritos. En una semana, los atajos serán automáticos.

---

## Configurar tu negocio
> Path: /primeros-pasos/configurar-negocio

# Configurar tu negocio

Cuando creas una nueva cuenta, Frihet te guía a través del **asistente de bienvenida**. Es el único formulario largo que verás — lo demás es atajos y automatización.

## Paso 1: Datos básicos de la empresa

- **Nombre de la empresa** — Cómo aparecerá en tus facturas
- **NIF/CIF** — Tu número fiscal (obligatorio en España)
- **Dirección fiscal** — Calle, número, postal, ciudad

## Paso 2: Zona fiscal

Selecciona dónde opera tu empresa:

- **Península y Baleares** — La mayoría de empresas
- **Canarias** — Régimen fiscal especial (IGIC en lugar de IVA)
- **Ceuta y Melilla** — Régimen especial también

Esto afecta cómo se calculan los impuestos en tus facturas.

## Paso 3: Configurar impuestos por defecto

### IVA

Selecciona el tipo de IVA que aplica a tu actividad:

- **21%** — Tipo general (la mayoría)
- **10%** — Reducido (hostelería, algunos servicios)
- **4%** — Superreducido (alimentos, medicinas)
- **Exento** — Si es tu caso

Este es el default que se aplicará a nuevas líneas de factura. Siempre puedes cambiarlo en cada documento.

### IRPF

Si retienen IRPF en tus facturas (clientes del sector público, principalmente):

- Porcentaje a aplicar (normalmente 15%)
- Esto se aplicará automáticamente en facturas a clientes configurados con retención

## Paso 4: Patrón de numeración

Define cómo se numeran tus facturas. Frihet soporta patrones como:

- `{YEAR}-{SEQ4}` → 2025-0001, 2025-0002, etc.
- `F-{YEAR}{SEQ3}` → F-2025001, F-2025002, etc.
- `{SEQ6}` → 000001, 000002, etc.
- Personalizado: usa `{YEAR}`, `{MONTH}`, `{SEQ3}`, `{SEQ4}`, etc.

El patrón se aplica a:
- Facturas
- Presupuestos
- Notas de crédito

Puedes cambiar esto después en `Ajustes > Numeración`.

## Paso 5: Branding (opcional)

### Logo

Sube un archivo PNG o SVG. Aparecerá en:
- PDFs de facturas
- Encabezado de la aplicación
- Documentos que envíes

Tamaño recomendado: 200x80px como máximo.

### Color de acento

Selecciona un color que represente tu marca. Se usará en:
- Botones principales
- Vínculos
- Indicadores de estado

Frihet viene con una paleta de colores predefinida, pero puedes usar un color hexadecimal personalizado.

---

## Después del asistente

Una vez completado:

- Serás redirigido al **Dashboard**
- Ya puedes crear tu [primera factura](./primera-factura)
- Puedes ajustar cualquier configuración después desde `Ajustes > Empresa`

Si necesitas cambiar algo después, todo está en `Ajustes`:
- Datos fiscales
- IVA/IRPF por defecto
- Numeración
- Logo y color

Descubre todas las [funcionalidades de Frihet](https://www.frihet.io/es/features) y las [integraciones disponibles](https://www.frihet.io/es/integrations) para sacar el máximo partido a tu configuración.

**Siguiente paso:** [Tu primera factura](./primera-factura)

---

## Crear una cuenta
> Path: /primeros-pasos/crear-cuenta

# Crear una cuenta

Registrarse en Frihet toma menos de 2 minutos. Puedes hacerlo con email o con tu cuenta de Google. No necesitas tarjeta de crédito para empezar con el [plan gratuito](https://www.frihet.io/es/pricing).

## Opción 1: Registrarse con email

1. Ve a [frihet.io/signup](https://frihet.io/signup)
2. Introduce tu email y elige una contraseña segura
3. Haz clic en "Crear cuenta"
4. Completa el desafío de **Cloudflare Turnstile** — simplemente verifica que no eres un bot
5. Recibirás un email de confirmación

## Opción 2: Registrarse con Google

1. Ve a [frihet.io/signup](https://frihet.io/signup)
2. Haz clic en "Continuar con Google"
3. Sigue el flujo de autenticación de Google
4. Frihet usará tu email de Google automáticamente

## Verificar tu email

Después de registrarte, revisa tu bandeja de entrada:

- Si registraste con **email/contraseña**, recibirás un email de verificación
- Haz clic en el enlace de confirmación dentro del email
- Si no ves el email en 5 minutos, revisa la carpeta de spam

Una vez verificado, estás listo para entrar.

## Tu primer login

Cuando accedas a Frihet por primera vez, te llevará automáticamente al **asistente de bienvenida** en 4 pasos:

1. **Tipo de usuario** — Autonomo, empresa, agencia o gestoría. Frihet adapta la experiencia según tu perfil.
2. **País** — Selecciona tu país de residencia fiscal. Determina la moneda, idioma y régimen fiscal.
3. **Datos fiscales** — Nombre de empresa, NIF/CIF, dirección fiscal.
4. **Primera acción** — Elige qué quieres hacer primero: crear una factura, registrar un gasto o explorar el dashboard.

Después del asistente, un **tour guiado** te muestra las secciones principales de la interfaz: sidebar, barra de atajos, asistente IA y módulo de facturación.

### Lista de primeros pasos

El dashboard muestra una checklist de onboarding con 6 pasos recomendados:

- Completar datos fiscales
- Crear tu primera factura
- Añadir un cliente
- Registrar un gasto
- Configurar series de numeración
- Conectar una integración

Los pasos se marcan automáticamente a medida que los completas. Al terminar todos, aparece una tarjeta de felicitación que puedes cerrar.

### Consejos contextuales

La primera vez que visitas cada sección (gastos, productos, clientes, presupuestos, banca), Frihet muestra un consejo breve con una acción directa para empezar. Estos consejos se ocultan automáticamente una vez los cierras.

---

**Siguiente paso:** [Configurar tu negocio](./configurar-negocio)

---

## Tu primera factura
> Path: /primeros-pasos/primera-factura

# Tu primera factura

Una factura en Frihet toma menos de un minuto. Aquí cómo hacerlo.

## Opción 1: Desde el Dashboard (lo más rápido)

1. En el Dashboard, haz clic en el botón verde **"+ Nueva factura"**
2. Serás llevado al editor de facturas

## Opción 2: Con atajos de teclado (aún más rápido)

1. Presiona `Cmd+K` para abrir la **Paleta de Comandos**
2. Escribe "Nueva factura"
3. Presiona Enter

O directamente: `Cmd+K` → `new invoice` → Enter.

---

## Paso a paso: crear la factura

### 1. Selecciona o crea un cliente

En el campo **"Cliente"**:

- **Si el cliente ya existe:** Empieza a escribir su nombre. Frihet mostrará coincidencias. Selecciona uno.
- **Si es cliente nuevo:** Sigue escribiendo. Verás un botón **"+ Crear cliente"**. Haz clic.
  - Frihet te pedirá nombre, email, y dirección (todos opcionales excepto el nombre)
  - Después puedes completar más datos (teléfono, CIF, etc.) desde `Clientes`

### 2. Añade líneas de factura

En la sección **"Líneas"**:

**Opción A: Desde el catálogo**
- Haz clic en **"+ Producto"**
- Busca un artículo (si lo has añadido antes)
- Frihet autocompleta descripción, precio e impuestos
- Ajusta cantidad si es necesario

**Opción B: Manual**
- Haz clic en **"+ Línea"**
- Escribe la descripción (ej: "Consultoría SEO — 5 horas")
- Introduce la cantidad y precio unitario
- El IVA por defecto se aplica automáticamente

**Opción C: Con el asistente IA**
- O simplemente di: *"Crea factura para Juan por 500 euros"*
- El asistente puede rellenar clientes, importes y líneas basándose en tu historial

### 3. Revisa impuestos y totales

Frihet calcula automáticamente:

- **Subtotal** — suma de líneas
- **IVA** — calculado según tipo de cliente y línea
- **IRPF** — si el cliente tiene retención configurada
- **Total** — cantidad final a cobrar

Puedes ajustar tasas de IVA línea por línea si es necesario.

### 4. (Opcional) Añade metadatos

- **Número de factura** — Se genera automáticamente. Puedes cambiar si quieres
- **Fecha** — Hoy por defecto
- **Fecha de vencimiento** — Por defecto 30 días después
- **Notas** — Términos de pago, referencias de proyecto, etc.
- **Condiciones de pago** — Trasferencia bancaria, efectivo, etc.

### 5. Genera un preview en PDF

Antes de enviar o guardar:

1. Haz clic en **"Vista previa"**
2. Frihet genera el PDF y lo muestra en pantalla
3. Verifica que todo sea correcto

El PDF incluye:
- Tu logo y datos fiscales
- Datos del cliente
- Líneas, impuestos, total
- Numeración fiscal válida (VeriFactu)

### 6. Guarda o envía

**Opción A: Guardar como borrador**
- Haz clic en **"Guardar"**
- Podrás editar después

**Opción B: Enviar por email**
- Haz clic en **"Enviar por email"**
- Introduce el email del cliente (o usa el que está en su perfil)
- Frihet envía el PDF + un enlace de pago (si lo tienes configurado)

**Opción C: Descargar**
- Haz clic en **"Descargar PDF"**
- Guarda el archivo en tu equipo

---

## Trucos de productividad

### Usa el asistente IA

En lugar de rellenar todo manualmente, puedes decir:

- *"Crea factura para María por 800 euros"*
- *"Factura a Juan — 200 euros de diseño, 100 de hosting"*
- *"Nueva factura a Acme Corp por los servicios de febrero"*

El asistente entiende el contexto, busca clientes en tu base de datos y crea la factura con los datos correctos.

### Plantillas rápidas

Si repites facturas iguales (servicios mensuales, retenciones, etc.):

1. Crea la primera factura con todos los detalles
2. Al final, verás un botón **"Guardar como plantilla"**
3. Próxima vez: `Cmd+K` → "Desde plantilla" → selecciona → rellena fecha/cliente

### Clientes recurrentes

Para clientes que factures cada mes:

1. Configura su email en su perfil (`Clientes > [Cliente] > Email`)
2. Al crear factura: Frihet sugiere automáticamente sus datos previos
3. Menos clics cada vez

---

## ¿Qué pasa después?

Una vez guardada, la factura aparece en:

- **Facturas** (`G then F`) — lista de todas tus facturas
- **Dashboard** — resumen de ingresos recientes
- **VeriFactu** — hash SHA-256 y QR AEAT se generan automáticamente

Si es borrador, puedes seguir editando. Si es final, aparece como emitida con su número de secuencia oficial.

---

**Siguiente paso:** [Aprende los atajos de teclado para ir aún más rápido](./atajos-teclado)

---

## Catalogo de productos y servicios
> Path: /productos/catalogo

# Catálogo de productos y servicios

Crea y gestiona tu catálogo de productos y servicios reutilizables. Frihet te permite agregar rápidamente líneas a facturas sin reescribir detalles cada vez.

## Crear producto o servicio

### Acceso

Ve a **Productos > Nuevo producto** o desde panel de factura, haz clic en **+ Producto** mientras editas.

### Datos generales

Completa la información básica:

- **Nombre**: Descripción clara (ej: "Consultoría estratégica", "Hosting VPS")
- **Descripción** (opcional): Detalle adicional visible en facturas
- **SKU**: Código único (ej: CONSULT-2026, VPS-BASIC)

El SKU es interno para tu organización. Frihet genera uno automático si no lo proporcionas.

### Precio y taxación

- **Precio unitario**: Precio sin impuestos (base imponible)
- **Tipo de impuesto**: IVA, IGIC, IPSI o Exento
- **Tasa de IVA**: 21%, 10%, 4% u otra (configurable por producto)
- **Tasa de IRPF**: Si aplica retención (ej: 15%, 19%, 21%)

Ejemplo para "Consultoría":
```
Precio: 1.000 EUR
IVA: 21% (210 EUR)
IRPF: 15% (150 EUR base imponible)
Total al cliente: 1.210 EUR (1.000 + 210 - se calcula IRPF en liquidación)
```

### Categoría

Agrupa productos para reporte y análisis:

- Servicios profesionales
- Licencias software
- Hosting y infraestructura
- Productos físicos
- Formación
- Otros

Puedes crear categorías personalización en **Configuración > Categorías de productos**.

### Unidad de medida

Especifica cómo se vende:

- **Unidad**: Cantidad discreta (1, 2, 100 unidades)
- **Hora**: Para servicios por tiempo (10 horas de desarrollo)
- **Día**: Proyectos por día (5 días de consultoría)
- **Mes**: Suscripciones (3 meses de hosting)
- **Personalizado**: Define tu unidad (ej: "sesión", "página")

## Editar producto

1. Ve a **Productos**
2. Selecciona el producto
3. Haz clic **Editar**
4. Modifica campos
5. Haz clic **Guardar**

Los cambios se aplican a:
- Nuevas facturas desde ahora
- Facturas en borrador (actualizadas si recargas)
- Facturas finalizadas: no cambian (histórico preservado)

## Archivar y restaurar

### Archivar producto

Si dejas de vender un producto pero quieres mantener el histórico:

1. Selecciona producto
2. Haz clic **Más > Archivar**
3. El producto desaparece de lista de facturación
4. Histórico se preserva

### Restaurar

Desde un producto archivado:

1. Ve a **Productos > Archivados**
2. Selecciona producto
3. Haz clic **Restaurar**
4. Vuelve a lista activa

## Eliminar producto

Si necesitas borrar un producto (ej: duplicado):

1. Selecciona producto
2. Haz clic **Más > Eliminar**
3. Frihet avisa si tiene uso en facturas pasadas
4. Si tiene historial, solo permite archivar (no eliminar)

Los productos con facturas asociadas **nunca se eliminan completamente** (auditoría).

## Uso de productos en facturas

### Agregar a factura

Al crear factura:

1. Haz clic en **+ Agregar línea**
2. Escribe primeras letras del producto (búsqueda autocomplete)
3. Selecciona de sugerencias
4. Se pre-rellena: precio, IVA, descripción
5. Edita cantidad y aplica descuentos si necesario

### Cálculo automático

Frihet calcula:

```
Línea: Consultoría estratégica
Cantidad: 3 días
Precio: 500 EUR/día
Subtotal: 1.500 EUR
IVA 21%: 315 EUR
IRPF 15% (si aplica): -225 EUR
Total línea: 1.590 EUR
```

### Historial de uso

En ficha de producto ves:

- **Usado en X facturas** (número de documentos)
- **Ingresos totales**: Dinero generado por este producto
- **Últimas facturas**: Los 5 documentos más recientes donde aparece
- **Gráfico de uso**: Tendencia mensual (ej: crecimiento/declinación)

Útil para identificar productos estrella vs vendidos solo una vez.

## Importar productos desde CSV

Si tienes catálogo en Excel u otro sistema:

### Preparar archivo

```csv
nombre,sku,precio,iva,categoria,unidad
Hosting VPS,VPS-BASIC,49.99,21%,Infraestructura,mes
Consultoría,CONSULT-H,120,21%,Servicios,hora
Licencia software,LIC-SOFT-2026,1500,21%,Software,unidad
```

Columnas mínimas: `nombre`, `precio`, `iva`

### Importar

1. Ve a **Productos > Importar > CSV**
2. Carga archivo
3. Frihet detecta columnas automáticamente
4. Valida precios y formatos
5. Avisa de duplicados (por SKU)
6. Haz clic **Importar**

Detección inteligente reconoce variaciones:
- "Nombre producto" = "nombre"
- "Código" = "sku"
- "Precio unitario" = "precio"
- "Impuesto" / "Tasa IVA" = "iva"

## Exportar catálogo

### CSV simple

1. Ve a **Productos**
2. Haz clic **Exportar > CSV**
3. Se descarga `catalogo-{fecha}.csv`

Incluye todos los campos.

### Casos de uso

- **Backup**: Guarda copia de seguridad regularmente
- **Compartir**: Envía catálogo a cliente o distribuidor
- **Auditoría**: Registro de precios históricos
- **Integración**: Importa en herramientas de ecommerce

## Búsqueda y filtrado

En lista de productos:

- **Busca por nombre**: Escribe y se filtra en tiempo real
- **Busca por SKU**: Referencia interna
- **Filtra por categoría**: Ej: "Solo servicios"
- **Filtra por estado**: Activos / Archivados

Ejemplo:

```
Busco: "hosting"
Resultados: Hosting VPS, Hosting Compartido, Hosting + Email
```

## Variantes (plan Premium)

Si un producto tiene múltiples versiones (ej: Hosting en 3 planes):

1. Crea producto base: "Hosting"
2. Agrega variantes:
   - **Hosting Basic**: 10 EUR/mes
   - **Hosting Pro**: 25 EUR/mes
   - **Hosting Business**: 50 EUR/mes

En factura, selecciona directamente la variante sin crear 3 productos separados.

Configurar en **Productos > Variantes** (plan Premium).

## Cambios de precio

### Actualizar precio

Si subes precio de un producto:

1. Edita producto
2. Cambia **Precio unitario**
3. Guarda

**Efecto:**
- Nuevas facturas: nuevo precio
- Facturas en borrador: actualizan si recargas
- Facturas finalizadas: precio histórico no cambia

### Histórico de precios

En plan Premium, Frihet mantiene:

- Precio vigente
- Cambios anteriores (con fecha)
- Auditoría: quién cambió y cuándo

Accede en **Productos > [Producto] > Historial de precios**.

## Descuentos en productos

### Descuento por volumen

En plan Premium, configura:

- Si cliente compra 10+ unidades: -5%
- Si cliente compra 50+ unidades: -10%

Descuentos se aplican automáticamente en factura.

### Descuentos por cliente

Configurar precio especial para cliente recurrente:

1. Ve a **Productos > [Producto] > Precios especiales**
2. Agrega cliente: "Acme Corp"
3. Nuevo precio: 450 EUR (vs 500 normal)
4. En facturas de Acme, se aplica automáticamente

## Productos digitales vs físicos

### Productos digitales

No tienen stock ni seguimiento de inventario:

- Software
- Licencias
- Servicios
- Membresías

Frihet los marca automáticamente si no especificas cantidad.

### Productos físicos

Si quieres rastrear inventario (plan Premium):

1. Ve a **Productos > [Producto]**
2. Habilita **Rastreo de inventario**
3. Especifica **stock actual**: 150 unidades
4. Al facturar, stock se decrementa automáticamente
5. Alerta si stock bajo (< 10 unidades)

Acceso a **Reportes > Inventario** para ver estado.

## Problemas comunes

### "Producto no aparece en búsqueda"

- Verifica que no esté archivado (**Productos > Archivados**)
- Busca por SKU en lugar de nombre
- Actualiza página

### "Precio cambió en factura antigua"

Cambios de precio no afectan facturas finalizadas. Precio es histórico. Es por diseño (auditoría).

### "Quiero precio diferente por cliente y cantidad"

En plan Premium, usa **Precios especiales** para cliente + cantidad.

En plan Pro, ajusta manualmente en cada factura (descuento manual).

## Próximas mejoras

Estamos desarrollando:

- **Imágenes en catálogo**: Sube foto de producto
- **Bundling**: Ofertas con múltiples productos
- **Descuentos automáticos**: Por fecha, temporada, volumen
- **Integración ecommerce**: Sincroniza catálogo con Shopify/WooCommerce
- **Control de inventario**: Alertas de reorden automáticas

---

## Precios e impuestos
> Path: /productos/precios-impuestos

# Precios e impuestos

Comprende cómo Frihet calcula precios, aplica impuestos y gestiona retenciones. Cada línea de factura tiene su propia lógica fiscal.

## Estructura de precio

Frihet diferencia entre tres conceptos clave:

### Precio unitario (base imponible)

El precio sin impuestos:

- Es el monto sobre el cual se calcula IVA/IGIC
- Es el declarado en facturas fiscales
- Es el que cambia cuando subes un producto
- Ejemplo: 1.000 EUR

### IVA/IGIC (impuesto indirecto)

Se suma al precio:

- **IVA 21%**: La mayoría de servicios y productos
- **IVA 10%**: Algunos alimentos, transporte, hospedaje
- **IVA 4%**: Libros, revistas, periódicos
- **IGIC 7%**: Canarias (sustituye al IVA)
- **IPSI**: Ceuta y Melilla
- **Exento**: Sin impuesto (ej: servicios financieros)

Cálculo:

```
Precio base:     1.000 EUR
IVA 21%:         + 210 EUR
Total cliente:   1.210 EUR
```

En factura aparece tanto el base como el IVA desglosado.

### IRPF (retención)

Se resta del precio para ciertos servicios:

- **15%**: Servicios de profesionales autónomos
- **19%**: Trabajos técnicos, artísticos, consultoría
- **21%**: Actividades de dirección y administración
- **Exento**: La mayoría de productos

Cálculo:

```
Precio base:     1.000 EUR
IVA 21%:         + 210 EUR
IRPF 15% (retención): - 150 EUR
Total cliente:   1.060 EUR
(Frihet retiene 150 EUR para Hacienda)
```

En factura aparece como "retención IRPF" o "retención impuesto sobre la renta".

## Cálculo por línea

Cada línea de factura tiene su propio régimen fiscal:

### Ejemplo 1: Producto físico con IVA

```
Producto:         Monitor Samsung
Cantidad:         2
Precio unitario:  200 EUR
Subtotal:         400 EUR
IVA 21%:          84 EUR
Total línea:      484 EUR
```

Frihet suma todas las líneas para total de factura.

### Ejemplo 2: Servicio con IVA + IRPF

```
Concepto:         Desarrollo web (30 horas)
Precio/hora:      50 EUR
Subtotal:         1.500 EUR
IVA 21%:          315 EUR
IRPF 15%:         -225 EUR (retención)
Total línea:      1.590 EUR (1.500 + 315 - 225)
```

Tu cliente paga 1.590 EUR. Frihet retiene 225 EUR de IRPF para liquidación.

### Ejemplo 3: Servicio exento de impuesto

```
Concepto:         Asesoría financiera
Subtotal:         800 EUR
IVA:              Exento (0%)
IRPF:             Exento (0%)
Total línea:      800 EUR
```

Sin impuestos ni retenciones.

## Aplicar impuestos en factura

### Por producto (predeterminado)

Cada producto en tu catálogo tiene impuesto configurado:

1. Creas producto "Desarrollo web": IVA 21%, IRPF 15%
2. Lo agregas a factura
3. Frihet aplica automáticamente esos impuestos

### Modificar por línea

Si necesitas cambiar para esta factura específica:

1. En factura, haz clic en la línea
2. Abre **Impuestos** (sección colapsable)
3. Cambia **IVA**: 21% → 10%
4. Cambia **IRPF**: 15% → 0% (ej: cliente extranjero exento)
5. Se recalcula automáticamente

Este cambio **solo afecta esta factura**. El producto sigue con su configuración original.

## Descuentos

Los descuentos se aplican **antes de calcular impuestos**:

```
Precio original:  1.000 EUR
Descuento 10%:    - 100 EUR
Base imponible:   900 EUR (base para IVA)
IVA 21%:          + 189 EUR
Total:            1.089 EUR
```

### Tipos de descuento

**Descuento por línea**:

Aplicable a cada producto. Aparece como % o EUR absoluto:

```
Desarrollo: 1.500 EUR
Descuento: -10% (150 EUR)
Subtotal: 1.350 EUR
```

**Descuento global** (factura completa):

Se aplica al total antes de summar IVA:

```
Subtotal facturas: 5.000 EUR
Descuento 5%:      -250 EUR
Base imponible:    4.750 EUR
IVA 21%:           +997,50 EUR
Total:             5.747,50 EUR
```

### Descuentos vs cortesías

- **Descuento**: Reduce el precio, aparece en factura, cliente ve rebaja
- **Cortesía**: Línea gratuita (ej: regalo por referencia). Aparece como producto con 0 EUR

Usa descuentos para negociaciones públicas. Cortesías para regalos internos.

## Cantidad y precio unitario

Frihet aplica:

```
Total línea = Precio unitario × Cantidad
```

Pero permite cambiar dinámicamente:

### Ejemplo: Cantidad variable

```
Producto:       Desarrollador Senior
Cantidad:       3.5 horas (puedes escribir decimales)
Precio:         80 EUR/hora
Subtotal:       280 EUR
```

Permite trabajar con horas, días fraccionales.

### Cambiar precio en factura

Si cliente negocia precio especial:

1. En factura, selecciona línea
2. Edita **Precio unitario**: 1.200 EUR → 1.050 EUR
3. Se recalcula automáticamente

El cambio es **solo para esta factura**. Producto base no se modifica.

## Diferentes tasas de IVA

En una **misma factura** pueden coexistir diferentes tasas:

```
Línea 1: Libro                   50 EUR  (IVA 4%)      → 52 EUR
Línea 2: Servicio de consultoría 1.000 EUR (IVA 21%)   → 1.210 EUR
Línea 3: Software               500 EUR  (IVA 21%)     → 605 EUR
─────────────────────────────────────────────────────
Subtotal:  1.550 EUR
IVA 4%:      2 EUR
IVA 21%:   345 EUR
Total:   1.897 EUR
```

Frihet agrupa automáticamente por tasa en el desglose de impuestos.

## IGIC (Canarias)

Si estás en Canarias:

- Automáticamente Frihet **sustituye IVA por IGIC**
- Tasa: 0%, 3%, 7%, 9.5% (según Hacienda Canaria)
- No se pueden mezclar IVA e IGIC en la misma factura

Frihet detecta región del cliente y aplica automáticamente. Si es error, edita en factura.

## IPSI (Ceuta/Melilla)

En Ceuta y Melilla:

- IPSI sustituye IVA
- Tasas: 0%, 4%, 8%, 12% (según el producto)
- Aplica solo si cliente está en esas ciudades autónomas

## Retención IRPF

### Cuándo aplica

La retención es obligatoria para:

- Servicios de profesionales autónomos (15%)
- Trabajos técnicos (19%)
- Algunos servicios especializados (21%)

NO aplica para:

- Productos físicos (no hay IRPF)
- Servicios de empresas con CIF (salvo excepciones)
- Servicios de extranjeros

### Cálculo

Frihet retiene automáticamente:

```
Precio base:        1.000 EUR
IRPF 15% (retención): -150 EUR
Cliente paga:         1.000 EUR
Frihet entrega a HC:   150 EUR (liquidación anual)
```

La retención **no es costo adicional** para cliente. Se deduce del precio.

### Liquidación anual

Al final del año fiscal:

1. Frihet suma todas las retenciones IRPF hechas
2. Genera **Resumen anual de retenciones**
3. Lo usas en tu **Impuesto sobre la Renta (IRPF)**
4. Declaras el total retenido en modelo 130/100

Ejemplo:

```
Retenciones efectuadas en 2026:
Ene: 150 EUR
Feb: 150 EUR
...
Dic: 150 EUR
TOTAL: 1.800 EUR
(Aparece en líquido a percibir del modelo 130)
```

## Recargo de equivalencia (profesionales del comercio)

Si eres distribuidor con recargo de equivalencia:

1. Ve a **Configuración > Régimen fiscal**
2. Selecciona **Recargo de equivalencia**
3. Frihet agrega % adicional tras IVA:

```
Precio:         100 EUR
IVA 21%:        21 EUR
Recargo 1.4%:   1,40 EUR
Total:          122,40 EUR
```

El recargo aparece separado en factura.

## Retenciones especiales

Algunos clientes (administraciones públicas) requieren retención adicional:

- **Administraciones**: 3% obligatorio
- **Telecom**: Retención especial si aplica

En **Configuración > Impuestos especiales**, habilita si necesario.

## Exportar desglose de impuestos

Para auditoría y declaraciones:

1. Ve a **Reportes > Desglose fiscal**
2. Rango de fechas
3. Descarga **Impuestos pagados (IVA/IGIC)**
4. Se genera desglose por tasa:

```
IVA 21%:  Total facturado: 10.000 EUR, Impuesto: 2.100 EUR
IVA 10%:  Total facturado: 2.000 EUR, Impuesto: 200 EUR
IVA 4%:   Total facturado: 500 EUR, Impuesto: 20 EUR
IGIC 7%:  Total facturado: 1.500 EUR, Impuesto: 105 EUR
─────────────────────────────────────────
Total IVA/IGIC ingresado: 2.425 EUR
```

Úsalo para rellenar modelo 303 (IVA trimestral).

## Cambios normativos

Si Hacienda cambia tasas de IVA:

- Frihet avisa en dashboard
- Updatea tasas disponibles automáticamente
- Nuevas facturas usan nuevas tasas
- Facturas antiguas: precios históricos (auditoría)

## Problemas comunes

### "Cliente es extranjero, ¿qué IVA aplico?"

Depende del servicio:

- **Servicios digitales a EU**: IVA del cliente (reverse charge, Frihet lo marca)
- **Servicios a fuera EU**: 0% IVA
- **Productos físicos**: Varía según aduanas

En factura, selecciona **IVA exento** y anota "Exportación/Servicio extranjero".

### "Cambié IVA en producto pero factura vieja no actualiza"

Por diseño. Las facturas finalizadas tienen precio histórico. Es auditoría. Crea nota de crédito si necesitas corrección.

### "Tengo IRPF y IVA, ¿cómo funciona?"

Ambos se aplican:

```
Base:  1.000 EUR
+ IVA 21%: +210 EUR
- IRPF 15%: -150 EUR (sobre base)
= Total: 1.060 EUR
```

Cliente paga 1.060 EUR. Frihet liquida IRPF aparte.

---

## Frihet Stay — PMS para alojamientos turísticos
> Path: /stay

# Frihet Stay

Frihet Stay es la app vertical de Frihet ERP para **alojamientos turísticos**: alquileres de corta estancia, casas rurales y hoteles boutique. Integra propiedades, reservas, huéspedes, limpieza, liquidaciones a propietarios y cumplimiento regulatorio sobre la misma base fiscal del ERP.

:::info Estado
Stay está en **fase beta cerrada**. La arquitectura técnica, las pruebas de reglas, el cumplimiento GDPR y las traducciones a 17 idiomas ya están en producción tras la Wave 2 + 2.5 (2026-04-11). Estamos preparando las invitaciones para los primeros partners de hospitality. Si quieres acceso anticipado, escribe a [ayuda@frihet.io](mailto:ayuda@frihet.io).
:::

## Qué incluye

Stay añade un dominio de negocio completo al ERP sin duplicar nada del core fiscal:

| Área                     | Qué hace                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------- |
| **Propiedades**          | Ficha de cada alojamiento con fotos, ubicación, capacidad, servicios, precio base   |
| **Reservas**             | Calendario con entradas y salidas, huésped vinculado, estado, importes y depósitos  |
| **Huéspedes**            | Datos del titular + acompañantes, DNI/pasaporte, consentimientos, firma digital     |
| **Compliance**           | Escaneo del ID, parte de viajeros (SES.HOSPEDAJES), registro policial, Modelo 179   |
| **Gastos por propiedad** | Suministros, mantenimiento, comisiones de plataforma — imputados al inmueble        |
| **Tareas de limpieza**   | Turnos entre reservas, checklist, asignación a housekeepers, estado offline         |
| **Liquidaciones**        | Cálculo automático de lo que toca pagar al propietario (si gestionas para terceros) |
| **Inbox**                | Conversaciones con huéspedes unificadas por reserva                                 |
| **Estadísticas**         | Ocupación, ADR, RevPAR, ingresos por propiedad y por periodo                        |

## Cumplimiento regulatorio

Stay nace con el cumplimiento español y canario como requisito, no como extra:

- **VeriFactu** — toda factura generada por Stay pasa por el motor VeriFactu del ERP
- **IGIC 7 %** — tipo canario aplicado automáticamente cuando la propiedad está en Canarias
- **SES.HOSPEDAJES** — parte de viajeros generado y firmado automáticamente tras el check-in
- **Impuesto Turístico Canario** — cálculo por noche y huésped cuando aplica
- **Modelo 179** — declaración trimestral de cesiones de uso para propietarios que declaran
- **GDPR** — derecho de acceso, borrado y portabilidad garantizados por funciones dedicadas. 6 años de retención fiscal, 90 días de gracia antes del archivado definitivo

## Precio

- **Base:** 19 €/mes
- **Propiedades incluidas:** 5
- **Propiedad adicional:** 2 €/mes cada una
- **Trial:** 14 días
- **Comisión sobre reservas:** 0 %

Requiere plan **Frihet ERP Pro** o superior. El plan Premium incluye descuento en apps.

[Ver planes →](https://www.frihet.io/es/pricing)

## Seguridad y cobertura

- **Aislamiento:** los datos de Stay quedan separados por cuenta y solo son accesibles desde tu workspace, con controles de acceso verificados en el servidor.
- **Acceso restringido:** las funciones de Stay requieren tener la app activa o en periodo de prueba.
- **Infraestructura:** alojada en la UE.
- **Cobertura:** 126 tests automatizados sobre las reglas de acceso.
- **i18n:** 258 claves `stay.*` traducidas a los 17 idiomas del ERP.
- **Offline:** soporte offline para los flujos móviles de limpieza (PWA).

## Flujos documentados

La documentación de cada flujo (crear propiedad, dar de alta una reserva, hacer check-in, registrar un gasto, programar limpieza, ver estadísticas) se irá publicando conforme avance la beta.

Si necesitas detalle técnico antes de su publicación oficial, contacta con [ayuda@frihet.io](mailto:ayuda@frihet.io).

## Preguntas frecuentes

**¿Funciona si no estoy en Canarias?**
Sí. El motor fiscal detecta automáticamente la comunidad autónoma de cada propiedad y aplica IVA o IGIC según corresponda. El Modelo 179 y SES.HOSPEDAJES aplican a todo el territorio español.

**¿Sincroniza con Airbnb, Booking, VRBO?**
La integración con canales (channel manager) está en el roadmap post-GA. Inicialmente Stay gestiona el inventario como fuente maestra y las reservas se importan manualmente o vía CSV.

**¿Puedo gestionar propiedades de terceros?**
Sí. Stay soporta el modelo de property manager con liquidaciones automáticas al propietario final, incluyendo retenciones y gastos repercutidos.

**¿Qué pasa si desactivo Stay?**
Entras en 90 días de gracia durante los cuales puedes reactivar sin perder datos. Después, los datos pasan por archivado cifrado (6 años de retención fiscal) y purga definitiva.

---

## Frihet Studio
> Path: /studio

# Frihet Studio

Frihet Studio es el servicio de implementacion oficial de Frihet. Configuramos todo por ti: integraciones, automatizaciones, migracion de datos y tu dashboard personalizado.

## Para quien es

- **Acabas de empezar** y quieres arrancar con todo bien configurado desde el dia uno.
- **Tu negocio crece** y necesitas orden antes de que el caos sea irreversible.
- **No tienes tiempo** para aprender otra herramienta. Solo quieres que funcione.

## Que incluye el Quickstart Pack

| Elemento | Detalle |
|----------|---------|
| Estructura fiscal | Impuestos, series de facturacion y datos de tu empresa configurados |
| 3 integraciones | Las que necesites: pagos, e-commerce, banca, comunicacion |
| 5 automatizaciones | Recordatorios, alertas, flujos de aprobacion y mas |
| Dashboard personalizado | Metricas que importan para tu negocio |
| Migracion de datos | Clientes, productos, facturas historicas importadas |
| Sesion de entrega | Te ensenamos tu sistema funcionando en directo |

## Como funciona

1. **Llamada** — 20 minutos. Entendemos tu negocio, tu stack y que necesitas automatizar.
2. **Implementacion** — Configuramos todo. Integraciones, automatizaciones, datos. Tu no tocas nada.
3. **Entrega** — Sesion en directo. Te ensenamos tu sistema funcionando. Soporte 30 dias incluido.

## Mas opciones

El Quickstart es solo el punto de partida. Si necesitas integraciones adicionales, automatizaciones a medida o soporte extendido, hablamos. Consulta todas las [integraciones disponibles](https://www.frihet.io/es/integrations) y las [funcionalidades de Frihet](https://www.frihet.io/es/features).

## Contacto

[Solicita informacion](https://www.frihet.io/studio) o [agenda una llamada](https://cal.eu/frihetstudio).

---