정산 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는 이의를 검토하고 이후 정산에 조정을 반영할 수 있습니다.

동기화 유지(폴링)

웹훅은 제공되지 않습니다. 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"