> ## 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 将登录、游戏、奖金、支付、争议和账户安全等非资金活动发送至为您交易评分的同一引擎。

交易是资金本身。事件则是你的平台掌握的其他一切信息：提现之前的那次登录、在两个账户之间转移筹码的那局牌、被重复领取的奖金、一周后才到达的拒付。

事件采用统一的信封结构（每个类别均相同），具备设计上的幂等性，并由[同一规则引擎](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)评估，该引擎也为你的[交易](https://docs.didit.me/zh/transaction-monitoring/transactions.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"}`，且不会存储、补充信息或评估任何内容。读取不受影响。

## Endpoints

| Endpoint | 认证 | 用途 |
| - | - | - |
| `POST /v3/events/` | API 密钥 | 从你的后端提交一个事件 |
| `POST /v3/events/batch/` | API 密钥 | 单次请求最多提交 500 个事件 |
| `POST /v3/events/sdk-token/` | API 密钥 | 签发限定范围的设备凭证 |
| `POST /v1/events/` | `X-Monitoring-Token` | 从设备 SDK 提交一个事件 |
| `POST /v1/events/batch/` | `X-Monitoring-Token` | 提交 SDK 缓冲区刷新后的一批事件 |
| `GET /v3/events/` | API 密钥 | 列出并筛选事件 |
| `GET /v3/events/{event_uuid}/` | API 密钥 | 查看单个事件及其规则证据 |
| `GET /v3/events/subjects/{vendor_data}/` | API 密钥 | 查看单个主体的时间线（见下方 `entity_type`） |
| `GET /v3/events/enrichment-metrics/` | API 密钥 | IP 信息补充缓存的健康状态 |

`/v3/` 通道是服务端通道，与交易 API 其余部分使用相同的 `x-api-key` 认证。`/v1/events/` 通道是设备通道，参见 [SDK 事件提交](https://docs.didit.me/zh/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` | 是 | 以下十个类别之一。 |
| `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` | 否 | 该类别的领域字段。最多 16 KB。 |
| `custom_values` | 否 | 最多 100 个标量键，规则中可通过 `custom_values.<key>` 引用。 |

## 类别

十个一级类别，每个都有类型化校验和托管的[规则字段](https://docs.didit.me/zh/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` 是风险等级更高的子集，带有账户接管规则所读取的有序生命周期。

### 必填 payload 字段

有些操作如果缺少特定字段就无法关联，因此校验会拒绝这些事件，而不是存储无人能关联的证据。

| 操作 | 必填字段 |
| - | - |
| `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` 或至少一个遥测指标 |
| `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 个事件**。批量请求按设计支持部分成功：一条格式错误的页面浏览事件，绝不能导致同批次的拒付事件也失败。

```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/zh/transaction-monitoring/event-rules.md#实时与异步规则)。

## 保留

事件的数量远高于交易，因此每个事件到达时都会归入一个保留类别。

| 类别 | 默认热数据保留期 | 归入此类的事件 |
| - | - | - |
| `low_value` | 14 天 | 页面浏览、心跳、设备可见性信号、机器人遥测、促销浏览 |
| `standard` | 30 天 | 认证、会话、游戏、奖金、联盟营销、自定义 |
| `risk_relevant` | 90 天 | 安全和负责任博彩事件，以及**任何被规则命中的事件** |
| `monetary_or_compliance` | 交易保留期 | 支付和争议事件 |

由此表得出两条规则：

* 命中规则的事件属于证据，因此会自动提升为 `risk_relevant`。
* 支付和争议事件沿用交易保留期。它们永远不会按事件计划过期，且各类别的覆盖设置无法缩短其保留期。

可在 **Transactions → Settings → Event monitoring** 中按应用覆盖三个可过期类别的保留期（每类 1-730 天）。

## IP 丰富信息

事件与交易一样，带有相同的 [IP 信息补充](https://docs.didit.me/zh/transaction-monitoring/ip-enrichment.md)，包括国家、ASN、VPN/代理和数据中心标记。信息补充按**每个唯一 IP 地址**解析，而不是按事件解析。一个会话从同一地址触发 200 次页面浏览时，该地址只解析一次。

低价值遥测走得更远：只有当其他事件已经解析过该地址时，它才会读取补充信息。它绝不会自行触发查询。

`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`）。

### 单个主体的时间线

```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 会将它们视为两个不同的主体。`entity_type` 用于指定你要查询的对象：`individual`（默认值）或 `company`。如果使用企业 ID 时省略该参数，返回的是个人的时间线，而不是两者都返回。同样的列表筛选参数也适用于此。

`GET /v3/events/{event_uuid}/` 会额外返回 payload、设备上下文、IP 信息富化、该主体缓存的风险信号，以及每个规则匹配结果及其证据，包括每个匹配字段是由服务端推导、由 SDK 推导，还是由客户提供。

`DELETE /v3/events/{event_uuid}/delete/` 用于删除单个事件。被删除的事件将不再出现在任何读取接口的返回结果中，且删除操作不可撤销。

## 下一步

> [card] [事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)
>
> 基于事件数据的速率、比率、序列和关联规则。

> [card] [SDK 事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission.md)
>
> 使用范围受限的凭证，直接从设备采集事件。


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