Skip to main content

SDK ja CLI

Frihet tarjoaa virallisen TypeScript-SDK:n ja CLI:n yrityksesi hallinnointiin koodista tai terminaalista. Molemmat paketit on julkaistu npm:ssä.

PakettinpmKäyttö
@frihet/sdknpmSDK Node.js:lle / TypeScriptille
frihetnpmCLI terminaalille

Asennus​

SDK​

npm install @frihet/sdk

CLI​

npm install -g frihet

Todennus​

Tarvitset API-avaimen. Luo se kohdassa Asetukset > Turvallisuus osoitteessa app.frihet.io. Avaimet alkavat tunnuksella fri_.

SDK​

import Frihet from '@frihet/sdk';

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

Lisäasetukset:

AsetusTyyppiOletusKuvaus
apiKeystring--API-avaimesi (pakollinen)
baseUrlstringhttps://api.frihet.io/v1API:n perus-URL
timeoutnumber30000Aikakatkaisu millisekunteina

CLI​

frihet login
# Syötä API-avaimesi interaktiivisesti

# Tai suoraan:
frihet login --key fri_live_...

Avain tallennetaan tiedostoon ~/.frihet/config.json oikeuksilla 0600. Voit käyttää myös ympäristömuuttujaa FRIHET_API_KEY.

SDK — Pikaopas​

Listaa laskut​

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} maksettua laskua`);

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

Luo lasku​

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

console.log(`Lasku ${invoice.documentNumber} luotu (${invoice.total} EUR)`);

Hae ja päivitä​

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

// Päivitä asiakas
await frihet.clients.update(results.data[0].id, {
  email: 'nuevo@acme.com',
  fiscalZone: 'peninsula',
});

Merkitse lasku maksetuksi ja lähetä sähköpostitse​

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

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

CLI — Pikaopas​

Katso yrityksen tila​

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

frihet status --month 2026-02

Hallinnoi laskuja​

# Listaa laskut
frihet invoices list --status paid --limit 5

# Hae
frihet invoices list -q "Acme"

# Katso tiedot
frihet invoices get inv_abc123

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

# Merkitse maksetuksi
frihet invoices paid inv_abc123

# Lähetä sähköpostitse
frihet invoices send inv_abc123 --to cliente@acme.com

Hallinnoi kuluja​

# Listaa kulut
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Luo kulu
frihet expenses create --desc "Kuukausittainen hosting" --amount 49.99 --category software --vendor "Hetzner"

Hallinnoi asiakkaita​

# Listaa asiakkaat
frihet clients list

# Hae
frihet clients list -q "Acme"

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

Saatavilla olevat resurssit​

SDK paljastaa seuraavat resurssit Frihet-instanssin ominaisuuksina:

ResurssiOminaisuusMetodit
Laskutfrihet.invoiceslist, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Kulutfrihet.expenseslist, retrieve, create, update, del, search, createBatch
Asiakkaatfrihet.clientslist, retrieve, create, update, del, search
Toimittajatfrihet.vendorslist, retrieve, create, update, del, search
Tuotteetfrihet.productslist, retrieve, create, update, del, search
Tarjouksetfrihet.quoteslist, retrieve, create, update, del, search, pdf, send
Webhooksfrihet.webhookslist, retrieve, create, update, del + verifySignature (staattinen)
Älykkyysfrihet.intelligencecontext, summary, monthly, quarterly

Kaikki list- ja search-metodit palauttavat Page<T>-objektin:

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

Virheiden käsittely​

SDK antaa tyypitettyjä virheitä jokaiselle virhetyypille:

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('Laskua ei löytynyt');
  } else if (err instanceof AuthenticationError) {
    console.log('API-avain virheellinen');
  } else if (err instanceof ValidationError) {
    console.log('Virheelliset tiedot:', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Pyynnön rajoitus ylitetty. Yritä uudelleen ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Aikakatkaisu');
  }
}
LuokkaHTTP-koodiMilloin
AuthenticationError401API-avain virheellinen tai puuttuu
NotFoundError404Resurssia ei löytynyt
ValidationError400 / 422Virheelliset syötetiedot
RateLimitError429Pyyntöjen raja ylitetty
TimeoutError--Ei vastausta määritetyssä aikakatkaisussa
APIErrorMuutYleinen palvelinvirhe

Automaattiset uudelleenyritykset​

SDK yrittää automaattisesti uudelleen pyyntöjä, jotka saavat koodit 429 (pyynnön rajoitus) tai 5xx (palvelinvirhe), enintään 3 kertaa eksponentiaalisella viiveellä. Sinun ei tarvitse toteuttaa uudelleenyrityslogiikkaa.

Idempotenssi​

Luontitoiminnoissa voit lähettää idempotencyKey-avaimen kaksoiskappaleiden välttämiseksi uudelleenyritysten yhteydessä:

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

Tarkista webhookit​

SDK sisältää staattisen metodin webhookien HMAC-SHA256-allekirjoituksen tarkistamiseksi:

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

const isValid = Webhooks.verifySignature(
  rawBody,              // body-merkkijono tai Buffer
  req.headers['x-frihet-signature'],  // allekirjoitusotsake
  'whsec_tu_secreto',   // webhookin salaisuus
);

Ympäristömuuttujat​

MuuttujaKuvaus
FRIHET_API_KEYAPI-avain (vaihtoehto frihet login CLI:ssä tai SDK:n konstruktorille)
FRIHET_API_URLMukautettu perus-URL

Lisätietoja​