> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# イベント取り込みAPI - 非金銭アクティビティのモニタリング

> Diditのイベント取り込みAPIは、ログイン、ゲームプレイ、ボーナス、決済、紛争、アカウントセキュリティなどの非金銭アクティビティを、取引をスコアリングするのと同じエンジンに送信します。

取引はお金の動きです。イベントは、それ以外にプラットフォームが把握しているすべてのことです。出金に先立つログイン、2つのアカウント間でチップを動かしたハンド、2回受け取られたボーナス、1週間後に届いたチャージバックなどがこれにあたります。

イベントはすべてのカテゴリで共通の1つのエンベロープを使用し、設計上冪等であり、[取引](https://docs.didit.me/ja/transaction-monitoring/transactions.md)をスコアリングするのと[同じルールエンジン](https://docs.didit.me/ja/transaction-monitoring/event-rules.md)で評価されます。

> [!NOTE]
>
> イベントの取り込みは**オプトイン**です。**Transactions → Settings → Event monitoring**で有効にしてください。
> 有効にするまでは何も変わりません。既存の取引ルールは引き続き取引に対してのみ発火します。また、ルールは明示的にイベントを含めない限り取引に適用されるため、誤ってイベントルールが作成されることはありません。
>
> 有効になるまでは、すべての書き込みレーン（`POST /v3/events/`、`POST /v3/events/batch/`、`POST /v3/events/sdk-token/`、および`/v1/events/`デバイスレーン）が`403`と`{"code": "event_monitoring_disabled"}`を返し、何も保存、エンリッチ、評価されることはありません。読み取りには影響しません。

## エンドポイント

| エンドポイント | 認証 | 用途 |
| - | - | - |
| `POST /v3/events/` | APIキー | バックエンドからの1件のイベント |
| `POST /v3/events/batch/` | APIキー | 1回のリクエストで最大500件のイベント |
| `POST /v3/events/sdk-token/` | APIキー | スコープ付きのデバイス認証情報を発行 |
| `POST /v1/events/` | `X-Monitoring-Token` | デバイスSDKからの1件のイベント |
| `POST /v1/events/batch/` | `X-Monitoring-Token` | フラッシュ済みのSDKバッファー |
| `GET /v3/events/` | APIキー | イベントの一覧取得とフィルタリング |
| `GET /v3/events/{event_uuid}/` | APIキー | ルールの根拠を含む1件のイベント |
| `GET /v3/events/subjects/{vendor_data}/` | APIキー | 1つのサブジェクトのタイムライン（下記の`entity_type`を参照） |
| `GET /v3/events/enrichment-metrics/` | APIキー | IPエンリッチメントキャッシュの健全性 |

`/v3/`はサーバー向けで、取引APIの他の部分と同じ`x-api-key`認証を使用します。`/v1/events/`はデバイス向けです。詳しくは[SDKからのイベント送信](https://docs.didit.me/ja/transaction-monitoring/sdk-event-submission.md)を参照してください。

## エンベロープ

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'
```

```json theme={null}
{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}
```

| フィールド | 必須 | 備考 |
| - | - | - |
| `event_id` | はい | 独自の識別子で、アプリケーションごとに一意です。冪等性キーとして使われます。 |
| `event_category` | はい | 下記の10カテゴリのいずれか。 |
| `action_type` | はい | 自由形式の文字列で、最大128文字。 |
| `occurred_at` | はい | 自社側で発生した日時。過去は7日前まで、未来は5分後まで指定できます。 |
| `subject.vendor_data` | はい | 自社のユーザーID。取引で特定されるユーザーと同じユーザーに紐付けられます。 |
| `subject.entity_type` | いいえ | `individual`（デフォルト）または`company`。 |
| `business.vendor_data` | いいえ | イベントが属する企業。 |
| `session` | いいえ | `session_id`、`sequence`、`page_url`、`referrer`。 |
| `device_context` | いいえ | `fingerprint`、`persistent_device_id`、`bot_score`、および`network_context.ip_address`。 |
| `transaction_context` | いいえ | `amount`、`currency`、`direction`、`payment_reference_id`。 |
| `payload` | いいえ | カテゴリ固有のドメインフィールド。最大16KB。 |
| `custom_values` | いいえ | 最大100個のスカラーキー。ルールから`custom_values.<key>`として参照できます。 |

## カテゴリ

10種類のファーストクラスカテゴリがあり、それぞれに型付きのバリデーションと管理された[ルールフィールド](https://docs.didit.me/ja/transaction-monitoring/event-rules.md#イベントフィールド)が用意されています。

| カテゴリ | 主なアクション |
| - | - |
| `auth` | `signup`、`login`、`login_failed`、`logout`、`password_forgot`、`password_reset`、`mfa_reset`、`mfa_challenge` |
| `session` | `session_started`、`session_ended`、`page_view`、`sdk_loaded`、`device_seen`、`bot_signal_observed`、`sdk_heartbeat` |
| `gameplay` | `round_started`、`round_completed`、`bet_placed`、`bet_settled`、`cashout`、`limit_change`、`p2p_settlement` |
| `bonus` | `bonus_claimed`、`bonus_wagered`、`bonus_released`、`promotion_viewed` |
| `affiliate` | `affiliate_attributed`、`referral_clicked`、`campaign_joined`、`commission_event` |
| `payment` | `deposit_initiated`、`deposit_completed`、`withdrawal_requested`、`withdrawal_completed`、`withdrawal_address_changed`、`payment_instrument_seen` |
| `dispute` | `chargeback_opened`、`chargeback_won`、`chargeback_lost`、`refund_issued`、`payment_dispute_updated` |
| `security` | `login_attempt`、`login_succeeded`、`login_failed`、`password_changed`、`mfa_changed`、`credential_reset`、`country_changed`、`device_changed`、`account_locked` |
| `responsible_gambling` | `self_exclusion_checked`、`self_exclusion_match`、`re_registration_attempt`、`limit_breach_attempt`、`registry_status_changed` |
| `custom` | 任意に定義したアクション |

`auth`はプロダクト全般を対象とする広いカテゴリです。`security`はリスク判定向けのサブセットで、アカウント乗っ取り対策のルールが参照する順序付きのライフサイクルを持ちます。

### 必須のペイロードキー

一部のアクションは特定のキーがないと関連付けができません。そのため、関連付けられない証跡を保存するのではなく、バリデーションでリジェクトします。

| アクション | 必須 |
| - | - |
| `gameplay.p2p_settlement` | `game_id`、`counterparty_vendor_data`、`stake_amount`、`net_result_amount`、`role`、および`hand_id` / `round_id` / `match_id`のいずれか |
| `gameplay.bet_placed`、`gameplay.bet_settled` | `game_id` |
| `payment.deposit_*`、`payment.withdrawal_completed`、`payment.withdrawal_requested`、`payment.deposit_initiated` | `payment_reference_id`、`amount`、`currency`、`payment_method`、`status` |
| `payment.withdrawal_address_changed` | `withdrawal_address_hash` |
| `dispute.chargeback_*` | `payment_reference_id`、および`dispute_id` / `chargeback_id`のいずれか |
| `security.*_changed` | `changed_field`。アカウント制御または出金制御の変更では、`previous_reference_hash`または`new_reference_hash`も必要です |
| `session.bot_signal_observed` | `telemetry_schema_version`に加えて、`bot_score`または1つ以上のテレメトリ指標 |
| `responsible_gambling.self_exclusion_match` | `registry_source`、`exclusion_status`、`identity_match_ref` |

> [!WARNING]
>
> 送信するのは**参照とハッシュ**だけにし、生のシークレットは絶対に送信しないでください。決済手段、出金先、アカウント管理に関する変更は、送信されたハッシュ化済みの参照として保存されます。カード番号、出金先アドレスの全体、パスワードハッシュ、MFAシークレットは絶対に送信しないでください。

### 例: P2P精算

```json theme={null}
{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}
```

### 例: チャージバック

```json theme={null}
{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}
```

紛争のライフサイクルは追記専用です。訂正は新しい`dispute`イベントとして送信し、最初のイベントを編集することはありません。

## 冪等性

`event_id`はアプリケーションごとに一意であり、これが冪等性の仕組みのすべてです。

* **同じ`event_id`で同じ内容**の場合は、`200`と`"idempotent_replay": true`、そして最初に保存されたイベントが返されます。何度でも再試行できます。
* **同じ`event_id`で異なる内容**の場合は、`409`が返されます。誤ってIDを再利用しています。

## バッチ

`POST /v3/events/batch/`は最大**500件のイベント**を受け付けます。バッチは設計上、部分的な成功を許容します。不正な形式のページビュー1件が、同じバッチ内のチャージバックを巻き添えにすることがあってはならないためです。

```json theme={null}
{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}
```

いずれかがリジェクトされた場合のレスポンスは`207 Multi-Status`、すべて保存された場合は`201 Created`です。

## ステータス

| ステータス | 意味 |
| - | - |
| `ACCEPTED` | 保存済み。ステータスを変更したルールはありません(ほとんどのイベントでは、これが通常の結果です)。 |
| `APPROVED` | ルールが実行され、スコアがレビューのしきい値を下回りました。 |
| `IN_REVIEW` | ルールによってスコアがレビューのしきい値を超えたか、ルールがステータスを直接設定しました。 |
| `DECLINED` | ルールによって却下されました。 |

`correlation_pending: true`は、複数のサブジェクトにまたがるルールがまだ実行待ちであることを示します。数分以内に解消され、イベントのステータスとスコアが更新されます。詳しくは[非同期ルール](https://docs.didit.me/ja/transaction-monitoring/event-rules.md#リアルタイムルールと非同期ルール)を参照してください。

## データ保持

イベントは取引よりもはるかに量が多いため、受信時にそれぞれ保持クラスに振り分けられます。

| クラス | デフォルトのホット保持期間 | 対象 |
| - | - | - |
| `low_value` | 14日 | ページビュー、ハートビート、デバイス検出のping、ボットのテレメトリ、プロモーション閲覧 |
| `standard` | 30日 | 認証、セッション、ゲームプレイ、ボーナス、アフィリエイト、カスタム |
| `risk_relevant` | 90日 | セキュリティおよび責任あるギャンブルのイベント、そして**ルールに一致したすべてのイベント** |
| `monetary_or_compliance` | 取引の保持期間 | 決済および紛争のイベント |

この表から、次の2つのルールが導かれます。

* ルールに一致したイベントは証跡となるため、自動的に`risk_relevant`に昇格します。
* 決済および紛争のイベントには取引の保持期間が適用されます。イベントの保持スケジュールでは期限切れにならず、クラスごとの上書き設定で短縮することもできません。

期限切れになる3つのクラスは、**Transactions → Settings → Event monitoring**でアプリケーションごとに上書きできます(それぞれ1〜730日)。

## IPエンリッチメント

イベントには、取引と同じ[IPエンリッチメント](https://docs.didit.me/ja/transaction-monitoring/ip-enrichment.md)(国、ASN、VPN/プロキシおよびデータセンターのフラグ)が付与されます。エンリッチメントは**イベントごとではなく、一意のIPアドレスごとに取得されます**。1つのアドレスから200件のページビューを送信するセッションでも、そのアドレスのエンリッチメントの取得は1回だけです。

重要度の低いテレメトリでは、エンリッチメントの参照がさらに制限されます。他のイベントがすでにそのアドレスを解決している場合にのみエンリッチメントを参照し、独自にルックアップをトリガーすることはありません。

`GET /v3/events/enrichment-metrics/`がその結果を返し、コンソールではイベント一覧の上に同じ数値が表示されます。

```json theme={null}
{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}
```

## イベントの読み出し

```bash theme={null}
curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"
```

フィルター:`event_category`、`action_type`、`status`、`retention_class`、`subject_vendor_data`、`business_vendor_data`、`session_id`、`device_fingerprint`、`ip_address`、`game_id`、`round_id`、`affiliate_code`、`payment_reference_id`、`counterparty_vendor_data`、`matched_only`、`occurred_from`、`occurred_to`、`search`。複数の値を指定するフィルターでは、パラメーターを繰り返して指定します(`?status=A&status=B`)。

### 1つの対象者のタイムライン

```bash theme={null}
curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"
```

`vendor_data`が一意となるのは、同じエンティティタイプの**中だけ**です。同じIDがユーザーと企業の両方を指すことがあり、Diditはそれらを2つの異なる対象者として扱います。どちらを要求するかは`entity_type`で指定します。指定できる値は`individual`(デフォルト)または`company`です。企業のIDに対してこれを省略すると、両方ではなく個人のタイムラインが返されます。一覧と同じフィルターを使用できます。

`GET /v3/events/{event_uuid}/`は、ペイロード、デバイスコンテキスト、IPエンリッチメント、対象者のキャッシュ済みリスクシグナル、および一致したすべてのルールとその根拠を追加で返します。根拠には、一致した各フィールドがサーバー由来、SDK由来、顧客提供のいずれであるかも含まれます。

`DELETE /v3/events/{event_uuid}/delete/`は、1件のイベントを削除します。削除されたイベントはどの読み出しでも返されなくなり、削除は取り消せません。

## 次のステップ

> [card] [イベントに対するルール](https://docs.didit.me/ja/transaction-monitoring/event-rules.md)
>
> イベントデータに対するベロシティ、比率、シーケンス、相関のルール。

> [card] [SDKによるイベント送信](https://docs.didit.me/ja/transaction-monitoring/sdk-event-submission.md)
>
> スコープ付きの認証情報を使い、デバイスから直接イベントを収集します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.