SDK y CLI

Frihet ofrece un SDK oficial de TypeScript y una CLI para gestionar tu negocio desde código o terminal. Ambos paquetes están publicados en npm.

Paquete	npm	Uso
@frihet/sdk		SDK para Node.js / TypeScript
frihet		CLI para terminal

---

Instalación

SDK

npm install @frihet/sdk

CLI

npm install -g frihet

---

Autenticación

Necesitas una API key. Genérala en Integraciones → API Keys dentro de app.frihet.io. Las claves comienzan con fri_.

SDK

import Frihet from '@frihet/sdk';

const frihet = new Frihet({
  apiKey: 'fri_live_...',
});

Opciones adicionales:

Opción	Tipo	Por defecto	Descripción
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

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. También puedes usar la variable de entorno FRIHET_API_KEY.

---

SDK — Inicio rápido

Listar facturas

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

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

// Busqueda por texto
const results = await frihet.clients.search('Acme');

// Actualizar un cliente
await frihet.clients.update(results.data[0].id, {
  email: 'nuevo@example.com',
  fiscalZone: 'peninsula',
});

Marcar factura como pagada y enviar por email

await frihet.invoices.markPaid('inv_abc123');

await frihet.invoices.send('inv_abc123', {
  recipientEmail: 'cliente@example.com',
  locale: 'es',
});

Crear abono / factura rectificativa

const creditNote = await frihet.invoices.createCreditNote('inv_abc123', {
  reason: 'error',
  reasonDescription: 'Correccion de importe',
  fullCredit: true,
});

console.log(`Abono ${creditNote.documentNumber} creado`);

CLI:

frihet invoices credit-note inv_abc123 --reason error --full

---

CLI — Inicio rápido

Ver estado del negocio

frihet status
# Revenue:   EUR 12.500,00
# Expenses:  EUR 3.200,00
# Net:       EUR 9.300,00

frihet status --month 2026-02

Gestionar facturas

# 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@example.com

Gestionar gastos

# 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

# Listar clientes
frihet clients list

# Buscar
frihet clients list -q "Acme"

# Crear cliente
frihet clients create --name "Acme S.L." --email info@example.com --tax-id B12345674 --zone peninsula

---

Recursos disponibles

El SDK expone los siguientes recursos como propiedades de la instancia Frihet:

Recurso	Propiedad	Métodos
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 (estático)
Inteligencia	frihet.intelligence	context, summary, monthly, quarterly

Todos los métodos list y search devuelven un objeto Page<T>:

interface Page<T> {
  data: T[];
  total: number;
  limit: number;
  offset: number;
}

---

Manejo de errores

El SDK lanza errores tipados para cada tipo de fallo:

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	Código HTTP	Cuando
AuthenticationError	401	API key invalida o ausente
NotFoundError	404	Recurso no encontrado
ValidationError	400 / 422	Datos de entrada inválidos
RateLimitError	429	Límite de peticiones excedido
TimeoutError	--	Sin respuesta en el timeout configurado
APIError	Otros	Error genérico del servidor

Reintentos automáticos

El SDK reintenta automáticamente las peticiones que reciben códigos 429 (rate limit) o 5xx (error de servidor), hasta 3 veces con backoff exponencial. No necesitas implementar lógica de reintentos.

---

Idempotencia

Para operaciones de creación, puedes enviar un idempotencyKey para evitar duplicados en caso de reintentos:

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 método estático para verificar la firma HMAC-SHA256 de los webhooks:

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	Descripción
FRIHET_API_KEY	API key (alternativa a frihet login en CLI o al constructor del SDK)
FRIHET_API_URL	URL base personalizada

---

Más información

• API REST — referencia completa de endpoints
• Webhooks — eventos y verificación de firma
• Repositorio en GitHub — código fuente, issues, contribuciones
• npm @frihet/sdk | npm frihet