SDK und CLI

Frihet bietet ein offizielles TypeScript SDK und eine CLI zur Verwaltung Ihres Geschäfts von Code oder Terminal aus. Beide Pakete sind auf npm veröffentlicht.

Paket	npm	Verwendung
@frihet/sdk		SDK für Node.js / TypeScript
frihet		CLI für Terminal

---

Installation

SDK

npm install @frihet/sdk

CLI

npm install -g frihet

---

Authentifizierung

Sie benötigen einen API-Schlüssel. Generieren Sie diesen unter Einstellungen > Sicherheit in app.frihet.io. Die Schlüssel beginnen mit fri_.

SDK

import Frihet from '@frihet/sdk';

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

Zusätzliche Optionen:

Option	Typ	Standard	Beschreibung
apiKey	string	--	Ihr API-Schlüssel (obligatorisch)
baseUrl	string	https://api.frihet.io/v1	Basis-URL der API
timeout	number	30000	Timeout in Millisekunden

CLI

frihet login
# Geben Sie Ihren API-Schlüssel interaktiv ein

# Oder direkt:
frihet login --key fri_live_...

Der Schlüssel wird in ~/.frihet/config.json mit den Berechtigungen 0600 gespeichert. Sie können auch die Umgebungsvariable FRIHET_API_KEY verwenden.

---

SDK — Schnellstart

Rechnungen auflisten

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} bezahlte Rechnungen`);

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

Eine Rechnung erstellen

const invoice = await frihet.invoices.create({
  clientName: 'Acme S.L.',
  items: [
    { description: 'Beratung', quantity: 10, unitPrice: 150 },
    { description: 'Webentwicklung', quantity: 1, unitPrice: 3000 },
  ],
  taxRate: 21,
  dueDate: '2026-04-15',
});

console.log(`Rechnung ${invoice.documentNumber} erstellt (${invoice.total} EUR)`);

Suchen und aktualisieren

// Textsuche
const results = await frihet.clients.search('Acme');

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

Rechnung als bezahlt markieren und per E-Mail senden

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

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

---

CLI — Schnellstart

Geschäftsstatus anzeigen

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

frihet status --month 2026-02

Rechnungen verwalten

# Rechnungen auflisten
frihet invoices list --status paid --limit 5

# Suchen
frihet invoices list -q "Acme"

# Details anzeigen
frihet invoices get inv_abc123

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

# Als bezahlt markieren
frihet invoices paid inv_abc123

# Per E-Mail senden
frihet invoices send inv_abc123 --to cliente@acme.com

Ausgaben verwalten

# Ausgaben auflisten
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Ausgabe erstellen
frihet expenses create --desc "Monatliches Hosting" --amount 49.99 --category software --vendor "Hetzner"

Kunden verwalten

# Kunden auflisten
frihet clients list

# Suchen
frihet clients list -q "Acme"

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

---

Verfügbare Ressourcen

Das SDK stellt die folgenden Ressourcen als Eigenschaften der Frihet-Instanz zur Verfügung:

Ressource	Eigenschaft	Methoden
Rechnungen	frihet.invoices	list, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Ausgaben	frihet.expenses	list, retrieve, create, update, del, search, createBatch
Kunden	frihet.clients	list, retrieve, create, update, del, search
Lieferanten	frihet.vendors	list, retrieve, create, update, del, search
Produkte	frihet.products	list, retrieve, create, update, del, search
Angebote	frihet.quotes	list, retrieve, create, update, del, search, pdf, send
Webhooks	frihet.webhooks	list, retrieve, create, update, del + verifySignature (statisch)
Intelligenz	frihet.intelligence	context, summary, monthly, quarterly

Alle list- und search-Methoden geben ein Page<T>-Objekt zurück:

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

---

Fehlerbehandlung

Das SDK löst typisierte Fehler für jeden Fehlertyp aus:

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('Rechnung nicht gefunden');
  } else if (err instanceof AuthenticationError) {
    console.log('API-Schlüssel ungültig');
  } else if (err instanceof ValidationError) {
    console.log('Ungültige Daten:', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate Limit. Wiederholen in ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Timeout');
  }
}

Klasse	HTTP-Code	Wann
AuthenticationError	401	API-Schlüssel ungültig oder fehlt
NotFoundError	404	Ressource nicht gefunden
ValidationError	400 / 422	Ungültige Eingabedaten
RateLimitError	429	Anfrage-Limit überschritten
TimeoutError	--	Keine Antwort innerhalb des konfigurierten Timeouts
APIError	Andere	Generischer Serverfehler

Automatische Wiederholungen

Das SDK versucht automatisch, Anfragen, die die Codes 429 (Rate Limit) oder 5xx (Serverfehler) erhalten, bis zu 3 Mal mit exponentiellem Backoff zu wiederholen. Sie müssen keine eigene Wiederholungslogik implementieren.

---

Idempotenz

Für Erstellungsoperationen können Sie einen idempotencyKey senden, um Duplikate bei Wiederholungsversuchen zu vermeiden:

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

---

Webhooks verifizieren

Das SDK enthält eine statische Methode zur Verifizierung der HMAC-SHA256-Signatur von Webhooks:

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

const isValid = Webhooks.verifySignature(
  rawBody,              // string oder Buffer des Bodys
  req.headers['x-frihet-signature'],  // Signatur-Header
  'whsec_tu_secreto',   // Webhook-Geheimnis
);

---

Umgebungsvariablen

Variable	Beschreibung
FRIHET_API_KEY	API-Schlüssel (Alternative zu frihet login in der CLI oder zum SDK-Konstruktor)
FRIHET_API_URL	Benutzerdefinierte Basis-URL

---

Weitere Informationen

• API REST — vollständige Endpunkt-Referenz
• Webhooks — Ereignisse und Signaturverifizierung
• GitHub-Repository — Quellcode, Issues, Beiträge
• npm @frihet/sdk | npm frihet