SDK e CLI

Frihet offre un SDK ufficiale TypeScript e una CLI per gestire la tua attività tramite codice o terminale. Entrambi i pacchetti sono pubblicati su npm.

Pacchetto	npm	Uso
@frihet/sdk		SDK per Node.js / TypeScript
frihet		CLI per terminale

---

Installazione

SDK

npm install @frihet/sdk

CLI

npm install -g frihet

---

Autenticazione

Hai bisogno di una chiave API. Generala in Configurazione > Sicurezza all'interno di app.frihet.io. Le chiavi iniziano con fri_.

SDK

import Frihet from '@frihet/sdk';

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

Opzioni aggiuntive:

Opzione	Tipo	Predefinito	Descrizione
apiKey	string	--	La tua chiave API (obbligatorio)
baseUrl	string	https://api.frihet.io/v1	URL base dell'API
timeout	number	30000	Timeout in millisecondi

CLI

frihet login
# Inserisci la tua chiave API interattivamente

# O direttamente:
frihet login --key fri_live_...

La chiave viene salvata in ~/.frihet/config.json con permessi 0600. Puoi anche usare la variabile d'ambiente FRIHET_API_KEY.

---

SDK — Avvio rapido

Elencare le fatture

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} fatture pagate`);

for (const inv of page.data) {
  console.log(`${inv.documentNumber} — ${inv.clientName} — ${inv.total}`);
}

Creare una fattura

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(`Fattura ${invoice.documentNumber} creata (${invoice.total} EUR)`);

Cercare e aggiornare

// Ricerca per testo
const results = await frihet.clients.search('Acme');

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

Contrassegnare la fattura come pagata e inviare via email

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

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

---

CLI — Avvio rapido

Visualizzare lo stato dell'attività

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

frihet status --month 2026-02

Gestire le fatture

# Elencare le fatture
frihet invoices list --status paid --limit 5

# Cercare
frihet invoices list -q "Acme"

# Visualizzare i dettagli
frihet invoices get inv_abc123

# Creare fattura
frihet invoices create --client "Acme S.L." --item "Consultoria,10,150" --tax 21

# Contrassegnare come pagata
frihet invoices paid inv_abc123

# Inviare via email
frihet invoices send inv_abc123 --to cliente@acme.com

Gestire le spese

# Elencare le spese
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Creare una spesa
frihet expenses create --desc "Hosting mensual" --amount 49.99 --category software --vendor "Hetzner"

Gestire i clienti

# Elencare i clienti
frihet clients list

# Cercare
frihet clients list -q "Acme"

# Creare un cliente
frihet clients create --name "Acme S.L." --email info@acme.com --tax-id B12345678 --zone peninsula

---

Risorse disponibili

L'SDK espone le seguenti risorse come proprietà dell'istanza Frihet:

Risorsa	Proprietà	Metodi
Fatture	frihet.invoices	list, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Spese	frihet.expenses	list, retrieve, create, update, del, search, createBatch
Clienti	frihet.clients	list, retrieve, create, update, del, search
Fornitori	frihet.vendors	list, retrieve, create, update, del, search
Prodotti	frihet.products	list, retrieve, create, update, del, search
Preventivi	frihet.quotes	list, retrieve, create, update, del, search, pdf, send
Webhook	frihet.webhooks	list, retrieve, create, update, del + verifySignature (statico)
Intelligence	frihet.intelligence	context, summary, monthly, quarterly

Tutti i metodi list e search restituiscono un oggetto Page<T>:

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

---

Gestione degli errori

L'SDK solleva errori tipizzati per ogni tipo di fallimento:

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('Fattura non trovata');
  } else if (err instanceof AuthenticationError) {
    console.log('Chiave API non valida');
  } else if (err instanceof ValidationError) {
    console.log('Dati non validi:', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Limite di richieste. Riprova tra ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Timeout');
  }
}

Classe	Codice HTTP	Quando
AuthenticationError	401	Chiave API non valida o assente
NotFoundError	404	Risorsa non trovata
ValidationError	400 / 422	Dati di input non validi
RateLimitError	429	Limite di richieste superato
TimeoutError	--	Nessuna risposta nel timeout configurato
APIError	Altri	Errore generico del server

Tentativi automatici

L'SDK ritenta automaticamente le richieste che ricevono codici 429 (limite di richieste) o 5xx (errore del server), fino a 3 volte con backoff esponenziale. Non è necessario implementare la logica di ritentativo.

---

Idempotenza

Per operazioni di creazione, puoi inviare una idempotencyKey per evitare duplicati in caso di tentativi:

await frihet.invoices.create(
  { clientName: 'Acme S.L.', items: [{ description: 'Servicio', quantity: 1, unitPrice: 500 }] },
  { idempotencyKey: 'mi-clave-unica-123' }
);

---

Verificare i webhook

L'SDK include un metodo statico per verificare la firma HMAC-SHA256 dei webhook:

import { Webhooks } from '@frihet/sdk';

const isValid = Webhooks.verifySignature(
  rawBody,              // stringa o Buffer del corpo
  req.headers['x-frihet-signature'],  // intestazione della firma
  'whsec_tu_secreto',   // segreto del webhook
);

---

Variabili d'ambiente

Variabile	Descrizione
FRIHET_API_KEY	Chiave API (alternativa a frihet login nella CLI o al costruttore dell'SDK)
FRIHET_API_URL	URL base personalizzata

---

Maggiori informazioni

• API REST — riferimento completo degli endpoint
• Webhook — eventi e verifica della firma
• Repository su GitHub — codice sorgente, issues, contributi
• npm @frihet/sdk | npm frihet