発注・取引先API

GET /api/v1/orders

発注の一覧を取得します（明細は含みません）。

必要なスコープ: orders:read

レスポンス

{
  "object": "list",
  "data": [
    {
      "object": "order",
      "id": "clxxx...",
      "order_number": "PO-2026-0123",
      "order_kind": "CUT",
      "status": "DELIVERED",
      "project_id": "clxxx...",
      "episode_id": "clxxx...",
      "vendor": { "id": "clxxx...", "name": "取引先名" },
      "process_type": "KEY_ANIMATION",
      "process_label": "原画",
      "master_part": null,
      "order_group_id": null,
      "order_date": "2026-11-01T00:00:00.000Z",
      "due_date": "2026-11-20T00:00:00.000Z",
      "sent_at": "2026-11-01T03:00:00.000Z",
      "vendor_accepted_at": "2026-11-01T05:00:00.000Z",
      "vendor_declined_at": null,
      "delivered_at": "2026-11-18T09:00:00.000Z",
      "cancelled_at": null,
      "invoice_id": null,
      "adjustment_for_order_id": null,
      "is_provisional_amount": false,
      "created_at": "2026-11-01T00:00:00.000Z",
      "updated_at": "2026-11-18T09:00:00.000Z",
      "amounts": {
        "currency": "JPY",
        "tax_included": true,
        "tax_rate": 0.1,
        "withholding_applied": true,
        "subtotal": 100000,
        "consumption_tax": 10000,
        "withholding_tax": 10210,
        "gross_amount": 110000,
        "total_amount": 99790
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

• ●並びは作成日時の古い順です。has_more が true のときは next_cursor を starting_after に渡して続きを取ります。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。
• ●status は発注全体の状態です（明細の状態は GET /api/v1/orders/{id} の items[].delivery_status）。

GET /api/v1/orders/[id]

発注1件を、明細・取引先の受諾/差し戻しの記録・発注書の明示事項・取消とあわせて取得します。

必要なスコープ: orders:read

レスポンス

{
  "data": {
    "object": "order",
    "id": "clxxx...",
    "order_number": "PO-2026-0123",
    "status": "DELIVERED",
    "…": "一覧と同じ項目",
    "adjustment_order_id": null,
    "terms": {
      "receipt_place": "電子データで納品",
      "inspection_days": 10,
      "inspection_due_date": "2026-11-30T00:00:00.000Z",
      "payment_due_date": "2026-12-31T00:00:00.000Z",
      "check_period_days": 3,
      "correction_period_days": 3,
      "quality_standard": "…",
      "rights_handling": "…",
      "cancellation_policy": "…"
    },
    "cancellation": null,
    "items": [
      {
        "object": "order_item",
        "id": "clxxx...",
        "process_id": "clxxx...",
        "cut_number": "C-001",
        "description": null,
        "seconds": 3.5,
        "sheets": 12,
        "delivery_status": "DELIVERED",
        "delivered_at": "2026-11-18T09:00:00.000Z",
        "confirmed_at": null,
        "invoice_id": null,
        "worker_id": null,
        "amounts": { "unit_price": 3800, "tax_rate": null, "invoiced_gross": null }
      }
    ],
    "vendor_responses": [
      { "id": "clxxx...", "action": "ACCEPTED", "channel": "PORTAL", "effective": true, "reason": null, "responded_at": "2026-11-01T05:00:00.000Z" }
    ]
  }
}

• ●パスパラメータ id は発注ID。APIキーの組織に属さない発注は 404 になります。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。
• ●terms は発注書を発行した時点の値です（組織の設定を後から変えても変わりません）。発行前の発注では null の項目があります。
• ●vendor_responses の effective が false の行は、先に別の返答が通った後に届いた返答の記録です。

GET /api/v1/vendors

取引先（社外の名簿、または発注先になったことがある名簿）の一覧を取得します。

必要なスコープ: vendors:read

レスポンス

{
  "object": "list",
  "data": [
    {
      "object": "vendor",
      "id": "clxxx...",
      "name": "取引先名",
      "company_name": null,
      "is_individual": true,
      "is_external": true,
      "contract_type": "SUBCONTRACT",
      "tax_status": "TAXABLE",
      "invoice_registration_number": "T1234567890123",
      "deactivated_at": null,
      "created_at": "2026-01-15T00:00:00.000Z",
      "updated_at": "2026-01-15T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

• ●並びは作成日時の古い順です。has_more が true のときは next_cursor を starting_after に渡して続きを取ります。
• ●メールアドレス・電話番号・振込口座は返しません。
• ●発注・請求書の vendor.id はこの一覧の id と同じです。

POST /api/v1/orders/[id]/items/[itemId]/delivery

発注明細の納品・検収を記録します。記録日はリクエストを受け取った時刻です。

必要なスコープ: orders:write

リクエスト

{
  "status": "CONFIRMED"   // DELIVERED（納品）または CONFIRMED（検収）
}

レスポンス

{
  "data": {
    "object": "order_item",
    "id": "clxxx...",
    "process_id": "clxxx...",
    "cut_number": "C-001",
    "description": null,
    "seconds": 3.5,
    "sheets": 12,
    "delivery_status": "CONFIRMED",
    "delivered_at": "2026-11-18T09:00:00.000Z",
    "confirmed_at": "2026-11-20T03:00:00.000Z",
    "invoice_id": null,
    "worker_id": null
  },
  "order": { "id": "clxxx...", "status": "CONFIRMED" },
  "changed": true,
  "process_sync": { "completed": ["clxxx..."], "reverted": [] }
}

• ●Idempotency-Key ヘッダが必須です。
• ●記録できるのは前へ進む向きだけです（PENDING → DELIVERED → CONFIRMED）。未納品から検収への直行・検収の取消・未納品への差し戻しは 409（INVALID_DELIVERY_TRANSITION）です。取消・差し戻しは画面で行います。
• ●納品日・検収日は AnimaTime がリクエストを受け取った時刻で記録します。日付は指定できません（delivered_at などを送ると 400 DATE_NOT_ACCEPTED）。
• ●取消済みの発注の明細は 409（ORDER_CANCELLED）、月次締め済みの月に帰属する発注・締め済みの月に入る検収は 409（MONTH_CLOSED）です。
• ●すでに同じ状態の明細には何もせず、changed: false を返します。
• ●画面での納品・検収と同じく、明細が覆う工程の状態も合わせて更新します（process_sync に更新した工程の ID）。発注全体が検収済みになると order.confirmed イベントが飛びます（actor.type は api_key）。
• ●記録は監査ログに「API: キーの名前」として残ります。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。

POST /api/v1/order-approval-requests

発注の承認依頼を作成します。発注書の発行・取引先への送付は行いません（オーナー/管理者が画面で承認すると発行されます）。

必要なスコープ: orders:write

リクエスト

{
  "episode_id": "clxxx...",          // 話数ID（必須）
  "vendor_id": "clxxx...",           // 取引先ID（GET /api/v1/vendors の id）。vendor_name とどちらか必須
  "vendor_name": "取引先名",         // 名簿に無い発注先（組織で自由入力を許可しているときだけ）
  "process_type": "KEY_ANIMATION",   // 工程（必須）。カスタム工程は custom_step_id も
  "order_kind": "CUT",               // CUT（カット単位・既定）または MASTER（話数まるごと）
  "due_date": "2026-12-10",          // 任意: 納品予定日
  "items": [                         // 1〜200件
    { "process_id": "clxxx...", "cut_number": "C-001", "sheets": 12, "unit_price": 3800 }
  ]
}

レスポンス

{
  "data": {
    "object": "order_approval_request",
    "id": "clxxx...",
    "status": "PENDING",
    "episode_id": "clxxx...",
    "vendor": { "id": "clxxx...", "name": "取引先名" },
    "process_type": "KEY_ANIMATION",
    "order_kind": "CUT",
    "master_part": null,
    "due_date": "2026-12-10",
    "item_count": 1,
    "price_deviations": [],
    "requested_by": { "type": "api_key", "name": "API: 制作管理ツール" },
    "order_id": null,
    "reject_reason": null,
    "decided_at": null,
    "created_at": "2026-11-05T03:00:00.000Z",
    "updated_at": "2026-11-05T03:00:00.000Z"
  }
}

• ●Idempotency-Key ヘッダが必須です。作成できたときは 201 です。
• ●API で作れるのは承認依頼までです。単価が基準単価どおりでも必ず承認待ちになり、オーナー/管理者が画面で承認すると、承認した人の名義で発注が発行されます（order_approval_request.approved と order.created のイベント）。取引先への送付も画面で行います。
• ●入力の検証は画面の発注作成と同じです。拒否の code は画面と同じ理由を大文字にしたものです: MISSING_FIELDS / INVALID_AMOUNT / FOREIGN_WORKER / EPISODE_NOT_FOUND（404）/ INVALID_MASTER_CATEGORY / INVALID_MASTER_PART / MASTER_AMOUNT_REQUIRED / ZERO_AMOUNT / INVALID_PROCESS / PROCESS_TYPE_MISMATCH / DUPLICATE_ORDER（409・すでに発注済みの工程）/ VENDOR_STAFF_NOT_FOUND（404）/ VENDOR_FREE_INPUT_DISABLED / INVALID_RECEIPT_PLACE / CHECK_PERIOD_EXCEEDS_PAYMENT_SITE。
• ●同じ話数・発注先・工程・パートのマスター発注の承認待ちがすでにあると 409（DUPLICATE_APPROVAL_REQUEST）です。
• ●明細の項目は process_id / cut_number / description / seconds / sheets / unit_price / notes / worker_id（実作業者のスタッフID）です。ほかに check_period_days / correction_period_days / due_time（HH:MM）/ master_part / notes / quality_standard / rights_handling / price_negotiation_note / cancellation_policy / receipt_place / is_provisional_amount / tax_included / withholding / withholding_is_individual を送れます（意味は画面の発注フォームと同じ）。
• ●依頼は監査ログに「API: キーの名前」として残り、承認できる人にアプリ内通知が届きます。
• ●金額（amounts）は amounts:read スコープを持つキーにだけ返します。組織で請求・支払の機能が使えない場合は付けても返しません。金額は発行時に保存した値で、再計算しません。

GET /api/v1/order-approval-requests/[id]

発注の承認依頼1件を取得します（承認・却下の結果と、承認で発行された発注の ID）。

必要なスコープ: orders:read

レスポンス

{
  "data": {
    "object": "order_approval_request",
    "id": "clxxx...",
    "status": "APPROVED",
    "…": "POST /api/v1/order-approval-requests の応答と同じ項目",
    "order_id": "clxxx...",
    "decided_at": "2026-11-05T05:00:00.000Z"
  }
}

• ●status は PENDING（承認待ち）/ APPROVED（承認済み・order_id に発行された発注）/ REJECTED（却下・reject_reason に理由）です。
• ●画面で作られた承認申請（単価が基準単価から外れた発注）も取れます。その場合 requested_by.type は user で、名前は返しません。
• ●price_deviations は基準単価から外れた明細（cut_number と direction: above / below）です。単価（standard_price / actual_price）と依頼額（amounts.total_amount）は amounts:read のキーにだけ返します。
• ●APIキーの組織に属さない依頼は 404 になります。