向 LinkHarbor 发送销售和自有数据

LinkHarbor 也接收来自外部的数据。有两种情况提供专用端点和各自的密钥，你不需要为此使用 API 密钥：销售回调用于上报网店中的销售，让你在统计中看到哪个链接带来了收入。“Custom (API)”集成会把你自己工具中的实时数据作为小组件显示在你的页面上，并能触发推送通知。

#销售回调：归因销售

点击 ID（lt_click_id）、归因和上报如何配合，请参阅归因转化和销售；这里列出面向开发者的所有字段和响应。简而言之：LinkHarbor 把一次被计数的点击重定向到 http 或 https 目标时，会附加参数 lt_click_id；你的网店记住它，并在购买完成后把它发回来。

创建回调密钥

1. 打开“回调与 API”
2. 在“回调密钥”卡片中点击“+ 创建新密钥”
3. 可以填写一个名称，例如“商店回调”，然后点击“创建密钥”
4. 立即复制密钥，它只会显示一次

谁可以创建

所有者和管理员，Creator Pro 起。在 Creator Free 中显示“回调密钥自 Creator Pro 起提供。”

数量

每个工作区最多 5 个密钥，例如每个网店一个。

“编辑”

修改名称，并把状态设为“已启用”或“未启用”。密钥未启用时，API 会拒绝回调。

“↺ 轮换”

生成新密钥；旧密钥立即失效。

“最后回调：”

显示该密钥最后一次成功使用的时间。

发送回调

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

可选签名

除了密钥之外，你还可以发送 X-Callback-Signature 请求头。它包含 sha256= 以及原始请求体的十六进制 HMAC-SHA256 签名。签名用的密钥不是回调密钥本身，而是它的二进制 SHA-256 哈希。如果你发送了这个请求头，它就必须正确，否则回调会被拒绝。

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // 密钥的二进制哈希
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// 请求头：X-Callback-Secret 和 X-Callback-Signature: $sig，请求体：$body

在哪里查看销售

上报的销售会作为转化出现在你的统计中，参见归因转化和销售。通过 API，你可以用 read:stats 在 /v1/stats/…/conversions/breakdown 下读取它们。

#Custom (API)：你自己的实时数据

借助“Custom (API)”集成，任何能发送 HTTP 请求的程序（例如游戏服务器插件、机器人或 cron 脚本）都可以向 LinkHarbor 发送数据。这些数据会变成你页面上的实时小组件，推送规则还可以通知你的关注者。

连接

1. 在工作区中打开“集成”
2. 选择“Custom (API)”并输入名称
3. 连接后，对话框会显示“接入 URL”和“密钥”（可用“显示密钥”查看）
4. 把两者保存在你的工具中

集成自 Creator Pro 起提供。只有所有者和管理员能看到接入 URL 和密钥，之后在集成的详情视图中也是如此。断开后重新连接会生成新的密钥。一般如何连接集成，请参阅连接集成。

发送数据

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

自由命名的事件名，例如 player.joined。它会被转换为小写，推送规则就是根据这个名称触发的。没有 event 时，事件名为 state.updated。

event_id

可选的键，用于防止重复处理。如果再次发送相同的 event_id，LinkHarbor 会返回 duplicate: true，并且不做任何处理。

data

推送文本中占位符的值，例如 {player}。最多 40 个键，只能是简单值。

state

小组件的完整状态，会完全替换之前的状态。type 为 game_server（游戏服务器卡片）或 status（状态卡片）。

除了 Authorization: Bearer，你也可以在 X-LinkHarbor-Secret 请求头中发送密钥。每个 IP 地址每分钟允许 120 次调用。你还可以选择为请求体签名：X-LinkHarbor-Signature 请求头包含 sha256= 以及以密钥为密钥计算出的原始请求体 HMAC-SHA256 签名。如果你发送了它，它就必须正确。