Ξεκινώντας

Κλειδιά API, πρώτες κλήσεις, ο πλήρης κύκλος τιμολόγησης, SDK και webhooks.

Το Nordlet είναι μια πλατφόρμα λογιστικής με επίκεντρο το API (API-first) για την αγορά της ΕΕ/ΕΟΧ, η οποία ξεκινά τη λειτουργία της με πλήρη συμμόρφωση στη λιθουανική νομοθεσία. Όλες οι λειτουργίες του προϊόντος - τιμολόγηση, γενικό καθολικό (general ledger), συμφωνία τραπεζικών λογαριασμών (bank reconciliation), i.SAF - είναι διαθέσιμες μέσω ενός ενιαίου API JSON.

1. Απόκτηση κλειδιού API

Κάθε αίτημα πιστοποιείται με ένα κλειδί API τύπου Bearer, το οποίο αντιστοιχεί σε μία μόνο εταιρεία:

Authorization: Bearer nl_...

Για την τοπική ανάπτυξη, μπορείτε να αρχικοποιήσετε μια εταιρεία και ένα κλειδί:

pnpm --filter @nordlet/db bootstrap:dev     # κενή εταιρεία
pnpm --filter @nordlet/api seed:demo        # εταιρεία με δεδομένα επίδειξης

Διατίθεται διαδραστική αναφορά API (προδιαγραφή OpenAPI στη διεύθυνση /openapi.json. Μια τοπική παρουσία παρέχει την ίδια αναφορά στη διεύθυνση http://localhost:3001/docs).

Postman

Προτιμάτε το Postman; Εισαγάγετε την έτοιμη συλλογή. Κάθε τελικό σημείο (endpoint), ομαδοποιημένο ανά ενότητα, με προδιαμορφωμένη πιστοποίηση bearer: συλλογή Postman του Nordlet. Μετά την εισαγωγή, ορίστε τη μεταβλητή bearerToken της συλλογής στο κλειδί API σας και κάθε αίτημα θα πιστοποιείται αυτόματα.

Εταιρείες δοκιμής (Sandbox)

Για δοκιμές ολοκλήρωσης (integration testing), δημιουργήστε μια εταιρεία με την παράμετρο isSandbox: true (POST /v1/account/companies/create ή επιλέξτε το πλαίσιο ελέγχου sandbox κατά την ενσωμάτωση στην εφαρμογή). Μια εταιρεία sandbox συμπεριφέρεται ακριβώς όπως μια πραγματική: διαθέτει τις ίδιες ενότητες και το ίδιο API, ώστε να μπορείτε να υποβάλετε ρεαλιστικό όγκο συναλλαγών. Ωστόσο, φέρει ευδιάκριτη σήμανση ως δεδομένα δοκιμής και η διαγραφή της διαγράφει τα πάντα άμεσα, αντί να τα διατηρεί για το διάστημα των 10 ημερών που προβλέπεται. Μπορείτε να εκτελέσετε οποιονδήποτε αριθμό εταιρειών sandbox παράλληλα με την πραγματική σας εταιρεία υπό τον ίδιο λογαριασμό. Η σημαία (flag) δεν μπορεί να τροποποιηθεί μετά τη δημιουργία, διασφαλίζοντας ότι τα πραγματικά λογιστικά βιβλία δεν μπορούν ποτέ να χαρακτηριστούν εκ των υστέρων ως δεδομένα δοκιμής. Η χρήση σε μια εταιρεία sandbox μετριέται και τιμολογείται ακριβώς όπως σε μια πραγματική εταιρεία: αιτήματα, σελίδες σάρωσης εγγράφων, αποθήκευση και τέλος επανενεργοποίησης. Οι υποβολές δηλώσεων και τα ηλεκτρονικά τιμολόγια μιας εταιρείας sandbox κατευθύνονται πάντα στα δοκιμιακά τελικά σημεία (endpoints) των φορολογικών αρχών.

2. Πρώτες κλήσεις

Κάθε λειτουργία εκτελείται ως POST /v1/{module}/{resource}/{action} με σώμα (body) JSON. Δημιουργία πελάτη:

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

Έκδοση τιμολογίου (τα ποσά είναι συμβολοσειρές δεκαδικών αριθμών, ποτέ τύπου float):

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

Η έκδοση εκχωρεί έναν συνεχή αριθμό χωρίς κενά (SF-1), ελέγχει ότι η λογιστική περίοδος είναι ανοιχτή και καταχωρεί την ισoσκελισμένη εγγραφή ημερολογίου (Χρέωση 2410 απαιτήσεις / Πίστωση 5001 έσοδα / Πίστωση 4492 ΦΠΑ) στην ίδια συναλλαγή.

3. Ο πλήρης κύκλος

Βήμα	Κλήση
Μεταφορά βιβλίων από προηγούμενο σύστημα	`migration/books/validate` → `migration/books/import` - δείτε την ενότητα Μετανάστευση από άλλο σύστημα
Καταχώριση τιμολογίου προμηθευτή	`purchases/invoices/create` → `purchases/invoices/register`
Εισαγωγή τραπεζικής κίνησης	`bank/statements/import` (XML camt.053) ή `bank/transactions/import` (JSON)
Λήψη προτάσεων αντιστοίχισης	`bank/transactions/suggest-matches`
Συμφωνία πληρωμής	`bank/transactions/match` - καταχωρεί την πληρωμή και ενημερώνει το πεδίο `paymentStatus`
Πληρωμή προμηθευτών	`bank/payments/export` - αρχείο SEPA pain.001 για την τράπεζά σας
Μηνιαία βιβλία ΦΠΑ	`declarations/lt/isaf/generate` - XML i.SAF 1.2 για την VMI
Στοιχεία περιοδικής δήλωσης ΦΠΑ	`declarations/lt/fr0600/compute` - πεδία FR0600 συμφωνημένα με τα βιβλία
Διακίνηση αγαθών με δελτίο αποστολής	`transport/waybills/create` → `issue`, και στη συνέχεια `declarations/lt/ivaz/generate` - XML i.VAZ για την 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 παράγεται αυτόματα από την τρέχουσα προδιαγραφή OpenAPI (pnpm --filter @nordlet/sdk generate), οπότε κάθε αίτημα και απόκριση διαθέτει πλήρη τύπο δεδομένων (fully typed).

5. Webhooks

Εγγραφείτε σε συμβάντα αντί να εκτελείτε περιοδικά αιτήματα (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"]}'

Τα μηνύματα παράδοσης περιέχουν μια υπογραφή HMAC με χρονική σήμανση (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> επί του <timestamp>.<raw body> με το μυστικό της συνδρομής σας) δίπλα στην αρχική x-nordlet-signature: sha256=<hex> του ακατέργαστου σώματος, και επαναλαμβάνονται για περίπου 24 ώρες. Δείτε την ενότητα Συμβάσεις API για το παράθυρο επανάληψης αποστολής.

Το σώμα κάθε παράδοσης έχει τη μορφή { id, version, companyId, eventType, createdAt, data }: το πεδίο version είναι η έκδοση του φακέλου (επί του παρόντος 1) και το companyId είναι η εταιρεία στην οποία ανήκει το συμβάν, ώστε ένας δέκτης να μπορεί να εξυπηρετεί πολλές εταιρείες. Η εγγραφή σε όνομα που δεν περιλαμβάνεται στην παρακάτω λίστα απορρίπτεται με κωδικό 400. Χρησιμοποιήστε το "*" για όλα τα συμβάντα. Εάν 5 διαδοχικά συμβάντα δεν μπορέσουν να παραδοθούν, η συνδρομή τίθεται σε παύση και οι ιδιοκτήτες της εταιρείας λαμβάνουν μήνυμα ηλεκτρονικού ταχυδρομείου. Μπορείτε να την επανενεργοποιήσετε στην ενότητα Λογαριασμός → Webhooks ή μέσω της κλήσης webhooks/subscriptions/update με την παράμετρο isActive: true.

Συμβάντα: 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 παραθέτει κάθε συμβάν στην ενότητα x-webhooks.

Ανατρέξτε στις Συμβάσεις API για ερωτήματα λίστας (list queries), φάκελους σφαλμάτων, σημασιολογία ταυτότητας (idempotency semantics) και όρια ρυθμού κλήσεων (rate limits).