受領請求書API

GET /api/v1/invoices

取引先から受け取った請求書（受領請求書）の一覧を取得します。

必要なスコープ: invoices:read

レスポンス

{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "clxxx...",
      "invoice_number": "INV-0042",
      "vendor": { "id": "clxxx...", "name": "取引先名" },
      "status": "UNPAID",
      "issue_date": "2026-11-30T00:00:00.000Z",
      "due_date": "2026-12-31T00:00:00.000Z",
      "paid_at": null,
      "payment_instructed_at": "2026-12-20T01:00:00.000Z",
      "scheduled_transfer_date": "2026-12-25T00:00:00.000Z",
      "has_file": true,
      "created_at": "2026-12-01T00:00:00.000Z",
      "updated_at": "2026-12-20T01:00:00.000Z",
      "amounts": { "currency": "JPY", "amount": 110000 }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

• ●並びは作成日時の古い順です。has_more が true のときは next_cursor を starting_after に渡して続きを取ります。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。

GET /api/v1/invoices/[id]

受領請求書1件を、消込先（紐付けた発注・明細）とあわせて取得します。

必要なスコープ: invoices:read

レスポンス

{
  "data": {
    "object": "invoice",
    "id": "clxxx...",
    "…": "一覧と同じ項目",
    "order_ids": ["clxxx..."],
    "order_items": [{ "id": "clxxx...", "order_id": "clxxx..." }]
  }
}

• ●パスパラメータ id は請求書ID。APIキーの組織に属さない請求書は 404 になります。
• ●order_ids は発注ごと（全額）の紐付け、order_items は明細ごと（分納の一部）の紐付けです。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。

POST /api/v1/invoices

取引先から受け取った請求書（受領請求書）を登録します。発注・明細への紐付け（消込）も同時にできます。

必要なスコープ: invoices:write

リクエスト

{
  "vendor_id": "clxxx...",          // 取引先ID（GET /api/v1/vendors の id）。vendor_name とどちらか必須
  "vendor_name": "取引先名",        // 名簿に無い請求元（組織で自由入力を許可しているときだけ）
  "amount": 110000,                 // 請求額（円・税込・源泉控除前）
  "invoice_number": "INV-0042",     // 任意
  "issue_date": "2026-11-30",       // 任意
  "due_date": "2026-12-31",         // 任意（省くと紐付けた発注の支払期日）
  "notes": "…",                     // 任意
  "order_ids": ["clxxx..."],        // 任意: 発注ごとに紐付け
  "order_item_ids": ["clxxx..."]    // 任意: 明細ごとに紐付け（分納の一部）
}

レスポンス

{
  "data": {
    "object": "invoice",
    "id": "clxxx...",
    "…": "GET /api/v1/invoices/{id} と同じ項目",
    "order_ids": ["clxxx..."],
    "order_items": []
  },
  "link_result": {
    "linked": true,
    "auto_linked": false,
    "candidates": [],
    "duplicate_warnings": []
  }
}

• ●Idempotency-Key ヘッダが必須です。登録できたときは 201、同じキーの再送（登録済み）は 200 で同じ請求書を返します。
• ●同じ請求元・同じ請求書番号の請求書がすでにあると 409（DUPLICATE_INVOICE_NUMBER）です。
• ●請求額が紐付けた発注・明細の金額と一致しないと 422（AMOUNT_MISMATCH）です。差額はマイナス伝票（画面）で調整してください。
• ●支払期日が月次締め済みの月だと 409（MONTH_CLOSED）です。
• ●order_ids・order_item_ids をどちらも省くと、画面での登録と同じく、同じ取引先の発注のうち金額が一つだけ一致するものへ自動で紐付けます（link_result.auto_linked が true）。一致が一つに決まらないときは紐付けず、候補を link_result.candidates に返します。
• ●link_result.duplicate_warnings は二重登録の疑い（番号の打ち間違い・近い期間の同額）です。登録は成立しています。
• ●支払指示・支払済の記録は API では行えません。

POST /api/v1/invoices/[id]/links

受領請求書の消込先（紐付ける発注・明細）を、指定したものに置き換えます。

必要なスコープ: invoices:write

リクエスト

{
  "order_ids": ["clxxx..."],        // 発注ごとに紐付け
  "order_item_ids": []              // 明細ごとに紐付け（分納の一部）
}

レスポンス

{
  "data": {
    "object": "invoice",
    "id": "clxxx...",
    "…": "GET /api/v1/invoices/{id} と同じ項目",
    "order_ids": ["clxxx..."],
    "order_items": []
  }
}

• ●Idempotency-Key ヘッダが必須です。
• ●今の紐付けは全部外れ、指定したものだけになります（省いた方の種類も空にします）。両方を空にすると紐付けを外します。
• ●未納品の発注・取消済みの発注・他の請求書に紐付いた発注は紐付けられません（400）。請求額と一致しないと 422（AMOUNT_MISMATCH）です。
• ●支払済の請求書は 409（INVOICE_PAID）、月次締め済みの月の請求書は 409（MONTH_CLOSED）です。