Nordlet

← 文档 / 指南

入门指南

API 密钥、首次调用、完整开票周期、SDK 和 Webhook。

Nordlet 是一个面向欧盟/欧洲经济区（EEA）市场的 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 密钥，即可对每个请求进行身份验证。

沙箱公司

若要进行集成测试，您可以创建一个将 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 - 为立陶宛国家税务局（VMI）生成 i.SAF 1.2 XML
增值税申报数据 declarations/lt/fr0600/compute - 根据明细账核对 FR0600 报表字段
凭运单发货 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 签名（x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>，使用您的订阅密钥对 <timestamp>.<raw body> 进行签名），并且失败后会重试约 24 小时。有关重放时间范围的说明，请参见API 约定。

每个投递的请求体格式为 { id, version, companyId, eventType, createdAt, data }：version 是信封版本（当前为 1），companyId 是事件所属的公司，因此单个接收端可以服务多家公司。订阅列表中不存在的事件名称将被拒绝并返回 400 错误；若要订阅所有事件，请使用 "*"。如果连续 5 个事件无法投递，订阅将暂停，并且公司所有者会收到一封电子邮件；您可以在“账户 -> 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 下列出了每一项。

有关列表查询、错误信封、幂等性语义和速率限制的详细信息，请参见API 约定。