行为事件（下单、登录、档案）用 /api/v1/track，网关访问记录里的机器人流量用 /api/v1/server/events，两者不能互换。人类访问留给浏览器脚本采集，避免重复计数；日志行导入见 日志导入。

行为事件

POSThttps://app.tapcub.com/api/v1/track

需要 API 密钥

写入服务端事件

Bearer API Key，权限 track:write。最多 1000 条。debug=1 或 true 只校验并返回逐条结果，不落库。validation_behavior=enforce 时，任何警告都会整条拒绝。身份绑定在入队前同步完成。限流：每个 API Key 每分钟 600 次（429 RATE_LIMIT）。Nest 返回 201。错误：400 VALIDATION、401 NO_API_KEY、401 BAD_API_KEY。

查询参数2

debugstring

只校验。其它值会落库。

1true

validation_behaviorstring

enforce 会拒绝带有任何警告的条目。

enforce

请求体 application/json必填

eventsTrackEvent[]必填

typestring

tracktrack_signupbindunbindprofile_setprofile_set_once

eventstring

device_idstring

login_idstring

login_id_typestring

loginemailmobileunionidopenidcustom

identitiesobject

timeinteger

Unix 毫秒。与当前时间相差超过 72 小时会被改成服务器时间并给出警告。

insert_idstring

track_update 和 track_overwrite 必填

session_idstring

propertiesobject

unsetstring[]

incrementobject

appendobject

item_typestring

item_idstring

groupstring

type:id，须匹配 ^[a-z][a-z0-9_]{0,23}:[A-Za-z0-9_@.-]{1,80}$

contextobject

响应

• 201接收计数，或调试结果
• 400请求体未通过校验（VALIDATION）
• 401缺少或被拒绝的 API Key（NO_API_KEY、BAD_API_KEY）
• 429超出速率限制

响应字段 201

debugboolean

receivedinteger

acceptedinteger

rejectedinteger

eventsinteger

写入人类事件缓冲的条数

resultsobject[]

落库时只含失败或有警告的条目。调试时含每一条。

indexinteger

okboolean

warningsstring[]

personIdstring

请求

curl -X POST "https://app.tapcub.com/api/v1/track" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "type": "track",
      "event": "purchase",
      "login_id": "user_42",
      "insert_id": "ord_1001",
      "time": 1759388400000,
      "properties": {
        "revenue": 19.9
      },
      "context": {
        "ip": "203.0.113.8",
        "platform": "server"
      }
    }
  ]
}'

响应

{
  "received": 1,
  "accepted": 1,
  "rejected": 0,
  "events": 1,
  "results": []
}

两条路由都只读 Authorization 里绑定了项目的密钥，项目来自密钥，不接受查询参数里的 site_id。

{
  "events": [
    {
      "type": "track",
      "event": "purchase",
      "device_id": "web_cookie:00000000-0000-4000-8000-000000000001",
      "time": 1759363200123,
      "insert_id": "ord_1001",
      "session_id": "sess_1001",
      "properties": { "revenue": 19.9 },
      "context": { "ip": "203.0.113.10", "user_agent": "ExampleApp/1", "url": "https://example.com/orders/1001", "platform": "server" }
    }
  ]
}

逐条规则：

• time 是毫秒，与服务器相差超过 72 小时会被改写成当前时间，并带警告 time_out_of_range。
• track_update 和 track_overwrite 必须带 insert_id。
• 没有 session_id 的事件不参与会话指标。
• 邮箱和手机号如果不是 64 位十六进制，会先做哈希，并在该条的 warnings 里写上 plaintext_identity_hashed。
• group 要匹配账户键格式，用于把事件归到组织。item_set 与 item_delete 使用 item_type 和 item_id。
• 档案类操作的属性键若以 $ 开头但不在保留表里，会被删掉并记 unknown_reserved_prop。

成功时返回 received、accepted、rejected、events（实际写入缓冲的条数）和 results。results 只列出失败或有警告的条，index 是该条在 events 里的下标，ok 为假表示没有进缓冲。调试模式不写缓冲，但身份校验和警告照常计算，返回 debug: true 和全部 results。

enforce 模式下，哈希明文身份这种警告也会让整条被拒。生产环境若必须收明文邮箱，不要开 enforce，或先自行哈希成 64 位十六进制。

机器人访问记录

POSThttps://app.tapcub.com/api/v1/server/events

需要 API 密钥

写入服务端访问事件

Bearer API Key，权限 events:write。只保存识别为机器人的请求；人类流量应走浏览器采集。这个处理函数不读 X-Api-Key。Nest 返回 201。错误：400 VALIDATION、401 NO_API_KEY、401 BAD_API_KEY。

请求体 application/json必填

eventsobject[]必填

tsnumber

ipstring

uastring必填

urlstring必填

methodstring

statusinteger

responseTimenumber

referrerstring

响应

• 201计数
• 400请求体未通过校验（VALIDATION）
• 401缺少或被拒绝的 API Key（NO_API_KEY、BAD_API_KEY）

响应字段 201

receivedinteger

acceptedinteger

识别为机器人并入队的条数

skippedHumaninteger

received 减 accepted

请求

curl -X POST "https://app.tapcub.com/api/v1/server/events" \
  -H "Authorization: Bearer $TAPCUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "ua": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
      "url": "https://shop.example/pricing",
      "method": "GET",
      "status": 200
    }
  ]
}'

响应

{
  "received": 2,
  "accepted": 1,
  "skippedHuman": 1
}

只有被识别成机器人的记录会进入缓冲，响应里的 skippedHuman 是被判为人类而跳过的条数：

{ "received": 2, "accepted": 1, "skippedHuman": 1 }

这条路由不认识 type 和 insert_id，把行为事件发到这里会被模式校验拒绝。