移动合作任务完成事件回调接口

业务流程图

sequenceDiagram
    participant App as APP
    participant Partner as 移动方
    participant API as 服务端

    App->>Partner: 1.打开H5页面_携带userToken
    Partner->>Partner: 2.用户完成任务
    Partner->>API: 3.POST回调_partnerId+token+userToken
    alt 验签失败
        API-->>Partner: 错误响应
    else 验签成功
        API->>API: 业务处理
        API-->>Partner: 成功响应
    end

1. 接口概述

1.1 功能说明

用于接收外部移动方系统的任务完成通知。当用户在APP内唤起移动方页面并完成指定任务（如下单、兑换等）后，移动方服务端需调用本接口通知服务端，以便触发相应的业务处理流程（如奖励发放、任务进度更新等）。

1.2 业务场景

  1. APP唤起移动方H5页面，传递 userToken（用户标识）
  2. 用户在H5页面内完成任务操作
  3. 移动方服务端将任务完成事件回调至OpenAPI
  4. 服务端根据 userToken 识别用户并完成业务处理

1.3 接入流程

  1. 获取分配的 partnerId（移动方标识）和 key（签名密钥），成对出现，配对有效
  2. 约定APP唤起H5时传递 userToken 的参数名称（待移动方同学确认）
  3. 按照本文档规范实现接口调用
  4. 在测试环境完成联调验证
  5. 切换至正式环境上线

2. 接口信息

2.1 请求地址

  • 测试环境: https://earth-openapi.lazyaudio.com/open/attribution/exchange_complete
  • 正式环境: https://open.lrts.me/open/attribution/exchange_complete

2.2 请求方式

  • Method: POST 或 GET
  • Protocol: HTTPS
  • Content-Type: application/x-www-form-urlencoded（参数拼接在URL）

2.3 测试账号示例

