Saltar al contenido principal

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:

PaqueteInstalaciónDescripción
@frihet/sdknpm i @frihet/sdkSDK TypeScript — frihet.invoices.create(), tipos completos, retry automático
frihetnpm i -g frihetCLI — 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​

RecursoLímite
Peticiones API100/minuto por clave
Tamaño de petición1 MB máximo
Offset máximo10.000
Tamaño de payload de webhook100 KB máximo
Webhooks por cuenta20 máximo
Reintentos de webhook3 intentos por entrega
Resultados por página100 máximo (50 por defecto)
Claves API activas por usuario5 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​

  1. En Frihet ERP, ve a Integraciones → API Keys y pulsa Crear clave (consulta Claves API para ver los detalles de permisos y caducidad).
  2. 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"
Ejemplos sintéticos validados contra el contrato OpenAPI

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 OK con 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 OK en una cuenta nueva o sin clientes ("data": []): si aún no has creado clientes en tu cuenta, recibirás "data": [] y "total": 0 con código HTTP 200. 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 cabecera X-API-Key, la variable $FRIHET_API_KEY está vacía, el prefijo fri_ 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​