← Документація / Посібники
Початок роботи
Ключі API, перші виклики, повний цикл виставлення рахунків, SDK та вебхуки.
Nordlet - це платформа бухгалтерського обліку, розроблена за принципом API-first, для ринку ЄС/ЄЕЗ, яка запускається з повною відповідністю законодавству Литви. Усі можливості продукту - виставлення рахунків, головна книга (general ledger), банківська звірка (bank reconciliation), i.SAF - доступні через єдиний JSON API.
1. Отримання ключа API
Кожен запит автентифікується за допомогою Bearer-ключа API, закріпленого за певною компанією:
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? Імпортуйте готову колекцію - кожен ендпоінт, згрупований за модулями, з попередньо налаштованою bearer-автентифікацією: Колекція Nordlet для Postman. Після імпорту встановіть змінну колекції bearerToken рівною вашому ключу API, і кожен запит проходитиме автентифікацію автоматично.
Компанії в пісочниці (Sandbox)
Для інтеграційного тестування створіть компанію з прапорцем isSandbox: true (POST /v1/account/companies/create або поставте галочку пісочниці під час реєстрації в застосунку). Компанія в пісочниці поводиться точно так само, як і реальна - ті самі модулі, той самий API, тож ви можете пропустити через неї реалістичний обсяг транзакцій, проте вона має помітну позначку як тестові дані, а її видалення стирає все миттєво, а не після 10-денного періоду зберігання (retention window). Ви можете запустити будь-яку кількість компаній у пісочниці паралельно з реальною компанією в межах одного облікового запису; цей прапорець неможливо змінити після створення, тому реальні облікові записи ніколи не можуть бути випадково рекласифіковані як тестові дані. Використання компанії в пісочниці тарифікується й обліковується точно так само, як і використання реальної компанії: запити, сторінки сканування документів, сховище та плата за повторну активацію. Звітність та електронні рахунки компанії в пісочниці завжди надсилаються на тестові ендпоінти контролюючих органів.
2. Перші виклики
Кожна операція виконується як POST /v1/{module}/{resource}/{action} із тілом у форматі 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"}'
Виставлення рахунка-фактури (суми є рядками десяткових чисел, ніколи не використовуйте числа з плаваючою комою):
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), перевіряє відкритість бухгалтерського періоду та в межах однієї транзакції створює збалансований бухгалтерський запис (Д-т 2410 дебіторська заборгованість / К-т 5001 дохід / К-т 4492 ПДВ).
3. Повний цикл
| Крок | Виклик |
|---|---|
| Перенесення обліку з попередньої системи | migration/books/validate → migration/books/import - див. Міграція з іншої системи |
| Реєстрація рахунка постачальника | purchases/invoices/create → purchases/invoices/register |
| Імпорт банківської виписки | bank/statements/import (camt.053 XML) або bank/transactions/import (JSON) |
| Отримання пропозицій щодо збігів | bank/transactions/suggest-matches |
| Звірка платежу | bank/transactions/match - проводить платіж та оновлює paymentStatus |
| Виплата коштів постачальникам | bank/payments/export - файл pain.001 SEPA для вашого банку |
| Щомісячні реєстри ПДВ | declarations/lt/isaf/generate - i.SAF 1.2 XML для VMI |
| Показники для декларації з ПДВ | declarations/lt/fr0600/compute - рядки FR0600, звірені з реєстрами |
| Відвантаження товарів за накладною | transport/waybills/create → issue, а потім declarations/lt/ivaz/generate - i.VAZ XML для 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), тому кожен запит і відповідь мають повну типізацію.
5. Вебхуки
Підписуйтеся на події замість використання опитувань (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> для сирого тіла запиту (raw body), а спроби їх доставки повторюються протягом приблизно 24 годин. Докладніше про вікно повторної доставки див. у розділі Угоди щодо API.
Тіло кожного повідомлення має такий формат: { id, version, companyId, eventType, createdAt, data }: version - це версія конверта (наразі 1), а companyId - ідентифікатор компанії, до якої належить подія, що дозволяє одному приймачу обслуговувати кілька компаній. Спроба підписатися на назву події, якої немає в списку нижче, відхиляється з кодом 400; використовуйте "*" для підписки на всі події. Якщо 5 подій поспіль не вдалося доставити, підписку буде призупинено, а власники компанії отримають електронний лист; відновити її можна в розділі Обліковий запис → Вебхуки або за допомогою запиту 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.
Інформацію про запити на отримання списків, конверти помилок, семантику ідемпотентності та обмеження кількості запитів (rate limits) див. у розділі Угоди щодо API.