渠道接口对接文档
AN 宏规范 v1 · 修订日期：2026-11-03
下载 2026-11-03 版 PDF本文说明渠道与我方平台之间的点击上报、转化回调、订单状态查询、曝光上报及 RTA 筛选接口。所有投放对象统一称为“订单”，通过 ckey 区分。
示例域名、凭证和设备值仅用于说明。实际接入时，请使用我方发放的链接和凭证，填写真实设备信息。
1. 接入准备与通用约定
1.1 对接资料
| 资料 | 用途 | 渠道需要确认的内容 |
|---|---|---|
订单 ckey | 标识订单，已包含在监测链接中 | 不要替换为产品名称、数字编号或其他凭证 |
查询 token | 查询本渠道订单状态 | 渠道级发放，通常为 32 位；不用于 RTA 查询 |
| 点击链接 | 上报真实点击 | 替换链接中的 AN 宏，保持参数名不变 |
| 曝光链接 | 按订单要求上报曝光 | 仅已开通曝光的订单使用 |
| 回调地址 | 接收我方转化通知 | 提交公网可访问、不带查询参数的 HTTP/HTTPS 地址；URL 解码后最长 512 字节，并完成联调 |
| 订单接入说明 | 明确本订单的接入差异 | 设备支持范围、附加必填项、事件代码、金额字段和单位、投放周期、限量及 RTA 要求 |
上线前，应逐单确认：是否需要 RTA、是否要求 32 位 clickid、是否需要点击关联 RTA 请求、回调金额以元还是分传递、是否已做金额折算。不要仅凭字段名称推断这些规则。
1.2 接口一览
| 接口 | 请求方式与路径 | 成功判断 |
|---|---|---|
| 点击上报 | GET /cpa/click | HTTP 200 且 JSON code=200 |
| 曝光上报 | GET /cpa/imp | HTTP 200 且 JSON code=200 |
| 订单状态查询 | POST /api/v1/order/status | HTTP 200 且 JSON code=0 |
| RTA 筛选 | POST /api/v1/rta | HTTP 200 且 JSON code=0；是否可投另看返回结果 |
| 转化回调 | 我方向约定地址发送 HTTP GET | 渠道返回 HTTP 200 |
监测接口与查询接口的业务码不同，不要将查询接口的 code=0 用于判断点击是否成功。处理响应时先看 HTTP 状态，再看 JSON code；msg 用于诊断，不作为稳定的程序分支条件。
1.3 编码、时间与凭证
- 使用 UTF-8。GET 参数逐个按参数值做 URL 编码，尤其是 UA、设备型号和回调地址；不要把整条监测链接作为一个值再次编码。
- AN 宏形如
{AN_CLICKID}。没有值的可选参数可删去，或替换为空串。未替换的{AN_...}宏在点击、曝光接口中按该参数未传处理；必填项因此缺失仍会拒绝。 - JSON 请求中的 UA 等字符串传原文，不要预先 URL 编码。RTA 不使用点击接口的宏清洗规则，必须发送真实字段值。
- 投放日期和限量周期按 Asia/Shanghai 计算。具体金额单位和时间字段口径见第 4 章。
ckey和token均需妥善保管，不要放入公开页面、客户端源码或公开日志。
2. 点击上报
2.1 请求与最小示例
发生真实点击后，调用我方发放的点击链接。以下为 Android 常见字段示例，实际必填项以订单接入说明为准：
curl --get 'https://click.example.com/cpa/click' \
--data-urlencode 'ckey=order-ckey-example' \
--data-urlencode 'clickid=channel-click-20261014-001' \
--data-urlencode 'os=android' \
--data-urlencode 'oaid=真实设备OAID' \
--data-urlencode 'ip=真实设备公网IP' \
--data-urlencode 'ua=真实设备User-Agent原文'
成功响应示例：
{"code":200,"msg":"ok"}
code=200 只表示本次点击上报成功，不代表发生转化或达到结算条件。请求超时建议至少 2 秒，具体时限以双方联调结果为准。
2.2 通用参数与宏
| 参数 | 链接中的宏 | 填写要求 |
|---|---|---|
ckey | 已写入链接 | 必填，保留我方发放值 |
clickid | {AN_CLICKID} | 必填，由渠道生成；在渠道所有订单中保持唯一，重试同一次点击时保持不变 |
os | {AN_OS} | 建议明确传 android 或 ios；不传时尝试从设备标识推断，无法确定则拒绝 |
ip | {AN_IP} | 必填，真实设备公网 IP；部分订单还校验 IP 格式 |
ua | {AN_UA} | 建议携带；部分订单必填，作为 URL 参数时编码 |
model | {AN_MODEL} | 设备型号，作为 URL 参数时编码；部分订单附加必填 |
osv | {AN_OSV} | 系统版本，如 17.5；部分订单附加必填 |
brand | {AN_BRAND} | 可选，设备品牌 |
cb | {AN_CALLBACK} | 可选，该次点击使用的基础回调 URL；不得自带查询参数，解码后最长 512 字节，再作为完整参数值编码 |
rta_req_id | {AN_RTA_REQ_ID} | RTA 查询返回的 req_id 原值；标注“需关联 RTA 请求”的订单必填 |
os 缺省推断时，iOS 参考 idfa/idfa_md5/caid/idfv，Android 参考 oaid/oaid_md5/imei/imei_md5/anid。两类字段同时有值或都没有值时无法推断。推断成功后仍会校验该系统要求的设备标识，辅助字段不能自动替代主设备标识。
2.3 设备参数
| 参数 | 链接中的宏 | 填写要求 |
|---|---|---|
idfa | {AN_IDFA} | iOS IDFA 原值 |
idfa_md5 | {AN_IDFA_MD5} | IDFA 的 MD5，建议统一为 32 位小写十六进制 |
caid | {AN_CAID} | CAID；格式与是否可单独使用须按订单确认 |
caid2 | {AN_CAID2} | 可选，另一版本 CAID；不要仅依赖此字段满足设备校验 |
idfv | {AN_IDFV} | 可选辅助字段，不单独满足常规设备要求 |
oaid | {AN_OAID} | Android OAID 原值 |
oaid_md5 | {AN_OAID_MD5} | OAID 的 MD5 |
imei | {AN_IMEI} | IMEI 原值，是否接受仅传明文取决于订单 |
imei_md5 | {AN_IMEI_MD5} | IMEI 的 MD5 |
anid | {AN_ANID} | 可选 Android ID，是否支持作为设备标识须逐单确认 |
anid_md5 | {AN_ANID_MD5} | 可选 Android ID 的 MD5 |
caid_version | {AN_CAID_VERSION} | 可选 CAID 版本；仅按发放链接和订单说明使用 |
mac | {AN_MAC} | 可选 MAC 原值，仅部分订单使用 |
mac_md5 | {AN_MAC_MD5} | 可选 MAC 的 MD5，仅部分订单使用 |
ts | {AN_TS} | 可选点击时间戳；使用该字段的订单通常要求 13 位毫秒时间戳 |
常规 iOS 点击至少携带 idfa/idfa_md5/caid 中的一项；常规 Android 点击至少携带 oaid/oaid_md5/imei/imei_md5 中的一项。并非每个订单都接受上述全部形式，设备标识还必须与所发放的监测链接匹配。
部分订单存在以下附加要求：
- 必须携带 UA；或允许“UA”与“model + osv”二选一。后者在 UA 未传时，model、osv 必须同时有值。
- iOS 必须携带 IDFA 或其 MD5，不能仅传 CAID；Android 支持范围以订单说明为准。
- 校验重复参数、MD5 格式和长度；可能要求 clickid 不超过 128 字节、UA 不超过 512 字节、IP 不超过 46 字节。
- CAID 可能采用原值、
值_8位版本号或其他约定格式。不同格式不可未经确认混用；MD5 原文大小写规则也应在联调时确认。
可选字段有值时也可能参与格式校验。没有有效值时请省略，不要填全零值、虚构设备号或未替换的宏。
2.4 clickid 与重复请求
常规点击按“渠道 + clickid”在 24 小时内判重，重复时返回业务码 401。同一 clickid 不应分配给不同订单或不同真实点击，也不要因超时、失败或到量而换一个 clickid 重放同一次点击。
部分小程序/快应用订单要求 clickid 为严格 32 位的全局唯一标识，仅允许英文字母、数字、下划线和短横线；可使用无连字符的 32 位 UUID。此类订单需在跳转链接、RTA 查询和点击上报中使用同一个 clickid，并可能在更长归因期内检查冲突。未经我方确认开通，不要仅凭订单类型自行启用这一流程。
3. 点击与曝光返回码
3.1 业务码
大多数业务响应为 HTTP 200，结果由 JSON code 表示。下表是业务含义和处理建议，不要求 msg 文案逐字一致。
| code | 含义 | 渠道处理建议 |
|---|---|---|
200 | 上报成功 | 不重试；转化另等回调 |
102 | 链接不存在、订单暂停/关停，或未开通该上报能力 | 暂停相关请求，核对链接和状态 |
104 | clickid 缺失或不符合订单要求 | 修正点击标识规则 |
201 | 设备、必填参数或请求格式不符合要求 | 按订单要求修正，不盲目重试 |
204 | OS 非法或与订单不匹配 | 核对设备系统和订单定向 |
302 | 缺少可用监测链接 | 联系我方确认配置；这不是 HTTP 重定向 |
401 | 重复 clickid 或标识冲突 | 停止重复请求，必要时核对首次请求结果 |
503 | 本次处理暂不可用，例如限量状态暂无法确认 | 降低频率，按第 3.2 节处理 |
701 | 不在投放日期范围内 | 停止当前投放，核对周期 |
801 | 点击限量已达到 | 停止新点击；恢复条件取决于限量周期 |
802 | 转化事件限量已达到 | 停止新点击；不只表示激活限量 |
901 | 渠道停用或订单不可用 | 暂停相关请求，查询状态或联系我方 |
902 | cb 地址不符合格式、安全或长度要求 | 修正回调地址 |
903 | 系统繁忙、超时或本次结果待确认 | 不自动重复上报；保留 clickid，按回调与对账核实 |
904 | 流量未通过筛选或点击参数被拒绝 | 按订单接入说明排查，不重复提交相同请求 |
905 | 订单限量，或本次请求未发出；具体含义随订单而异 | 未确认具体含义前不自动重试；由我方确认恢复或重试方式 |
906 | 订单配置异常或所需功能未启用 | 联系我方处理 |
907 | 请求被拒绝 | 排查参数及订单要求 |
908 | 存在归因告警，结果待确认 | 保留本次记录并联系我方核对，不重复上报 |
| 其他 | 未列出的业务结果 | 保存完整响应并联系我方，不自行归类为成功 |
3.2 HTTP 异常与重试边界
除了上述业务响应，点击处理失败还可能返回 HTTP 500 或 HTTP 503，JSON 中的 code 也可能为 500 或 503。不要只解析 HTTP 200 的响应，也不要将业务码 503 与 HTTP 状态混为一谈。
| 场景 | 处理方式 |
|---|---|
| HTTP 500 | 当前不能保证同一 clickid 重试一定成功；如重试，必须保留原 clickid。若随后返回 401，停止重试并由我方核对，不据此认定原点击已经成功 |
| HTTP 503 / 业务码 503 | 暂缓发送、限次退避；重试同一次点击仍使用原 clickid。持续异常或出现 401 时联系我方 |
| 请求超时、断网、无响应 | 结果未知，不等同于请求未送达；保留原始请求记录，不换 clickid 重放 |
| 903 / 908 | 按结果待确认处理，依据回调和对账核实 |
| 明确到量 | 停止新点击，待订单恢复可投后再处理；不要循环重试消耗请求量 |
建议同时记录 HTTP 状态、业务码、msg、ckey、clickid 和请求时间，供双方核对。不要通过增加并发、频繁重试或更换 clickid 绕过异常与限量。
4. 转化回调
4.1 通知协议与地址
我方确认可通知的转化事件后，以 HTTP GET 调用约定的回调地址。点击时携带有效 cb，该次点击的通知优先使用此地址；未携带则使用预先约定并配置的回调地址。
- 仅提交协议、域名（可含端口）和路径，不得包含
?查询串、#片段或自定义占位符。 - URL 解码后的完整地址最长 512 字节，包含协议、域名和路径；不得提交 2 KB、3 KB 等超长地址。
- 不得把渠道业务参数、设备信息、JSON、签名串或其他上下文塞入回调 URL，也不得在点击请求中增加自定义参数并期望平台自动回传。
- 点击级
cb和预先登记的回调地址都遵循此约定。cb仅指定通知目标，不提供额外数据的存储或透传能力。
可提交的地址示例：
https://channel.example.com/callback
以下地址不符合约定，即使其总长度未超过 512 字节也不能使用：
https://channel.example.com/callback?clickid=abc&extra=payload
提交点击级 cb 时，将符合上述约定的完整基础 URL 作为一个参数值做 URL 编码。实际发送通知时，平台会添加约定的标准转化字段，渠道接收端应按第 4.2 节读取；这些字段不由渠道预先拼入提交地址。
回调地址还需为公网可访问的 HTTP/HTTPS URL，不能指向内网或环回地址。完整请求须满足双方 HTTP 服务及网关的大小限制，地址在发送时也必须能够正常访问。无有效回调地址时不发送通知。
| 项目 | 规则 |
|---|---|
| 成功应答 | 渠道返回 HTTP 200；不以响应正文作为成功条件 |
| 等待超时 | 5 秒，建议接收成功后及时返回 200，业务处理放异步 |
| 失败重试 | 首次失败后，按 1 分钟、5 分钟、15 分钟、1 小时、6 小时依次重试，最多额外 5 次 |
| 重复通知 | 重试和人工重发可能产生重复，渠道必须实现幂等 |
| 归因期 | 默认点击后 30 天，实际归因期以订单约定为准 |
4.2 平台回调字段
以下为平台通知中使用的字段，不是供渠道填写到回调地址里的自定义参数或模板。实际携带范围以订单约定和联调结果为准。
| 字段 | 含义 | 接入要点 |
|---|---|---|
click_id | 渠道原始 clickid | 平台用于关联点击的通知字段；渠道据此匹配该次点击 |
conv_action | 对渠道通知的事件代码 | 使用我方确认的事件表；不要写死为固定事件 |
conv_time | 按订单约定可能携带的秒级通知时间 | 可能为事件发生时间，也可能为我方接收/记录时间，具体见第 4.4 节 |
pay_amount / amount | 该订单约定的金额数值 | 是否携带、字段名称和元/分单位按第 4.3 节确认 |
conversion_id | 本平台转化流水 ID | 普通付费按流水携带；同一流水重试保持不变，各次真实付费使用不同 ID，不等同于渠道交易号 |
渠道不得在提交地址中填写 __click_id__、__conv_action__ 等占位符，或通过自定义字段名要求平台替换。点击参数、渠道自定义宏和额外业务数据均不属于本接口支持的参数透传范围。
部分订单可能携带已约定的 trade_id、order_no、sign 等转化附加字段，是否出现及其含义需按订单联调确认；不能将这些订单差异视为通用的自定义参数透传能力。
4.3 金额字段、单位与对账
当前接入中存在不同金额口径，同名 pay_amount 也可能代表不同单位。上线前必须用带金额的真实联调样例，确认本订单的字段名、单位、是否折算，以及零值和缺失值的含义。 金额含义尚未确认时，不应据此自动结算。
| 回调金额形态 | 解释与处理 |
|---|---|
已确认按元传递的 pay_amount | 如 5.00 表示 5 元；是否已做金额折算，以本订单确认结果为准 |
已确认按分传递的 amount 或 pay_amount | 如 500 表示 5 元；展示为元时除以 100，不能当成 500 元 |
| 原值传递的金额 | 数值可能保留前导零或小数形式，且未做金额折算；不要因外观带小数就判定为元 |
| 未携带金额，或出现零值 | 不能仅据此认定发生零元交易，也不能用订单单价补造用户付款金额 |
某些订单始终使用 amount 传递金额，仅在订单另有约定时同时携带 pay_amount；两者若代表同一笔金额，不得相加。没有金额字段的转化，也可能是有效的激活、注册或其他非金额事件。
订单结算方式、计费事件与回调金额是不同约定。对账时按已确认的口径处理，不统一套用“所有金额均为元”或“所有金额均已折算”的规则。
4.4 时间与幂等
conv_time 按秒级时间戳处理。当前部分订单返回我方接收或记录时间，不保证所有订单均返回原始事件发生时间；有明确业务时间要求时，必须在联调中确认时间来源。不要仅凭该字段判定留存天数、首日付费或归因窗口。
普通付费 buy 按每次有效转化分别记录和派发，自动携带 conversion_id（本平台流水 ID），失败重试和人工重发沿用相同 ID。渠道收到此字段时，应按本平台流水 ID 实现幂等，同一 clickid、同金额的不同流水仍是不同付款。渠道使用已约定的事件代码时同样遵循这条流水语义。上线逐次付费前需确认渠道接收并使用此字段。
其他事件继续按“渠道 clickid + 实际收到的事件代码”处理重复通知。一个点击可能对应多个不同事件，不应仅按 clickid 去重。旧通知未携带流水 ID 时，按已确认的订单协议处理，不推测其对应哪次交易。
4.5 常见事件
以下为常见默认代码。订单可能仅启用其中一部分，或使用双方确认的自定义事件代码。渠道应支持按订单配置映射，并记录未识别事件，避免把未知代码直接当成激活或付费。
| Android 示例 | iOS 示例 | 含义 |
|---|---|---|
android_activate | ios_activate | 激活 |
android_register | ios_register | 注册 |
android_next_day_retention | ios_next_day_retention | 次日留存 |
android_3days_retention | ios_3days_retention | 3 日留存 |
android_7days_retention | ios_7days_retention | 7 日留存 |
android_add_to_cart | ios_add_to_cart | 加入购物车 |
android_buy | ios_buy | 购买/付费 |
android_credit | ios_credit | 授信 |
android_pull_up | ios_pull_up | 唤起应用 |
android_custom | ios_custom | 自定义事件 |
android_first_open | ios_first_open | 首次打开 |
android_place_order | ios_place_order | 下单 |
android_submit_form | ios_submit_form | 提交表单 |
android_first_day_pay | ios_first_day_pay | 首日付费，不能等同于首次付费 |
4.6 地址提交与通知示例
渠道提交的基础回调地址（不带任何查询参数）：
https://channel.example.com/callback
假设订单已确认 pay_amount 按元传递，平台生成的 5 元付款通知示例（标准转化字段由平台添加）：
https://channel.example.com/callback?click_id=channel-click-001&conv_action=android_buy&pay_amount=5.00&conversion_id=123456
若该订单确认按分传递，同一金额应按 500 解读；若实际约定使用 amount，应读取该字段。上述示例不代表所有订单使用同一金额口径。
我方连通性测试会发送 conv_action=test、test=1，测试 clickid 为 test_click_001。渠道应应答成功，但不得将测试通知计入真实转化或结算。
5. 订单状态与限量
5.1 查询请求
POST https://api.example.com/api/v1/order/status，Content-Type: application/json。建议每个渠道每 5 分钟查询一次；异常时可补充查询，避免高频轮询。
| 字段 | 类型 | 要求 |
|---|---|---|
token | string | 必填，我方发放的渠道查询凭证 |
ckeys | string 数组 | 可选，指定订单；不传或空数组表示查询本渠道全部订单 |
指定查询建议每批不超过 100 个。当前实现只保留前 100 个有效匹配项，超出不保证返回，也不保证报错；请自行分批。未知订单或非本渠道订单不会返回。全量查询与指定查询的数量行为不同，不要用超长指定列表替代全量查询。
{"token":"your_query_token","ckeys":["order-ckey-example"]}
成功响应示例：
{
"code": 0,
"msg": "ok",
"data": [
{"ckey":"order-ckey-example","status":"running","os":"android"}
]
}
os 表示订单定向，通常为 android 或 ios，未限定时可能为空。接口返回状态，不提供具体额度或已用数量；如需额度信息，请按双方约定对接。
5.2 状态与投放动作
| status | 含义 | 渠道动作 |
|---|---|---|
running | 当前订单处于可投状态 | 仍需满足点击参数、RTA 和实时限量要求 |
paused | 当前暂停 | 停止新投放，等待恢复 |
not_started | 尚未到投放开始日期 | 等待约定开始日期，重新查询确认 |
ended | 已超过投放结束日期 | 停止投放 |
closed | 订单关停 | 停止投放并联系我方 |
limited | 订单已达到限量 | 停止新点击，按周期或额度调整情况等待恢复 |
unavailable | 当前无法确认订单额度可用性 | 暂停新投放，稍后查询；持续出现则联系我方 |
| 未识别的值 | 状态无法按现有规则解释 | 暂停并联系我方，不默认视为 running |
limited、unavailable 在启用相应限量能力的订单中使用。查询结果只反映查询时刻状态，后续点击仍可能因并发用量、状态变化或其他校验被拒绝。
5.3 限量周期与恢复
订单可按点击次数或约定转化事件配置每日、每周、累计限量。任一适用规则到量即可暂停接收新点击；转化事件限量并不只包含激活。
| 周期 | 恢复条件 |
|---|---|
| 每日 | 下一自然日重新按该日用量判断 |
| 每周 | 周一 00:00 开始新周期 |
| 累计 | 不会因跨日、跨周自动重置，需要我方确认调整或恢复 |
即使某个周期已经更新，其他规则仍到量或订单仍暂停时，也不能恢复投放。因此不能将 801/802 一概解释为“明天自动恢复”。请以状态查询和我方确认结果为准。
被限量拒绝、重复提交的请求不应作为新的有效点击。订单停止接收新点击后，已有点击的转化仍可能到达并通知；转化存在延迟，事件限量不是最终转化数量的硬上限。
5.4 查询错误
| HTTP | code | 含义与处理 |
|---|---|---|
| 400 | 1 | 请求格式或参数错误，检查 token 和 JSON |
| 401 | 2 | token 无效，核对凭证 |
| 403 | 4 | 渠道停用，停止查询并联系我方 |
| 500 | 3 | 查询异常，退避后重试，持续异常联系我方 |
单个订单的 unavailable 可能出现在 HTTP 200、code=0 的成功响应中。不要只根据接口调用成功就继续向该订单发送流量。
6. 曝光上报
仅对我方已开通并发放曝光链接的订单上报。请求方式为 GET https://click.example.com/cpa/imp，使用发放链接上的宏，设备及附加参数要求通常与点击一致。
- 曝光不使用
cb发送转化回调，不代替真实点击，也不参与点击归因。 - 曝光不按点击规则判重，也不消耗点击/转化限量，但仍检查订单状态、投放日期及参数。
- 曝光仍需有效 clickid 和订单要求的设备字段。未开通曝光时返回业务码
102。 - 响应按第 3 章处理；曝光失败不应导致重复点击或补造转化。
Android 请求示例：
curl --get 'https://click.example.com/cpa/imp' \
--data-urlencode 'ckey=order-ckey-example' \
--data-urlencode 'clickid=channel-impression-001' \
--data-urlencode 'os=android' \
--data-urlencode 'oaid=真实设备OAID' \
--data-urlencode 'ip=真实设备公网IP' \
--data-urlencode 'ua=真实设备User-Agent原文'
7. RTA 筛选查询
7.1 使用流程
仅 RTA 订单需要在投放前查询。渠道发送设备信息和待查询订单，得到本次可投的 ckeys；仅对中选订单继续当前投放流程，发生真实点击后，再按点击接口上报。
RTA 成功不代表点击已上报，也不保证随后点击一定被接收。RTA 不替代状态查询或实时限量检查；已到量或额度暂不可确认的订单仍可能出现在筛选结果中，渠道应同时检查订单状态。
7.2 请求字段
POST https://api.example.com/api/v1/rta，Content-Type: application/json。请求体最多 64 KiB，无需 token。
| 字段 | 类型 | 要求 |
|---|---|---|
req_id | string | 必填，非空，最多 64 字节；渠道生成并保证唯一，响应原样返回 |
ckey | string | 必填，我方发放的订单凭证，与点击链接一致 |
ckeys | string 数组 | 可选，追加本渠道订单；数组最多 100 项，与 ckey 合并去重后最多 100 个 |
os | string | 建议明确填写 android / ios；缺省时按设备标识推断，混合或无法推断则报错 |
ip / ua | string | 建议始终携带，部分订单必填；UA 在 JSON 中传原文 |
oaid / oaid_md5 / imei / imei_md5 | string | Android 设备标识，具体支持范围见第 7.3 节 |
idfa / idfa_md5 / caid | string | iOS 设备标识，具体支持范围见第 7.3 节 |
clickid | string | 常规订单可选；指定小程序/快应用订单必填 32 位标识，查询与点击保持一致 |
caid2 | string | 可选，另一版本 CAID，不单独满足常规设备要求 |
anid / anid_md5 | string | 可选辅助设备字段，不单独满足常规 RTA 设备要求 |
mac / mac_md5 | string | 可选辅助字段，仅按订单约定使用 |
ts | string | 可选，使用时按订单要求传 13 位毫秒时间戳 |
osv / model | string | 可选，系统版本和设备型号 |
未传 ckeys 时只查 ckey，不会查询本渠道全部订单。追加项中未知或不属于本渠道的订单会被忽略；必填 ckey 无效时返回参数错误。数量限制针对输入及合并去重结果，不应依赖无效项被忽略来绕过上限。
7.3 设备及关联要求
| 系统 | 常见建议 | 需要逐单确认的差异 |
|---|---|---|
| Android | oaid、oaid_md5、imei_md5 至少一项 | 部分订单接受仅传明文 imei，部分不接受 |
| iOS | 优先明确提供 idfa_md5 | 部分订单接受 idfa 或 CAID；未经确认，不要仅传 CAID |
MD5 建议统一使用 32 位小写十六进制。字段不得使用未替换宏、虚构值或全零值。需要 MD5 的订单请明确填写对应字段，不要依赖接口自动从明文生成。混合查询时必须满足所有实际参与筛选订单的要求，否则可能整次报参数错误。
未启用 RTA、暂停、关停、不在投放日期或 OS 不匹配的订单不参与筛选。没有可参与筛选的订单时返回空列表；空列表不一定表示设备不命中，也可能表示没有符合条件的订单。
特殊小程序/快应用订单的 clickid 必须满足第 2.4 节的 32 位规则。若订单要求 RTA 与点击严格复用 clickid、ts 或其他上下文，必须在确认该订单已具备相应关联能力后接入，不能仅凭 req_id 自行假设已完成关联。
RTA 允许省略 IP/UA 的订单，点击时仍须满足点击接口的要求。用于查询的设备信息应与真实点击一致，并通过发放的监测链接上报。
7.4 请求与响应示例
Android 常规订单示例，所有设备值需替换为真实值：
{
"req_id": "auction-20261014-001",
"ckey": "order-ckey-example",
"os": "android",
"oaid": "真实设备OAID",
"ip": "真实设备公网IP",
"ua": "真实设备User-Agent原文"
}
iOS 将 os 改为 ios，并使用该订单接受的 idfa_md5 等字段替换 oaid。要求特殊 clickid 的订单，另行添加 "clickid":"0123456789abcdef0123456789abcdef"，实际值由渠道唯一生成。
成功响应：
{
"code": 0,
"msg": "ok",
"data": {
"req_id": "auction-20261014-001",
"is_ta": true,
"ckeys": ["order-ckey-example"]
}
}
| 字段 | 含义 |
|---|---|
req_id | 本次请求 ID 原值 |
is_ta | 至少一个订单被选中时为 true，否则为 false |
ckeys | 本次选中的订单列表，按请求顺序去重；未选中时为空数组 |
is_ta=false、ckeys=[] 是正常业务结果，本次不投即可。结果仅用于当前竞价，不要跨竞价复用。
真实点击时建议携带 rta_req_id=<本次响应req_id>；标注“需关联 RTA 请求”的订单必须携带。该字段与 clickid 不同，不要把 req_id 自动替代为点击标识，也不要混用不同查询的 req_id。
7.5 失败处理
失败响应为 HTTP 4xx/5xx，正文形如 {"code":1,"msg":"参数错误"}。
| HTTP | code | 含义与处理 |
|---|---|---|
| 400 | 1 | 参数或设备不符合要求、ckey 无效、数量或请求体超限；修正后再查 |
| 500 | 6 | RTA 尚未配置、未启用或不支持；联系我方 |
| 502 | 7 | 查询失败、超时或结果异常；建议本次不投 |
| 429 | 8 | 查询限流；降低请求量，避免立即重试 |
| 503 | 9 | 查询服务暂不可用；建议本次不投，持续异常联系我方 |
批量查询中任一部分失败，整次返回错误，不返回部分成功结果。建议渠道为查询预留约 1 秒，最终以双方确认的竞价时限为准。查询失败或超时不代表已获准投放，避免同步重试放大流量。
8. 联调与上线检查
- 确认我方发放的域名、ckey、查询 token、点击/曝光链接及订单接入说明，区分查询接口与监测接口的成功码。
- 用真实设备数据验证常规点击；确认缺参、OS 错误、重复 clickid、回调地址错误等响应符合渠道处理逻辑。
- 确认提交的回调地址不带查询参数或自定义占位符、解码后不超过 512 字节；完成连通性测试并过滤
test=1，再用真实联调事件确认平台实际添加的字段、事件代码、幂等键、金额单位、是否折算和时间来源。 - 状态查询须识别 limited、unavailable；只在可投状态下发送新流量，正确处理日、周、累计限量。
- RTA 订单测试命中、不命中、批量查询、错误和超时；有特殊标识要求时，核对查询、跳转及点击中的 clickid 是否一致。
- 对 HTTP 500/503、业务码 503/903/905/908 和网络异常建立明确处理规则，不因结果未知而更换 clickid 重放。
- 对账保留 ckey、渠道 clickid、事件代码、金额原值及单位、请求/接收时间、HTTP 状态和业务码；异常由双方按同一标识核对。
普通点击成功、RTA 中选、订单状态为 running，均不能代替真实转化通知或双方确认的结算结果。