Nordlet

← Podstawy / Pakiety SDK

Pierwsze kroki

Klucze API, pierwsze wywołania, pełny cykl faktur, pakiety SDK i webhooki.

Nordlet to platforma księgowa oparta na architekturze API dla rynku UE i EOG, startująca z pełną zgodnością z przepisami litewskimi. Wszystkie funkcje produktu - fakturowanie, księga główna (general ledger), uzgadnianie wyciągów bankowych (bank reconciliation), pliki i.SAF - są dostępne za pośrednictwem jednego interfejsu API typu JSON.

1. Uzyskanie klucza API

Każde żądanie jest uwierzytelniane za pomocą klucza API przekazywanego w nagłówku Bearer i przypisanego do jednej spółki:

Authorization: Bearer nl_...

Do prac lokalnych można zainicjować spółkę oraz klucz za pomocą poleceń:

pnpm --filter @nordlet/db bootstrap:dev     # pusta spółka
pnpm --filter @nordlet/api seed:demo        # spółka z danymi demonstracyjnymi

Interaktywna dokumentacja API (specyfikacja OpenAPI dostępna pod adresem /openapi.json; lokalna instancja udostępnia tę samą dokumentację pod adresem http://localhost:3001/docs).

Postman

Wolisz korzystać z programu Postman? Zaimportuj gotową kolekcję zawierającą wszystkie punkty końcowe (endpoints) pogrupowane według modułów, z wstępnie skonfigurowaną autoryzacją typu bearer: kolekcja Nordlet dla programu Postman. Po imporcie ustaw zmienną bearerToken kolekcji na swój klucz API, a każde żądanie będzie automatycznie uwierzytelniane.

Spółki w środowisku testowym (sandbox)

Na potrzeby testów integracyjnych utworzyć spółkę z parametrem isSandbox: true (POST /v1/account/companies/create lub zaznaczając pole wyboru środowiska testowego podczas wdrażania w aplikacji). Spółka w środowisku testowym (sandbox company) zachowuje się dokładnie tak samo jak prawdziwa - ma te same moduły oraz to samo API, dzięki czemu można przesyłać przez nią realistyczną wolumenowo transakcyjność - jednak jest wyraźnie oznaczona jako dane testowe, a jej usunięcie powoduje natychmiastowe wyczyszczenie wszystkich danych zamiast oczekiwania na 10-dniowy okres retencji. W ramach tego samego konta można utworzyć dowolną liczbę spółek testowych równolegle z prawdziwą spółką. Flagi tej nie można zmienić po utworzeniu, co uniemożliwia przypadkową reklasyfikację prawdziwych ksiąg rachunkowych jako danych testowych. Korzystanie ze spółki w środowisku testowym podlega pomiarowi i fakturowaniu na takich samych zasadach jak spółka produkcyjna: uwzględnia żądania, strony skanowane w ramach odczytu dokumentów, przestrzeń dyskową oraz opłatę aktywacyjną. Deklaracje oraz e-faktury ze spółki testowej są zawsze wysyłane do testowych punktów końcowych administracji skarbowej.

2. Pierwsze wywołania

Każda operacja ma postać żądania POST /v1/{module}/{resource}/{action} z ciałem w formacie JSON. Tworzenie kontrahenta:

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"}'

Wystawianie faktury (kwoty są przekazywane jako łańcuchy znaków reprezentujące liczby dziesiętne, nigdy jako zmiennoprzecinkowe):

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"}'

Wystawienie faktury przydziela numer z ciągłej numeracji (SF-1), sprawdza, czy okres księgowy jest otwarty, oraz w ramach tej samej transakcji zapisuje zbilansowany zapis księgowy (Wn 2410 należności / Ma 5001 przychody / Ma 4492 VAT należny).

3. Pełny cykl

Krok Wywołanie
Przeniesienie ksiąg z poprzedniego systemu migration/books/validate → migration/books/import - zobacz Migracja z innego systemu
Rejestracja faktury zakupowej purchases/invoices/create → purchases/invoices/register
Import wyciągu bankowego bank/statements/import (camt.053 XML) lub bank/transactions/import (JSON)
Pobieranie sugerowanych dopasowań bank/transactions/suggest-matches
Uzgadnianie płatności bank/transactions/match - księguje płatność i aktualizuje pole paymentStatus
Płatności dla dostawców bank/payments/export - plik SEPA w formacie pain.001 dla banku
Miesięczne rejestry VAT declarations/lt/isaf/generate - plik XML i.SAF 1.2 dla VMI
Dane do deklaracji VAT declarations/lt/fr0600/compute - pozycje deklaracji FR0600 uzgodnione z rejestrami
Wydanie towaru z magazynu dokumentem WZ transport/waybills/create → issue, a następnie declarations/lt/ivaz/generate - plik XML i.VAZ dla VMI

4. Pakiet SDK dla języka TypeScript

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}`),
})

Pakiet SDK jest generowany automatycznie na podstawie aktualnej specyfikacji OpenAPI (pnpm --filter @nordlet/sdk generate), dzięki czemu każde żądanie i odpowiedź są w pełni otypowane.

5. Webhooki

Subskrybuj zdarzenia zamiast odpytywać API (polling):

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"]}'

Komunikaty doręczeń zawierają opatrzoną znacznikiem czasu sygnaturę HMAC (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> obliczoną dla ciągu <timestamp>.<raw body> przy użyciu klucza tajnego subskrypcji) obok oryginalnego nagłówka x-nordlet-signature: sha256=<hex> dla surowej treści. Próby doręczenia są ponawiane przez około 24 godziny. Okno ponawiania opisano w sekcji Konwencje API.

Ciało każdego doręczenia ma strukturę { id, version, companyId, eventType, createdAt, data }: version oznacza wersję koperty (obecnie 1), a companyId to identyfikator spółki, której dotyczy zdarzenie, dzięki czemu jeden odbiorca może obsługiwać wiele podmiotów. Subskrypcja zdarzenia spoza poniższej listy zostanie odrzucona z kodem 400; użyj wartości "*" dla wszystkich zdarzeń. Jeśli 5 kolejnych zdarzeń nie mogło zostać doręczonych, subskrypcja zostaje wstrzymana, a właściciele spółki otrzymują powiadomienie e-mail. Subskrypcję można wznowić w sekcji Account → Webhooks lub za pomocą żądania webhooks/subscriptions/update z parametrem isActive: true.

Zdarzenia: 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. Dokument OpenAPI wymienia każde z nich w sekcji x-webhooks.

Informacje na temat zapytań dotyczących list, kopert błędów, semantyki idempotentności oraz limitów częstotliwości żądań (rate limits) można znaleźć w sekcji Konwencje API.