API 規約

リクエストの形式、認証スコープ、一覧クエリ、金額、エラー、冪等性、レートリミット。

リクエストの形式

すべての操作は RPC スタイルの POST です:

POST /v1/{module}/{resource}/{action}

モジュール: reference、partners、catalog、sales、purchases、ledger、bank、declarations、files、webhooks、audit。アクションは動詞です: create、get、update、delete、list に加え、issue、register、match、apply-advance、generate などのドメイン固有のアクションがあります。

認証とスコープ

Authorization: Bearer <api key>。キーには、アクションごとに検証されるスコープが付与されます:

{module}:read - 取得および一覧系のアクション
{module}:write - 変更系のアクション
{module}:* または * - ワイルドカード

スコープが不足している場合は 403 forbidden、キーがないか無効な場合は 401 unauthorized が返されます。

一覧クエリ

すべての list アクションは共通の契約を共有します:

{
  "page": 1,
  "pageSize": 50,
  "sort": [{ "field": "createdAt", "dir": "desc" }],
  "filter": [{ "field": "paymentStatus", "op": "eq", "value": "unpaid" }]
}

フィルター演算子: eq (等しい)、ne (等しくない)、contains (大文字小文字を区別しないテキスト一致、テキストフィールドのみ)、gte (以上)、lte (以下)、in (最大 500 個の値のリストのいずれか)。ソートおよびフィルター可能なフィールドは、エンドポイントごとにホワイトリストに登録されています (OpenAPI 仕様を参照)。不明なフィールドを指定すると 400 が返されます。リクエストに totals: ["field", …] を追加すると、条件に一致するすべての行にわたって数値フィールドを集計できます。レコードに通貨が含まれている場合、totalsByCurrency によって通貨コード別に分割された同じ集計結果が得られます。レスポンス: { rows, total, page, pageSize, totals?, totalsByCurrency? }.

金額と日付

金額は、最大 4 桁の小数部を持つ十進数の文字列表現 ("121.0000") であり、浮動小数点数ではありません。消費税 (VAT) は、明細ごとに四捨五入 (half-up rounding) で計算されます。日付は YYYY-MM-DD、タイムスタンプは ISO 8601 形式の UTC です。

エラー

すべてのエラーは統一されたエンベロープで返されます:

{
  "error": {
    "code": "validation",
    "message": "Request validation failed",
    "requestId": "k1x…",
    "key": "request_invalid",
    "fieldErrors": { "lines.0.unitPriceExclVat": ["Invalid value"] }
  }
}

コード: validation (400 および 422、アップロードされたファイルやリクエストボディが大きすぎる場合は 413)、unauthorized (401)、payment_required (402、試用期間または前払いクレジットが終了しています。メッセージに継続方法が記載されます)、forbidden (403)、not_found (404)、conflict (409)、idempotency_key_reuse (422)、idempotency_in_progress (409)、rate_limited (429)、internal (5xx)。メッセージが固定メッセージのいずれかである場合、クライアントが独自の翻訳を表示できるように key で名前が指定され、params にそこに挿入される値が保持されます (例えば、ロックされた会計期間の場合は { "period": "2026-09" })。問題を報告する際は requestId を含めてください。

冪等性

変更を伴うすべての呼び出しに Idempotency-Key: <any string ≤255 chars> を追加します:

同じキーとペイロードでリトライした場合、保存されたレスポンスが x-idempotent-replay: true とともにバイト単位でそのまま再生されます。
同じキーで異なるペイロードを指定した場合、422 idempotency_key_reuse が返されます。
最初のリクエストの処理中に同時に重複リクエストが行われた場合、409 idempotency_in_progress が返されます。
キーは、呼び出し対象の企業内で、それを送信した API キーまたはユーザーに紐づくため、1つの企業の複数の連携機能で同じキーを使用できます。企業が存在する前に行われた呼び出しおよび account/* の呼び出しでは、キーはユーザー単位で保持されるため、繰り返し行われた account/companies/create は 1 つの企業のみを作成します。
保存されたレスポンスは、呼び出し元が再度同一の権限チェック (スコープ、ロール、企業、および請求ステータス) を通過した後にのみ返されます。そうでない場合、呼び出しには現在のエラーが返されます。
キーは 24 時間後に有効期限が切れます。エラーレスポンス (4xx) も再生されますが、5xx のレスポンスは保存されないため、リトライ時は再実行されます。

レートリミット

API キーごとに 1 分あたり 300 リクエスト (提示された認証情報ごと。認証されていないリクエストは IP ごとに制限されます)。429 が返された場合は、retry-after ヘッダーに従ってください。制限の残量については x-ratelimit-* ヘッダーで通知されます。

Webhook

イベントは、変更と同じデータベーストランザクション内でトランザクション型の送信トレイ (outbox) に書き込まれます。ロールバックされたドキュメントからイベントが発火されることはなく、イベントが失われることもありません。配信仕様:

イベントの JSON を指定された URL に POST 送信
x-nordlet-timestamp: <unix seconds> (配信が署名された時刻)
x-nordlet-signature-v2: t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>"> (サブスクリプションシークレットを使用)
x-nordlet-signature: sha256=<hex HMAC-SHA256 of the raw body> (既存の受信側との互換性のため維持)
x-nordlet-delivery (配信 ID を保持し、同一配信のリトライでは常に同じ値になります)
2xx 以外の応答またはリダイレクトがあった場合、30 秒後、2 分後、10 分後、30 分後、1 時間後、3 時間後、6 時間後、12 時間後 (合計でおよそ 24 時間) にリトライされ、その後配信は失敗としてマークされます
各配信は一度に 1 つのサーバーから送信されるため、複数の API インスタンスを実行しても重複して送信されることはありません

ペイロードを信頼する前に定数時間比較 (constant-time comparison) を用いて x-nordlet-signature-v2 を検証し、タイムスタンプが自社の時計から 5 分以上離れている配信は拒否してください。タイムスタンプは署名対象のテキストの一部であるため、キャプチャされた配信を後から新しいタイムスタンプで再送 (リプレイ) することはできません。処理済みの x-nordlet-delivery ID を保存することで、その期間内の重複を無視してください。失敗した配信は webhooks/deliveries/redeliver を使用して再送信できます。

監査

すべての変更操作が記録され (actor、action、entity、diff)、audit/list を通じて照会可能です。

会計上の保証

仕訳の貸借は常に一致します。アプリケーションコードだけでなく、コミット時の遅延データベーストリガーによって強制されます。
伝票番号は、シリーズ/年度ごとに欠番なく採番されます。割り当ては同時実行安全性 (concurrency-safe) が確保されています。
ロックされた会計期間に対する日付の仕訳や伝票の起票は拒否されます (409)。
論理削除された伝票の監査証跡は保持されます。発行済みまたは登録済みの伝票を削除することはできません。