精算API

月次精算を確認し、明細を調べ、不一致に異議を申し立てます。参照にはsettlement:read、異議にはsettlement:disputeが必要です。すべて実金融データを扱うためnsp_live_ Productionキーのみ受け付け、Sandboxは403 production_key_requiredを返します。パートナーにはpending_review以降だけが表示され、内部のdraftとcalculatedは非表示です。

エンドポイント

メソッド	パス	スコープ	用途
GET	`/settlements`	`settlement:read`	精算一覧をstatusとupdated_sinceで絞り込みます。
GET	`/settlements/{id}`	`settlement:read`	精算詳細です。
GET	`/settlements/{id}/items`	`settlement:read`	タイトル、エピソード、国別の明細です。
POST	`/settlements/{id}/dispute`	`settlement:dispute`	異議を申し立てます。

一覧と詳細

curl "https://signal-partners.newunivers.ai/v1/settlements?status=approved&updated_since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_id": "stl_2026_05",
      "period": "2026-05",
      "currency": "USD",
      "gross_revenue": 120000.00,
      "net_revenue": 76100.00,
      "nu_share": 49465.00,
      "partner_share": 26635.00,
      "status": "approved",
      "updated_at": "2026-06-24T00:00:00Z"
    }
  ]
}

一覧は精算ごとの要約を返します。すべての控除を見るには単一精算を取得してください。

{
  "data": {
    "settlement_id": "stl_2026_05",
    "period": "2026-05",
    "currency": "USD",
    "gross_revenue": 120000.00,
    "refunds": 1500.00,
    "platform_fee": 12000.00,
    "payment_processing_fee": 3400.00,
    "tax_withholding": 2000.00,
    "mg_recouped": 25000.00,
    "net_revenue": 76100.00,
    "nu_share": 49465.00,
    "partner_share": 26635.00,
    "rights_holder_share": 0.00,
    "status": "approved",
    "updated_at": "2026-06-24T00:00:00Z"
  }
}

精算フィールド

フィールド	意味
`gross_revenue`	精算対象イベントの総売上
`refunds`	負の売上イベントによる取消し
`platform_fee`	NUプラットフォーム料金
`payment_processing_fee`	決済処理費用
`tax_withholding`	源泉徴収税
`mg_recouped`	期間中に回収された最低保証（MG）
`net_revenue`	返金、手数料、税、MG回収後の売上
`nu_share / partner_share`	契約の収益分配率によるnet_revenueの配分
`rights_holder_share`	net_revenueの権利者分（詳細のみ）

控除フィールド（refunds、platform_fee、payment_processing_fee、tax_withholding、mg_recouped、rights_holder_share）は一覧ではなく詳細エンドポイントだけで返されます。

periodはYYYY-MM形式です。

精算明細

curl "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/items" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_item_id": "sti_001",
      "title_id": "ttl_abc",
      "episode_id": "ep_001",
      "country": "KR",
      "revenue_type": "payment_completed",
      "gross_revenue": 4200.00,
      "net_revenue": 2730.00,
      "nu_share": 1774.50,
      "partner_share": 955.50,
      "rights_holder_share": 0.00
    }
  ]
}

明細は精算書をtitle_id、episode_id、country、revenue_type別に分解し、送信イベントと照合できるようにします。

異議申立てフロー

精算は支払期限前のpending_review、approved、invoiced状態でのみ異議申立てできます。それ以外は409 settlement_not_disputableを返します。

curl -X POST "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/dispute" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%",
    "disputed_amount": 820.00,
    "currency": "USD"
  }'

{
  "data": {
    "dispute_id": "dsp_001",
    "settlement_id": "stl_2026_05",
    "status": "open",
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%"
  }
}

NUが異議を審査し、後の精算で調整する場合があります。

同期を維持（ポーリング）

Webhookはありません。GET /v1/settlementsをupdated_sinceと任意のstatusでポーリングし、新規・変更済み精算を取得します。各項目にはカーソル用のupdated_atがあります。

curl "https://signal-partners.newunivers.ai/v1/settlements?updated_since=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"