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

API-ключи, первые вызовы, полный цикл выставления счетов, SDK и веб-хуки.

Nordlet - это бухгалтерская платформа, разработанная с расчетом на API (API-first), для рынка ЕС/ЕЭЗ, которая запускается с полной поддержкой законодательства Литвы. Все функции продукта - выставление счетов, главная книга, банковская сверка, 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 companies)

Для интеграционного тестирования создайте компанию с флагом 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. Веб-хуки

Подписывайтесь на события вместо опроса сервера:

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/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.