정산 API

월별 정산을 검토하고, 정산 항목을 상세히 살펴보며, 불일치에 대해 이의를 제기합니다. 조회에는 settlement:read가, 이의 제기에는 settlement:dispute가 필요합니다.

엔드포인트

Method	Path	스코프	용도
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://nu-signal-partners.vercel.app/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"
  }
}

정산 필드

필드	의미
`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://nu-signal-partners.vercel.app/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://nu-signal-partners.vercel.app/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는 이의 제기를 검토하며 이후 정산에서 조정을 반영할 수 있습니다.

동기화 유지 (폴링)

웹훅은 제공되지 않습니다. updated_since(및 선택적으로 status)와 함께 GET /v1/settlements를 폴링하여 신규 및 변경된 정산을 가져오세요. 각 항목은 커서로 사용할 수 있는 updated_at을 포함합니다.

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