はじめに

Nordlet は、EU および EEA 市場向けの API ファーストの会計プラットフォームであり、リトアニアの法規制に完全に準拠した状態で提供を開始します。請求書発行、総勘定元帳 (general ledger)、銀行口座照合 (bank reconciliation)、i.SAF など、このプロダクトのすべての機能は、単一の JSON API を介して利用できます。

1. API キーの取得

すべてのリクエストは、1 つの企業にスコープされた 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 キーを設定すると、すべてのリクエストが認証されます。

サンドボックス企業

統合テストを行うには、isSandbox: true を指定して企業を作成します（POST /v1/account/companies/create、またはアプリでのオンボーディング時にサンドボックスのチェックボックスをオンにします）。サンドボックス企業は実際の企業とまったく同様に動作します（同じモジュール、同じ API を使用するため、現実的なトランザクション量を流し込むことができます）。ただし、テストデータであることが視覚的に表示され、削除すると 10 日間の保持期間を待たずに即座にすべてのデータが完全に消去されます。同じアカウントのもとで、実際の企業と並行して任意の数のサンドボックス企業を稼働させることができます。このフラグは作成後に変更できないため、実際の帳簿がテストデータにこっそり再分類されることはありません。サンドボックス企業での利用量は、実際の企業での利用量と同様に測定および課金されます（リクエスト、書類スキャンページ、ストレージ、および再有効化手数料）。サンドボックス企業の申告書や電子インボイス (e-invoice) は、常に行政のテスト用エンドポイントに送信されます。

2. 最初の呼び出し

すべての操作は、JSON ボディを指定した POST /v1/{module}/{resource}/{action} です。取引先 (partner) を作成します。

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 - 別のシステムからの移行を参照
仕入先請求書 (supplier bill) を登録する	purchases/invoices/create → purchases/invoices/register
銀行取引明細書 (bank statement) をインポートする	bank/statements/import（camt.053 XML）または bank/transactions/import（JSON）
消込候補の提案を取得する	bank/transactions/suggest-matches
入金の消込 (reconcile) を行う	bank/transactions/match - 支払いを計上し、paymentStatus を更新します
仕入先に支払う	bank/payments/export - お使いの銀行向けの pain.001 SEPA ファイル
月次 VAT 登録簿	declarations/lt/isaf/generate - VMI 向けの i.SAF 1.2 XML
VAT 申告書の数値	declarations/lt/fr0600/compute - 登録簿と突合された FR0600 の項目
納品書 (waybill) を伴う商品の出荷	transport/waybills/create → issue、続いて declarations/lt/ivaz/generate - VMI 向けの i.VAZ XML

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

ポーリングの代わりにイベントを購読します。

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

配信には、元の生データの x-nordlet-signature: sha256=<hex> に加え、タイムスタンプ付きの HMAC 署名（購読シークレットを使用した <timestamp>.<raw body> に対する x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>）が付与され、約 24 時間にわたって再試行されます。リプレイウィンドウについては、API 規約を参照してください。

各配信のボディは { id, version, companyId, eventType, createdAt, data です。version はエンベロープのバージョン（現在は 1）、companyId はイベントが属する企業であるため、1 つのレシーバーで複数の企業にサービスを提供できます。以下のリストにない名前を購読しようとすると 400 エラーで拒否されます。すべてのイベントを対象にするには "*" を使用してください。イベントの配信失敗が 5 回連続すると、購読は一時停止され、企業のオーナーにメールが送信されます。「アカウント (Account)」 > 「Webhook」または 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 の下でリストされています。

リストクエリ、エラーエンベロープ、べき等性（idempotency）のセマンティクス、およびレートリミットについては、API 規約を参照してください。