API 参考
集成方真正需要的两条路由：代码和服务器到服务器回传。参数、限制与响应。
本参考涵盖的是由客户集成的部分。代码还会使用一些内部路由来拉取广告系列配置和记录事件—— 那些是自动调用的，任何人都不需要去实现。它们的规格会在有正式技术评审时依据合同提供。
基础信息#
https://bridge.moclick.com.br
| 方法 | 路由 | 认证 | 用途 |
|---|---|---|---|
GET | /moclick-{slug}.js | 公开 | 全局代码 |
GET | /wp-json/moclick/v1/postback | Token | 服务器到服务器的转化 |
GET /moclick-{slug}.js#
全局代码，广告系列已内嵌识别信息。
| 响应头 | 取值 |
|---|---|
Content-Type | application/javascript; charset=utf-8 |
Cache-Control | public, max-age=300, must-revalidate |
ETag | 随内容和广告系列而变化 |
Access-Control-Allow-Origin | * |
当 If-None-Match 匹配时返回 304 Not Modified。
还存在一个不内嵌广告系列的 /moclick.js，供手动声明配置的场景使用——参见
子域名与跨域。
GET /wp-json/moclick/v1/postback#
服务器到服务器的转化记录，通过广告系列 token 认证。完整实现指南、四种语言的示例 以及重发策略，见 S2S 回传。
参数#
| 参数 | 必填 | 限制 | 说明 |
|---|---|---|---|
slug | 是 | — | 广告系列标识符。 |
token | 是 | — | 广告系列 token。 |
click_id | 是 | 100 | 点击标识符。没有它则不写入任何数据。 |
txid | 建议 | 100 | 交易标识符。去重的键。 |
value | 建议 | 2 位小数 | 金额。非数字会被写为空值。 |
响应#
| 状态码 | 响应体 | 含义 |
|---|---|---|
200 |
text/plain 格式的 OK |
已接收。包括重复项，按设计这同样算成功。 |
403 |
{"error":"invalid_token"} |
token 无效、缺失，或广告系列不存在。 |
token 采用恒定时间比较，且三种失败情形返回完全相同的响应——响应不会泄露哪些广告系列存在。
清洗与限制#
这些规则在任何事件记录的入口处生效。对集成方和安全评估都有意义：
| 字段 | 处理方式 | 限制 |
|---|---|---|
| 点击标识符与交易标识符 | 文本清洗后截断 | 100 个字符 |
| 来源与会话标识符 | 文本清洗后截断 | 190 个字符 |
| Referrer | 校验为 URL 后截断 | 500 个字符 |
| 广告系列参数 | 按允许列表过滤并重新编码 | 每个值 190 个字符 |
| 转化金额 | 转换为小数，或写为空值 | 2 位小数 |
| 浏览器 UA | 文本清洗后截断 | 255 个字符 |
超出限制的值会被截断，而不是被拒绝——请求照常处理并写入记录。 这一点在点击标识符上尤其重要：如果你的平台生成的标识符超过 100 个字符， 值会被截短，重发时可能与原始值对不上。集成前请先检查长度。
响应策略#
记录类路由按设计是静默的：在广告系列不存在、缺少点击标识符、广告系列未使用平台自有测量、 来源被判定为机器人，或事件是重复项时，它们都会正常响应而不写入任何数据。
对集成方的实际影响是：不要把响应状态码当作已写入的凭据。 请到结果后台面板确认。
CORS#
公开路由由访客浏览器调用，响应带 Access-Control-Allow-Origin: * 和
Cache-Control: no-store。这些调用既不接受也不发送任何凭据，
也不会暴露任何敏感数据——特别地，回传 token 绝不会出现在 API 的任何响应中。