服务端事件

1. 接入准备

网站安装 ID

打开 Arenza Portal → AI Integrations，选择你的品牌，复制 Website install ID。它以 arz_pub_ 开头。用这个值替换示例中的 YOUR_INSTALL_ID。

服务端凭据

Python / Go 使用现有的 Personal Access Token 作为 API Key：

打开 AI Integrations → Personal Access Tokens。
点击 New token，填写名称，例如 Server events，勾选 Write。
点击 Create token，复制以 arn_pat_ 开头的 Key。完整 Key 只显示一次。
在后端将 Key 配置为 ARENZA_API_KEY，将 Website install ID 配置为 ARENZA_INSTALL_ID。

这些是示例使用的环境变量名。通过服务端密钥管理服务注入 Key，不要放进网页代码。不需要另外申请 Signing Secret。接收端会校验 Authorization: Bearer <API_KEY>、Write 权限和对目标品牌的访问权限。

更换 Key 时，先创建新 Key 并更新后端，再在同一个令牌列表撤销旧 Key。撤销后，使用旧 Key 的后续请求会被拒绝。

创建 Key 不等于配置事件。 品牌必须已有服务端事件连接及允许的 event_handle。仅用于网站采集的安装 ID 会返回 422 server_event_not_configured；创建 Key 不会自动创建计费合同，也不会启用任意事件类型。尚未配置时，请先与 Arenza 确认该品牌支持的事件。

2. 接入示例

Python

配置接入准备中的 ARENZA_API_KEY 和 ARENZA_INSTALL_ID，准备服务端字段中的事件对象，以及已保存的本次请求 UUID。不需要浏览器会话凭证。

将 HTTP 辅助代码复制到项目中，文件名为 arenza_events.py，然后在事件处理代码中调用：

from arenza_events import send_event

# event：已保存的事件对象，结构见“服务端字段”。
# delivery_id：本次请求的 UUID，只生成一次，重试时复用。
receipt = send_event(event, delivery_id)
# 将 receipt["receipt_id"] 保存到本次上报记录中。

Go

配置接入准备中的 ARENZA_API_KEY 和 ARENZA_INSTALL_ID，准备服务端字段中的事件对象，以及已保存的本次请求 UUID。不需要浏览器会话凭证。

将 HTTP 辅助代码复制到 Go 模块的 arenza 包中（Go 1.18+），在事件处理代码中导入该包后调用：

// event：已保存的事件 map，结构见“服务端字段”。
// deliveryID：本次请求的 UUID。ctx：当前任务的 context。
receipt, err := arenza.SendEvent(ctx, event, deliveryID)
if err != nil {
    return err // 交给现有任务系统处理错误或重试。
}
// 将 receipt.ReceiptID 保存到本次上报记录中。

3. 参数与响应

触发时机

由你决定执行示例代码的时机：

示例	代码位置
预约确认	预约接口返回确认成功后。
询价提交	询价接口接受提交后，不在校验失败时发送。
试用开通	业务系统确认开通后，而不只是点击开通按钮时。

**当前限制：**浏览器 track() 不支持命名事件类型。这些只是触发位置示例，不代表 Arenza 报表会区分对应的业务事件名称。track('booking_confirmed') 不受支持。同一次事件只选 SDK、直接 HTTP 或服务端上报中的一种方式。

访客关联

按 HTML 或 JavaScript 示例安装后，读取访客 ID：

JavaScript（浏览器）

const visitorId = window.arenzaEvents.getVisitorId();

将该值作为 arenza_visitor_id 加入发往你自己后端的现有业务请求。后端应将它与业务记录一起保存，供异步任务上报时使用。这个读取方法不发送事件；已经由后端上报的同一次事件，不要再调用浏览器 track()。

服务端字段

请求地址：

POST https://api.arenza.ai/api/v1/billing-events/{website_install_id}

使用 API Key 鉴权时，arz_pub_… 安装 ID 用来定位该品牌已配置的连接。已有的连接 UUID 仍然可用。不要把 API Key 放进 URL。

必需的请求头：Authorization: Bearer <API_KEY>、Content-Type: application/json 和 webhook-id: <delivery UUID>。使用 Bearer 时，不需要 HMAC 签名或签名时间戳。

向 Arenza 上报时，访客 ID 应放在 attribution.visitor_id 中，而不是顶层的 arenza_visitor_id。

JSON——测试事件示例；请替换为实际业务记录及已配置的事件类型。

{
  "spec_version": "1.0",
  "event_id": "booking-event-123",
  "event_handle": "YOUR_CONFIGURED_EVENT_HANDLE",
  "occurred_at": "2026-09-24T12:00:00Z",
  "subject": { "type": "booking", "id": "booking-123" },
  "attribution": { "visitor_id": "arz_v_aaaaaaaaaaaa" },
  "status": "test"
}

字段	值的来源
`event_id`	你后端为这一次事件分配的唯一 ID；重试时保持不变。
`event_handle`	该连接已配置的事件类型。
`occurred_at`	事件实际发生时间，使用 ISO 格式。
`subject`	业务对象的类型，以及不含个人信息的对象 ID；不要使用邮箱地址。
`attribution.visitor_id`	前端传来的 SDK 访客 ID，不是鉴权凭据。
`status`	经批准的测试使用 `test`，真实事件使用 `confirmed`；`reversed` 仅用于双方已约定的撤销流程。

响应与错误

**HTML / JavaScript：**触发一次经批准的测试，在浏览器开发者工具的 Network 中确认只有一次 /events 请求，且返回 202。它只表示已接收，不是业务成功的独立证明。

**Python / Go：**请求成功时返回 202，响应结构为：

{
  "accepted": true,
  "receipt_id": "<receipt ID>",
  "duplicate": false,
  "status_url": "/api/v1/billing-events/<connection ID>/receipts/<receipt ID>"
}

202 表示已接收并入队，不代表归因、报表或计费已完成。保存回执 ID，用于检查后续处理结果。

401：API Key 缺失、无效或已撤销。
403 insufficient_scope：Key 缺少 Write 权限，请创建带 Write 权限的 Key。
404：连接不可用，或 Key 无权访问该品牌。
422 server_event_not_configured：安装 ID 尚未配置服务端事件。
422 event_handle_not_allowed：连接不允许该事件类型。
409：可能复用了事件 ID 或请求 ID，但修改了请求内容。
网络失败或 5xx：按现有任务系统的策略重试，保持事件内容和两个 ID 不变，不要无限连续重试。

仅对经批准的连接进行测试。Python/Go 辅助代码只有在调用发送函数时才会发送请求。

预配置连接

已有预绑定事件的连接，可以向 /api/v1/billing-events/{website_install_id}/preconfigured 发送最小请求体 {"arenza_visitor_id":"arz_v_…"}，同时携带相同的 Bearer、Content-Type 和 webhook-id 请求头。

这只适用于已绑定的事件，不支持任意事件类型。不要把这个最小请求体发送到前面的通用事件接口。

HTTP / curl 参考 · JSON Schema · 停止采集

已有 HMAC 签名接入仍可继续使用原连接 UUID 和签名请求头。API Key 接入方不需要获取或轮换这些签名密钥。

线上验证记录：2026-09-24列明了已验证的路径、部署版本、鉴权检查和验证范围。它不代表客户网站已完成安装或同意管理验收。