Hoppa till huvudinnehåll

SDK och CLI

Frihet erbjuder en officiell TypeScript SDK och en CLI för att hantera ditt företag från kod eller terminal. Båda paketen är publicerade på npm.

PaketnpmAnvändning
@frihet/sdknpmSDK för Node.js / TypeScript
frihetnpmCLI för terminal

Installation​

SDK​

npm install @frihet/sdk

CLI​

npm install -g frihet

Autentisering​

Du behöver en API-nyckel. Generera den under Inställningar > Säkerhet i app.frihet.io. Nycklarna börjar med fri_.

SDK​

import Frihet from '@frihet/sdk';

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

Ytterligare alternativ:

AlternativTypStandardBeskrivning
apiKeystring--Din API-nyckel (obligatoriskt)
baseUrlstringhttps://api.frihet.io/v1Bas-URL för API:et
timeoutnumber30000Timeout i millisekunder

CLI​

frihet login
# Ange din API-nyckel interaktivt

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

Nyckeln sparas i ~/.frihet/config.json med behörigheter 0600. Du kan också använda miljövariabeln FRIHET_API_KEY.

SDK — Snabbstart​

Lista fakturor​

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} betalda fakturor`);

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

Skapa en faktura​

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

Sök och uppdatera​

// Sökning via text
const results = await frihet.clients.search('Acme');

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

Markera faktura som betald och skicka via e-post​

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

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

CLI — Snabbstart​

Se företagets status​

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

frihet status --month 2026-02

Hantera fakturor​

# Lista fakturor
frihet invoices list --status paid --limit 5

# Sök
frihet invoices list -q "Acme"

# Visa detaljer
frihet invoices get inv_abc123

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

# Markera som betald
frihet invoices paid inv_abc123

# Skicka via e-post
frihet invoices send inv_abc123 --to cliente@acme.com

Hantera utgifter​

# Lista utgifter
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Skapa utgift
frihet expenses create --desc "Månatlig hosting" --amount 49.99 --category software --vendor "Hetzner"

Hantera kunder​

# Lista kunder
frihet clients list

# Sök
frihet clients list -q "Acme"

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

Tillgängliga resurser​

SDK:n exponerar följande resurser som egenskaper för Frihet-instansen:

ResursEgenskapMetoder
Fakturorfrihet.invoiceslist, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Utgifterfrihet.expenseslist, retrieve, create, update, del, search, createBatch
Kunderfrihet.clientslist, retrieve, create, update, del, search
Leverantörerfrihet.vendorslist, retrieve, create, update, del, search
Produkterfrihet.productslist, retrieve, create, update, del, search
Offerterfrihet.quoteslist, retrieve, create, update, del, search, pdf, send
Webhooksfrihet.webhookslist, retrieve, create, update, del + verifySignature (statisk)
Intelligensfrihet.intelligencecontext, summary, monthly, quarterly

Alla list- och search-metoder returnerar ett Page<T>-objekt:

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

Felhantering​

SDK:n kastar typade fel för varje typ av misslyckande:

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('Faktura hittades inte');
  } else if (err instanceof AuthenticationError) {
    console.log('Ogiltig API-nyckel');
  } else if (err instanceof ValidationError) {
    console.log('Ogiltiga data:', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limit. Försök igen om ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Timeout');
  }
}
KlassHTTP-kodNär
AuthenticationError401Ogiltig eller saknad API-nyckel
NotFoundError404Resurs hittades inte
ValidationError400 / 422Ogiltiga indata
RateLimitError429Förfrågningsgräns överskriden
TimeoutError--Inget svar inom konfigurerad timeout
APIErrorÖvrigaGeneriskt serverfel

Automatiska försök​

SDK:n försöker automatiskt igen med förfrågningar som får koder 429 (rate limit) eller 5xx (serverfel), upp till 3 gånger med exponentiell backoff. Du behöver inte implementera omförsökslogik.

Idempotens​

För skapande operationer kan du skicka en idempotencyKey för att undvika dupliceringar vid omförsök:

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

Verifiera webhooks​

SDK:n inkluderar en statisk metod för att verifiera HMAC-SHA256-signaturen för webhooks:

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

const isValid = Webhooks.verifySignature(
  rawBody,              // sträng eller Buffer av body
  req.headers['x-frihet-signature'],  // signaturhuvud
  'whsec_tu_secreto',   // webhook-sekretess
);

Miljövariabler​

VariabelBeskrivning
FRIHET_API_KEYAPI-nyckel (alternativ till frihet login i CLI eller till SDK-konstruktorn)
FRIHET_API_URLAnpassad bas-URL

Mer information​