结算 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。使用 updated_since 和可选 status 轮询 GET /v1/settlements，获取新增及变更结算。每项包含可作游标的 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"