イベントAPI

再生、エンゲージメント、売上シグナルをNUへ送信します。検証済み売上イベントは精算に反映されます。events:writeが必要です。

エンドポイント

イベントタイプ

次のevent_type値だけを受け付けます。不明なタイプはvalidation_failedを返します。

精算適格性は取り込みパイプラインがタイプから導出し、パートナー提供フラグでは決めません。

必須フィールドと検証

すべてのイベントにevent_idとevent_typeが必要です。occurred_atは任意で、既定はサーバー受信時刻です。タイプ別フィールドは上記のとおりです。

• event_idは組織ごとに一意で冪等性を提供します。重複はno-opとして409 duplicate_event_idを返し、二重計上しません。
• completion_rateは[0, 1]の範囲内である必要があります。
• 売上タイプにはtitle_id、revenue_amount、ISO 4217のcurrencyが必要で、なければvalidation_failedです。照合できるよう売上をタイトルに帰属させます。
• occurred_atは未来にできません。未来イベントはoccurred_at_in_future付きのfailedとして拒否されます。24時間より古いイベントは受理されますがpayload.late = trueになります。
• viewer_id_hashはハッシュ済み識別子で、生のPIIを含めません。違反するとvalidation_failedを返します。
• title_id、episode_id、playback_session_idを送る場合、キー環境で表示可能かつ組織に属する必要があります。参照失敗はunknown_title_for_environment、unknown_episode_for_environment、playback_session_mismatch、license_not_active、episode_not_licensedなどの詳細付きでvalidation_failedを返します。

フィールド制限

文字列フィールドには長さ制限があり、超過するとvalidation_failedを返します:

payloadはパートナーメタデータ用の任意の自由形式JSONです。シリアライズ後は4,096バイト（4KB）以下でなければならず、超過すると値が無効です。付きでvalidation_failedを返します。

単一イベントを送信

curl -X POST "https://signal-partners.newunivers.ai/v1/events" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "Accept-Language: ja" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_acme_0001",
    "event_type": "PAYMENT_COMPLETED",
    "title_id": "ttl_abc",
    "episode_id": "ep_001",
    "viewer_id_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "country": "KR",
    "device": "web",
    "revenue_amount": 3.99,
    "currency": "USD",
    "occurred_at": "2026-06-24T00:00:00Z"
  }'

{ "data": { "event_id": "evt_acme_0001", "status": "validated", "received_at": "2026-06-24T00:00:05.123Z" } }

単一イベント取り込み成功時はHTTP 200、status: "validated"、ISO-8601のreceived_atタイムスタンプを返します。

重複

同じevent_idを再送すると次を返します:

{
  "error": {
    "code": "duplicate_event_id",
    "message": "このイベントIDはすでに受理されています。",
    "request_id": "req_..."
  }
}

検証エラー

{
  "error": {
    "code": "validation_failed",
    "message": "リクエストの検証に失敗しました。",
    "request_id": "req_...",
    "details": [
      {
        "field": "currency",
        "issue": "required",
        "message": "必須の値がありません。"
      }
    ]
  }
}

バッチイベント

1リクエスト最大500イベントを送れます。各項目は独立検証され、失敗項目があってもリクエスト自体は成功できるよう項目別結果を持つHTTP 207を返します。

curl -X POST "https://signal-partners.newunivers.ai/v1/events/batch" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "Accept-Language: ja" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_id": "evt_1", "event_type": "EPISODE_STARTED", "title_id": "ttl_abc", "episode_id": "ep_001", "occurred_at": "2026-06-24T00:00:00Z" },
      { "event_id": "evt_1", "event_type": "EPISODE_STARTED", "title_id": "ttl_abc", "episode_id": "ep_001", "occurred_at": "2026-06-24T00:00:01Z" },
      { "event_id": "evt_3", "event_type": "PAYMENT_COMPLETED", "occurred_at": "2026-06-24T00:00:02Z" }
    ]
  }'

{
  "data": {
    "received": 3,
    "accepted": 1,
    "duplicated": 1,
    "failed": 1,
    "results": [
      { "event_id": "evt_1", "status": "accepted" },
      { "event_id": "evt_1", "status": "duplicated" },
      { "event_id": "evt_3", "status": "failed" }
    ]
  }
}

receivedは送信数（1〜500）です。各項目のstatusはaccepted | duplicated | failedのいずれかです。項目にはerror_codeフィールドがありません。

冪等性

サーバー側のevent_id重複排除により安全に再試行できます。再試行では同じevent_idを使い、HTTP試行ごとではなく実イベントに対して生成します。レスポンスとリクエストログで状態を確認してください。受理済みはVALIDATED、重複IDはduplicatedのno-opです。売上イベントは精算へ反映されます。