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 y las integraciones disponibles.
Recursos principales
API REST
API RESTful con autenticación por API key. Accede a facturas, gastos, clientes, productos, presupuestos y proveedores de forma programática.
- Endpoints CRUD completos para 8 recursos: facturas, gastos, clientes, proveedores, productos, presupuestos, depósitos 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, facturación de gastos, depósitos
- Creación en lote (batch): hasta 50 registros por petición
- Filtrado por estado, rango de fechas, búsqueda full-text y paginación (offset + cursor)
- Límite de 100 peticiones/minuto por clave
- Respuestas JSON estandarizadas con validación estricta (Zod)
Webhooks
Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta de Frihet. 15 tipos de evento con firma HMAC-SHA256 para verificar la autenticidad de cada payload.
- 15 tipos de evento (facturas, pagos, presupuestos, gastos, clientes, productos)
- Firma criptográfica HMAC-SHA256 en cada entrega
- Reintentos automáticos con backoff exponencial (3 intentos)
- Circuit breaker: 3 fallos consecutivos pausa el webhook automáticamente
- Logs de entrega consultables desde el panel
Servidor MCP
Servidor MCP oficial publicado en npm como @frihet/mcp-server (v1.17.0), 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, audit GL, gestoría)
- Transporte local (stdio) y remoto (mcp.frihet.io)
- Logging estructurado, métricas por herramienta, rate-limit retry automático
- Autenticación vía API key o flujo OAuth
- Open source (MIT) en GitHub
Skill para Claude Code
Skill oficial que añade inteligencia de negocio sobre el servidor MCP. Comandos conversacionales, contexto fiscal español, recetas de flujos de trabajo y formateo de informes.
- Comandos:
/frihet invoice,/frihet expense,/frihet report,/frihet clients - Resumen trimestral de IVA para preparar el Modelo 303
- Cierre mensual, seguimiento de morosos, conversión presupuesto-factura
- Instalación:
npx skills add Frihet-io/frihet-mcp
Integraciones
Cada integración tiene su página en la sección Integraciones de esta documentación. Puedes complementarlas con la API REST y los webhooks. Para automatizaciones, consulta Zapier, n8n y Make.
Seguridad
La seguridad es una prioridad en toda la capa de integraciones de Frihet.
- Cifrado AES-256-GCM para datos sensibles almacenados (tokens de integración, 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
- Validación 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
- Validación estricta de datos con Zod — campos desconocidos se rechazan
- Validación 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
- Validación de IDs de documento para prevenir path traversal e inyección
- Tokens con expiración 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 | Instalación | Descripción |
|---|---|---|
@frihet/sdk | npm i @frihet/sdk | SDK TypeScript — frihet.invoices.create(), tipos completos, retry automático |
frihet | npm i -g frihet | CLI — frihet invoices list --status overdue |
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
Límites y cuotas
| Recurso | Límite |
|---|---|
| Peticiones API | 100/minuto por clave |
| Tamaño de petición | 1 MB máximo |
| Offset máximo | 10.000 |
| Tamaño de payload de webhook | 100 KB máximo |
| Webhooks por cuenta | 20 máximo |
| Reintentos de webhook | 3 intentos por entrega |
| Resultados por página | 100 máximo (50 por defecto) |
| Claves API activas por usuario | 5 máximo (vía OAuth) |
Primeros pasos
Sigue este recorrido de solo lectura (GET /v1/clients?limit=5) para verificar tu conexión y tu clave API en menos de dos minutos sin modificar datos en tu cuenta.
1. Requisitos y variable de entorno
- En Frihet ERP, ve a Integraciones → API Keys y pulsa Crear clave (consulta Claves API para ver los detalles de permisos y caducidad).
- Copia la clave generada (
fri_..., solo se muestra una vez al crearla) y guárdala en una variable de entorno en tu terminal para no exponerla en código ni en capturas:
export FRIHET_API_KEY="fri_tu_clave_aqui"
2. Primera lectura: verificar conexión y código HTTP
Ejecuta una petición GET de solo lectura a https://api.frihet.io/v1/clients?limit=5 incluyendo -i para inspeccionar el código HTTP y las cabeceras X-RateLimit-* sin truncar el cuerpo JSON:
curl -i -s "https://api.frihet.io/v1/clients?limit=5" \
-H "X-API-Key: $FRIHET_API_KEY"
Los bloques JSON siguientes son ejemplos sintéticos validados contra el esquema OpenAPI (/openapi.json) para ayudarte a interpretar la respuesta de tu terminal; no corresponden a ejecuciones en vivo desde esta página.
3. Resultado esperado: cuenta con datos vs cuenta vacía
- Respuesta
200 OKcon clientes registrados: confirma que tu clave API es válida y devuelve la colección paginada (data,total,limit,offset):
{
"data": [
{
"id": "cli_01J8X9M2K4",
"name": "Estudio Norte S.L.",
"email": "facturacion@example.com",
"taxId": "B12345674",
"createdAt": "2026-10-15T09:30:00.000Z",
"updatedAt": "2026-10-15T09:30:00.000Z"
}
],
"total": 1,
"limit": 5,
"offset": 0
}
- Respuesta
200 OKen una cuenta nueva o sin clientes ("data": []): si aún no has creado clientes en tu cuenta, recibirás"data": []y"total": 0con código HTTP200. Esto también confirma que tu conexión y tu clave API funcionan correctamente:
{
"data": [],
"total": 0,
"limit": 5,
"offset": 0
}
4. Diagnóstico y recuperación ante errores (401, 403, 429)
401 Unauthorized(falta la cabeceraX-API-Key, la variable$FRIHET_API_KEYestá vacía, el prefijofri_es inválido o la clave ha expirado o sido revocada):
{
"error": "Invalid or expired API key",
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}
Recuperación: comprueba en tu terminal que la variable esté definida (test -n "$FRIHET_API_KEY" && echo "OK") o genera una clave nueva en Integraciones → API Keys (Claves API).
403 Forbidden(la clave o el plan activo no tiene permisos sobre el recurso solicitado):
{
"error": "Insufficient permissions",
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}
Recuperación: verifica los permisos asociados a tu clave y el plan de tu cuenta en Claves API.
429 Too Many Requests(se han superado las 100 peticiones por minuto de la clave):
{
"error": "Rate limit exceeded",
"message": "Maximum 100 requests per minute",
"retryAfter": 60,
"meta": {
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}
Recuperación: espera los segundos indicados en retryAfter o en la cabecera Retry-After (o hasta el timestamp X-RateLimit-Reset) antes de reintentar.
5. Siguiente acción
- Consultar los endpoints de creación, filtros y paginación por cursor en la Referencia de la API REST o en el explorador OpenAPI (
/api-reference). - Si prefieres usar un agente de IA (Claude Code, Cursor, Windsurf, ChatGPT o Hermes) en lugar de hacer llamadas HTTP manuales, sigue la guía Conectar tu agente o la referencia del Servidor MCP.
- Configurar notificaciones de eventos en Webhooks o revisar Soporte y diagnóstico rápido.