Начало на работа

API ключове, първи заявки, пълният цикъл на фактуриране, SDK и уебхукове.

Nordlet е счетоводна платформа с водещо API за пазара на ЕС/ЕИП, стартираща с пълно съответствие с литовското законодателство. Всичко, което продуктът прави - фактуриране, главна книга (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 справка (API reference) (OpenAPI спецификация на адрес /openapi.json; локална инстанция предоставя същата справка на http://localhost:3001/docs).

Postman

Предпочитате Postman? Импортирайте готовата колекция - всеки ендпоинт (endpoint), групов по модули, с предварително настроено Bearer удостоверяване: Nordlet Postman collection. След импортиране задайте на променливата bearerToken на колекцията вашия API ключ и всяка заявка ще бъде автентикирана.

Тестови компании (Sandbox)

За целите на интеграционното тестване създайте компания с isSandbox: true (POST /v1/account/companies/create или поставете отметка в квадратчето за тестова среда по време на регистрацията в приложението). Една тестова компания функционира точно като реална - със същите модули и същото API, което ви позволява да преминете през реален обем от транзакции - но тя е видимо обозначена като тестови данни, а изтриването ѝ премахва всичко незабавно, вместо след 10-дневния срок за съхранение. Можете да стартирате произволен брой тестови компании успоредно с реалната си компания в рамките на един и същ акаунт; флагът е неизменен след създаването, така че реалните счетоводни регистри никога да не могат да бъдат прекласифицирани тихо като тестови данни. Използването в тестова компания се отчита и таксува точно както в реална компания: заявки, страници за сканиране на документи, съхранение и такса за реактивиране. Данъчните декларации и електронните фактури на тестовата компания винаги се изпращат към тестовите ендпоинти на администрацията.

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. Уебхукове (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 неуспешни опита за доставка подред, абонаментът се поставя на пауза и собствениците на компанията получават имейл; можете да го възобновите в Акаунт → Уебхукове (Account → 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 конвенции за заявки за списъци, обвивки за грешки, семантика на идемпотентността (idempotency) и лимити на заявките (rate limits).