변경 이력

NU Signal Partners API의 주요 변경 사항입니다. API 버전은 경로에 고정되어 있으며 (/v1), 이 항목들은 스펙 리비전 (openapi/partner-api.yaml)을 추적합니다.

0.4.0

웹뷰 재생 링크 — 이제 POST /playback/tokens는 기존 manifest와 함께 호스팅된 webview_url을 반환합니다. WebView/iframe에서 열기만 하면 되며 플레이어 연동이 필요 없습니다. 둘 다 동일한 세션에 바인딩됩니다(재생 API).
고객 선호 설정 — 선택적 비PII preferences(선호 언어/장르, 자막/오디오 기본값, 자동 재생, 관람 등급)는 웹뷰 플레이어를 개인화하고 세션에 저장됩니다(GET /playback/sessions/{id}로 반환). 형식이 엄격하며, @/공백을 포함하는 값은 validation_failed(422)로 거부됩니다.

무결성 가드 강화 — 이제 알려진 Prisma 데이터베이스 오류는 깔끔한 4xx 응답으로 매핑됩니다: P2002 → 신규 conflict(409), P2003 → validation_failed(참조된 리소스 없음), P2025 → resource_not_found(오류 코드).
요청 크기 상한 — 이벤트 페이로드는 4KB로 제한되며, 요청 문자열 필드에는 명시적 길이 제한이 적용됩니다.
공개 경로 속도 제한 — 미인증 엔드포인트(POST /partner-applications, POST /v1/api-keys/bootstrap)는 클라이언트 IP당 20/min으로 속도가 제한됩니다.
멱등성 충돌 — 재생 토큰 또는 라이선스 요청 생성에서 처리 중인 X-NU-Request-Id를 재요청하면 중복 쓰기 대신 conflict(409)를 반환합니다. 완료된 요청은 원본 응답을 다시 재생합니다.

표준화된 오류 봉투 — 모든 오류는 고정된 코드 집합과 함께 { "error": { code, message, request_id, details? } }를 반환합니다(오류 코드).
요청 헤더 — Authorization, X-NU-Partner-Id, 그리고 선택적 X-NU-Request-Id를 정식화했습니다(인증).
이벤트 분류 enum — 정산 적격성이 파생되는 표준 EventType 값(이벤트 API).
정산 분쟁 & 조정 — POST /settlements/{id}/dispute 및 확장된 정산 수수료/배분 필드(정산 API).
커서 페이지네이션 — 목록 엔드포인트는 cursor를 받고 page/limit과 함께 next_cursor를 반환합니다(카탈로그 API).

초기 MVP 스캐폴드: 격리된 샌드박스 환경을 대상으로 하는 카탈로그, 라이선스, 재생, 이벤트 API.