以下账号、密钥为测试环境使用

  • 移动方标识: partnerId=200323001810
  • 签名密钥: key=M(z-hhV#e:KANS&k&wnU!NKJ

3. 请求鉴权

3.1 鉴权说明

为确保只有授权的移动方访问接口，本接口采用基于 MD5 的签名机制进行身份验证。

3.2 签名生成规则

步骤 1: 提取参与签名的参数

对所有请求参数，排除以下字段： - partnerId（不参与签名） - token（签名结果本身）

参与签名的参数示例： - userToken（必填） - requestId（可选） - 其他业务参数（如有）

步骤 2: 按参数名排序

对参与签名的参数按照 参数名（key）的字符 ASCII 码升序排列。

排序示例：

原始参数：requestId=req001, userToken=user123
排序后：requestId, userToken

步骤 3: 拼接签名字符串

按以下格式拼接：

/接口路径?key1=value1&key2=value2

格式说明： - 以接口路径开头：/open/attribution/exchange_complete - 拼接排序后的参数：?requestId=req001&userToken=user123

完整示例：

/open/attribution/exchange_complete?requestId=req001&userToken=user123

步骤 4: 追加密钥

在步骤 3 得到的字符串末尾追加 key（签名密钥）。

示例：

/open/attribution/exchange_complete?requestId=req001&userToken=user123M(z-hhV#e:KANS&k&wnU!NKJ

步骤 5: MD5 计算

对步骤 4 得到的字符串进行 MD5 加密（32 位小写十六进制），得到的结果即为 token 的值。

4. 请求参数

4.1 参数列表

参数名 类型 必填 描述 是否参与签名
partnerId long 是 移动方标识，由服务方分配 否
token string 是 参数签名，计算规则见"3.2 签名生成规则" 否（签名结果本身）
userToken string 是 用户标识，由APP生成并透传给移动方H5，移动方需原样回传，用于标识用户信息 是
taskId string 是 任务完成的唯一标识，由移动方生成，用于防止重复发放奖励 是
eventType string 否 完成事件类型，用于区分不同的任务完成场景（便于后续扩展不同处理逻辑） 是
requestId string 否 请求唯一ID，由调用方生成，用于链路追踪和问题排查 是

4.2 参数说明

partnerId 字段

  • 用途：唯一标识移动方身份
  • 获取方式：由服务方商务团队分配
  • 示例：200323001810
  • 注意：不参与签名计算

token 字段

  • 用途：参数签名，用于验证请求的合法性和完整性
  • 计算方式：见"3.2 签名生成规则"
  • 格式：32位小写十六进制字符串
  • 示例：a1b2c3d4e5f6789012345678901234ab
  • 注意：
  • 签名结果本身，不参与签名计算
  • 服务端会验证签名，不匹配则返回错误

taskId 字段（重要-防重）

  • 用途：任务完成的唯一标识，用于防止重复发放奖励
  • 生成规则：由移动方系统生成，确保全局唯一
  • 注意：
  • 必须保证唯一性，相同 taskId 的重复请求将幂等处理
  • 建议包含移动方标识、用户标识、时间戳等信息
  • 长度建议不超过 64 字符
  • 使用场景：
  • 防止网络重试导致的重复奖励发放
  • 用于任务完成记录的唯一标识和去重

eventType 字段（扩展性）

  • 用途：完成事件类型，用于区分不同的任务完成场景
  • 是否必填：否（可选参数）
  • 推荐值（示例）：
  • task_complete：普通任务完成
  • order_complete：订单完成
  • subscribe_complete：订阅完成
  • share_complete：分享完成
  • 或其他自定义事件类型
  • 使用场景：
  • 便于服务端针对不同事件类型进行差异化处理
  • 后续扩展新的任务类型时无需修改接口定义
  • 支持业务方根据实际需求灵活定义事件类型
  • 注意：
  • 参与签名计算
  • 如不传递，服务端将按默认逻辑处理
  • 长度建议不超过 32 字符

userToken 字段（重要）

  • 用途：用户标识，由APP生成并透传
  • 业务流程：
  • APP唤起移动方H5页面时，在URL中携带 userToken 参数
  • 用户在H5页面内完成任务
  • 移动方服务端回调时，将 userToken 原样回传
  • 服务端根据 userToken 识别用户并完成业务处理
  • 格式建议：字符串，建议使用Base64或类似编码，确保URL安全
  • 示例：
  • user_20250121_123_001
  • dXNlcl8yMDI1MDEyMV8xMjNfMDAx（Base64编码）
  • 重要提示：
  • 必须原样回传，不可修改、截断或丢失
  • 参与签名计算
  • 该字段由APP生成，移动方无需理解其内部结构

requestId 字段

  • 用途：请求唯一ID，用于双方日志关联和问题排查
  • 格式建议：具有时序性和唯一性
  • 示例：req_20250121_000001 或 UUID
  • 参与签名：是

4.3 请求示例

最小必填请求

GET /open/attribution/exchange_complete?partnerId=200323001810&token=xxx&userToken=user_20250121_123_001&taskId=200323001810_123456_1737534000

完整请求（推荐，包含 eventType）

POST /open/attribution/exchange_complete?partnerId=200323001810&token=xxx&userToken=user_20250121_123_001&taskId=200323001810_123456_1737534000&eventType=task_complete&requestId=req_20250121_000001

说明

  • eventType 为可选参数，用于标识任务完成的事件类型
  • 如需针对不同场景进行差异化处理，建议传递此参数
  • 示例值：task_complete、order_complete、subscribe_complete 等

5. 响应参数

5.1 响应格式

参数名 类型 必返回 描述
status int 是 状态码，0 表示成功，非 0 表示失败
msg string 是 返回说明
requestId string 否 回显请求ID（如请求中携带）

5.2 响应示例

成功响应

{
  "status": 0,
  "msg": "处理成功",
  "requestId": "req_20250121_000001"
}

失败响应（签名错误）

{
  "status": 38,
  "msg": "token校验失败"
}

失败响应（参数错误）

{
  "status": 4,
  "msg": "参数验证失败: taskId不能为空"
}

6. 错误码说明

错误码 说明 处理建议
0 请求成功 包含"首次处理成功"和"去重命中（已处理过）"两种情况，均视为成功
4 参数验证失败 检查必填参数是否完整，参数类型、格式是否正确（对应OpenapiConst.PARAMS_ERROR）
38 签名验证失败 检查 partnerId 和 key 是否正确，签名计算逻辑是否符合规范（对应OpenapiConst.NO_AUTH_TOKEN_INVALID）
1 服务器内部错误 服务端处理异常，请联系技术支持并提供 requestId（对应OpenapiConst.ABNORMAL_SYSTEM）

7. 调用示例

7.1 cURL 请求模拟

签名示例（无需计算，可直接测试）

以下示例使用预先计算好的签名，可直接复制执行，无需任何依赖：

示例1：不带 eventType（最小参数）
# 测试环境
curl -v -X POST "http://earth-openapi.lazyaudio.com/open/attribution/exchange_complete?partnerId=200323001810&token=9e4f7a58c98aabdf8cccaf7a66612951&userToken=user_20250121_123_001&taskId=200323001810_123456_1737534000&requestId=req_20250121_000001"

# 正式环境
curl -v -X POST "https://open.lrts.me/open/attribution/exchange_complete?partnerId=200323001810&token=9e4f7a58c98aabdf8cccaf7a66612951&userToken=user_20250121_123_001&taskId=200323001810_123456_1737534000&requestId=req_20250121_000001"

签名计算过程：

签名字符串 = /open/attribution/exchange_complete?requestId=req_20250121_000001&taskId=200323001810_123456_1737534000&userToken=user_20250121_123_001M(z-hhV#e:KANS&k&wnU!NKJ
MD5(签名字符串) = 9e4f7a58c98aabdf8cccaf7a66612951
示例2：带 eventType（推荐，便于扩展）
# 测试环境
curl -v -X POST "http://earth-openapi.lazyaudio.com/open/attribution/exchange_complete?partnerId=200323001810&token=51192f5fe5ad8553159573c0395fdd0b&userToken=user_20250122_123_001&taskId=200323001810_123456_1737534000&eventType=task_complete&requestId=req_20250122_000001"

# 正式环境
curl -v -X POST "https://open.lrts.me/open/attribution/exchange_complete?partnerId=200323001810&token=51192f5fe5ad8553159573c0395fdd0b&userToken=user_20250122_123_001&taskId=200323001810_123456_1737534000&eventType=task_complete&requestId=req_20250122_000001"

参数说明： - partnerId: 200323001810（测试账号） - userToken: user_20250122_123_001（示例用户标识） - taskId: 200323001810_123456_1737534000（示例任务ID） - eventType: task_complete（事件类型） - requestId: req_20250122_000001（示例请求ID） - token: 51192f5fe5ad8553159573c0395fdd0b（已计算好的签名）

签名计算过程（注意参数按 ASCII 码升序）：

签名字符串 = /open/attribution/exchange_complete?eventType=task_complete&requestId=req_20250122_000001&taskId=200323001810_123456_1737534000&userToken=user_20250122_123_001M(z-hhV#e:KANS&k&wnU!NKJ
MD5(签名字符串) = 51192f5fe5ad8553159573c0395fdd0b