Aloitusopas

Nordlet on EU- ja ETA-alueen markkinoille suunnattu ohjelmistorajapintakeskeinen (API-first) kirjanpitoalusta, jonka julkaisuvaiheessa on täysi Liettuan lainsäädännön vaatimustenmukaisuus. Kaikki tuotteen toiminnot – laskutus, pääkirjanpito, tiliöintien täsmäytys ja i.SAF – ovat käytettävissä yhden JSON-muotoisen API:n kautta.

1. API-avaimen hankkiminen

Jokaista pyyntöä todennetaan tietylle yritykselle rajatulla Bearer-API-avaimella:

Authorization: Bearer nl_...

Paikallista kehitystä varten voit alustaa yrityksen ja avaimen seuraavasti:

pnpm --filter @nordlet/db bootstrap:dev     # tyhjä yritys
pnpm --filter @nordlet/api seed:demo        # yritys, jossa on demotietoja

Interaktiivinen API-viite (API reference) (OpenAPI-määritys osoitteessa /openapi.json; paikallinen esiintymä tarjoaa saman viitteen osoitteessa http://localhost:3001/docs).

Postman

Käytätkö mieluummin Postmania? Tuo valmis kokoelma – jokainen päätepiste ryhmiteltynä moduuleittain ja Bearer-todennuksella valmiiksi määritettynä: Nordlet Postman collection. Aseta tuonnin jälkeen kokoelman bearerToken-muuttujaksi API-avaimesi, niin kaikki pyynnöt todennetaan automaattisesti.

Testiyritykset (Sandbox companies)

Integraatiotestausta varten voit luoda yrityksen, jonka parametri on isSandbox: true (POST /v1/account/companies/create tai valitsemalla testiyrityksen valintaruudun sovelluksen käyttöönoton yhteydessä). Testiyritys toimii täsmälleen kuten oikea yritys – samat moduulit ja sama API, joten sen kautta voi ajaa realistisen määrän tapahtumia – mutta se on selvästi merkitty testidataksi, ja sen poistaminen tyhjentää kaiken välittömästi sen sijaan, että tietoja säilytettäisiin 10 päivän säilytysajan ajan. Samalle tilille voi luoda minkä tahansa määrän testiyrityksiä oikean yrityksen rinnalle. Tätä lippua (flag) ei voi muuttaa luonnin jälkeen, joten oikeaa kirjanpitoa ei voi koskaan vahingossa luokitella uudelleen testidataksi. Testiyrityksen käyttöä mitataan ja laskutetaan täsmälleen samalla tavalla kuin oikean yrityksen käyttöä: pyynnöt, asiakirjojen skannaussivut, tallennustila ja uudelleenaktivointimaksu. Testiyrityksen veroilmoitukset ja verkkolaskut ohjataan aina viranomaisten testipäätepisteisiin.

2. Ensimmäiset kutsut

Jokainen toiminto on muodossa POST /v1/{module}/{resource}/{action} ja sisältää JSON-muotoisen rungon. Asiakkaan luominen:

curl -X POST https://api.nordlet.com/v1/partners/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-create-001" \
  -d '{"name": "UAB Klientas", "code": "301111222", "vatCode": "LT100001112223"}'

Laskun lähettäminen (summat ovat desimaalimerkkijonoja, ei koskaan liukulukuja):

curl -X POST https://api.nordlet.com/v1/sales/invoices/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "partnerId": "<partner id>",
    "lines": [{"description": "Konsultacijos", "quantity": 4, "unitPriceExclVat": "75.0000", "vatClassifierCode": "PVM1"}]
  }'

curl -X POST https://api.nordlet.com/v1/sales/invoices/issue \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": "<invoice id>", "issueDate": "2026-07-09"}'

Laskun virallistaminen (issue) varaa aukottoman juoksevan numeron (SF-1), tarkistaa, että tilikausi on avoinna, ja kirjaa tasapainoisen tositteen (D 2410 myyntisaamiset / C 5001 myyntituotot / C 4492 arvonlisäverovelka) samassa transaktiossa.

3. Koko kierto

