集成

S2S 回传

由广告主后端回报转化，通过 token 认证。不需要 JavaScript，不需要 cookie，不需要浏览器。

何时使用#

服务器到服务器回传是记录转化最可靠的方式，因为它不依赖浏览器里发生的任何事情。以下场景中它就是正确答案：

结账在第三方域名上，cookie 无法存活
转化在下单之后才确认——支付通过、票据付清、订阅生效
转化发生在站点之外：电话、即时通讯应用、线下门店、CRM
广告主不能或不愿安装第三方 JavaScript
脚本拦截非常激进的环境

回传 URL#

Moclick 团队会提供完整 URL 和广告系列的 token。token 按广告系列自动生成，不会在广告系列之间复用。

GET /wp-json/moclick/v1/postback Token

格式

https://bridge.moclick.com.br/wp-json/moclick/v1/postback
  ?slug=YOUR-CAMPAIGN
  &token=YOUR-TOKEN
  &click_id={CLICK_ID}
  &txid={TXID}
  &value={VALUE}

参数	必填	说明
`slug`	是	广告系列标识符。
`token`	是	广告系列 token，由 Moclick 提供。
`click_id`	是	点击标识符，最长 100 个字符。没有它则不写入任何数据。
`txid`	建议	交易标识符，最长 100 个字符。这是去重的键。
`value`	建议	转化金额。小数分隔符用点号。

广告主如何获取 click_id#

该标识符必须传到广告主后端并与订单一起保存。如果已安装全局代码，它就已经在 cookie 里了—— 写入订单时在服务端读取即可：

PHP在广告主后端

// Moclick 团队会告知你的广告系列所使用的 cookie 名称。
$click_id = $_COOKIE[MOCLICK_COOKIE] ?? '';

// 与订单一起保存，供转化确认时使用
save_order_meta($order_id, 'moclick_click_id', $click_id);

没有安装全局代码时，请在访客进入时捕获识别参数并持久化到会话中。 Moclick 团队会告知该广告系列使用哪个参数。

调用示例#

Shell

curl -sS -G "https://bridge.moclick.com.br/wp-json/moclick/v1/postback" 
  --data-urlencode "slug=my-campaign" 
  --data-urlencode "token=YOUR_TOKEN" 
  --data-urlencode "click_id=abc-123" 
  --data-urlencode "txid=ORDER-9001" 
  --data-urlencode "value=249.90"

PHP

$url = 'https://bridge.moclick.com.br/wp-json/moclick/v1/postback?'
    . http_build_query([
        'slug'     => 'my-campaign',
        'token'    => MOCLICK_TOKEN,
        'click_id' => $click_id,
        'txid'     => $order_number,
        'value'    => number_format($total, 2, '.', ''),
    ]);

$res = wp_remote_get($url, ['timeout' => 5]);

if (is_wp_error($res) || wp_remote_retrieve_response_code($res) !== 200) {
    // 加入队列以便重试——见下文「重发」
}

JavaScript

const url = new URL("https://bridge.moclick.com.br/wp-json/moclick/v1/postback");
url.search = new URLSearchParams({
  slug: "my-campaign",
  token: process.env.MOCLICK_TOKEN,
  click_id: clickId,
  txid: orderNumber,
  value: total.toFixed(2)
});

const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
if (!res.ok) throw new Error(`postback failed: ${res.status}`);

Python

import requests

r = requests.get(
    "https://bridge.moclick.com.br/wp-json/moclick/v1/postback",
    params={
        "slug": "my-campaign",
        "token": MOCLICK_TOKEN,
        "click_id": click_id,
        "txid": order_number,
        "value": f"{total:.2f}",
    },
    timeout=5,
)
r.raise_for_status()

响应#

状态码	响应体	含义
`200`	`text/plain` 格式的 `OK`	已接收。包括重复项的情况，按设计这同样算成功。
`403`	`{"error":"invalid_token"}`	token 无效、缺失，或广告系列不存在。

为什么这三种情况返回同一个 403

token 错误、token 为空和广告系列不存在会产生完全相同的响应，并且 token 采用恒定时间比较。这样响应就不会泄露哪些广告系列存在，也堵住了通过计时测量来猜出 token 的路。

有一个细节可以少走弯路：200 OK 确认的是已接收，未必是已写入。缺少 click_id 的请求，或针对未使用平台自有测量的广告系列的请求，都会返回 OK 而不写入任何数据——这与其他端点的静默策略一致。集成时，请到后台面板确认事件确实出现了。

重发与幂等性#

该调用按 click_id + txid 组合是幂等的：重复发送同一请求不会产生重复转化。这让重发变得安全，而且我们建议重发。

切勿因网络故障而丢弃转化

把回传当作队列来处理，而不是一次性调用。超时或 5xx 错误应进入带渐进退避的重试—— 例如 1 分钟、5 分钟、30 分钟、2 小时。由于操作是幂等的，再试一次没有风险。而 403 则绝不应重发：那是配置错误，重发也解决不了。

Token 安全#

把 token 保管在服务器上。绝不要放进 JavaScript、HTML 或移动应用
存放在环境变量或密钥保管库中，不要放进代码仓库
每个广告系列一个 token：其中一个泄露不会波及其他广告系列
持有 token 的人就能往该广告系列里写入转化——请当作凭据对待

回传 URL 中包含 token。不要把它发布到共享文档、支持工单、公开访问日志或代码仓库中。如果 token 泄露，请向 Moclick 团队申请新的并更新集成。