Saltar al contenido principal

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.

PaquetenpmUso
@frihet/sdknpmSDK para Node.js / TypeScript
frihetnpmCLI para terminal

Instalacion​

SDK​

npm install @frihet/sdk

CLI​

npm install -g frihet

Autenticacion​

Necesitas una API key. Generala en Configuracion > Seguridad 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:

OpcionTipoPor defectoDescripcion
apiKeystring--Tu API key (obligatorio)
baseUrlstringhttps://api.frihet.io/v1URL base de la API
timeoutnumber30000Timeout 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. Tambien puedes usar la variable de entorno FRIHET_API_KEY.

SDK — Inicio rapido​

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@acme.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@acme.com',
  locale: 'es',
});

CLI — Inicio rapido​

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@acme.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@acme.com --tax-id B12345678 --zone peninsula

Recursos disponibles​

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

RecursoPropiedadMetodos
Facturasfrihet.invoiceslist, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Gastosfrihet.expenseslist, retrieve, create, update, del, search, createBatch
Clientesfrihet.clientslist, retrieve, create, update, del, search
Proveedoresfrihet.vendorslist, retrieve, create, update, del, search
Productosfrihet.productslist, retrieve, create, update, del, search
Presupuestosfrihet.quoteslist, retrieve, create, update, del, search, pdf, send
Webhooksfrihet.webhookslist, retrieve, create, update, del + verifySignature (estatico)
Inteligenciafrihet.intelligencecontext, summary, monthly, quarterly

Todos los metodos 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');
  }
}
ClaseCodigo HTTPCuando
AuthenticationError401API key invalida o ausente
NotFoundError404Recurso no encontrado
ValidationError400 / 422Datos de entrada invalidos
RateLimitError429Limite de peticiones excedido
TimeoutError--Sin respuesta en el timeout configurado
APIErrorOtrosError 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:

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:

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​

VariableDescripcion
FRIHET_API_KEYAPI key (alternativa a frihet login en CLI o al constructor del SDK)
FRIHET_API_URLURL base personalizada

Mas informacion​