Vaihe	Kutsu
Siirrä kirjanpito aiemmasta järjestelmästä	migration/books/validate → migration/books/import – katso Siirtyminen toisesta järjestelmästä
Kirjaa ostolasku	purchases/invoices/create → purchases/invoices/register
Tuo tiliote	bank/statements/import (camt.053 XML) tai bank/transactions/import (JSON)
Hae täsmäytusehdotuksia	bank/transactions/suggest-matches
Täsmäytä suoritus	bank/transactions/match – kirjaa maksun ja päivittää tilan paymentStatus
Maksa ostoja	bank/payments/export – pain.001 SEPA-tiedosto pankillesi
Kuukausittaiset arvonlisäverorekisterit	declarations/lt/isaf/generate – i.SAF 1.2 XML Verohallinnolle (VMI)
Arvonlisäveroilmoituksen tiedot	declarations/lt/fr0600/compute – FR0600-kentät täsmäytettyinä rekistereihin
Lähetä tavarat rahtikirjan kanssa	transport/waybills/create → issue, minkä jälkeen declarations/lt/ivaz/generate – i.VAZ XML Verohallinnolle (VMI)

4. TypeScript SDK

import { createNordletClient, idempotent } from '@nordlet/sdk'

const client = createNordletClient({
  baseUrl: 'https://api.nordlet.com',
  apiKey: process.env.NORDLET_API_KEY!,
})

const { data, error } = await client.POST('/v1/sales/invoices/create', {
  body: {
    partnerId,
    lines: [{ description: 'Konsultacijos', quantity: 4, unitPriceExclVat: '75.0000' }],
  },
  ...idempotent(`order-${orderId}`),
})

SDK generoidaan reaaliaikaisen OpenAPI-määrityksen pohjalta (pnpm --filter @nordlet/sdk generate), joten jokainen pyyntö ja vastaus on täysin tyypitetty.

5. Webhooks (Verkkohauat)

Tilaa tapahtumat kyselyjen (polling) sijaan:

curl -X POST https://api.nordlet.com/v1/webhooks/subscriptions/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/hyperion", "events": ["sale_invoice.issued", "sale_invoice.paid"]}'

Toimitukset sisältävät aikaleimatun HMAC-allekirjoituksen (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> laskettuna muodosta <timestamp>.<raw body> käyttäen tilaussalaisuuttasi) alkuperäisen x-nordlet-signature: sha256=<hex> -otsikon rinnalla, ja niitä yritetään uudelleen noin 24 tunnin ajan. Lisätietoja toistoikkunasta löytyy kohdasta API-käytännöt.

Jokainen toimituksen runko on muotoa { id, version, companyId, eventType, createdAt, data }: version on sanoman versio (tällä hetkellä 1) ja companyId on yritys, johon tapahtuma liittyy, joten yksi vastaanotin voi palvella useita yrityksiä. Sellaisen nimen tilaaminen, jota ei ole alla olevassa luettelossa, hylätään palauttamalla virhekoodi 400; käytä merkintää "*" kaikkien tapahtumien tilaamiseen. Kun 5 tapahtumaa peräkkäin on jäänyt toimittamatta, tilaus keskeytetään ja yrityksen omistajille lähetetään sähköposti. Voit ottaa tilauksen uudelleen käyttöön kohdassa Tili → Webhooks tai kutsumalla rajapintaa webhooks/subscriptions/update parametrilla isActive: true.

Tapahtumat: agreement.invoice_generated, bank_feed.synced, document_capture.peppol_received, filing.failed, filing.rejected, goods_receipt.posted, intercompany.invoice_mirrored, item.created, item.deleted, item.updated, lead.converted, lead.created, partner_inquiry.created, payroll_run.approved, payroll_run.reversed, pos_report.created, price_list.updated, purchase_invoice.paid, purchase_invoice.registered, purchase_order.approved, purchase_order.received, refund_liability.actual, refund_liability.trued_up, report.completed, report.failed, revenue_recognition.modified, revenue_recognition.posted, sale_invoice.einvoice_sent, sale_invoice.issued, sale_invoice.paid, sale_invoice.peppol_delivered, sale_invoice.peppol_failed, sale_invoice.peppol_rejected, sale_invoice.peppol_sent, sale_invoice.quote_sent, sale_invoice.sent, sales_order.created, sales_order.fulfilled, settlement.imported, settlement.posted, settlement.updated, stock.changed, stock.reorder_needed, vat_review.opened, vat_review.resolved. OpenAPI-dokumentti luettelee ne kukin kohdassa x-webhooks.

Katso kohdasta API-käytännöt ohjeet listakyselyille, virhesanomille, idempotentille toiminnalle ja pyyntötiheyden rajoituksille (rate limits).