商户 API 接入指南

一、背景与目标

1.1 业务背景

商户 API 面向商户自有业务系统，提供一套围绕“项目合作、创客招募、额度校验、结算发放、交付验收、账户与开票”展开的标准接入能力。

对商户而言，实际接入的目标通常不是“调用几个接口”，而是把平台能力稳定嵌入自己的业务流程中，例如：

• 在商户后台展示可用项目和项目配置
• 判断某个创客在当前项目下是否已经招募、是否仍需签约
• 批量发起招募，并在商户系统中收取异步处理结果
• 在发起结算前，先确认创客在当前项目下是否具备真实可结算额度
• 创建结算单、触发支付、追踪结算明细结果并获取回单
• 在需要上传成果物的项目中，按结算明细提交交付文件
• 查询企业账户余额和充值信息
• 查询已发放成功流水的可开票金额并提交开票申请

因此，本文档的重点不是介绍平台内部实现细节，而是从商户接入视角明确：

• 每个接口解决什么问题
• 每个接口该在什么时机调用
• 同步返回与最终业务结果之间是什么关系
• 哪些字段和状态需要商户系统长期保存
• 哪些业务规则会直接影响商户的接入设计

1.2 设计原则

项目中心化：所有核心能力围绕项目展开

• 项目是招募、签约、额度、结算、交付物和发票归集的统一业务载体。
• 商户在系统设计时，应优先以 projectId 为主线组织数据和流程，而不是把项目当成一个可有可无的辅助字段。

同步受理、异步收口：复杂链路不在同步接口中做最终承诺

• recruit 属于典型异步接口。同步响应只说明“平台是否接受本次任务”，不直接代表“已经签约成功”。
• 实名、历史资格复用、OCR、活体、签约链接生成等复杂动作都在异步任务中完成，最终结果通过回调通知商户。

结果可理解：优先返回商户真正关心的业务结论

• 对于额度接口，很多“不具备资格”的情况不会直接抛业务异常，而是返回 eligible=false 和 0 额度，并明确原因字段。
• 对于招募状态接口，使用相对稳定的五态结果，方便商户直接做前端展示、失败识别和业务流转。

边界清晰：区分受理结果、处理中结果与最终结果

• accepted=true、status=进行中、paymentTime!=null 这类字段都不等价于“业务最终成功”。
• 商户接入时需要明确哪些接口用于“受理”，哪些接口用于“查状态”，哪些回调用于“最终确认”。

安全优先：签名、加密、权限隔离统一执行

• 所有接口调用都需要验签。
• POST 业务请求统一按 AES 加密方式接入。
• 商户只能访问自己有权限的数据，不能依赖“知道某个 ID 就能查到数据”的假设。

1.3 设计目标

• 统一接入方式：统一使用 /merchantapi/v2 路径前缀、统一请求头、统一签名与加密规则。
• 降低实施成本：商户只需要关注项目、创客标识、结算金额、收款账户、交付文件等业务数据，不需要理解平台内部模型。
• 降低误判风险：明确异步接口的受理口径、回调口径和历史数据复用口径，避免商户把“处理中”当成“已完成”。
• 提高联调效率：通过快速开始、通用请求规则、字段说明和错误码说明，让商户可以按固定顺序完成联调。
• 提升长期稳定性：帮助商户在自己的系统中形成稳定的数据模型、幂等策略和异常处理策略，降低后续维护成本。

1.4 术语说明

术语	说明
商户	接入商户 API 的业务主体
创客	平台侧可参与项目、签约、结算的自由职业者
项目	平台中的业务载体，招募、额度、结算、交付物均围绕项目发生
招募批次号	商户为一次招募请求定义的业务批次号，用于幂等和结果关联
外部用户ID	商户自身业务系统中标识创客的稳定业务 ID
招募任务	平台为单个创客生成的异步处理任务，对应 taskId
结算单	一次结算申请，包含一个或多个结算明细
结算明细	结算单中的单笔记录，通常对应某个创客的一笔付款
交付物	围绕某个结算明细上传的成果文件
可结算额度	创客在当前项目、当前收款方式下还能继续结算的真实金额
同税地资格	创客在某个税地下的实名、活体、签约等资格组合状态

说明 1：ID 字段统一建议按字符串处理

为避免前端或弱类型语言处理 64 位整型时出现精度丢失，所有代表 ID 的字段在接入侧都建议按字符串处理。常见字段包括：

• projectId
• taskId
• makerId
• settlementId
• detailId
• deliverableId
• invoiceId
• accountId

说明 2：projectId 以“显式传入优先，client 默认项目兜底”为基本口径

部分接口支持两种项目来源：

• 请求体显式传入 projectId
• 平台为当前 client 预先绑定默认 projectId

如果两者同时存在，以请求体中的 projectId 为准。
如果商户存在多项目场景，建议始终显式传入 projectId，不要依赖默认项目兜底。

说明 3：外部用户ID应视为商户侧稳定主键

在招募、查询状态、查询额度、解绑等链路中，platformUserId 不是一个可随意替换的展示字段，而是商户侧用来识别创客的重要业务标识。
商户侧应避免在正常招募链路中频繁更换同一创客的 platformUserId，否则容易触发历史绑定冲突或未决任务冲突。

1.5 常见状态对照表

1.5.1 项目状态

状态码	状态描述	说明
0	未开始	项目尚未进入可执行阶段
1	进行中	当前可用于招募、额度、结算等业务
2	已结束	项目已结束，不能继续招募和结算

1.5.2 项目审核状态

状态码	状态描述	说明
0	未审核	项目已创建但还未审核通过
1	已审核	项目审核通过，可进入正式使用阶段
2	已驳回	项目审核未通过

1.5.3 招募状态

queryRecruitStatus 使用五态表示创客在当前项目下的状态：

状态值	状态描述	说明
UNRECRUITED	未招募	创客不存在，或存在但尚未加入当前项目
RECRUITING	招募中	已发起当前项目招募，且招募流程尚未终结，例如签约链接仍有效、创客尚未完成签约
RECRUITED_UNSIGNED	已招募待签约	已加入当前项目，但实名、活体、签约任一未完成，或历史签约已无法覆盖当前项目要求
RECRUITED_SIGNED	已招募已签约	已加入当前项目，且同税地资格完整、签约仍在有效期内
FAILED	失败	当前项目下最近一次匹配的招募任务已失败

1.5.4 招募异步任务状态

recruit 的最终业务结果依赖异步回调，当前商户需要重点关注以下三类异步状态：

状态值	状态描述	说明
FAILED	失败	异步处理失败，商户应结合错误码和错误信息处理
SIGN_URL_READY	签约链接已生成	已生成签约链接，等待创客完成签约
SIGNED	已签约	已签约成功，或复用了仍然有效的历史签约结果

1.5.5 结算单状态

状态码	状态描述	说明	可执行操作
0	未发放	结算单已创建，但尚未发起支付	可发起支付
1	发放中	结算支付处理中	可查询状态
2	发放完成	结算流程已完成	可查询状态、查询回单
3	拒绝发放	结算被拒绝或不可继续处理	不可再次发起支付

1.5.6 结算明细状态

状态码	状态描述	说明
0	待打款	明细已创建，等待打款
1	打款中	明细打款处理中
2	打款成功	明细打款成功，可查询回单
3	打款失败	明细打款失败
4	拒绝打款	明细被拒绝打款

说明：

• 商户接入时应按上述数字协议处理，不要把主单状态和明细状态混用。

1.5.7 交付物审核状态

状态码	状态描述	说明
0	待审核	已上传，等待审核
1	已通过	审核通过
2	已驳回	审核驳回，通常会返回驳回原因

1.5.8 发票状态

状态码	状态描述	说明
0	开票中	发票申请已提交，处理中
1	已开票	已完成开票
2	拒绝开票	发票申请被拒绝

二、核心设计理念

2.1 项目中心化模式

API 的核心不是“提供很多接口”，而是“围绕项目形成一条完整业务链路”。

对商户而言，项目不是单纯用于展示的配置对象，而是业务处理的中心：

项目
├── 招募与签约
├── 创客额度
├── 结算单与结算明细
├── 交付物
└── 发票归集

这意味着商户在自己系统中接入 API 时，建议先建立“项目主数据”视角，再围绕项目串联能力：

1. 先查询项目列表和项目详情
2. 再围绕项目查询招募状态、发起招募、查询额度
3. 之后围绕项目创建结算单并上传交付物

如果商户内部系统存在“活动”“批次”“订单”“任务包”等概念，建议将这些概念映射到平台项目之上，而不是跳过项目直接建结算。

2.2 招募、额度、结算、交付的一体化闭环

API 不再只关注“最后一笔钱怎么发出去”，而是把创客从进入项目到最终开票的关键动作串起来：

项目 -> 招募 -> 签约 -> 额度 -> 结算 -> 交付物 -> 发票

商户如果只接入结算接口，仍然可以完成基础支付动作；但如果希望减少线下人工处理和状态割裂，建议按下列顺序接入：

• 在招募前查询创客状态
• 招募后等待异步回调
• 结算前查询额度
• 结算后按明细上传交付物
• 结算完成后根据需要发起开票

2.3 异步招募与回调收口

recruit 是 API 中最容易接错的接口。

它的同步返回，重点是告诉商户“本次任务有没有被平台接受”；它的异步回调，重点是告诉商户“这个创客最终走到了哪一步”。因此商户在系统设计上必须把两件事拆开：

• 同步响应负责记录“是否已受理”“是否需要立即拦截”
• 异步回调负责更新“签约链接是否生成”“是否已签约”“最终失败原因”

建议商户系统至少保存以下字段，用于和回调对账：

• recruitBatchNo
• projectId
• platformUserId
• taskId
• 同步受理结果
• 异步最终状态

商户需要形成两个固定认知：

1. 同步 accepted=true 不代表已经签约成功，只代表该创客的任务已进入处理链路
2. 商户前端若需要展示“可去签约”，应以 SIGN_URL_READY 回调或状态查询结果为准，而不是以同步受理结果为准

2.4 资格复用与有效期覆盖

API 确实支持复用一部分历史资格，但复用不是“历史上签过就一定还能用”。

平台当前判断能否复用历史签约，核心看三件事：

1. 创客是否已经加入当前项目
2. 创客在当前项目所属税地下是否具备完整资格
3. 历史合同的有效期是否仍能覆盖当前项目的要求

当前项目的签约有效期口径为：

max(默认合同截止时间, 项目 check_date_end + 1个月)

这意味着：

• 历史上确实签过约，不等于当前项目一定可以直接复用
• 如果当前项目的 check_date_end 更晚，系统可能仍会要求重新签约
• 商户不应自行在前端推断“以前签过，所以本次一定不用签”，应以接口状态和回调结果为准

2.5 标识绑定与 URL 化简化

API 在两个方面做了明显收敛，目的是让商户系统更容易稳定接入。

第一，外部用户ID收敛为商户范围内的稳定业务主键

• 在招募、查状态、查额度等链路中，platformUserId 应被视为商户自己定义的稳定创客编号。
• 如果同一个商户在未完成历史处理的情况下，给同一手机号或同一身份证切换不同的 platformUserId，系统会按冲突处理，而不是默默覆盖。
• 若确有误绑场景，应通过解绑接口和人工排查处理，而不是在招募时直接改绑。

第二，交付物上传参数收敛为 URL 模式

交付物接口当前只保留两个文件字段：

• fileName
• fileUrl

商户只需要保证：

• 文件 URL 使用 HTTPS
• 文件在平台下载处理阶段可访问
• 文件内容与文件名基本一致，便于审核

三、快速开始

3.1 准备工作

接入前，建议商户按下面四件事完成准备。

第一步：获取接入凭证

联系平台管理员获取以下信息：

• AppId
• AppSecret
• AESKey
• 是否启用响应验签
• 回调是否需要独立验签或加密
• 当前 client 是否已绑定默认 projectId

第二步：确认环境地址

建议的接入地址如下：

• 测试环境：https://s.qa.gaosiqihui.com/merchantapi/v2
• 生产环境：https://s.gaosiqihui.com/merchantapi/v2

建议商户将环境配置做成显式切换，不要把测试环境地址写死在代码中。

第三步：完成安全侧准备

商户至少需要完成以下能力：

• 能按请求头规则生成 X-Sign
• 能对 POST 请求体进行 AES 加密
• 能校验响应签名
• 能接收并校验平台异步回调
• 能记录 requestId 方便问题排查

第四步：明确项目接入方式

很多 API 接口都依赖 projectId。如果当前 client 已绑定默认项目，部分接口可以不传 projectId；但如果商户有多项目、跨团队、跨业务线使用场景，建议统一显式传入 projectId，避免调用落到错误项目。

3.2 五步快速接入

以下步骤按“最短联调路径”组织，建议严格按顺序执行。

Step 1：打通签名、加密、解密与响应验签

先调用：

POST /merchantapi/v2/test/crypto

建议请求体（加密前）：

{
  "message": "Hello World! 测试V2加密功能"
}

本步骤的成功标准：

• 平台成功识别 AppId
• 平台成功验签
• 平台成功解密请求体
• 商户收到 code=0
• data.originalMessage 与原始明文一致
• 商户能成功校验响应中的 signature

如果这一步没有打通，不建议直接联调业务接口。

Step 2：查询项目并确认项目是否可用

调用：

GET /merchantapi/v2/projects?page=1&size=20&status=1&auditStatus=1

本步骤主要获取：

• projectId
• projectName
• status
• auditStatus
• availableMethods
• monthlyAvailable

商户至少应确认：

• 项目归属当前商户
• 项目状态为进行中
• 项目审核状态为已审核
• 项目确实支持后续计划使用的收款方式

Step 3：查询项目详情并确认结算前提

调用：

GET /merchantapi/v2/projects/{projectId}

建议重点确认：

• 项目所属税地
• 当前项目的收款方式配置
• 各收款方式的规则额度
• 项目绑定的账户摘要
• 是否要求交付物
• 项目的 checkDateStart / checkDateEnd

对需要招募和签约的业务，这一步还应重点关注 checkDateEnd，因为它会影响历史合同是否可复用。

Step 4：验证创客侧链路

这一阶段根据商户业务类型分成两种接入方式。

方式 A：需要招募新创客

建议顺序：

1. 先调用 POST /merchantapi/v2/projects/queryRecruitStatus
2. 如返回未招募、待签约或失败，再调用 POST /merchantapi/v2/projects/recruit
3. 保存同步返回中的 taskId
4. 等待异步回调收口最终状态

方式 B：创客已经入项，只需要发起结算

建议调用：

POST /merchantapi/v2/projects/makers/quota

重点确认：

• eligible=true
• receiveMethodQuotas[].availableQuota 足够覆盖本次结算金额

Step 5：试算税费、创建结算单、发起支付并核对结果

创建结算单前，可先调用个税试算接口预估单笔及汇总税费：

POST /merchantapi/v2/settlements/taxTrial

试算接口只返回税费预估，不创建结算单、不占用额度、不触发支付；但会校验项目税地、项目收款方式配置和创客项目归属。

创建结算单：

POST /merchantapi/v2/settlements

如未选择立即支付，后续可调用：

POST /merchantapi/v2/settlements/{settlementId}/pay

然后建议按以下顺序核对：

1. 查询结算单详情，确认主单状态和每条明细状态
2. 对成功明细调用回单接口
3. 如项目要求交付物，再按明细上传交付文件
4. 后续按需查询企业账户和开票余额

3.3 下一步

完成上述五步后，建议继续重点阅读：

• 第四章：接口设计
• 第五章：安全设计
• 第七章：异常处理
• 第九章：注意事项

如果商户接入的是完整业务闭环，而不是单一结算场景，建议优先把“招募接口、招募回调、额度接口、结算接口、交付物接口”放在同一轮联调中完成，这样更容易尽早发现状态流转问题。

3.4 异步通知总览

API 中需要重点接入的异步通知如下：

场景	所属接口/配置	回调地址来源	必须	典型结果
项目审核结果	POST /merchantapi/v2/projects/create	请求体 notifyUrl	否	项目审核通过 / 驳回
招募结果	POST /merchantapi/v2/projects/recruit	请求体 notifyUrl	是	FAILED / SIGN_URL_READY / SIGNED
结算结果	POST /merchantapi/v2/settlements	请求体 notifyUrl	否	结算主单和明细状态更新
充值上账结果	商户 API 客户端配置	客户端配置 rechargeNotifyUrl	否	企业账户充值到账
发票结果	POST /merchantapi/v2/invoice/apply	请求体 notifyUrl	否	开票中 / 已开票 / 拒绝开票

对商户而言，接入时应把这些异步通知视为“最终状态收口”机制，而不是同步接口的附属补充。
同步接口解决的是“是否受理”，异步通知解决的是“最终发生了什么”。

3.5 异步通知通用规范

除个别历史兼容差异外，商户异步通知统一遵循以下规则：

3.5.1 回调方式

• 平台通过 HTTP POST 向商户回调地址发送 JSON Body。
• 商户应将任意一次回调都视为可重放消息，按业务主键做幂等处理。
• 对于同一业务对象，平台可能因为网络异常、非 2xx 响应等原因发起重试。

3.5.2 外层通知包

异步通知的 HTTP Body 不是直接返回业务字段，而是先包一层统一外壳：

{
  "sign": "xxxxx",
  "signType": "AES_ONLY",
  "timestamp": "1742891000000",
  "nonce": "0d7d8f1a-xxxx",
  "appId": "pico_app_002",
  "data": "......"
}

字段	说明
sign	通知签名
signType	通知签名/加密模式标识；用于参与验签
timestamp	毫秒时间戳
nonce	随机串
appId	商户应用 ID
data	业务数据；若客户端配置 notifyEncrypt=1 则为 AES 加密后的 Base64 字符串，否则为明文 JSON

3.5.3 验签与解密规则

商户处理异步通知时，建议固定按以下顺序执行：

1. 校验外层 sign
2. 如果 data 为加密串，先解密 data
3. 再解析业务 JSON
4. 按业务主键完成幂等更新

通知签名与普通 API 请求签名使用同一套商户密钥体系，但签名串不同。
通知验签参与字段为：

• appId
• body（即外层 data）
• nonce
• signType
• timestamp

3.5.4 成功判定与重试

• 商户返回任意 2xx 状态码，平台即视为本次通知成功。
• 商户响应体内容当前不参与成功判定。
• 若商户返回非 2xx，或平台发送过程中出现网络异常，平台会自动重试。
• 当前默认重试节奏为：首次发送后，最多再重试 6 次，典型间隔为 1 / 2 / 4 / 5 / 10 / 20 分钟。

3.5.5 幂等处理建议

• 以业务主键做幂等，不要仅依赖回调到达次数。
• 建议保存外层原文、解密后业务数据、接收时间、处理结果、错误原因。
• 若商户内部存在多个系统订阅同一结果，建议先由统一接入层完成验签、解密和幂等，再分发给下游系统。
• 若商户需要排查链路问题，建议同时保存请求时的主键和回调时的主键映射，例如 taskId、settlementId、invoiceId、dealId 等。

四、接口设计

4.1 核心接口列表

接口名称	请求方式	接口路径	功能描述
加密测试	POST	/merchantapi/v2/test/crypto	测试验签、解密和上下文识别
查询项目列表	GET	/merchantapi/v2/projects	获取商户可用项目列表
创建项目	POST	/merchantapi/v2/projects/create	创建项目
查询项目详情	GET	/merchantapi/v2/projects/{projectId}	获取项目完整详情
查询创客招募状态	POST	/merchantapi/v2/projects/queryRecruitStatus	查询创客在当前项目下的招募与签约状态
批量招募创客	POST	/merchantapi/v2/projects/recruit	批量异步招募创客
单笔同步招募创客	POST	/merchantapi/v2/projects/syncRecruit	单笔招募并同步返回当前处理结论
查询创客额度	POST	/merchantapi/v2/projects/makers/quota	查询单个创客可结算额度
批量查询创客额度	POST	/merchantapi/v2/projects/makers/quota/batch	批量查询创客可结算额度
上传交付物	POST	/merchantapi/v2/projects/uploadDeliverable	上传结算明细对应交付物
查询已上传交付物	POST	/merchantapi/v2/projects/queryDeliverables	查询结算明细下历史交付物
查询结算单列表	GET	/merchantapi/v2/settlements	分页查询结算单列表
查询结算单详情	GET	/merchantapi/v2/settlements/{settlementId}	查询结算单详情
个税试算	POST	/merchantapi/v2/settlements/taxTrial	创建结算单前预估个人所得税、个人增值税和附加税
创建结算单	POST	/merchantapi/v2/settlements	创建结算单
发起支付	POST	/merchantapi/v2/settlements/{settlementId}/pay	对已创建结算单发起支付
提交验收凭证	POST	/merchantapi/v2/settlements/{settlementId}/acceptance	按结算主单提交验收凭证
查询验收凭证	GET	/merchantapi/v2/settlements/{settlementId}/acceptance	查询结算主单当前验收状态和最近一次提交文件
获取结算回单	GET	/merchantapi/v2/settlementDetails/{detailId}/receipt	获取结算回单
查询自由职业者信息	POST	/merchantapi/v2/makers/query	批量查询自由职业者信息
解绑自由职业者	POST	/merchantapi/v2/makers/unbind	按外部用户ID解绑自由职业者
查询企业账户信息	GET	/merchantapi/v2/account/queryMerchantAccountInfo	查询企业账户列表与余额信息
查询可开票余额	GET	/merchantapi/v2/invoice/queryAvailableInvoiceBalance	查询当前商户已发放成功流水按税地和税目归集后的开票状态金额
查询可开票结算单列表	GET	/merchantapi/v2/invoice/queryAvailableInvoiceSettlements	查询可用于开票申请的结算单列表
开票申请	POST	/merchantapi/v2/invoice/apply	发起开票申请
查询发票详情	GET	/merchantapi/v2/invoice/myInvoice/{invoiceId}	查询发票申请结果和附件

4.1.1 通用请求头

除个别内部调用场景外，商户调用接口时统一使用以下请求头：

请求头	必填	说明
X-App-Id	是	平台分配的应用 ID
X-Timestamp	是	毫秒级时间戳
X-Nonce	是	随机字符串，建议每次请求唯一
X-Sign	是	请求签名
X-Encrypt-Type	POST 请求是	当前按 AES 接入

4.1.2 通用响应格式

所有接口统一返回 MerchantApiResponse<T> 结构：

{
  "code": 0,
  "message": "成功",
  "data": {},
  "timestamp": "1742891000000",
  "requestId": "req_xxx",
  "encrypted": false,
  "signature": "xxxx"
}

字段说明：

字段	类型	说明
code	Integer	顶层结果码，0 表示接口调用成功
message	String	顶层结果描述
data	Object / null	业务数据；不同接口的 data 结构不同，后续各接口章节均只展开 data 字段的完整结构
timestamp	Long	响应时间戳（毫秒）
requestId	String	平台侧请求标识，联调和问题排查时请保留
encrypted	Boolean	当前对外响应中通常为 false；未来如启用响应加密时用于标识
encryptedData	String	预留字段；当前通常为空或不返回
signature	String	响应签名，商户建议校验

4.1.3 通用接入约定

• GET 请求通常不加密，但仍需要签名。
• POST 请求体统一按 AES 加密后，以 {"encryptedData":"..."} 形式传输。
• 商户应把所有 ID 字段按字符串处理。
• 多数带 projectId 的 POST 接口遵循“请求体优先，client 默认项目兜底”的口径。
• 对于异步接口，code=0 只代表请求受理成功，不代表业务最终成功。

4.2 加密测试接口

4.2.1 接口说明

用于验证商户侧签名、AES 加密、服务端解密和响应签名链路是否正常。

4.2.2 请求参数（需加密）

POST /merchantapi/v2/test/crypto

{
  "message": "Hello World! 测试V2加密功能"
}

参数	类型	必填	说明
message	String	是	测试消息，最长 1000 字符

4.2.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "originalMessage": "Hello World! 测试V2加密功能",
    "encryptionInfo": "AES加密方案"
  }
}

字段	类型	说明
originalMessage	String	原始消息
encryptionInfo	String	当前识别到的加密方案说明

4.2.4 关键说明

• 商户在正式联调前必须先打通该接口。
• 当前业务接口默认按 AES 模式接入。

4.3 查询项目列表接口

4.3.1 接口说明

分页查询当前商户名下的项目列表，可按项目状态、审核状态筛选。

4.3.2 请求参数

GET /merchantapi/v2/projects?page=1&size=20&status=1&auditStatus=1

参数	类型	必填	说明
page	Integer	否	页码，默认 1，必须大于 0
size	Integer	否	每页数量，默认 20，范围 1-100
status	Integer	否	项目状态：0-未开始，1-进行中，2-已结束
auditStatus	Integer	否	审核状态：0-未审核，1-已审核，2-已驳回

4.3.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "total": 5,
    "page": 1,
    "size": 20,
    "projects": [
      {
        "projectId": "2016422018623922178",
        "projectName": "直播活动推广项目",
        "projectCode": "XM100086",
        "taxCompanyId": "17",
        "taxCompanyName": "上海税地",
        "status": 1,
        "statusDesc": "进行中",
        "auditStatus": 1,
        "auditStatusDesc": "已审核",
        "createTime": "2026-03-23T10:00:00",
        "availableMethods": ["bank", "alipay"],
        "currentMonth": "2026-03",
        "monthlyAvailable": 5000.00
      }
    ]
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
total	Integer	总记录数
page	Integer	当前页码
size	Integer	每页数量
pages	Integer	总页数
projects	Array	项目摘要列表
projects[].projectId	String	项目 ID
projects[].projectName	String	项目名称
projects[].projectCode	String	项目编码
projects[].status	Integer	项目状态：0-未开始、1-进行中、2-已结束
projects[].statusDesc	String	项目状态描述
projects[].auditStatus	Integer	审核状态：0-未审核、1-已审核、2-已驳回
projects[].auditStatusDesc	String	审核状态描述
projects[].taxCompanyId	String	税地 ID
projects[].taxCompanyName	String	税地名称
projects[].createTime	String	创建时间，格式通常为 yyyy-MM-ddTHH:mm:ss
projects[].availableMethods	Array	当前项目支持的创客收款方式；无可用方式时返回空数组
projects[].currentMonth	String	当前月份，格式 yyyy-MM
projects[].monthlyAvailable	BigDecimal	当前月份税地可用剩余额度摘要，单位元

4.3.4 关键说明

• 项目列表主要用于拿到 projectId 和判断项目是否可用。
• monthlyAvailable 是摘要值，详细额度需查看项目详情或创客额度接口。

4.4 创建项目接口

4.4.1 接口说明

创建单个项目。项目创建成功后，通常仍需要审核通过后才能用于正式业务。

4.4.2 请求参数（需加密）

POST /merchantapi/v2/projects/create

{
  "notifyUrl": "https://merchant.example.com/callback/project-audit",
  "name": "直播活动推广项目",
  "content": "负责直播活动推广与线索收集",
  "calculationType": "DAY",
  "calculationDesc": "按天结算",
  "projectBudget": 12.34,
  "type": 0,
  "makerNumber": 20,
  "settlementRule": "验收通过后T+7结算",
  "verify": "提交成果并审核通过视为验收完成",
  "checkDateStart": "2026-03-25",
  "checkDateEnd": "2026-03-31",
  "remark": "优先安排有直播经验的创客"
}

参数	类型	必填	说明
notifyUrl	String	否	项目审核状态回调地址，长度不超过 200
name	String	是	项目名称，最长 100
content	String	是	项目内容，最长 1000
calculationType	String	是	计价方式
calculationDesc	String	是	计价方式描述，最长 500
projectBudget	BigDecimal	是	项目预算，单位万
type	Integer	否	当前仅支持 0
makerNumber	Integer	是	招募人数
settlementRule	String	是	结算规则，最长 100
verify	String	是	验收标准，最长 1000
checkDateStart	String	是	验收开始日期，格式 yyyy-MM-dd
checkDateEnd	String	是	验收结束日期，格式 yyyy-MM-dd
remark	String	否	备注，最长 200

4.4.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "1967533227101458434",
    "code": "XM100086",
    "projectName": "直播活动推广项目",
    "auditStatus": 0,
    "auditStatusDesc": "未审核",
    "message": "创建成功，待审核"
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
code	String	项目编号
projectName	String	项目名称
auditStatus	Integer	审核状态：0-未审核、1-已审核、2-已驳回；创建成功后初始固定为 0
auditStatusDesc	String	审核状态描述；创建成功后通常为“未审核”
message	String	处理结果信息；成功时通常为“创建成功，待审核”

4.4.4 关键说明

• 创建成功不代表项目立即可用。
• 项目必须审核通过后，才能用于招募、额度和结算。

4.4.5 项目审核结果通知

如果创建项目时传入了 notifyUrl，项目审核状态发生变化后，平台会向该地址发送异步通知。

触发时机：

• 项目审核通过
• 项目审核驳回

外层通知包：

项目审核通知使用第三章“异步通知通用规范”中的统一外层通知包。

业务 payload：

项目审核通知的业务字段与“查询项目详情接口”的响应字段保持一致，商户可直接复用项目详情的数据结构进行解析。
以下为回调 data 的完整字段：

字段	说明
projectId	项目 ID
projectName	项目名称
projectCode	项目编码
content	项目内容
calculationType	计价方式
calculationDesc	计价方式描述
projectBudget	项目预算，单位万元
type	项目类型；当前 0-派单项目
auditStatus	审核状态：0-未审核、1-已审核、2-已驳回
auditStatusDesc	审核状态描述
rejectReason	驳回原因；审核通过时通常为空
makerNumber	招募创客数
settlementRule	结算规则
verify	验收标准
checkDateStart	验收开始日期，格式 yyyy-MM-dd
checkDateEnd	验收结束日期，格式 yyyy-MM-dd
remark	备注
taxCompanyId	税地 ID
taxCompanyName	税地名称
taxCompanyCode	税地编码
taxCategoryId	税目 ID
taxCategoryName	税目名称
settleRate	结算费率；百分比值；按字符串返回并固定保留两位小数，例如 6.00 表示 6%；结算费公式：settleFee = amount × settleRate ÷ 100
settleRateDesc	结算费率说明；明确费率单位为百分比值，并给出结算费计算公式
serviceRate	技术服务费率；百分比值；按字符串返回并固定保留两位小数，例如 1.50 表示 1.5%；服务费公式：serviceFee = (amount + settleFee) × serviceRate ÷ 100
serviceRateDesc	技术服务费率说明；明确费率单位为百分比值，并给出服务费计算公式
status	项目状态：0-未开始、1-进行中、2-已结束
statusDesc	项目状态描述
currentMonth	当前月份
monthlyQuota	税地月度总额度
monthlyUsed	税地本月已使用额度
monthlyAvailable	税地本月剩余额度
receiveMethodConfigs[]	按收款方式聚合的规则额度配置
receiveMethodConfigs[].receiveMethod	收款方式
receiveMethodConfigs[].status	状态：1-正常、0-停用
receiveMethodConfigs[].singleLimit	单笔规则限额
receiveMethodConfigs[].monthlyQuota	月度规则额度
receiveMethodConfigs[].monthlyUsed	本月已使用规则额度
receiveMethodConfigs[].monthlyAvailable	本月剩余规则额度
paymentAccounts[]	项目绑定账户摘要
paymentAccounts[].merchantAccountId	商户账户 ID
paymentAccounts[].displayName	展示名称
paymentAccounts[].receiveMethod	收款方式
paymentAccounts[].amount	账户余额参考值
paymentAccounts[].availableAmount	账户可用余额参考值
deliverableRate	交付物提交率

实际业务样例如下：

{
  "projectId": "2016422018623922178",
  "projectName": "直播活动推广项目",
  "projectCode": "XM100086",
  "content": "直播推广合作",
  "calculationType": "DAY",
  "calculationDesc": "按天结算，每日8小时",
  "projectBudget": 12.34,
  "type": 0,
  "auditStatus": 1,
  "auditStatusDesc": "已审核",
  "rejectReason": null,
  "makerNumber": 20,
  "settlementRule": "提交并验收后结算",
  "verify": "按要求完成直播排班与交付",
  "checkDateStart": "2026-03-25",
  "checkDateEnd": "2026-03-31",
  "remark": "项目审核通过",
  "taxCompanyId": "17",
  "taxCompanyName": "上海税地",
  "taxCompanyCode": "SH",
  "taxCategoryId": "8",
  "taxCategoryName": "劳务报酬",
  "settleRate": "6.00",
  "settleRateDesc": "结算费率为百分比值，按 settleFee = amount × settleRate ÷ 100 计算；例如 settleRate=8 表示 8%",
  "serviceRate": "8.00",
  "serviceRateDesc": "技术服务费率为百分比值，按 serviceFee = (amount + settleFee) × serviceRate ÷ 100 计算；例如 serviceRate=8 表示 8%",
  "status": 1,
  "statusDesc": "进行中",
  "currentMonth": "2026-03",
  "monthlyQuota": 200000.00,
  "monthlyUsed": 65000.00,
  "monthlyAvailable": 135000.00,
  "receiveMethodConfigs": [
    {
      "receiveMethod": "bank",
      "status": 1,
      "singleLimit": 50000.00,
      "monthlyQuota": 100000.00,
      "monthlyUsed": 35000.00,
      "monthlyAvailable": 65000.00
    }
  ],
  "paymentAccounts": [
    {
      "merchantAccountId": "3001",
      "displayName": "平安银行尾号1234",
      "receiveMethod": "bank",
      "amount": 120000.00,
      "availableAmount": 118000.00
    }
  ],
  "deliverableRate": 75.50
}

补充说明：

• 项目审核通知的 data 字段与项目详情接口 data 结构一致，不是精简版。
• 因此商户如果已经接了项目详情解析模型，通常可以直接复用。

处理建议：

• 项目审核通知建议以 projectId 做幂等更新。
• 当 auditStatus=1 时，可将项目切换到“可进入招募/额度/结算联调”的状态。
• 当 auditStatus=2 时，建议保存 rejectReason 并阻断后续业务发起。

4.5 查询项目详情接口

4.5.1 接口说明

获取单个项目的完整详情，包含税地、费率、收款方式额度、绑定账户摘要等信息。

4.5.2 请求参数

GET /merchantapi/v2/projects/{projectId}

参数	类型	必填	说明
projectId	String	是	项目 ID

4.5.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "projectName": "直播活动推广项目",
    "projectCode": "XM100086",
    "taxCompanyId": "17",
    "taxCompanyName": "上海税地",
    "auditStatus": 1,
    "auditStatusDesc": "已审核",
    "status": 1,
    "statusDesc": "进行中",
    "projectBudget": 12.34,
    "settleRate": "6.00",
    "settleRateDesc": "结算费率为百分比值，按 settleFee = amount × settleRate ÷ 100 计算；例如 settleRate=8 表示 8%",
    "serviceRate": "8.00",
    "serviceRateDesc": "技术服务费率为百分比值，按 serviceFee = (amount + settleFee) × serviceRate ÷ 100 计算；例如 serviceRate=8 表示 8%",
    "currentMonth": "2026-03",
    "monthlyQuota": 200000.00,
    "monthlyUsed": 65000.00,
    "monthlyAvailable": 135000.00,
    "receiveMethodConfigs": [
      {
        "receiveMethod": "bank",
        "status": 1,
        "singleLimit": 50000.00,
        "monthlyQuota": 100000.00,
        "monthlyUsed": 35000.00,
        "monthlyAvailable": 65000.00
      }
    ],
    "paymentAccounts": [
      {
        "merchantAccountId": "3001",
        "displayName": "平安银行尾号1234",
        "receiveMethod": "bank",
        "amount": 120000.00,
        "availableAmount": 118000.00
      }
    ],
    "deliverableRate": 75.50
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
projectName	String	项目名称
projectCode	String	项目编码
content	String	项目内容
calculationType	String	计价方式，如 DAY / WEEK / MONTH / QUARTER / YEAR / TIME / ITEM
calculationDesc	String	计价方式描述
projectBudget	BigDecimal	项目预算，单位万元
type	Integer	项目类型；当前仅支持 0-派单项目
auditStatus	Integer	审核状态：0-未审核、1-已审核、2-已驳回
auditStatusDesc	String	审核状态描述
rejectReason	String	驳回原因；未驳回时通常为空
makerNumber	Integer	招募创客数
settlementRule	String	结算规则
verify	String	验收标准
checkDateStart	String	验收开始日期，格式 yyyy-MM-dd
checkDateEnd	String	验收结束日期，格式 yyyy-MM-dd
remark	String	备注
taxCompanyId	String	税地 ID
taxCompanyName	String	税地名称
taxCompanyCode	String	税地编码
taxCategoryId	String	税目 ID
taxCategoryName	String	税目名称
settleRate	String	结算费率，百分比值；按字符串返回并固定保留两位小数；6.00 表示 6%；结算费公式：settleFee = amount × settleRate ÷ 100
settleRateDesc	String	结算费率说明；明确费率单位为百分比值，并给出结算费计算公式
serviceRate	String	技术服务费率，百分比值；按字符串返回并固定保留两位小数；1.50 表示 1.5%；服务费公式：serviceFee = (amount + settleFee) × serviceRate ÷ 100
serviceRateDesc	String	技术服务费率说明；明确费率单位为百分比值，并给出服务费计算公式
status	Integer	项目状态：0-未开始、1-进行中、2-已结束
statusDesc	String	项目状态描述
currentMonth	String	当前月份，格式 yyyy-MM
monthlyQuota	BigDecimal	税地月度总额度，单位元
monthlyUsed	BigDecimal	税地本月已使用额度，单位元
monthlyAvailable	BigDecimal	税地本月剩余额度，单位元
receiveMethodConfigs	Array	按收款方式聚合的规则额度配置
receiveMethodConfigs[].receiveMethod	String	收款方式，如 bank / alipay / wechat
receiveMethodConfigs[].status	Integer	方式状态：1-正常、0-停用
receiveMethodConfigs[].singleLimit	BigDecimal	单笔规则限额，单位元
receiveMethodConfigs[].monthlyQuota	BigDecimal	月度规则额度，单位元
receiveMethodConfigs[].monthlyUsed	BigDecimal	本月已使用规则额度，单位元
receiveMethodConfigs[].monthlyAvailable	BigDecimal	本月剩余规则额度，单位元
paymentAccounts	Array	项目绑定账户摘要
paymentAccounts[].merchantAccountId	String	商户账户 ID
paymentAccounts[].displayName	String	账户展示名称，例如银行尾号或账号别名
paymentAccounts[].receiveMethod	String	收款方式
paymentAccounts[].amount	BigDecimal	账户余额参考值，单位元
paymentAccounts[].availableAmount	BigDecimal	账户可用余额参考值，单位元
deliverableRate	BigDecimal	交付物提交率，百分制

4.5.4 关键说明

• settleRate 和 serviceRate 的返回值都是百分比值，不是小数系数。
• 这两个字段按字符串返回，并固定保留两位小数，例如 8.00、1.50。
• settleRate = 6.00 表示 6%，结算费公式：settleFee = amount × settleRate ÷ 100。
• serviceRate = 1.50 表示 1.5%，服务费公式：serviceFee = (amount + settleFee) × serviceRate ÷ 100。
• settleRateDesc 和 serviceRateDesc 用于直接向调用方说明费率单位和计算口径，避免误把费率当作小数系数。
• receiveMethodConfigs 反映项目规则额度。
• paymentAccounts 表示本项目绑定的商户账户摘要，余额字段为参考值。
• deliverableRate 是项目交付进度指标，不参与费率和金额计算。

4.6 查询创客招募状态接口

4.6.1 接口说明

查询某个创客在当前项目下的招募与签约状态。

4.6.2 请求参数（需加密）

POST /merchantapi/v2/projects/queryRecruitStatus

{
  "projectId": "2016422018623922178",
  "phone": "13800000000",
  "platformUserId": "DY20260115105692"
}

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
phone	String	否	与 platformUserId 至少传一个
platformUserId	String	否	与 phone 至少传一个

4.6.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "maskedPhone": "138****0000",
    "platformUserId": "DY20260115105692",
    "status": "RECRUITED_SIGNED",
    "statusDesc": "已招募已签约",
    "contractId": "1967533227101458437",
    "contractDownloadUrl": "https://oss.example.com/contracts/202606/8808.pdf?Expires=3600"
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
maskedPhone	String	脱敏手机号；若本次未能定位到手机号，则可能为空
platformUserId	String	外部用户ID；若本次未能定位到外部用户ID，则可能为空
status	String	招募状态：UNRECRUITED、RECRUITING、RECRUITED_UNSIGNED、RECRUITED_SIGNED、FAILED
statusDesc	String	招募状态描述，如“未招募”“招募中”“已招募待签约”“已招募已签约”“失败”
contractId	String	仅当 status=RECRUITED_SIGNED 且可定位到合同记录时返回
contractDownloadUrl	String	仅当 status=RECRUITED_SIGNED 且合同文件已在平台私有 OSS 中时返回短时效预签名 URL；当前默认有效期为 1 小时（3600 秒），链接过期后可重新调用本接口获取

4.6.4 关键说明

• 该接口是“招募前置判断接口”，适合用于商户前端展示“去招募”“去签约”“已完成”“失败后重试”之类的状态。
• 平台会先识别当前项目下最近一次匹配的招募任务；若命中，则按该任务 process_stage 直接映射返回状态。
• 只有当未命中招募任务时，平台才再判断创客是否已经加入当前项目，以及同税地资格是否完整。
• 当返回 status=RECRUITED_SIGNED 时，如果系统可定位到合同记录，会一并返回 contractId；若合同文件已存入平台私有 OSS，还会返回 contractDownloadUrl 短时效预签名链接，当前默认有效期为 1 小时（3600 秒）。
• 即使创客在别的项目下同税地已经签约，只要还没加入当前项目，这里仍返回 UNRECRUITED。
• 当前项目视角下的“已签约可用”要求签约有效期覆盖：

项目 check_date_end + 1个月

• 商户不应自行根据“历史签约过”来跳过本接口，因为历史合同可能已经无法覆盖当前项目的结束时间要求。

4.7 批量招募创客接口

4.7.1 接口说明

异步受理招募任务。同步响应只表达“是否受理”，最终结果通过回调通知商户。

4.7.2 请求参数（需加密）

POST /merchantapi/v2/projects/recruit

{
  "projectId": "2016422018623922178",
  "recruitBatchNo": "RB202603230001",
  "notifyUrl": "https://merchant.example.com/api/recruit/callback",
  "redirectUrl": "https://merchant.example.com/app/sign-result",
  "makers": [
    {
      "name": "张三",
      "phone": "13812345678",
      "idNumber": "310101199001011234",
      "platformUserId": "DY20260115105692",
      "address": "上海市浦东新区",
      "platformName": "某平台",
      "platformUserName": "张三",
      "obversePic": "https://secure-oss.example.com/front.jpg",
      "reversePic": "https://secure-oss.example.com/back.jpg",
      "livenessFaceImageUrl": "https://secure-oss.example.com/face.jpg",
      "livenessVideoUrl": "https://secure-oss.example.com/video.mp4"
    }
  ]
}

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
recruitBatchNo	String	是	招募批次号，幂等键之一，最长 64
notifyUrl	String	是	结果回调地址，生产环境必须为 HTTPS
redirectUrl	String	否	签约完成后的跳转地址，最长 200
makers	Array	是	招募创客列表，单次最多 50 条

单条 makers[] 字段：

字段	必填	说明
name	是	姓名
phone	是	手机号
idNumber	是	身份证号
platformUserId	是	外部用户ID
address	否	地址
platformName	否	平台名称
platformUserName	否	平台用户名
obversePic	否	身份证正面 URL
reversePic	否	身份证反面 URL
livenessFaceImageUrl	否	活体照片 URL
livenessVideoUrl	否	活体视频 URL

注意事项：

• 同一请求内 phone 和 platformUserId 都不能重复。
• obversePic 和 reversePic 必须成对传入，不能只传一个。
• platformUserId 被视为商户侧稳定业务标识，不允许在活跃招募链路中随意改绑。

4.7.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "recruitBatchNo": "RB202603230001",
    "totalCount": 2,
    "acceptedCount": 1,
    "rejectedCount": 1,
    "results": [
      {
        "platformUserId": "DY20260115105692",
        "maskedPhone": "138****5678",
        "accepted": true,
        "message": "已受理，后续结果请关注回调",
        "errorCode": 0,
        "taskId": "2034454171060154370"
      },
      {
        "platformUserId": "DY20260115105693",
        "maskedPhone": "139****5678",
        "accepted": false,
        "message": "同一请求内platformUserId不能重复",
        "errorCode": 40259,
        "taskId": null
      }
    ]
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
recruitBatchNo	String	招募批次号
totalCount	Integer	本次请求总数
acceptedCount	Integer	受理成功数量
rejectedCount	Integer	同步拒绝数量
results	Array	逐条处理结果
results[].platformUserId	String	外部用户ID
results[].maskedPhone	String	脱敏手机号
results[].accepted	Boolean	是否已受理
results[].message	String	结果描述
results[].errorCode	Integer	错误码；成功时通常为 0
results[].taskId	String	招募任务 ID；accepted=true 时通常返回

4.7.4 关键说明

• accepted=true 只代表已受理，不代表已经签约成功。
• 异步最终结果通过回调返回：
  • FAILED
  • SIGN_URL_READY
  • SIGNED
• 历史签约能否复用，取决于旧签约是否仍覆盖当前项目的 check_date_end + 1个月 要求。
• 商户侧建议以 recruitBatchNo + platformUserId 作为本次招募任务的主关联键，以 taskId 作为平台侧任务主键保存。
• 招募接口会同步拦截明显冲突，例如：
  • 同一请求内 phone 重复
  • 同一请求内 platformUserId 重复
  • 已存在未决招募任务且本次标识冲突
  • platformUserId 在商户范围内已稳定绑定到其他创客
• 若同一个商户、同一个项目、同一个 recruitBatchNo + platformUserId 发起的是“参数完全一致的重放请求”，系统不会重复新建任务，而是按历史任务当前状态返回结果：
  • 若历史任务已签约，可能直接返回“已签约”
  • 若历史任务签约链接仍有效，可能直接返回“签约链接已生成”
  • 若历史任务已失败，会直接返回失败信息
  • 若历史任务签约链接已失效，会要求重新发起招募
• 若重放请求的姓名、手机号、身份证号、回调地址、跳转地址、身份证图片、活体材料等关键字段与历史已受理任务不一致，系统会按“请求冲突”直接拒绝，不会默默覆盖历史任务。
• 身份证图片、活体图片、活体视频均要求传可访问 URL。平台在异步校验通过后会下载并转存平台 OSS，商户不需要长期为已通过的材料提供原始 URL。

4.7.5 招募回调说明

招募接口的最终结果通过商户提供的 notifyUrl 回调。

回调 HTTP Body 不是直接返回业务字段，而是先包一层通知外壳：

外层字段	说明
sign	回调签名
signType	签名/加密类型
timestamp	时间戳
nonce	随机串
appId	应用 ID
data	业务数据

说明：

• 商户应先校验外层签名，再解析 data。
• 若客户端配置了 notifyEncrypt=1，则 data 不是明文 JSON，而是 AES 加密后的 Base64 字符串；商户需要先解密，再解析业务字段。

以下为回调 data 的完整字段：

字段	说明
notifyType	通知类型，固定为招募结果通知
recruitBatchNo	招募批次号
projectId	项目 ID
taskId	招募任务 ID
platformUserId	外部用户ID
maskedPhone	脱敏手机号
taskStatus	SIGN_URL_READY / SIGNED / FAILED
message	结果描述
signUrl	当 taskStatus=SIGN_URL_READY 时返回签约链接
contractId	当 taskStatus=SIGNED 时通常返回合同 ID
errorCode	错误码
errorMessage	错误信息
finishTime	任务完成时间

实际业务样例如下：

{
  "notifyType": "MERCHANT_RECRUIT_RESULT",
  "recruitBatchNo": "RB202603230001",
  "projectId": "2016422018623922178",
  "taskId": "2034454171060154370",
  "platformUserId": "DY20260115105692",
  "maskedPhone": "138****5678",
  "taskStatus": "SIGN_URL_READY",
  "message": "签约链接已生成",
  "signUrl": "https://sign.example.com/sign?token=3f2d8d44a8c34973a7359b6057f5fd5f",
  "contractId": null,
  "errorCode": 0,
  "errorMessage": null,
  "finishTime": "2026-03-25 18:00:00"
}

补充说明：

• maskedPhone 为脱敏手机号，不返回明文手机号。
• signUrl 是平台生成的完整签约地址；商户回调中不会单独拿到 signToken。
• 招募专项回调说明和更多样例见 docs/apiv2/recruit-回调说明.md。

商户建议按以下方式处理回调：

1. 先校验外层回调签名
2. 如 data 为加密数据，先解密 data
3. 再以 taskId 或 recruitBatchNo + platformUserId 做幂等更新
4. SIGN_URL_READY 时更新待签约状态并向前端暴露签约入口
5. SIGNED 时更新为已签约可结算，并记录 contractId
6. FAILED 时记录 errorCode / errorMessage 并允许人工或业务重试

关于 SIGNED 状态，商户应重点理解两类典型场景：

1. 平台在处理招募任务时直接命中“已签约”结果，例如命中当前项目历史有效签约或同税地资格复用
2. 平台先返回 SIGN_URL_READY，创客通过签约链接完成签约后，平台再以 SIGNED 收口最终结果

因此，商户侧不应把 SIGN_URL_READY 误判为最终成功，只有收到 SIGNED 回调或查询状态明确已完成时，才应将该创客置为“已签约可结算”。

4.8 单笔同步招募创客接口

4.8.1 接口说明

单笔发起创客招募，并在当前请求内完成一次招募处理，返回当前处理结论。

与批量招募接口相比，该接口不需要传 recruitBatchNo 和 makers[] 数组，适合商户前端或业务系统对单个创客即时发起招募、即时获取签约入口的场景。

需要注意的是，同步返回的“签约链接已生成”仍不等于创客已经完成签约。若创客需要打开签约页继续操作，最终是否签约完成仍应以 SIGNED 回调或招募状态查询结果为准。

4.8.2 请求参数（需加密）

POST /merchantapi/v2/projects/syncRecruit

{
  "projectId": "2016422018623922178",
  "notifyUrl": "https://merchant.example.com/api/recruit/callback",
  "redirectUrl": "https://merchant.example.com/app/sign-result",
  "name": "张三",
  "phone": "13812345678",
  "idNumber": "310101199001011234",
  "platformUserId": "DY20260115105692",
  "address": "上海市浦东新区",
  "platformName": "某平台",
  "platformUserName": "张三",
  "obversePic": "https://secure-oss.example.com/front.jpg",
  "reversePic": "https://secure-oss.example.com/back.jpg",
  "livenessFaceImageUrl": "https://secure-oss.example.com/face.jpg",
  "livenessVideoUrl": "https://secure-oss.example.com/video.mp4"
}

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
notifyUrl	String	否	结果回调地址，最长 200；生产环境必须为 HTTPS
redirectUrl	String	否	签约完成后的跳转地址，最长 200
name	String	是	姓名，最长 50
phone	String	是	手机号
idNumber	String	是	身份证号
platformUserId	String	是	外部用户ID，最长 100
address	String	否	地址，最长 200
platformName	String	否	平台名称，最长 100
platformUserName	String	否	平台用户名，最长 100
obversePic	String	否	身份证正面 URL；如传入，必须同时传 reversePic
reversePic	String	否	身份证反面 URL；如传入，必须同时传 obversePic
livenessFaceImageUrl	String	否	活体照片 URL
livenessVideoUrl	String	否	活体视频 URL

4.8.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "platformUserId": "DY20260115105692",
    "maskedPhone": "138****5678",
    "accepted": true,
    "message": "签约链接已生成",
    "errorCode": 0,
    "taskId": "2034454171060154370",
    "makerId": "2034454171060154371",
    "url": "https://sign.example.com/sign?token=3f2d8d44a8c34973a7359b6057f5fd5f"
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
platformUserId	String	外部用户ID
maskedPhone	String	脱敏手机号
accepted	Boolean	是否已受理或当前处理成功
message	String	当前处理结论，例如“签约链接已生成”“已签约”“待创客补资料”“招募处理中”或失败原因
errorCode	Integer	错误码；成功时通常为 0
taskId	String	招募任务 ID；accepted=true 时通常返回
makerId	String	创客 ID；已能定位或创建创客时返回
url	String	招募/签约页面地址；当需要创客继续补资料或签约时返回

4.8.4 关键说明

• 该接口只支持单个创客，不支持批量提交。
• 该接口会在当前请求内创建或复用招募任务，并尝试完成实名校验、历史资格复用、材料处理和签约链接生成。
• accepted=true 且 message=已签约 表示当前项目视角下已经满足签约要求。
• accepted=true 且返回 url 时，表示平台已经生成创客操作入口，但创客仍需要继续打开页面完成补资料或签约动作。
• accepted=true 且 message=招募处理中 时，表示当前已有未终结任务或本次处理尚未形成最终结论，商户应结合 taskId、回调或招募状态查询继续跟踪。
• accepted=false 时，应读取 errorCode 和 message 判断失败原因。
• 如果传入 notifyUrl，平台仍会在招募处理节点推送回调。同步响应适合前端即时展示，回调适合服务端最终状态收口。
• 当同一商户、同一项目、同一 platformUserId 已存在未过期招募任务时，接口会优先复用该任务并返回其当前状态，不会无条件新建任务。

4.9 查询创客额度接口

4.9.1 接口说明

查询单个创客在当前项目下的真实可结算额度。

4.9.2 请求参数（需加密）

POST /merchantapi/v2/projects/makers/quota

{
  "projectId": "2016422018623922178",
  "phone": "13800000000",
  "platformUserId": "DY20260115105692"
}

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
phone	String	否	与 platformUserId 至少传一个
platformUserId	String	否	与 phone 至少传一个

4.9.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "maskedPhone": "138****0000",
    "platformUserId": "DY20260115105692",
    "eligible": true,
    "reasonCode": "ELIGIBLE",
    "eligibleDesc": "可结算",
    "currentMonth": "2026-03",
    "totalAvailableQuota": 65000.00,
    "receiveMethodQuotas": [
      {
        "receiveMethod": "bank",
        "personalAvailableQuota": 80000.00,
        "sharedAvailableQuota": 65000.00,
        "availableQuota": 65000.00
      }
    ]
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
maskedPhone	String	脱敏手机号；若本次未能定位到手机号，则可能为空
platformUserId	String	外部用户ID；若本次未能定位到外部用户ID，则可能为空
eligible	Boolean	是否具备可结算资格
reasonCode	String	资格结果码，如 ELIGIBLE / MAKER_NOT_FOUND / NOT_IN_PROJECT / QUALIFICATION_NOT_READY
eligibleDesc	String	资格描述
currentMonth	String	当前月份，格式 yyyy-MM
totalAvailableQuota	BigDecimal	当前项目下单个可用收款方式可结算额度的最大值
receiveMethodQuotas	Array	按项目支持的收款方式返回额度明细
receiveMethodQuotas[].receiveMethod	String	收款方式
receiveMethodQuotas[].personalAvailableQuota	BigDecimal	创客个人可用额度
receiveMethodQuotas[].sharedAvailableQuota	BigDecimal	项目共享可用额度
receiveMethodQuotas[].availableQuota	BigDecimal	真实可结算额度，取个人可用额度与共享可用额度的最小值

4.9.4 关键说明

• 创客不存在、未入项、未完成资格时，不一定返回业务错误，而是直接返回：
  • eligible=false
  • reasonCode
  • eligibleDesc
  • 0 额度
• 这类返回并不表示接口失败，而是表示“当前创客在当前项目下暂不具备结算条件”。
• 商户前端若需要展示失败原因，建议直接使用 eligibleDesc，不要自行硬编码推断。
• totalAvailableQuota 是摘要值，适合快速判断“当前是否还有额度”；真正落单时仍应结合具体 receiveMethodQuotas[].availableQuota 判断。

单方式额度口径：

availableQuota = min(personalAvailableQuota, sharedAvailableQuota)

4.10 批量查询创客额度接口

4.10.1 接口说明

按手机号或外部用户ID批量查询多个创客在项目下的额度。

4.10.2 请求参数（需加密）

POST /merchantapi/v2/projects/makers/quota/batch

{
  "projectId": "2016422018623922178",
  "makers": [
    { "phone": "13800000000" },
    { "platformUserId": "DY20260115105692" }
  ]
}

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
makers	Array	是	创客标识列表，单次最多 50 条
makers[].phone	String	否	与 platformUserId 至少传一个
makers[].platformUserId	String	否	与 phone 至少传一个

4.10.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
currentMonth	String	当前月份，格式 yyyy-MM
totalCount	Integer	总条数
eligibleCount	Integer	有资格条数
ineligibleCount	Integer	无资格或参数异常条数
results	Array	单个创客额度结果列表
results[].projectId	String	项目 ID
results[].maskedPhone	String	脱敏手机号
results[].platformUserId	String	外部用户ID
results[].eligible	Boolean	是否具备可结算资格
results[].reasonCode	String	资格结果码
results[].eligibleDesc	String	资格描述
results[].currentMonth	String	当前月份，格式 yyyy-MM
results[].totalAvailableQuota	BigDecimal	当前项目下单个可用收款方式可结算额度的最大值
results[].receiveMethodQuotas	Array	按收款方式返回的额度明细
results[].receiveMethodQuotas[].receiveMethod	String	收款方式
results[].receiveMethodQuotas[].personalAvailableQuota	BigDecimal	创客个人可用额度
results[].receiveMethodQuotas[].sharedAvailableQuota	BigDecimal	项目共享可用额度
results[].receiveMethodQuotas[].availableQuota	BigDecimal	真实可结算额度
results[].errorCode	Integer	单条结果码；0 表示该条具备可结算资格
results[].errorMessage	String	单条结果描述

4.10.4 关键说明

• 顶层通常仍返回 code=0。
• 单条结果中的参数错误、标识冲突、创客不存在、未入项、未具备资格，会通过单条 errorCode / errorMessage 表达。
• 商户在做批量导入、批量结算前预检时，建议优先使用该接口，而不要循环调用单创客额度接口。
• 对于批量接口，商户应按单条结果处理成功与失败，不能只看顶层 code。

4.11 上传交付物接口

4.11.1 接口说明

按结算明细上传交付物。
商户只需要传 detailId，平台会自动反查对应项目、结算单和创客任务。

4.11.2 请求参数（需加密）

POST /merchantapi/v2/projects/uploadDeliverable

{
  "detailId": "2034461359380058114",
  "deliveryDate": "2025-01-20",
  "description": "本月工作成果交付",
  "files": [
    {
      "fileName": "deliverable_1.jpg",
      "fileUrl": "https://merchant-oss.example.com/deliverable_1.jpg"
    }
  ]
}

参数	类型	必填	说明
detailId	String	是	结算明细 ID
deliveryDate	String	是	交付日期，格式 yyyy-MM-dd
description	String	否	交付说明
files	Array	是	文件列表，至少 1 个，最多 20 个
files[].fileName	String	是	文件名，最长 200
files[].fileUrl	String	是	文件 URL，必须为 HTTPS

4.11.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "deliverableId": "2036730053746438146",
    "detailId": "2034461359380058114",
    "files": [
      {
        "fileId": "2036730053775798274",
        "fileName": "deliverable_1.jpg",
        "fileUrl": "https://oss.example.com/merchant-deliverable-xxx-file-1.jpg"
      }
    ],
    "fileCount": 1,
    "uploadTime": "2026-03-25 17:01:00"
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
deliverableId	String	交付物记录 ID
detailId	String	结算明细 ID
files	Array	文件处理结果列表
files[].fileId	String	文件 ID
files[].fileName	String	文件名
files[].fileUrl	String	平台转存后的文件访问地址；若返回的是预签名 URL，过期后请重新调用查询接口获取
fileCount	Integer	文件数量
uploadTime	String	上传时间，格式通常为 yyyy-MM-dd HH:mm:ss

4.11.4 关键说明

• 交付物只接受 HTTPS URL，不接受 Base64 内容。
• 服务端会在请求处理过程中同步下载源文件并转存到平台普通 OSS。
• 上传成功只代表“记录已创建，待审核”，不代表交付物已审核通过。
• 交付物与结算明细一一关联，商户应优先保存 detailId，而不是自行用结算单号模糊关联。
• 平台当前不要求商户传文件大小、文件类型、文件 MD5，但商户仍应保证文件 URL 在接口调用时真实可访问。
• 当前支持的常见文件类型包括：
  • 图片：jpg、jpeg、png、gif、bmp、webp
  • 视频：mp4、avi、mov、wmv、mkv
  • 文档：pdf、doc、docx、xls、xlsx
• 如果文件扩展名不在当前支持范围内，接口会直接拒绝上传。

4.12 查询已上传交付物接口

4.12.1 接口说明

按结算明细查询该明细下历史上传的交付物记录。

4.12.2 请求参数（需加密）

POST /merchantapi/v2/projects/queryDeliverables

{
  "detailId": "2034461359380058114"
}

参数	类型	必填	说明
detailId	String	是	结算明细 ID

4.12.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
detailId	String	结算明细 ID
totalCount	Integer	上传记录总数
deliverables	Array	交付物上传记录列表，按上传时间倒序返回
deliverables[].deliverableId	String	交付物记录 ID
deliverables[].deliverableNo	String	交付物编号
deliverables[].deliveryDate	String	交付日期，格式 yyyy-MM-dd
deliverables[].description	String	交付描述
deliverables[].verifyStatus	Integer	审核状态：0-待审核、1-已通过、2-已驳回
deliverables[].verifyStatusDesc	String	审核状态描述
deliverables[].rejectReason	String	驳回原因；仅驳回时通常返回
deliverables[].uploadTime	String	上传时间
deliverables[].verifyTime	String	审核时间
deliverables[].fileCount	Integer	文件数量
deliverables[].files	Array	文件明细列表
deliverables[].files[].fileId	String	文件 ID
deliverables[].files[].fileName	String	文件名
deliverables[].files[].fileUrl	String	文件地址；若返回的是短时效预签名 URL，过期后请重新调用查询接口获取最新地址

4.12.4 关键说明

• 结果按上传时间倒序返回。
• 若当前明细没有任何交付物记录，接口仍然成功返回，totalCount=0。
• 商户若只需要最新一次上传记录，建议取返回列表的第一条，而不要自行假定同一明细只会有一条交付物记录。

4.13 查询结算单列表接口

4.13.1 接口说明

分页查询结算单列表。

4.13.2 请求参数

GET /merchantapi/v2/settlements?page=1&size=20&status=1&projectId=2016422018623922178

参数	类型	必填	说明
page	Integer	否	页码，默认 1
size	Integer	否	每页数量，默认 20
status	Integer	否	结算单状态
projectId	String	否	项目 ID
settlementNo	String	否	结算单号
startTime	String	否	开始时间，格式 yyyy-MM-ddTHH:mm:ss
endTime	String	否	结束时间，格式 yyyy-MM-ddTHH:mm:ss，且不能晚于当前日期

4.13.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
total	Integer	总记录数
page	Integer	当前页码
size	Integer	每页数量
pages	Integer	总页数
list	Array	结算单列表
list[].settlementId	String	结算单 ID
list[].settlementNo	String	系统结算单号
list[].projectId	String	项目 ID
list[].projectName	String	项目名称
list[].taxCompanyName	String	税地名称
list[].receiveMethod	String	收款方式
list[].totalAmount	BigDecimal	结算总金额
list[].totalCount	Integer	结算总笔数
list[].status	Integer	结算状态：0-未发放、1-发放中、2-发放完成、3-拒绝发放
list[].statusDesc	String	结算状态描述
list[].acceptanceStatus	Integer	当前验收凭证状态：0-未提交、1-审核中、2-审核通过、3-审核失败；历史空值统一返回 0；其他整数原样返回并由状态描述标记为“未知”
list[].acceptanceStatusDesc	String	当前验收凭证状态描述
list[].createTime	String	创建时间
list[].paymentTime	String	支付时间
list[].completeTime	String	完成时间
list[].successCount	Integer	成功笔数
list[].failCount	Integer	失败笔数

4.13.4 关键说明

• 该接口适合用于商户后台分页检索结算单，不建议用于查询单笔实时支付结果。
• 联调阶段如果查询不到结果，建议优先核对 projectId、状态过滤条件、时间范围和结算单号是否一致。
• 当前实现中，若查询结果为空，接口会直接返回业务异常“查询结果不存在”，而不是返回空列表。
• 当同时传 startTime 和 endTime 时，要求 startTime <= endTime。
• endTime 不能大于当前日期。
• 商户可通过 acceptanceStatus 发现需要提交或重新提交验收凭证的结算单：0 表示未提交，3 表示审核失败；1 和 2 分别表示审核中和审核通过。
• acceptanceStatus 只表示验收凭证状态。实际提交时仍会校验结算单归属、结算业务状态和成功笔数等条件，不能仅凭该字段判断一定允许提交。
• 若 acceptanceStatus 返回 0 至 3 之外的整数，表示平台存量数据状态异常；调用方不应自行推断其业务含义，提交接口会按验收状态异常处理。

4.14 查询结算单详情接口

4.14.1 接口说明

查询单个结算单的主信息和明细信息。

4.14.2 请求参数

GET /merchantapi/v2/settlements/{settlementId}

参数	类型	必填	说明
settlementId	String	是	结算单 ID

4.14.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
settlementId	String	结算单 ID
settlementNo	String	结算单编号
projectId	String	项目 ID
projectName	String	项目名称
taxCompanyName	String	税地名称
receiveMethod	String	收款方式
totalAmount	BigDecimal	提交总金额
totalCount	Integer	总笔数
status	Integer	结算状态：0-未发放、1-发放中、2-发放完成、3-拒绝发放
statusDesc	String	结算状态描述
acceptanceStatus	Integer	当前验收凭证状态：0-未提交、1-审核中、2-审核通过、3-审核失败；历史空值统一返回 0；其他整数原样返回并由状态描述标记为“未知”
acceptanceStatusDesc	String	当前验收凭证状态描述
createTime	String	创建时间
paymentTime	String	支付时间
completeTime	String	完成时间
remark	String	备注
successCount	Integer	成功笔数
failCount	Integer	失败笔数
details	Array	结算明细列表
details[].detailId	String	明细 ID
details[].detailNo	String	明细编号
details[].merchantDetailNo	String	商户结算明细号
details[].amount	BigDecimal	提交金额
details[].personalIncomeTaxAmount	BigDecimal	个人所得税
details[].personalValueAddedTaxAmount	BigDecimal	个人增值税
details[].surtaxAmount	BigDecimal	附加税
details[].feeAmount	BigDecimal	结算服务费
details[].serviceFeeAmount	BigDecimal	系统服务费
details[].bankFeeAmount	BigDecimal	银行服务费
details[].idCardHash	String	身份证哈希值
details[].status	Integer	明细状态：0-待打款、1-打款中、2-打款成功、3-打款失败、4-拒绝打款
details[].paymentTime	String	支付时间
details[].failureReason	String	失败原因
details[].remark	String	备注

4.14.4 关键说明

• 明细中返回的是身份证哈希值，而不是明文身份证号。
• 若商户需要对账，应优先使用 merchantDetailNo 作为商户侧明细主键，不建议依赖身份证相关字段做关联。
• acceptanceStatus=0 时尚未提交验收凭证，acceptanceStatus=3 时可根据验收凭证查询接口返回的驳回原因修正后重新提交；1 和 2 状态不允许重复提交。
• acceptanceStatus 只描述验收凭证状态，不改变 status 所表示的结算发放状态，也不能单独替代验收凭证提交接口的业务校验。
• 若 acceptanceStatus 返回 0 至 3 之外的整数，表示平台存量数据状态异常；调用方不应自行推断其业务含义，提交接口会按验收状态异常处理。

4.15 个税试算接口

4.15.1 接口说明

创建结算单前，按结算明细试算个人所得税、个人增值税和附加税。

该接口用于商户在创建真实结算单前预估税费和实发金额。接口只做试算，不创建结算单、不生成结算明细、不占用额度、不扣除企业账户余额、不触发支付、不发送结算回调。

试算会校验项目税地、项目收款方式配置和创客项目归属。receiveMethod 不在当前项目可用收款方式内，或当前项目未配置匹配的支付账号时，返回 40109 PROJECT_PAYMENT_ACCOUNT_NOT_CONFIGURED。

当前试算仅支持直营税地。若项目绑定的是第三方税地，平台会返回业务异常，提示当前项目暂不支持试算。

个税金额复用平台真实结算时的统一税费计算组件，试算接口本身不维护独立个税算法。

建议调用顺序：

查询招募/签约状态 -> 查询创客额度 -> 个税试算 -> 创建结算单 -> 发起支付

4.15.2 请求参数（需加密）

POST /merchantapi/v2/settlements/taxTrial

{
  "projectId": "2016422018623922178",
  "receiveMethod": "bank",
  "details": [
    {
      "merchantDetailNo": "MERCHANT_DETAIL_001",
      "amount": 5000.00,
      "phone": "13812345678",
      "platformUserId": "DY20260115105692",
      "paymentAccount": {
        "accountNo": "6222021234567890123",
        "accountName": "张三",
        "phone": "13812345678",
        "bankName": "杭州银行",
        "branchName": "杭州银行股份有限公司",
        "branchCode": "313331000014"
      },
      "remark": "3月技术服务费"
    }
  ]
}

顶层参数：

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
receiveMethod	String	是	收款方式，支持 bank / alipay / wechat；必须为当前项目已配置且可用的收款方式，否则返回 40109
details	Array	是	试算明细列表，至少 1 条，最多 200 条

单条 details[] 参数：

参数	类型	必填	说明
merchantDetailNo	String	是	商户明细号，仅用于响应关联，不创建真实结算明细
amount	BigDecimal	是	试算金额，单位元，必须在 1 到 300000 之间，最多 2 位小数
phone	String	否	手机号，与 platformUserId 至少传一个
platformUserId	String	否	外部用户ID，与 phone 至少传一个；若两个都传，应指向同一创客
paymentAccount	Object	是	收款账户信息；用于保持与真实结算创建的校验口径一致
remark	String	否	明细备注，仅用于请求结构与创建结算单保持一致

paymentAccount 参数：

参数	类型	必填	说明
accountNo	String	是	收款账号
accountName	String	否	账户名
phone	String	否	银行卡预留手机号。已有本人银行卡且未传时复用平台已存手机号；新卡未传时使用创客手机号；传入与已有卡不同的手机号时更新原卡。新卡及手机号变更是否执行四要素由 bankCardVerification 控制
bankName	String	否	标准银行名称
branchName	String	否	开户行全称
branchCode	String	否	联行号

4.15.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
projectId	String	项目 ID
projectName	String	项目名称
taxCompanyName	String	税地名称
receiveMethod	String	收款方式
totalAmount	BigDecimal	试算总金额
totalCount	Integer	试算总笔数
totalTax	BigDecimal	税费合计，等于个人所得税、个人增值税和附加税之和
totalPersonalIncomeTaxAmount	BigDecimal	个人所得税合计
totalPersonalValueAddedTaxAmount	BigDecimal	个人增值税合计
totalSurtaxAmount	BigDecimal	附加税合计
totalNetAmount	BigDecimal	预估税后实发金额合计；当前不扣附加税
calculationTime	String	试算时间
details	Array	试算明细列表
details[].merchantDetailNo	String	商户结算明细号
details[].amount	BigDecimal	试算金额
details[].tax	BigDecimal	单笔税费合计，等于个人所得税、个人增值税和附加税之和
details[].personalIncomeTaxAmount	BigDecimal	个人所得税
details[].personalValueAddedTaxAmount	BigDecimal	个人增值税
details[].surtaxAmount	BigDecimal	附加税
details[].feeAmount	BigDecimal	结算服务费
details[].serviceFeeAmount	BigDecimal	系统服务费
details[].bankFeeAmount	BigDecimal	银行服务费
details[].netAmount	BigDecimal	预估税后实发金额；当前不扣附加税

响应示例：

{
  "code": 0,
  "message": "成功",
  "data": {
    "projectId": "2016422018623922178",
    "projectName": "直播活动推广项目",
    "taxCompanyName": "上海税地",
    "receiveMethod": "bank",
    "totalAmount": 5000.00,
    "totalCount": 1,
    "totalTax": 500.00,
    "totalPersonalIncomeTaxAmount": 400.00,
    "totalPersonalValueAddedTaxAmount": 80.00,
    "totalSurtaxAmount": 20.00,
    "totalNetAmount": 4520.00,
    "calculationTime": "2026-06-24 15:30:00",
    "details": [
      {
        "merchantDetailNo": "MERCHANT_DETAIL_001",
        "amount": 5000.00,
        "tax": 500.00,
        "personalIncomeTaxAmount": 400.00,
        "personalValueAddedTaxAmount": 80.00,
        "surtaxAmount": 20.00,
        "feeAmount": 20.00,
        "serviceFeeAmount": 30.00,
        "bankFeeAmount": 2.00,
        "netAmount": 4520.00
      }
    ]
  }
}

4.15.4 税费口径

个人所得税、个人增值税、附加税均属于个人承担税费。当前附加税仅在系统内预留展示，尚未实际扣收，因此试算合计税费和预估实发金额的公式不同：

tax = personalIncomeTaxAmount + personalValueAddedTaxAmount + surtaxAmount
netAmount = amount - personalIncomeTaxAmount - personalValueAddedTaxAmount

也就是说，details[].tax 和 totalTax 会包含附加税；details[].netAmount 和 totalNetAmount 当前不会扣减附加税。

如果后续业务开始实际扣收附加税，平台会同步调整实发金额公式和接口说明。

4.15.5 关键说明

• 该接口是纯试算接口，不会创建结算单或结算明细。
• 当前仅支持直营税地试算；第三方税地暂不处理试算。
• receiveMethod 不只是格式校验，平台会按当前项目、商户和税地匹配可用支付账号；未配置或不支持时返回 40109 PROJECT_PAYMENT_ACCOUNT_NOT_CONFIGURED。
• 该接口不占用额度；额度是否足够仍建议通过额度接口判断。
• 该接口不触发支付，也不会发送结算结果通知。
• 商户应使用 merchantDetailNo 将试算结果与本地明细行关联。
• 个税金额复用平台真实结算时的统一税费计算组件，避免试算和落单采用两套个税口径。
• details[].feeAmount、details[].serviceFeeAmount、details[].bankFeeAmount 按创建结算单时的项目费率和税地银行服务费口径试算，仅用于创建前预估。
• 多条明细属于同一创客时，平台会按同一请求内的明细顺序纳入累计试算，尽量保持与真实结算创建时的税费口径一致。
• 试算结果依赖当前直营税地配置、创客历史累计收入和收款方式，仅代表试算时点的预估值；最终金额以真实结算创建和支付结果为准。

4.16 创建结算单接口

4.16.1 接口说明

创建结算单。

创建前会检查当前项目下的历史结算单，但仅“已发放完成且成功笔数大于 0”的历史单参与验收判断。其验收状态为 1-审核中或 2-审核通过时不拦截；状态为未提交、审核失败、历史空值或其他异常值时，只有从该历史单完成时间起已超过平台配置天数才拦截。命中时返回 40341，错误消息列出需补交凭证的结算单号。平台配置天数不是 API 固定常量，调用方不要硬编码默认天数；交付物比率不参与判断。immediatePay=true 也遵守该规则。

4.16.2 请求参数（需加密）

POST /merchantapi/v2/settlements

{
  "projectId": "2016422018623922178",
  "merchantSettlementNo": "MERCHANT_SETTLEMENT_001",
  "receiveMethod": "bank",
  "immediatePay": true,
  "remark": "2026年3月技术服务费",
  "notifyUrl": "https://merchant.example.com/api/settlement/callback",
  "details": [
    {
      "merchantDetailNo": "MERCHANT_DETAIL_001",
      "amount": 5000.00,
      "phone": "13812345678",
      "platformUserId": "DY20260115105692",
      "paymentAccount": {
        "accountNo": "6222021234567890123",
        "accountName": "张三",
        "phone": "13812345678"
      },
      "remark": "3月技术服务费"
    }
  ]
}

顶层参数：

参数	类型	必填	说明
projectId	String	否	请求体优先，client 绑定项目兜底
merchantSettlementNo	String	是	商户结算单号，长度 1-64
receiveMethod	String	是	bank / alipay / wechat
immediatePay	Boolean	否	是否立即支付；当前默认 false
remark	String	否	结算备注，最长 200
notifyUrl	String	否	异步通知地址，最长 200
details	Array	是	结算明细列表，至少 1 条，最多 200 条

单条 details[] 参数：

参数	类型	必填	说明
merchantDetailNo	String	是	商户明细号
amount	BigDecimal	是	结算金额，单位元，必须在 1 到 300000 之间
phone	String	否	手机号，与 platformUserId 至少传一个
platformUserId	String	否	外部用户ID，与 phone 至少传一个
paymentAccount	Object	是	收款账户信息
remark	String	否	明细备注

paymentAccount 参数：

参数	类型	必填	说明
accountNo	String	是	收款账号
accountName	String	否	账户名
phone	String	否	银行卡预留手机号。已有本人银行卡且未传时复用平台已存手机号；新卡未传时使用创客手机号；传入与已有卡不同的手机号时更新原卡。新卡及手机号变更是否执行四要素由 bankCardVerification 控制

4.16.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
settlementId	String	结算单 ID
settlementNo	String	系统结算单号
merchantSettlementNo	String	商户结算单号
projectId	String	项目 ID
projectName	String	项目名称
taxCompanyName	String	税地名称
receiveMethod	String	收款方式
totalAmount	BigDecimal	结算总金额
totalCount	Integer	结算总笔数
totalTax	BigDecimal	试算税费合计
totalNetAmount	BigDecimal	税后实发金额合计；当前不扣附加税
status	Integer	结算状态：0-未发放、1-发放中、2-发放完成、3-拒绝发放
statusDesc	String	结算状态描述
createTime	String	创建时间
remark	String	结算备注
paymentInitiated	Boolean	是否已发起立即支付
paymentFailureReason	String	立即支付失败原因；仅 paymentInitiated=false 时可能返回
details	Array	结算明细列表
details[].detailId	String	明细 ID
details[].detailNo	String	系统明细编号
details[].merchantDetailNo	String	商户结算明细号
details[].idCardHash	String	证件号哈希
details[].amount	BigDecimal	结算金额
details[].tax	BigDecimal	试算税费合计，等于个人所得税、个人增值税和附加税之和
details[].personalIncomeTaxAmount	BigDecimal	个人所得税
details[].personalValueAddedTaxAmount	BigDecimal	个人增值税
details[].surtaxAmount	BigDecimal	附加税
details[].feeAmount	BigDecimal	结算服务费
details[].serviceFeeAmount	BigDecimal	系统服务费
details[].bankFeeAmount	BigDecimal	银行服务费
details[].netAmount	BigDecimal	税后实发金额；当前不扣附加税
details[].status	Integer	明细状态：0-待打款、1-打款中、2-打款成功、3-打款失败、4-拒绝打款
details[].paymentTime	String	支付时间
details[].failureReason	String	失败原因
details[].remark	String	明细备注

4.16.4 关键说明

• 创建结算单前，建议商户先完成两项预检：
  • 当前创客在项目下具备可结算资格
  • 当前收款方式下的 availableQuota 足够覆盖结算金额
• 如需在创建结算单前预估税费和实发金额，可先调用 POST /merchantapi/v2/settlements/taxTrial。
• details[].tax 是单笔税费合计，包含个人所得税、个人增值税和附加税；如需拆分税费，请分别读取 personalIncomeTaxAmount、personalValueAddedTaxAmount、surtaxAmount。
• 附加税当前仅预留展示，尚未实际扣收，因此 details[].netAmount 当前不扣减附加税。
• merchantSettlementNo 和 merchantDetailNo 都应由商户自行保证稳定唯一，避免幂等冲突。
• 在未提供 makerId 的情况下，商户至少需要保证 phone 或 platformUserId 中有一个能稳定定位到目标创客。
• receiveMethod=bank 时，paymentAccount.phone 可选：已有本人银行卡且未传时复用平台已存预留手机号；新卡未传时使用创客手机号；传入与已有卡不同的手机号时，在本次请求通过所需校验后更新原卡。新卡及手机号变更是否执行四要素由客户端 bankCardVerification 开关控制；启用时四要素不匹配常见返回 40244 MAKER_BANK_CARD_VERIFICATION_FAILED 或“认证信息不匹配”。
• 创建结算单时，若多条结算明细同时校验失败（例如多条明细金额格式错误、或多条明细银行卡四要素不通过），平台会一次性返回全部失败明细的汇总信息，而不再只返回第一条：
  • 顶层 code 为 40300 SETTLEMENT_CUSTOM_ERROR；
  • message 按明细/创客逐条列出，形如 创建结算单失败；第1条明细(D001): xxx；第2条明细(D002): yyy（参数结构校验失败、银行卡信息/四要素预校验失败）或 创建结算单失败；1.创客A:xxx；2.创客B:yyy（导入业务校验失败）；
  • 仅单条明细失败时，保持原有行为不变：错误码和 message 与改造前完全一致，不返回聚合消息。
  • 若按错误码做分支处理，请注意：多明细同时失败时错误码统一为 40300，不再返回第一条明细的具体错误码。

4.16.5 结算结果通知

如果创建结算单时传入了 notifyUrl，后续结算状态变化时，平台会向该地址发送异步通知。

重要：

• 结算结果通知地址是在“创建结算单”时确定的。
• POST /merchantapi/v2/settlements/{settlementId}/pay 本身不再单独接收新的 notifyUrl。

适用场景：

• 创建结算单后，商户又单独调用了支付接口
• 商户希望通过通知而不是轮询来接收结算最终结果

外层通知包：

结算结果通知使用第三章“异步通知通用规范”中的统一外层通知包。

业务 payload 完整字段：

字段	说明
merchantId	商户 ID
settlementId	结算单 ID
settlementNo	平台结算单号
merchantSettlementNo	商户结算单号
projectId	项目 ID
projectName	项目名称
projectNo	项目编号
taxCompanyName	税地名称
receiveMethod	收款方式
payAccount	实际打款账号
totalAmount	结算总金额
totalNetAmount	税后总金额；当前不扣附加税
totalTax	总税费，等于个人所得税、个人增值税和附加税之和
totalCount	结算总笔数
status	结算单状态：0/1/2/3
statusDesc	结算状态描述
createTime	创建时间
paymentTime	支付时间
completeTime	完成时间
successCount	成功笔数
failCount	失败笔数
detailList[]	明细结果列表

detailList[] 常见字段：

字段	说明
detailId	明细 ID
detailNo	平台明细号
merchantDetailNo	商户明细号
makerId	创客 ID
amount	金额
totalTax	明细税费合计，等于个人所得税、个人增值税和附加税之和
personalIncomeTaxAmount	个人所得税
personalValueAddedTaxAmount	个人增值税
surtaxAmount	附加税
feeAmount	结算服务费
serviceFeeAmount	系统服务费
bankFeeAmount	银行服务费
netAmount	税后实发金额；当前不扣附加税
status	明细状态
statusDesc	明细状态描述
failReason	失败原因
completeTime	明细完成时间

实际业务样例如下：

{
  "merchantId": "1001",
  "settlementId": "202603250001",
  "settlementNo": "SET202603250001",
  "merchantSettlementNo": "OUT_SET_20260325_001",
  "projectId": "2016422018623922178",
  "projectName": "直播活动推广项目",
  "projectNo": "XM100086",
  "taxCompanyName": "上海税地",
  "receiveMethod": "bank",
  "payAccount": "6222021234567890123",
  "totalAmount": 5000.00,
  "totalNetAmount": 4368.00,
  "totalTax": 660.00,
  "totalCount": 2,
  "status": 2,
  "statusDesc": "发放完成",
  "createTime": "2026-03-25 10:00:00",
  "paymentTime": "2026-03-25 10:05:00",
  "completeTime": "2026-03-25 10:08:00",
  "successCount": 2,
  "failCount": 0,
  "detailList": [
    {
      "detailId": "30001",
      "detailNo": "SD10001879",
      "merchantDetailNo": "OUT_DETAIL_001",
      "makerId": "80001",
      "amount": 3000.00,
      "totalTax": 396.00,
      "personalIncomeTaxAmount": 300.00,
      "personalValueAddedTaxAmount": 80.00,
      "surtaxAmount": 16.00,
      "feeAmount": 20.00,
      "serviceFeeAmount": 30.00,
      "bankFeeAmount": 2.00,
      "netAmount": 2620.00,
      "status": "2",
      "statusDesc": "发放完成",
      "failReason": null,
      "completeTime": "2026-03-25 10:07:00"
    },
    {
      "detailId": "30002",
      "detailNo": "SD10001880",
      "merchantDetailNo": "OUT_DETAIL_002",
      "makerId": "80002",
      "amount": 2000.00,
      "totalTax": 264.00,
      "personalIncomeTaxAmount": 200.00,
      "personalValueAddedTaxAmount": 52.00,
      "surtaxAmount": 12.00,
      "feeAmount": 15.00,
      "serviceFeeAmount": 20.00,
      "bankFeeAmount": 2.00,
      "netAmount": 1748.00,
      "status": "2",
      "statusDesc": "发放完成",
      "failReason": null,
      "completeTime": "2026-03-25 10:08:00"
    }
  ]
}

补充说明：

• 结算通知是“主单 + 明细”一起推，不需要商户再自己拼装。
• 附加税当前仅预留展示，尚未实际扣收，因此 totalNetAmount 和 detailList[].netAmount 当前不扣减附加税。
• status 和 detailList[].status 当前都是数字编码，但因 DTO 定义为字符串字段，商户按字符串或数字兼容解析都更稳妥。

处理建议：

• 商户建议先按 settlementId 或 merchantSettlementNo 更新主单，再按 merchantDetailNo 更新明细。
• 不建议仅依据同步创建响应里的 paymentInitiated=true 判断支付成功。
• 结算结果通知与结算详情查询应结合使用：通知负责“收口”，查询负责“补数”和“复核”。

4.17 发起支付接口

4.17.1 接口说明

对已创建的结算单发起支付。

4.17.2 请求参数（需加密）

POST /merchantapi/v2/settlements/{settlementId}/pay

{
  "confirmPay": true
}

Path 参数：

参数	类型	必填	说明
settlementId	String	是	结算单 ID，在 URL 路径中传入

请求体参数（需加密）：

参数	类型	必填	说明
confirmPay	Boolean	是	是否确认发起支付

4.17.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
settlementId	String	结算单 ID
settlementNo	String	系统结算单号
projectId	String	项目 ID
projectName	String	项目名称
receiveMethod	String	收款方式
status	Integer	结算状态：0-未发放、1-发放中、2-发放完成、3-拒绝发放
paymentStatus	String	支付状态，如 PENDING / PROCESSING / COMPLETED / REJECTED / UNKNOWN
paymentTime	String	发起支付时间
expectedTime	String	预计完成时间
totalAmount	BigDecimal	结算总金额
totalCount	Integer	总笔数
successCount	Integer	成功笔数
failCount	Integer	失败笔数
processingCount	Integer	处理中笔数
details	Array	结算明细列表
details[].detailId	String	明细 ID
details[].detailNo	String	系统明细编号
details[].merchantDetailNo	String	商户结算明细号
details[].amount	BigDecimal	结算金额
details[].tax	BigDecimal	试算税费合计，等于个人所得税、个人增值税和附加税之和
details[].personalIncomeTaxAmount	BigDecimal	个人所得税
details[].personalValueAddedTaxAmount	BigDecimal	个人增值税
details[].surtaxAmount	BigDecimal	附加税
details[].feeAmount	BigDecimal	结算服务费
details[].serviceFeeAmount	BigDecimal	系统服务费
details[].bankFeeAmount	BigDecimal	银行服务费
details[].netAmount	BigDecimal	税后实发金额；当前不扣附加税
details[].status	Integer	明细状态：0-待打款、1-打款中、2-打款成功、3-打款失败、4-拒绝打款
details[].paymentTime	String	支付时间
details[].failureReason	String	失败原因
details[].remark	String	备注

paymentStatus 当前常见取值：

取值	含义
PENDING	待支付
PROCESSING	支付处理中
COMPLETED	支付完成
REJECTED	已拒绝或不可继续处理
UNKNOWN	未识别状态

4.17.4 关键说明

• 已完成或已拒绝的结算单不能重复支付。
• 支付中的结算单再次发起支付时，商户应谨慎处理重试逻辑。
• confirmPay 的作用是显式确认本次支付动作，建议商户仅在人工确认或流程节点明确时调用。
• 商户若实现自动重试，应先查询结算单详情确认当前状态，避免并发重复发起。
• confirmPay=true 的实际发放请求会再次检查上述历史验收凭证逾期规则；命中时返回 40341，错误消息列出需要补交凭证的结算单号。confirmPay=false 仅查询当前支付信息，不触发该检查；交付物比率不参与判断。
• 平台配置天数不是 API 固定常量，调用方不要硬编码验收截止日期；收到 40341 后补交消息中列出的验收凭证，再重新发起支付。

4.18 获取结算回单接口

4.18.1 接口说明

按结算明细获取回单文件。

4.18.2 请求参数

GET /merchantapi/v2/settlementDetails/{detailId}/receipt

参数	类型	必填	说明
detailId	String	是	结算明细 ID

4.18.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "detailId": "3024091600001001",
    "detailNo": "DTL202409160001",
    "receiptNo": "REC202409160001",
    "receiptContent": "JVBERi0xLjQKJeLjz9...",
    "receiptType": "PDF",
    "fileName": "回单_DTL202409160001.pdf",
    "fileSize": 102400,
    "generateTime": "2025-09-16 10:30:00"
  }
}

以下仅展开 data 字段的完整结构：

字段	类型	说明
detailId	String	结算明细 ID
detailNo	String	结算明细编号
receiptNo	String	回单编号
receiptContent	String	回单内容（Base64）
receiptType	String	回单类型，如 PDF
fileName	String	文件名称
fileSize	Long	文件大小，单位字节
generateTime	String	回单生成时间

4.18.4 关键说明

• 当前接口直接返回 Base64 编码的回单文件内容。
• 只有成功完成支付的明细才允许获取回单。
• 商户若需要长期留存回单，建议在收到成功结果后自行落盘或转存，不建议每次展示时重复拉取。

4.19 查询自由职业者信息接口

4.19.1 接口说明

按手机号列表或外部用户ID列表批量查询自由职业者信息。

4.19.2 请求参数（需加密）

POST /merchantapi/v2/makers/query

{
  "phoneNumbers": ["13812345678", "13912345678"]
}

参数	类型	必填	说明
phoneNumbers	Array	否	手机号列表，最多 50 个。与 platformUserIds 二选一
phoneNumbers[]	String	否	单个手机号
platformUserIds	Array	否	外部用户ID列表，最多 50 个。与 phoneNumbers 二选一
platformUserIds[]	String	否	单个外部用户ID

4.19.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
makers	Array	自由职业者信息列表
makers[].makerId	String	创客 ID；查询成功时返回
makers[].code	String	创客编号
makers[].name	String	姓名（脱敏）
makers[].idCard	String	证件号（脱敏）
makers[].idType	String	证件类型
makers[].country	String	国家或地区代码
makers[].address	String	地址
makers[].phone	String	联系电话（脱敏）
makers[].platformUserId	String	外部用户ID
makers[].platformName	String	平台名称
makers[].platformUserName	String	平台用户名（脱敏）
makers[].status	Integer	状态：1-正常、0-禁用
makers[].statusDesc	String	状态描述
makers[].taxCompanyQualifications	Array	创客税地资格信息
makers[].taxCompanyQualifications[].taxCompanyId	String	税地 ID
makers[].taxCompanyQualifications[].taxCompanyName	String	税地名称
makers[].taxCompanyQualifications[].isRealNamed	Boolean	是否已完成税地实名认证
makers[].taxCompanyQualifications[].realNameTime	String	税地实名通过时间
makers[].taxCompanyQualifications[].liveness	Boolean	是否已完成税地活体认证
makers[].taxCompanyQualifications[].livenessTime	String	税地活体通过时间
makers[].taxCompanyQualifications[].signStatus	Integer	税地签约状态：0-未签约、1-已签约、2-已过期、3-签约中
makers[].taxCompanyQualifications[].signStatusDesc	String	税地签约状态描述
makers[].taxCompanyQualifications[].signTime	String	税地签约时间
makers[].createTime	String	创建时间
makers[].updateTime	String	更新时间
makers[].errorCode	String	单条错误码；查询成功时通常为空
makers[].errorMessage	String	单条错误信息；查询成功时通常为空

4.19.4 关键说明

• 该接口是查询接口，不负责保存或更新自由职业者信息。
• 单条查询失败时，会在单条结果中返回 errorCode / errorMessage。
• phoneNumbers 和 platformUserIds 两者至少传一种，但不能同时传。
• 商户应根据自己的查询入口二选一：按手机号查，或按 platformUserId 查。
• 该接口采用“部分成功”模式，单条异常不会阻断其他条目的返回。

4.20 解绑自由职业者接口

4.20.1 接口说明

按外部用户ID解绑自由职业者。

4.20.2 请求参数（需加密）

POST /merchantapi/v2/makers/unbind

{
  "platformUserId": "USERID_001"
}

参数	类型	必填	说明
platformUserId	String	是	外部用户ID

4.20.3 响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": null
}

该接口成功时 data 固定返回 null。

4.20.4 关键说明

• 该接口主要用于处理商户侧 platformUserId 异常绑定场景。
• 解绑属于纠错动作，不建议作为正常招募链路的一部分频繁调用。
• 解绑前建议先核对历史招募任务、结算记录和业务订单，避免把仍在使用中的绑定关系解除。

4.21 查询企业账户信息接口

4.21.1 接口说明

查询当前商户的企业账户及各账户的余额快照。accountList[] 中每一项都是独立的企业账户；
开启 includeRechargeOptions 后，该账户项会同时返回只适用于该 accountId 的充值转账信息。

商户充值时必须从 available=true 的 payerAccount 转账到同一充值方式下的 payeeAccount。
本接口返回的所有充值方式均按自动上账处理：平台识别到账并完成上账后，资金进入该充值方式所属的
accountId，并通过充值上账通知告知商户。商户不需要另行提交充值申请或打款凭证。

4.21.2 请求参数

GET /merchantapi/v2/account/queryMerchantAccountInfo?includeRechargeOptions=true

参数	类型	必填	默认值	说明
includeRechargeOptions	Boolean	否	false	是否在每个账户中返回结构化充值方式 rechargeOptions

无业务请求体。未传或传 false 时，响应结构与原接口保持一致，不返回 rechargeOptions。
该查询参数不改变现有 V2 GET 签名规则，签名串仍只包含 nonce 和 timestamp，详见 5.1.1。

4.21.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
accountList	Array	当前商户的企业账户列表，固定返回数组；每个账户及其余额、充值方式相互独立
accountList[].accountId	String	账户 ID
accountList[].accountType	String	账户类型（展示字段，如银行卡/支付宝/微信支付）
accountList[].accountUserName	String	当前企业账户底层支付配置中的账户持有人名称，不是商户充值付款户名
accountList[].accountUserIdCard	String	当前企业账户底层支付配置中的账户持有人证件号；企业账户可能为统一社会信用代码
accountList[].account	String	当前企业账户底层支付配置中的主账户号，不是商户充值付款账号；不得据此推断转账方向
accountList[].accountName	String	账户展示名称；银行账户下与 bankName 取值相同
accountList[].bankName	String	银行名称；非银行账户通常为空字符串
accountList[].branchName	String	支行名称/开户行全称，仅银行账户且已维护时返回
accountList[].rechargeAccount	String	运营人员在支付配置中维护的充值展示值；可能为空，不保证是可直接转账的银行账号
accountList[].rechargeAccountName	String	与 rechargeAccount 配套的运营配置展示名称；可能为空，不代表商户付款账户名称
accountList[].rechargeOptions	Array	仅适用于当前 accountId 的结构化充值方式；仅当 includeRechargeOptions=true 时返回，未知扩展支付方式可能返回空数组
accountList[].rechargeOptions[].mode	String	稳定的充值方式代码，见下表
accountList[].rechargeOptions[].modeName	String	充值方式展示名称
accountList[].rechargeOptions[].available	Boolean	是否已具备完整、无冲突的付款和收款账号配置；不代表付款余额、渠道实时状态或上账结果，为 false 时不得发起转账
accountList[].rechargeOptions[].unavailableCode	String	不可用原因代码；可用时不返回
accountList[].rechargeOptions[].unavailableMessage	String	不可用原因说明；可用时不返回
accountList[].rechargeOptions[].payerAccount	Object	商户应使用的付款账户；付款配置无效时不返回
accountList[].rechargeOptions[].payeeAccount	Object	平台为当前企业账户及税地配置的实际收款账户；收款配置无效时不返回
accountList[].rechargeOptions[].payerAccount.accountType	String	付款账户类型稳定代码：BANK、ALIPAY、WECHAT
accountList[].rechargeOptions[].payerAccount.accountName	String	付款户名
accountList[].rechargeOptions[].payerAccount.account	String	商户应使用的付款账号
accountList[].rechargeOptions[].payerAccount.bankName	String	付款银行或支付渠道名称；不适用时不返回
accountList[].rechargeOptions[].payerAccount.branchName	String	付款账户开户行/支行；不适用或未维护时不返回
accountList[].rechargeOptions[].payeeAccount.accountType	String	收款账户类型稳定代码：BANK、ALIPAY、WECHAT
accountList[].rechargeOptions[].payeeAccount.accountName	String	实际收款户名，通常为当前企业账户所属的税地公司名称；转账时必须使用返回值
accountList[].rechargeOptions[].payeeAccount.account	String	商户应汇入的收款账号
accountList[].rechargeOptions[].payeeAccount.bankName	String	收款银行或支付渠道名称；不适用时不返回
accountList[].rechargeOptions[].payeeAccount.branchName	String	收款账户开户行/支行；不适用或未维护时不返回
accountList[].availableAmount	BigDecimal	当前账户可用于发起结算或支付的余额，单位：元
accountList[].settleAmount	BigDecimal	当前账户正在结算处理中的税后金额，暂不可重复使用，单位：元
accountList[].otherAmount	BigDecimal	当前账户结算处理中涉及的税费、手续费、服务费等其他金额，单位：元
accountList[].freezeAmount	BigDecimal	当前账户被冻结、暂不可使用的金额，单位：元

充值方式代码：

mode	付款方向	上账方式
BANK_TRANSFER	商户银行卡 -> 当前税地配置的银行收款账户	到账后自动上账
ALIPAY_TRANSFER	商户企业支付宝 -> 当前企业账户配置的支付宝收款账户	到账后自动上账
OFFLINE_BANK_TRANSFER	同 BANK_TRANSFER， 商户银行卡 -> 当前税地配置的银行收款账户	到账后自动上账
ALIPAY_ISV_TRANSFER	商户银行卡 -> 当前支付宝 ISV 企业账户配置的银行收款账户	到账后自动上账
WECHAT_TRANSFER	商户银行卡 -> 当前微信企业账户配置的收款账户	到账后自动上账

银行卡账户完整成功响应示例：

{
  "code": 0,
  "message": "成功",
  "data": {
    "accountList": [
      {
        "accountId": "3001",
        "accountType": "银行卡",
        "accountUserName": "示例税地有限公司",
        "accountUserIdCard": "91310000MA1EXAMPLE",
        "account": "6222021234567890123",
        "accountName": "招商银行",
        "bankName": "招商银行",
        "branchName": "招商银行上海支行",
        "rechargeAccount": "招商沙盒尾号000",
        "rechargeAccountName": null,
        "rechargeOptions": [
          {
            "mode": "BANK_TRANSFER",
            "modeName": "银行卡汇款",
            "available": true,
            "payerAccount": {
              "accountType": "BANK",
              "accountName": "示例商户有限公司",
              "account": "6222021234567890",
              "bankName": "招商银行",
              "branchName": "招商银行厦门分行"
            },
            "payeeAccount": {
              "accountType": "BANK",
              "accountName": "示例税地有限公司",
              "account": "6222021234567890123",
              "bankName": "招商银行",
              "branchName": "招商银行上海支行"
            }
          }
        ],
        "availableAmount": 98.56,
        "settleAmount": 0,
        "otherAmount": 0,
        "freezeAmount": 0.56
      }
    ]
  },
  "timestamp": 1784255694775,
  "requestId": "req_00201969d38d4dc5b51c2999531d24d7",
  "encrypted": false,
  "signature": "5e9beee47b43e37538446c8b53c5e0fe6dd15a550c00c6b546c86d0d141614c3"
}

企业支付宝账户可能同时返回两种候选方式；以下两种方式都只为示例中的同一个 accountId
充值，并在到账后自动上账：

{
  "accountId": "3002",
  "accountType": "支付宝",
  "rechargeOptions": [
    {
      "mode": "ALIPAY_TRANSFER",
      "modeName": "企业支付宝汇款",
      "available": true,
      "payerAccount": {
        "accountType": "ALIPAY",
        "accountName": "示例商户有限公司",
        "account": "2088123456789012",
        "bankName": "支付宝"
      },
      "payeeAccount": {
        "accountType": "ALIPAY",
        "accountName": "示例税地有限公司",
        "account": "platform@example.com",
        "bankName": "支付宝"
      }
    },
    {
      "mode": "OFFLINE_BANK_TRANSFER",
      "modeName": "银行卡汇款",
      "available": false,
      "unavailableCode": "OFFLINE_PAYEE_NOT_CONFIGURED",
      "unavailableMessage": "税地下未维护线下银行收款账户",
      "payerAccount": {
        "accountType": "BANK",
        "accountName": "示例商户有限公司",
        "account": "6222021234567890",
        "bankName": "招商银行",
        "branchName": "厦门分行"
      }
    }
  ]
}

不可用原因代码：

代码	说明
PAYER_BANK_ACCOUNT_NOT_CONFIGURED	商户付款银行卡未维护或信息不完整
PAYER_ALIPAY_ACCOUNT_NOT_CONFIGURED	商户企业支付宝未维护
PAYER_ACCOUNT_CONFIG_CONFLICT	同一商户存在多条付款账户配置
PAYEE_ACCOUNT_NOT_CONFIGURED	当前入账账户没有可执行收款账号
PAYEE_ACCOUNT_INVALID	收款账号格式无效
OFFLINE_PAYEE_NOT_CONFIGURED	税地下未维护线下银行收款账户
OFFLINE_PAYEE_CONFIG_CONFLICT	税地下存在多条冲突的线下收款配置

4.21.4 关键说明

• 未开启 includeRechargeOptions 时，本接口仍只是企业账户和余额查询入口，不包含完整充值指引。
• 项目详情里的账户信息只是项目维度摘要，不应替代本接口。
• 开启后，调用方只能使用 available=true 的 payerAccount 和 payeeAccount 发起转账；不得使用 account、rechargeAccount 或 rechargeAccountName 推断转账方向。
• 每个 rechargeOptions[] 只适用于其所在的 accountList[]；不同 accountId 之间不得混用付款或收款信息。
• 所有返回的充值方式均为到账后自动上账。商户按返回账号完成转账后等待充值上账通知，无需另行提交充值申请或打款凭证。
• available 只表示该方式的账号配置完整且无冲突，不代表付款余额充足、渠道实时可用或已经上账成功。
• 单个充值方式配置缺失或冲突时，仅该方式返回 available=false，不影响账户和其他充值方式返回。
• 本接口所有金额字段均以元为单位返回，不是分。
• accountType 当前返回展示值，不保证可作为长期稳定枚举使用；如需程序分支，建议不要仅依赖该字段文案。
• accountName 在银行账户场景下当前与 bankName 相同；账户持有人名称应读取 accountUserName。
• branchName 为可选字段；未维护支行信息时可能为空。该接口不返回支行联行号。

4.21.5 充值上账通知

充值上账通知属于企业账户维度的异步通知，不通过业务请求体传入回调地址，而是由平台在商户 API 客户端配置中维护 rechargeNotifyUrl。

触发时机：

• 商户按 payerAccount -> payeeAccount 完成转账后，平台自动识别到账并上账至对应 accountId
• 平台完成上账并记录为成功后，向商户推送到账结果；收到通知前不得把转账视为上账成功

回调地址来源：

• 非某个 API 业务接口请求参数
• 由平台为当前商户 API 客户端预先配置 rechargeNotifyUrl

外层通知包：

充值上账通知使用第三章“异步通知通用规范”中的统一外层通知包。

业务 payload：

以下为回调 data 的完整字段：

{
  "merchantId": "1234567890",
  "amount": 100.00,
  "accountNo": "6222021234567890123",
  "accountName": "XX有限公司",
  "counterpartyAccountNo": "6217000012345678901",
  "counterpartyAccountName": "付款方有限公司",
  "dealTime": "2026-03-25 10:10:10",
  "dealId": "R202603250001",
  "zfCode": "bank",
  "remark": "充值成功"
}

字段	说明
merchantId	商户 ID
amount	上账金额
accountNo	充值到账账户号
accountName	充值到账账户名称
counterpartyAccountNo	交易对方账户号
counterpartyAccountName	交易对方账户名称
dealTime	上账时间
dealId	交易流水号
zfCode	支付通道，如 bank / alipay / wechat
remark	备注

补充说明：

• 当前代码中 remark 可能为空，商户应按可空字段处理。
• 该通知不区分“申请成功/审核成功”等中间态，实际收到时表示平台已经确认到账并完成上账。
• counterpartyAccountNo、counterpartyAccountName 对应实际付款方信息；accountNo、accountName 对应平台确认入账的企业账户信息。

处理建议：

• 建议以 dealId 作为上账通知的主幂等键。
• 商户若需要做账户余额展示，建议收到通知后仍再调用企业账户查询接口做一次余额校验。
• 若商户系统区分“资金到账”和“可发起结算”，建议将上账通知作为资金事件，而不要混同为结算事件。

4.22 查询可开票余额接口

4.22.1 接口说明

查询当前商户已发放成功流水按税地和税目归集后的开票状态金额。

该接口返回的是开票口径金额，不是企业账户可用余额，也不是可发放额度。只有已发放成功的结算明细才会进入统计。

4.22.2 请求参数

GET /merchantapi/v2/invoice/queryAvailableInvoiceBalance

无业务请求体。

4.22.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
taxCompanyData	Array	税地公司数据列表
taxCompanyData[].taxCompanyId	String	税地公司 ID
taxCompanyData[].taxCompanyName	String	税地公司名称
taxCompanyData[].invoiceDataList	Array	当前商户在该税地下的税目开票状态金额列表
taxCompanyData[].invoiceDataList[].taxCategoryName	String	税目名称
taxCompanyData[].invoiceDataList[].hasInvoiceFee	BigDecimal	当前商户已发放成功且已开票金额，单位元
taxCompanyData[].invoiceDataList[].applyInvoiceFee	BigDecimal	当前商户已发放成功且开票申请中金额，单位元
taxCompanyData[].invoiceDataList[].ableInvoiceFee	BigDecimal	当前商户已发放成功且未开票金额，可用于发起开票申请，单位元

4.22.4 关键说明

• 该接口是开票申请前的查询入口。
• 商户应优先根据该接口判断是否具备开票条件；ableInvoiceFee 只表示已发放成功且未开票的历史流水金额。
• 该接口只统计当前商户数据，不会包含同一税地下其他商户的结算流水。
• 未发放、发放失败、待发放或账户充值未形成发放成功流水的金额，不会计入 ableInvoiceFee。
• ableInvoiceFee 不是企业账户可用余额或可发放额度；企业账户可用余额请以企业账户查询接口返回的 availableAmount 为准。
• 可开票余额按税地和税目维度聚合，商户在开票前应确认要申请的结算单是否落在同一归集口径下。

4.23 查询可开票结算单列表接口

4.23.1 接口说明

查询当前商户已发放成功且未开票的结算单列表。

该接口返回结算单粒度的数据，主要用于开票申请前选择 outSettlementNoList。开票申请时应传本接口返回的 merchantSettlementNo，不要传平台系统结算单号 settlementNo。

4.23.2 请求参数

GET /merchantapi/v2/invoice/queryAvailableInvoiceSettlements?projectId=2016422018623922178

参数	类型	必填	说明
projectId	String	条件必填	项目 ID；传入时只查询该项目下的可开票结算单。未传时仅在 client 已绑定默认项目时可省略

4.23.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
settlements	Array	可开票结算单列表
settlements[].settlementId	String	平台结算单 ID
settlements[].settlementNo	String	平台系统结算单号，仅用于排查和展示
settlements[].merchantSettlementNo	String	商户结算单号；开票申请 outSettlementNoList[] 应传该字段
settlements[].projectId	String	项目 ID
settlements[].projectName	String	项目名称
settlements[].taxCompanyId	String	税地公司 ID
settlements[].taxCompanyName	String	税地公司名称
settlements[].taxCategoryName	String	税目名称
settlements[].receiveMethod	String	收款方式，如 bank / alipay / wechat
settlements[].ableInvoiceFee	BigDecimal	该结算单当前可开票金额，单位元
settlements[].detailCount	Integer	当前可开票结算明细数量
settlements[].completeTime	String	结算完成时间，格式 yyyy-MM-dd HH:mm:ss

响应示例：

{
  "code": 0,
  "message": "成功",
  "data": {
    "settlements": [
      {
        "settlementId": "2034454171060154368",
        "settlementNo": "JS202606200001",
        "merchantSettlementNo": "MERCHANT_SETTLEMENT_001",
        "projectId": "2016422018623922178",
        "projectName": "示例项目",
        "taxCompanyId": "17",
        "taxCompanyName": "上海税地",
        "taxCategoryName": "劳务报酬-推广服务",
        "receiveMethod": "bank",
        "ableInvoiceFee": 8000.00,
        "detailCount": 2,
        "completeTime": "2026-06-20 14:10:00"
      }
    ]
  }
}

4.23.4 关键说明

• 本接口按结算单明细判断是否可开票：只有 pay_status=2（打款成功）且 invoice_status=0（未开票）的结算明细会进入列表统计。
• 若同一结算单下存在任何已开票或开票中的明细，该结算单不会出现在本列表中，避免后续开票申请被重复开票校验拒绝。
• merchantSettlementNo 对应创建结算单时传入的商户结算单号，也对应库表 lg_merchant_settlement.out_settlement_no。
• settlementNo 是平台系统结算单号，不作为开票申请的入参。
• 商户可先调用查询可开票余额接口判断税地、税目维度的总可开票金额，再调用本接口获取可直接传给开票申请的结算单号。

4.24 开票申请接口

4.24.1 接口说明

发起开票申请。

4.24.2 请求参数（需加密）

POST /merchantapi/v2/invoice/apply

{
  "projectId": "2016422018623922178",
  "outSettlementNoList": ["MERCHANT_SETTLEMENT_001", "MERCHANT_SETTLEMENT_002"],
  "invoiceType": 1,
  "invoiceAddress": "上海市浦东新区XXX路88号",
  "invoicePhone": "021-12345678",
  "invoiceAcctNo": "3100000123456789",
  "invoiceBankName": "招商银行上海分行",
  "remark": "请尽快开票",
  "merchantInvoiceNo": "MERCHANT_INVOICE_20260924001",
  "notifyUrl": "https://merchant.example.com/api/invoice/callback"
}

参数	类型	必填	说明
projectId	String	条件必填	请求体优先；未传时仅在 client 已绑定默认项目时可省略。多项目商户建议始终显式传入
outSettlementNoList	Array	是	商户结算单号列表；建议使用“查询可开票结算单列表接口”返回的 merchantSettlementNo
outSettlementNoList[]	String	是	单个商户结算单号，对应 lg_merchant_settlement.out_settlement_no
invoiceType	Integer	否	当前默认 1，表示专票
invoiceAddress	String	否	发票抬头地址
invoicePhone	String	否	发票抬头电话
invoiceAcctNo	String	否	发票抬头银行账户
invoiceBankName	String	否	发票抬头开户行
remark	String	否	备注
merchantInvoiceNo	String	否	商户侧申请发票编号，最长 100 个字符；用于商户内部申请单关联和后续核对
notifyUrl	String	否	通知地址，最长 200

4.24.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
invoiceId	String	发票 ID
taxCompanyId	String	税地公司 ID
taxCategoryName	String	税目名称
invoiceAmount	BigDecimal	发票金额
invoiceType	Integer	发票类型；当前默认 1-专票
invoiceAddress	String	发票抬头地址
invoicePhone	String	发票抬头电话
invoiceAcctNo	String	发票抬头银行账户
invoiceBankName	String	发票抬头开户行
remark	String	审核意见或备注
invoiceStatus	Integer	开票状态：0-开票中、1-已开票、2-拒绝开票
fileList	Array	发票附件列表
fileList[].fileName	String	文件名
fileList[].fileUrl	String	文件地址

4.24.4 关键说明

• outSettlementNoList 中应传商户结算单号，即查询可开票结算单列表接口返回的 merchantSettlementNo，不是平台系统结算单号 settlementNo。
• outSettlementNoList 中的结算单必须属于当前商户和当前项目。
• 若结算单已经处于开票中或已开票，不允许重复申请。
• 申请开票的结算单必须已发放成功且未开票；系统会按结算单明细重新计算本次可申请开票金额。
• merchantInvoiceNo 为商户侧自定义的申请发票编号，平台会随开票申请记录保存；建议使用商户系统中稳定、可追踪的业务编号。
• 建议商户在调用前先使用可开票余额接口确认目标税地和税目下是否存在已发放成功且未开票金额，再使用查询可开票结算单列表接口组织申请单。
• 开票申请返回成功只代表申请已创建，不代表发票文件已经生成。

4.24.5 发票结果通知

如果开票申请时传入了 notifyUrl，后续发票状态变化后，平台会向该地址发送异步通知。

触发时机：

• 发票申请进入处理中
• 发票开具完成并生成附件
• 发票申请被拒绝

外层通知包：

发票结果通知使用第三章“异步通知通用规范”中的统一外层通知包。

业务 payload：

发票结果通知的业务字段与“查询发票详情接口”的响应字段保持一致，商户可直接复用发票详情的数据结构进行解析。
以下为回调 data 的完整字段：

字段	说明
invoiceId	发票 ID
taxCompanyId	税地 ID
taxCategoryName	税目名称
invoiceAmount	发票金额
invoiceType	发票类型
invoiceAddress	发票抬头地址
invoicePhone	发票抬头电话
invoiceAcctNo	发票抬头银行账户
invoiceBankName	发票抬头开户行
remark	审核意见或备注
invoiceStatus	发票状态：0开票中 / 1已开票 / 2拒绝开票
fileList[]	发票附件列表

fileList[] 常见字段：

字段	说明
fileName	文件名
fileUrl	文件地址

实际业务样例如下：

{
  "invoiceId": "2034454171060154370",
  "taxCompanyId": "17",
  "taxCategoryName": "劳务报酬-推广服务",
  "invoiceAmount": 8000.00,
  "invoiceType": 1,
  "invoiceAddress": "上海市浦东新区示例路88号",
  "invoicePhone": "021-12345678",
  "invoiceAcctNo": "310066666666666666",
  "invoiceBankName": "招商银行上海分行",
  "remark": "已开票",
  "invoiceStatus": 1,
  "fileList": [
    {
      "fileName": "增值税专用发票.pdf",
      "fileUrl": "https://cdn.example.com/invoice/2034454171060154370.pdf"
    }
  ]
}

补充说明：

• invoiceStatus=0 时，fileList 通常为空。
• invoiceStatus=2 时，商户应重点关注 remark 中的拒绝原因。

处理建议：

• 建议以 invoiceId 做幂等更新。
• 当 invoiceStatus=1 时，再处理 fileList 中的发票附件展示或归档。
• 若商户系统对开票流程做了审批或财务节点控制，建议把“开票申请成功”和“发票已开具”明确拆成两个不同状态。

4.25 查询发票详情接口

4.25.1 接口说明

按发票 ID 查询发票详情和附件。

4.25.2 请求参数

GET /merchantapi/v2/invoice/myInvoice/{invoiceId}

参数	类型	必填	说明
invoiceId	String	是	发票 ID

4.25.3 响应参数（明文+签名）

以下仅展开 data 字段的完整结构：

字段	类型	说明
invoiceId	String	发票 ID
taxCompanyId	String	税地公司 ID
taxCategoryName	String	税目名称
invoiceAmount	BigDecimal	发票金额
invoiceType	Integer	发票类型；当前默认 1-专票
invoiceAddress	String	发票抬头地址
invoicePhone	String	发票抬头电话
invoiceAcctNo	String	发票抬头银行账户
invoiceBankName	String	发票抬头开户行
remark	String	审核意见或备注
invoiceStatus	Integer	开票状态：0-开票中、1-已开票、2-拒绝开票
fileList	Array	发票附件列表
fileList[].fileName	String	文件名
fileList[].fileUrl	String	文件地址

4.25.4 关键说明

• 当发票已生成电子文件时，通常可通过 fileList 获取文件下载地址。
• 商户若需要在自身系统展示开票附件，建议以 invoiceStatus=已开票 作为展示前提。

4.26 提交验收凭证接口

4.26.1 接口说明

按结算主单提交验收凭证。验收凭证使用 settlementId 关联结算主单，不是按 detailId 关联的结算明细交付物。请求体按现有 Merchant API V2 规则加密并签名。

结算单满足以下任一条件时可提交：

1. 未发放：status=0 且 amount>0；
2. 发放中：status=1；
3. 发放完成：status=2 且 successCount>0。

结算单必须同时满足上述结算业务条件和验收状态条件：acceptanceStatus 为 0-未提交、3-审核失败 或历史数据为 null；1-审核中 不允许重复提交，2-审核通过 不允许再次提交。审核失败后的重新提交会新增验收记录，不删除、不覆盖历史记录和文件。

4.26.2 请求参数（需加密）

POST /merchantapi/v2/settlements/{settlementId}/acceptance

{
  "files": [
    {
      "fileName": "acceptance-report.pdf",
      "fileUrl": "https://merchant-oss.example.com/acceptance/acceptance-report.pdf"
    },
    {
      "fileName": "acceptance-detail.xlsx",
      "fileUrl": "https://merchant-oss.example.com/acceptance/acceptance-detail.xlsx"
    }
  ]
}

参数	类型	必填	说明
settlementId	String	是	路径参数；结算主单 ID
files	Array	是	验收凭证文件，至少 1 个、最多 5 个
files[].fileName	String	是	原始文件名，最长 200 个字符；不得包含目录片段或控制字符
files[].fileUrl	String	是	商户提供的临时文件地址，必须使用 HTTPS，最长 2048 个字符

文件规则：

• 单个文件最大 20 MiB。
• 支持 jpg、jpeg、png、pdf、xls、xlsx、zip、7z、rar。
• 不接受 Base64 文件内容。平台会同步下载并转存文件，成功响应中的 fileUrl 是平台转存后的地址，不是商户请求中的原始 URL。
• fileUrl 必须能够通过公网 HTTPS 匿名访问；不得使用内网、环回、链路本地、云元数据地址，也不得携带用户名或密码。平台下载请求不会携带商户的 Cookie、Authorization 或其他自定义鉴权头。
• 每次重定向后的地址都会重新校验，必须仍是公网 HTTPS，最多允许 3 次重定向；URL 至少要在本次提交同步下载和转存完成前保持有效。

4.26.3 成功响应（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "acceptanceRecordId": "2071000000000000001",
    "settlementId": "2069720243669520385",
    "settlementNo": "JS10088004",
    "acceptanceStatus": 1,
    "acceptanceStatusDesc": "审核中",
    "submitTime": "2026-07-28 15:30:00",
    "fileCount": 2,
    "files": [
      {
        "fileId": "2071000000000000101",
        "fileName": "acceptance-report.pdf",
        "fileUrl": "https://oss.example.com/merchant-acceptance-2071000000000000001-file-1.pdf"
      },
      {
        "fileId": "2071000000000000102",
        "fileName": "acceptance-detail.xlsx",
        "fileUrl": "https://oss.example.com/merchant-acceptance-2071000000000000001-file-2.xlsx"
      }
    ]
  },
  "timestamp": 1785223800000,
  "requestId": "req_example",
  "encrypted": false,
  "signature": "example-signature"
}

字段	类型	说明
acceptanceRecordId	String	本次新增的验收审核记录 ID
settlementId	String	结算主单 ID
settlementNo	String	平台结算单号
acceptanceStatus	Integer	提交成功后固定为 1-审核中
acceptanceStatusDesc	String	验收状态说明
submitTime	String	本次提交时间，格式 yyyy-MM-dd HH:mm:ss
fileCount	Integer	本次提交的文件数
files	Array	本次提交并由平台转存的文件列表
files[].fileId	String	平台文件 ID
files[].fileName	String	文件名
files[].fileUrl	String	平台转存后的文件访问地址，不是商户请求中的原始 URL；访问有效期沿用平台现有存储配置

若客户端在提交后超时，不要立即盲目重试；应先调用查询验收凭证接口，确认本次提交是否已进入审核中。平台不提供验收审核结果回调；提交成功后，调用方必须主动轮询查询接口，直到 acceptanceStatus 不再为 1-审核中。

4.26.4 业务错误码

错误码	说明
40008	请求参数验证失败
40303	结算单不存在
40304	当前结算单状态不允许提交
40312	无权操作该结算单
40338	验收凭证正在审核，不可重复提交
40339	验收凭证已审核通过，不可再次提交
40340	验收状态异常，暂不可提交
40401	文件大小超过限制
40403	文件数量超限
40404	不支持的文件格式
50000	系统内部错误

4.27 查询验收凭证接口

4.27.1 接口说明

查询结算主单当前验收状态，以及最近一次提交对应的凭证文件。接口不返回历次验收审核记录列表，也不返回更早提交的文件。GET 请求无请求体，仍需携带 Merchant API V2 认证和签名请求头。

GET /merchantapi/v2/settlements/{settlementId}/acceptance

参数	类型	必填	说明
settlementId	String	是	路径参数；结算主单 ID

4.27.2 成功响应（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "settlementId": "2069720243669520385",
    "settlementNo": "JS10088004",
    "acceptanceStatus": 3,
    "acceptanceStatusDesc": "审核失败",
    "acceptanceSubmitTime": "2026-07-28 15:30:00",
    "acceptanceAuditTime": "2026-07-28 16:00:00",
    "rejectReason": "验收凭证缺少商户盖章",
    "fileCount": 2,
    "files": [
      {
        "fileId": "2071000000000000201",
        "fileName": "acceptance-report.pdf",
        "fileUrl": "https://oss.example.com/merchant-acceptance-2071000000000000002-file-1.pdf"
      },
      {
        "fileId": "2071000000000000202",
        "fileName": "acceptance-detail.xlsx",
        "fileUrl": "https://oss.example.com/merchant-acceptance-2071000000000000002-file-2.xlsx"
      }
    ]
  },
  "timestamp": 1785225600000,
  "requestId": "req_example",
  "encrypted": false,
  "signature": "example-signature"
}

4.27.3 响应字段

字段	类型	说明
settlementId	String	结算主单 ID
settlementNo	String	平台结算单号
acceptanceStatus	Integer	当前验收状态：0-未提交、1-审核中、2-审核通过、3-审核失败；其他整数原样返回并由状态描述标记为“未知”
acceptanceStatusDesc	String	当前验收状态说明
acceptanceSubmitTime	String / null	最近一次提交时间；尚未提交时为 null
acceptanceAuditTime	String / null	最近一次审核时间；尚未审核时为 null
rejectReason	String / null	最近一次审核失败原因；非审核失败状态时为 null
fileCount	Integer	本次查询返回的文件数；通常为最近一次提交文件数，历史兼容场景为该结算单遗留验收文件数
files	Array	通常为最近一次提交的文件列表；若旧数据尚未按审核记录绑定，则兼容返回该结算单遗留的验收文件集合
files[].fileId	String	平台文件 ID
files[].fileName	String	文件名
files[].fileUrl	String	平台转存后的文件访问地址，与商户后台 lg_file.file_url 访问语义一致；访问有效期沿用平台现有存储配置

结算单尚无验收记录时，接口仍返回成功，其中 acceptanceStatus=0、时间和驳回原因为 null、fileCount=0、files=[]。

若 acceptanceStatus 返回 0 至 3 之外的整数，表示平台存量数据状态异常，acceptanceStatusDesc 返回“未知”。调用方不应自行推断该状态的业务含义，提交接口会按验收状态异常处理。

4.27.4 与后续结算发放的关系

• 只有历史结算单已发放完成、successCount>0 且存在完成时间时，才参与后续发放检查。
• acceptanceStatus=1 或 2 视为验收有效，不拦截后续发放。
• acceptanceStatus=0、3、null 或其他状态，仅在从历史结算完成时间起已超过配置天数时才拦截。
• 交付物比率不参与发放判断。

查询接口可能返回 40008-参数验证失败、40303-结算单不存在、40312-无权操作该结算单 或 50000-系统内部错误。

五、安全设计

5.1 认证机制

所有接口调用都需要在请求头中携带认证参数：

参数名	类型	必填	说明
X-App-Id	String	是	应用 ID
X-Timestamp	String	是	毫秒时间戳，建议 5 分钟内有效
X-Nonce	String	是	随机字符串，用于防重放
X-Sign	String	是	请求签名
X-Encrypt-Type	String	POST 请求是	当前按 AES 对接

5.1.1 请求签名算法

商户需要使用 HMAC-SHA256 对请求进行签名。

签名参与参数：

• timestamp
• nonce
• body（POST 请求时为加密后的完整请求体字符串；GET 请求无 body 时不参与）

POST 请求示例签名串：

body={"encryptedData":"..."}&nonce=abc123&timestamp=1742891000000

GET 请求示例签名串：

nonce=abc123&timestamp=1742891000000

签名公式：

signature = HMAC_SHA256(appSecret, signString).toLowerCase()

5.1.2 响应签名算法

响应数据为明文返回，但带签名。

商户收到响应后，建议验证响应签名，以确保：

• 数据未被篡改
• 响应确实来自平台

建议商户统一封装一层 SDK 或网关能力，至少包含：

• 请求头生成
• 时间戳和随机数生成
• 签名串构造
• AES 加解密
• 响应验签
• requestId 透传日志

5.2 数据加密

5.2.1 加密方式

当前 API 商户接入文档默认按 AES 方式对接。

说明：

• POST 请求业务数据需要加密
• GET 请求 URL 参数不加密
• 响应数据不加密，但带签名

5.2.2 请求数据格式

AES 模式下，请求体通常为：

{
  "encryptedData": "Base64编码的密文"
}

5.2.3 响应数据格式

响应统一为明文 JSON + 签名：

{
  "code": 0,
  "message": "成功",
  "data": {},
  "timestamp": "1742891000000",
  "requestId": "req_xxx",
  "signature": "xxxx"
}

5.2.4 安全建议

• 商户应在服务端生成签名，不建议在前端直接持有 AppSecret
• 回调验签逻辑应和主动请求验签逻辑同等对待
• X-Timestamp 超时、nonce 重复、签名不匹配的请求都应视为非法请求
• 商户不应把身份证、活体材料、结算收款信息等敏感数据以明文方式打印到业务日志中
• 如需保存回调原文，建议进行字段脱敏

5.3 权限控制

• 商户只能访问自己名下的数据
• 项目、结算单、交付物、发票都存在归属校验
• 商户在接入时不应假设“知道一个 ID 就能查询到数据”
• 若商户内部存在多业务线或多系统共享同一套凭证，建议在接入层自行增加业务隔离和审计日志

六、环境说明

6.1 环境配置

环境类型	API地址	用途	注意事项
测试环境	https://s.qa.gaosiqihui.com/merchantapi/v2	功能测试、联调测试	数据仅用于测试
生产环境	https://s.gaosiqihui.com/merchantapi/v2	正式业务	请使用真实商户凭证

建议商户在环境切换时同步检查以下配置：

• AppId / AppSecret / AESKey
• 回调地址
• IP 白名单
• 默认 projectId
• 日志级别和脱敏策略

七、异常处理

7.1 通用错误码

错误码	说明	处理建议
0	成功	-
40001	缺少必要认证参数	检查请求头
40002	请求已过期	检查时间戳
40003	无效的 AppId	检查 AppId
40004	客户端已被禁用	联系平台
40005	签名验证失败	检查签名算法和密钥
40006	IP 地址未授权	检查客户端 IP 白名单
40007	数据解密失败	检查 AES 密钥和加密方式
40008	参数验证失败	检查请求体格式和字段类型
40009	请求频率超限	降低请求频率后重试
40010	Nonce 重复	使用新的随机串
40011	渠道商客户端需要指定商户 ID	检查渠道商客户端配置
40012	渠道商客户端商户未绑定	联系平台检查绑定关系
40602	商户不存在	检查商户配置
40603	商户状态异常，无法访问 API	联系平台处理商户状态
50000	系统内部错误	稍后重试
50001	业务处理异常	查看 message 后重试或联系平台

处理建议：

• 40001-40012 通常属于接入层问题，应先检查请求头、签名、加密、时间戳和客户端配置。
• 40602-40603 属于商户或客户端配置问题，应联系平台确认商户配置状态。
• 50000-50001 不建议立即高频重试，建议保留 requestId 后联系平台排查。

7.2 业务异常码

7.2.1 项目与招募相关（401xx）

错误码	说明
40101	项目不存在
40102	项目已结束
40105	项目未配置收款方式
40107	项目不属于当前商户
40110	项目 ID 不能为空且必须大于 0
40113-40125	创建项目字段校验失败
40126	项目尚未审核通过
40127	回调地址不能为空
40128	回调地址长度不能超过 200 字符
40130	税地配置有误，请联系客服
40138	页码必须大于 0
40139	每页数量必须在 1-100 之间
40140	项目状态参数错误
40141	手机号和外部用户ID至少传一个
40142	手机号和外部用户ID匹配到的创客不一致
40143	生产环境回调地址必须为 HTTPS
40144	跳转地址长度不能超过 200 字符
40145	项目审核状态参数错误
40146	验收结束时间必须晚于当前时间

7.2.2 创客、招募材料与交付物基础校验（402xx）

错误码	说明
40203	必填字段缺失
40204	批量数量超限
40221	手机号格式不正确
40224	外部用户ID长度不能超过 100 字符
40229	交付文件名称不能为空
40230	交付文件名称过长
40238	交付日期不能为空
40239	交付日期格式错误
40240	交付文件列表不能为空
40241	单次最多上传 20 个交付文件
40242	交付文件地址不能为空
40243	交付文件地址必须使用 HTTPS
40253	创客尚未参与项目，不能上传交付物
40254	招募批次号不能为空
40255	招募批次号长度不能超过 64 字符
40256	招募创客列表不能为空
40257	身份证正反面图片必须同时传入
40259	同一请求内 platformUserId 不能重复
40262	同一招募任务请求参数不一致
40263	同一请求内手机号不能重复
40264	当前项目下已有进行中的招募任务

7.2.3 结算相关（403xx）

错误码	说明
40301	商户结算单号重复
40303	结算单或关联记录不存在
40312	无权操作当前结算相关数据
40313	结算明细或交付物明细不存在
40316-40334	创建结算单字段校验失败
40335	当前结算单打款失败，请勿再次操作
40338	验收凭证正在审核，不可重复提交
40339	验收凭证已审核通过，不可再次提交
40340	验收状态异常，暂不可提交
40341	存在已超过平台配置期限且验收凭证无效的历史结算单

7.2.4 文件与交付物相关（404xx）

错误码	说明
40403	文件数量超限
40404	不支持的文件格式
40401	文件实际大小超过 20 MiB

7.2.5 资格与额度相关

部分额度场景不通过顶层错误码表达，而是通过业务字段表达：

字段	含义
eligible=false	当前不具备可结算资格
reasonCode=MAKER_NOT_FOUND	未找到创客
reasonCode=NOT_IN_PROJECT	未加入项目
reasonCode=QUALIFICATION_NOT_READY	未完成税地资格

说明：

这类情况不代表接口失败，而代表“业务上当前不可继续结算”。
商户应把它们当作可展示、可流转的业务状态，而不是统一当作系统异常处理。

7.2.6 发票相关（600xx）

错误码	说明
60001	申请开票金额超过当前商户已发放成功且未开票金额
60002	发票不存在
60003	当前商户已发放成功且未开票金额为 0

说明：

• 当前部分发票业务校验仍通过 50001 + message 返回具体原因，例如“结算单不属于当前商户/项目”“结算单开票中或已开票”。
• 接入方若需要稳定分支处理，应优先按独立错误码处理；若收到 50001，再结合 message 做排查和兜底提示。

7.3 系统异常码（5xxxx）

错误码	说明	处理建议
50000	系统内部错误	稍后重试
50001	业务处理异常	结合 message 排查

八、测试接口

8.1 加密测试接口

接口说明

用于验证商户侧签名、AES 加密、服务端解密和响应签名链路。

请求地址

POST /merchantapi/v2/test/crypto

请求参数（需加密）

原始业务数据：

{
  "message": "Hello World! 测试V2加密功能"
}

加密请求体示例：

{
  "encryptedData": "U2FsdGVkX1+..."
}

响应参数（明文+签名）

{
  "code": 0,
  "message": "成功",
  "data": {
    "originalMessage": "Hello World! 测试V2加密功能",
    "encryptionInfo": "AES加密方案"
  },
  "timestamp": "1742891000000",
  "requestId": "req_xxx",
  "signature": "xxxx"
}

使用说明

1. 先确认请求签名正确。
2. 再确认服务端能成功解密请求体。
3. 最后确认商户侧能正常验证响应签名。
4. 该接口通过后，再进入业务接口联调。

错误码说明

错误码	说明
40007	解密失败
40008	参数验证失败
50000	系统处理异常

九、注意事项

1. 多项目场景请始终显式传入 projectId
   默认项目兜底适合单项目商户；一旦商户存在多项目并行，建议所有关键接口都显式传 projectId。

2. 招募同步返回不是最终结果
   accepted=true 只代表平台接受了任务。商户必须处理异步回调，才能知道是否生成签约链接、是否已签约、为什么失败。

3. 历史签约能否复用，取决于是否覆盖当前项目的结束时间要求
   当前口径不是“签过就算”，而是“历史合同是否仍覆盖 check_date_end + 1个月 的要求”。

4. platformUserId 应作为商户范围内稳定唯一的业务标识
   不建议在正常招募过程中反复更换同一创客的 platformUserId。误绑场景应通过解绑接口处理。

5. 额度为 0 不一定是接口异常
   在额度接口中，创客不存在、未入项、未完成资格，都会以 code=0 返回，只是在 eligible / reasonCode / eligibleDesc 中体现业务结论。

6. 交付物接口只接受 HTTPS URL
   商户不需要再上传 Base64 文件内容，但必须保证 URL 在平台处理时可以访问，且文件内容与业务描述一致。

7. 账户摘要和账户主数据不是同一口径
   项目详情中的账户余额用于项目视角展示，企业账户接口才是账户维度的主要查询入口。

8. 联调和问题排查时请保留 requestId
   一旦出现加密、签名、业务状态不一致等问题，requestId 是平台排查的第一关键信息。

附录：错误码说明

以下错误码按当前代码定义整理，若存在重复码、历史兼容码或命名与编码不一致的情况，以服务端实际返回为准。

特殊说明：

• 40214 在当前代码中同时对应 MAKER_ID_TYPE_INVALID 和 MAKER_ID_NUMBER_REQUIRED
• ERROR_423 当前源码中的实际错误码定义为 403

1. 系统级别错误

错误码	常量名	说明
429	LIMIT_ERROR	请求过于频繁，请稍后再试
404	ERROR_404	未知的数据404
500	ERROR_500	系统错误500

2. 业务级别错误

错误码	常量名	说明
1000	BUSINESS_ERROR	业务错误

3. 认证级别错误

错误码	常量名	说明
1002	CREATE_DTO_ERROR	创建DTO错误
2001	TOKEN_EXPIRE_ERROR	Token过期或异常

4. 业务认证补充错误

错误码	常量名	说明
3001	MAKER_UNCERTIFIED_ERROR	创客未认证异常
3002	MAKER_HAS_UNSIGNED_CONTRACT_ERROR	创客存在未签约合同
3003	MAKER_CONTRACT_NOT_SIGNED_ERROR	创客未在该税源地完成签约
3404	PROJECT_NOT_FOUND	项目不存在
3405	TAX_NOT_FOUND	项目关联的税地不存在
3100	TOKEN_EXPIRED	Token已过期

5. 商户API通用错误码（400xx）

错误码	常量名	说明
40000	API_PARAM_ERROR	参数错误
40001	API_AUTH_MISSING	缺少必要的认证参数
40002	API_REQUEST_EXPIRED	请求已过期
40003	API_INVALID_APP_ID	无效的AppId
40004	API_CLIENT_DISABLED	客户端已被禁用
40005	API_SIGNATURE_FAILED	签名验证失败
40006	API_IP_NOT_AUTHORIZED	IP地址未授权
40007	API_DECRYPT_FAILED	数据解密失败
40008	API_VALIDATION_FAILED	参数验证失败
40009	API_RATE_LIMIT_EXCEEDED	请求频率超限
40010	API_NONCE_DUPLICATE	Nonce重复
40011	API_NEED_MERCHANT_ID	渠道商客户端需要指定商户ID
40012	API_DISTRIBUTOR_MERCHANT_NOT_BIND	渠道商-商户未绑定

6. 项目相关（401xx）

错误码	常量名	说明
40101	PROJECT_NOT_EXISTS	项目不存在
40102	PROJECT_DISABLED	项目已结束
40103	PROJECT_QUOTA_NOT_ENOUGH	项目额度不足
40104	PROJECT_TAX_NOT_CONFIGURED	项目未配置税地
40105	PROJECT_PAYMENT_METHOD_NOT_CONFIGURED	项目未配置收款方式
40106	PROJECT_NO_PERMISSION	无权访问该项目
40107	PROJECT_NOT_BELONG_TO_MERCHANT	项目不属于当前商户
40108	PROJECT_RATE_NOT_CONFIGURED	项目费率配置不完整
40109	PROJECT_PAYMENT_ACCOUNT_NOT_CONFIGURED	项目未配置支付账号
40110	PROJECT_ID_REQUIRED	项目ID不能为空
40111	PROJECT_INFO_LIST_REQUIRED	项目信息列表不能为空
40112	PROJECT_INFO_LIST_TOO_LONG	单次最多支持50个项目信息
40113	PROJECT_NAME_REQUIRED	项目名称不能为空
40114	PROJECT_NAME_TOO_LONG	项目名称过长，最长100字符
40115	PROJECT_CONTENT_REQUIRED	项目内容不能为空
40116	PROJECT_CONTENT_TOO_LONG	项目内容需在1000字内
40117	PROJECT_CALCULATION_TYPE_REQUIRED	计价方式不能为空
40118	PROJECT_CALCULATION_TYPE_INVALID	计价方式错误
40119	PROJECT_BUDGET_REQUIRED	项目预算不能为空
40120	PROJECT_MAKER_NUMBER_REQUIRED	招募创客数不能为空
40121	PROJECT_SETTLEMENT_RULE_REQUIRED	结算规则不能为空
40122	PROJECT_SETTLEMENT_RULE_TOO_LONG	结算规则过长，最长100字符
40123	PROJECT_VERIFY_REQUIRED	验收标准不能为空
40124	PROJECT_VERIFY_TOO_LONG	验收标准需在1000字内
40125	PROJECT_REMARK_TOO_LONG	备注过长，最长200字符
40126	PROJECT_NOT_AUDITED	项目尚未审核通过
40127	NOTIFY_URL_REQUIRED	异步通知地址不能为空
40128	NOTIFY_URL_TOO_LONG	回调地址长度不能超过200字符
40129	PROJECT_PARAMS_REQUIRED	创客身份证号和外部用户ID至少填写一个
40130	PROJECT_TAX_COMPANY_REQUIRED	税地配置有误，请联系客服
40131	PROJECT_CALCULATION_DESC_REQUIRED	计价方式描述不能为空
40132	PROJECT_CALCULATION_DESC_TOO_LONG	计价方式描述需在500字内
40133	PROJECT_TYPE_INVALID	项目类型参数错误，仅支持0-派单项目
40134	PROJECT_CHECK_DATE_START_REQUIRED	验收开始时间不能为空
40135	PROJECT_CHECK_DATE_END_REQUIRED	验收结束时间不能为空
40136	PROJECT_CHECK_DATE_RANGE_INVALID	验收开始时间不能晚于验收结束时间
40137	PROJECT_CONTENT_CONTAINS_SENSITIVE_WORD	项目内容包含违禁词
40138	PROJECT_PAGE_INVALID	页码必须大于0
40139	PROJECT_PAGE_SIZE_INVALID	每页数量必须在1-100之间
40140	PROJECT_STATUS_INVALID	项目状态参数错误，仅支持0-未开始、1-进行中或2-已结束
40141	PROJECT_RECRUIT_QUERY_PARAM_INVALID	手机号和外部用户ID至少传一个
40142	PROJECT_RECRUIT_QUERY_IDENTIFIER_CONFLICT	手机号和外部用户ID匹配到的创客不一致
40143	CALLBACK_URL_NOT_HTTPS	回调地址必须为HTTPS链接
40144	REDIRECT_URL_TOO_LONG	跳转地址长度不能超过200字符
40145	PROJECT_AUDIT_STATUS_INVALID	项目审核状态参数错误，仅支持0-未审核、1-已审核或2-已驳回
40146	PROJECT_CHECK_DATE_END_MUST_BE_FUTURE	验收结束时间必须晚于当前时间
40147	PROJECT_QUOTA_MAKER_NOT_FOUND	未找到创客
40148	PROJECT_QUOTA_MAKER_NOT_IN_PROJECT	创客未加入项目
40149	PROJECT_QUOTA_QUALIFICATION_NOT_READY	创客未完成签约资格

7. 创客相关（402xx）

错误码	常量名	说明
40201	MAKER_ID_CARD_FORMAT_ERROR	身份证号格式错误
40202	MAKER_PHONE_FORMAT_ERROR	手机号格式错误
40203	MAKER_REQUIRED_FIELD_MISSING	必填字段缺失
40204	MAKER_BATCH_LIMIT_EXCEEDED	批量数量超限
40205	MAKER_INFO_DUPLICATE	创客信息重复
40206	MAKER_NOT_EXISTS	创客不存在
40207	MAKER_NOT_CERTIFIED	创客未实名认证
40208	MAKER_DISABLED	创客已被冻结
40209	MAKER_QUOTA_NOT_ENOUGH	创客额度不足
40210	MAKER_NOT_BELONG_TO_MERCHANT	创客未关联商户
40211	MAKER_NAME_REQUIRED	创客姓名不能为空
40212	MAKER_NAME_TOO_LONG	创客姓名长度不能超过50字符
40213	MAKER_ID_TYPE_REQUIRED	证件类型不能为空
40214	MAKER_ID_TYPE_INVALID	证件类型仅支持ID_CARD或PASSPORT
40214	MAKER_ID_NUMBER_REQUIRED	证件号码不能为空
40215	MAKER_ID_NUMBER_LENGTH_INVALID	证件号码长度需在6-32之间
40216	MAKER_COUNTRY_REQUIRED	国家或地区不能为空
40217	MAKER_COUNTRY_LENGTH_INVALID	国家或地区代码长度需在2-20之间
40218	MAKER_ADDRESS_REQUIRED	地址不能为空
40219	MAKER_ADDRESS_TOO_LONG	地址长度不能超过200字符
40220	MAKER_PHONE_REQUIRED	联系电话不能为空
40221	MAKER_PHONE_FORMAT_INVALID	联系电话格式不正确
40222	MAKER_PLATFORM_NAME_TOO_LONG	平台名称长度不能超过100字符
40223	MAKER_PLATFORM_USER_NAME_TOO_LONG	平台用户名长度不能超过100字符
40224	MAKER_PLATFORM_USER_ID_TOO_LONG	外部用户ID长度不能超过100字符
40225	MAKER_INFO_LIST_REQUIRED	列表不能为空
40226	MAKER_INFO_LIST_TOO_LONG	单次最多支持50个创客信息
40227	MAKER_ID_TYPE_INVALID2	证件类型暂时仅支持ID_CARD
40228	MAKER_ID_REQUIRED	makerId不能为空
40229	MAKER_CONTRACT_FILENAME_REQUIRED	fileName不能为空
40230	MAKER_CONTRACT_FILENAME_TOO_LONG	文件名长度不能超过200
40231	MAKER_CONTRACT_FILETYPE_REQUIRED	fileType不能为空
40232	MAKER_CONTRACT_FILETYPE_INVALID	文件类型仅支持pdf/jpg/jpeg/png
40233	MAKER_CONTRACT_FILESIZE_REQUIRED	fileSize不能为空
40234	MAKER_CONTRACT_FILESIZE_TOO_LARGE	文件大小不能超过2MB
40235	MAKER_CONTRACT_FILEMD5_REQUIRED	fileMd5不能为空
40236	MAKER_CONTRACT_FILEMD5_INVALID	文件MD5长度需在16-64之间
40237	MAKER_CONTRACT_FILECONTENT_REQUIRED	fileContent不能为空
40238	MAKER_DELIVERY_DATE_REQUIRED	deliveryDate不能为空
40239	MAKER_DELIVERY_DATE_FORMAT_ERROR	deliveryDate格式不正确，应为yyyy-MM-dd
40240	MAKER_DELIVERY_FILES_REQUIRED	files不能为空
40241	MAKER_DELIVERY_FILES_TOO_MANY	单次最多上传20个文件
40242	MAKER_DELIVERY_FILEURL_REQUIRED	fileUrl不能为空
40243	MAKER_DELIVERY_FILEURL_NOT_HTTPS	文件URL必须为HTTPS链接
40244	MAKER_BANK_CARD_VERIFICATION_FAILED	四要素认证失败；银行卡号、账户名、创客实名身份证或银行卡预留手机号不匹配
40245	MAKER_REAL_NAME_VERIFICATION_FAILED	实名认证失败
40246	MAKER_NAME_NOT_EQ	创客姓名与识别信息不一致
40247	MAKER_ID_NUMBER_NOT_EQ	创客身份证号码与识别信息不一致
40248	MAKER_ID_CARD_INVALID	身份证已失效
40249	MAKER_ID_CARD_MISSING	证件照缺失
40250	MAKER_PLATFORM_MISSING	平台相关信息缺失
40251	MAKER_PLATFORM_USER_ID_REQUIRED	外部用户ID不能为空
40252	MAKER_LIVENESS_FAILED	活体发起失败，请重试
40253	MAKER_DELIVERY_TASK_NOT_JOINED	创客未参与该项目，不能上传交付物
40254	RECRUIT_BATCH_NO_REQUIRED	招募批次号不能为空
40255	RECRUIT_BATCH_NO_TOO_LONG	招募批次号长度不能超过64字符
40256	RECRUIT_MAKERS_REQUIRED	招募创客列表不能为空
40257	RECRUIT_OBVERSE_REVERSE_REQUIRED_TOGETHER	身份证正反面图片必须同时传入
40258	RECRUIT_LIVENESS_REQUIRED_TOGETHER	活体照片和活体视频必须同时传入
40259	RECRUIT_DUPLICATE_PLATFORM_USER_ID	同一请求内外部用户ID不能重复
40260	RECRUIT_TASK_NOT_EXISTS	招募任务不存在
40261	RECRUIT_OCR_FAILED	OCR校验失败
40262	RECRUIT_TASK_REQUEST_CONFLICT	同一招募任务的请求参数不一致
40263	RECRUIT_DUPLICATE_PHONE	同一请求内手机号不能重复
40264	RECRUIT_ACTIVE_TASK_EXISTS	该创客在当前项目下已有进行中的招募任务
40265	MAKER_INFO_LIST_REQUIRED_ONLY_ONE	查询自由职业者信息手机号或外部用户ID列表只能传一种

8. 结算相关（403xx）

错误码	常量名	说明
40300	SETTLEMENT_CUSTOM_ERROR	结算自定义错误
40301	SETTLEMENT_MERCHANT_NO_DUPLICATE	商户结算单号重复
40302	SETTLEMENT_DETAIL_NO_DUPLICATE	商户明细号重复
40303	SETTLEMENT_NOT_EXISTS	结算单不存在
40304	SETTLEMENT_STATUS_NOT_ALLOW	当前结算单未完成，请勿提前操作
40305	SETTLEMENT_AMOUNT_INVALID	结算金额无效
40306	SETTLEMENT_DETAIL_EMPTY	结算明细为空
40307	SETTLEMENT_DETAIL_LIMIT_EXCEEDED	结算明细超限
40308	SETTLEMENT_PAYMENT_METHOD_NOT_SUPPORTED	收款方式不支持
40309	SETTLEMENT_PAYMENT_ACCOUNT_INVALID	收款账号无效
40310	SETTLEMENT_ALREADY_PAID	结算单已支付
40311	SETTLEMENT_ALREADY_CANCELLED	结算单已取消
40312	SETTLEMENT_NO_PERMISSION	无权操作该结算单
40313	SETTLEMENT_DETAIL_NOT_EXISTS	结算单明细尚未生成
40314	SETTLEMENT_PAYMENT_ACCOUNT_NOT_BELONG_TO_MAKER	支付账户不属于该创客
40315	SETTLEMENT_PAYMENT_ACCOUNT_TYPE_MISMATCH	支付账户类型不匹配
40316	SETTLEMENT_NO_REQUIRED	商户结算单号不能为空
40317	SETTLEMENT_NO_LENGTH_INVALID	商户结算单号长度必须在1-64个字符之间
40318	SETTLEMENT_NO_INVALID	商户结算单号仅支持字母、数字、下划线、横线
40319	RECEIVE_METHOD_REQUIRED	收款方式不能为空
40320	RECEIVE_METHOD_INVALID	收款方式必须为bank、alipay或wechat
40321	SETTLEMENT_DETAIL_TOO_MANY	结算明细数量不能超过200条
40322	SETTLEMENT_REMARK_TOO_LONG	结算备注长度不能超过200字符
40323	SETTLEMENT_DETAIL_NO_REQUIRED	商户结算明细号不能为空
40324	SETTLEMENT_DETAIL_NO_INVALID	商户结算明细号仅支持字母、数字、下划线、横线
40325	SETTLEMENT_DETAIL_NO_LENGTH_INVALID	商户结算明细号长度需在1-64之间
40326	SETTLEMENT_DETAIL_AMOUNT_REQUIRED	结算金额不能为空
40327	SETTLEMENT_DETAIL_AMOUNT_INVALID	结算金额格式错误
40328	SETTLEMENT_DETAIL_AMOUNT_NEGATIVE	结算金额必须大于等于1元
40337	SETTLEMENT_DETAIL_AMOUNT_EXCEED_LIMIT	结算金额不能超过300000元
40329	SETTLEMENT_PAYMENT_ACCOUNT_REQUIRED	收款账户信息不能为空
40330	SETTLEMENT_ACCOUNT_NO_REQUIRED	收款账号不能为空
40331	SETTLEMENT_ACCOUNT_NO_LENGTH_INVALID	收款账号长度需在5-64之间
40332	SETTLEMENT_ACCOUNT_NAME_TOO_LONG	账户名长度不能超过50字符
40333	SETTLEMENT_PHONE_INVALID	预留手机号格式错误
40334	SETTLEMENT_DETAIL_ID_REQUIRED	detailId不能为空
40335	SETTLEMENT_STATUS_FAIL	当前结算单打款失败，请勿再次操作
40336	SETTLEMENT_NOTIFY_URL_TOO_LONG	回调地址长度不能超过200字符
40338	SETTLEMENT_ACCEPTANCE_REVIEWING	验收凭证正在审核，不可重复提交
40339	SETTLEMENT_ACCEPTANCE_APPROVED	验收凭证已审核通过，不可再次提交
40340	SETTLEMENT_ACCEPTANCE_STATUS_INVALID	验收状态异常，暂不可提交
40341	SETTLEMENT_ACCEPTANCE_OVERDUE	历史结算单验收凭证已超过平台配置期限，暂不可继续发放

9. 交付物相关（404xx）

错误码	常量名	说明
40401	FILE_SIZE_EXCEED_ERROR	文件大小超限
40402	FILE_FORMAT_NOT_SUPPORTED	文件格式不支持
40403	FILE_COUNT_EXCEED_ERROR	文件数量超限
40404	FILE_TYPE_NOT_SUPPORTED_ERROR	不支持的文件格式
40405	DELIVERABLE_MAKER_NOT_FOUND	创客不存在
40406	DELIVERABLE_PROJECT_NOT_FOUND	项目不存在
40407	DELIVERABLE_SETTLEMENT_NOT_FOUND	结算单不存在

10. 收入申报相关（405xx）

错误码	常量名	说明
40501	INCOME_MAKER_NOT_FOUND	创客不存在
40502	INCOME_DATA_FORMAT_ERROR	申报数据格式错误
40503	INCOME_PERIOD_INVALID	申报期间无效
40504	INCOME_AMOUNT_FORMAT_ERROR	金额格式错误
40505	INCOME_DATE_FORMAT_ERROR	日期格式错误
40506	INCOME_RECORD_EXISTS	申报记录已存在
40507	INCOME_DATA_MISSING	申报数据缺失
40508	INCOME_BATCH_LIMIT_ERROR	批量数量超限

11. 商户相关（406xx）

错误码	常量名	说明
40601	MERCHANT_EXIST_ERROR	商户已存在
40602	MERCHANT_NOT_EXISTS	商户不存在
40603	MERCHANT_STATUS_INVALID	商户状态异常，无法访问API

12. 额度相关（408xx）

错误码	常量名	说明
40801	QUOTA_MONTH_NOT_ENOUGH	月度额度不足
40802	QUOTA_SINGLE_AMOUNT_EXCEEDED	单笔金额超限
40803	QUOTA_DAY_LIMIT_EXCEEDED	日累计额度超限
40804	QUOTA_MAKER_MONTH_NOT_ENOUGH	创客月度额度不足
40805	QUOTA_PAYMENT_METHOD_NOT_ENOUGH	收款方式额度不足
40806	QUOTA_YEAR_EXCEEDED	年度额度超限
40807	QUOTA_CALCULATION_ERROR	额度计算异常

13. 支付相关（409xx）

错误码	常量名	说明
40901	PAYMENT_CHANNEL_ERROR	支付渠道异常
40902	PAYMENT_BANK_ACCOUNT_INVALID	银行账号无效
40903	PAYMENT_ALIPAY_ACCOUNT_INVALID	支付宝账号无效
40904	PAYMENT_WECHAT_ACCOUNT_INVALID	微信账号无效
40905	PAYMENT_NAME_MISMATCH	收款人姓名不匹配
40906	PAYMENT_PROCESSING	支付处理中
40907	PAYMENT_FAILED	支付失败
40908	PAYMENT_BANK_MAINTENANCE	银行维护中
40909	PAYMENT_AMOUNT_EXCEEDED	支付金额超限

14. 系统异常码（5xxxx）

错误码	常量名	说明
50000	SYSTEM_INTERNAL_ERROR	系统内部错误
50001	SYSTEM_BUSINESS_ERROR	业务处理异常
50002	SYSTEM_CACHE_ERROR	缓存服务异常
50003	SYSTEM_THIRD_PARTY_TIMEOUT	第三方服务超时
50004	SYSTEM_THIRD_PARTY_ERROR	第三方服务异常
50005	SYSTEM_NETWORK_ERROR	网络异常
50006	SYSTEM_SERVICE_UNAVAILABLE	服务暂时不可用
50007	SYSTEM_MAINTENANCE	系统维护中
50099	SYSTEM_DATABASE_ERROR	数据库异常

15. 发票相关（6xxxx）

错误码	常量名	说明
60001	INVOICE_AMOUNT_EXCEEDED	申请开票金额超出当前商户已发放成功且未开票金额
60002	INVOICE_NOT_FOUND	发票不存在
60003	INVOICE_AMOUNT_ZERO	当前商户已发放成功且未开票金额为0

16. 历史通用错误码

错误码	常量名	说明
400	ERROR_400	请求参数错误400
401	ERROR_401	未授权401
403	ERROR_403	未授权403
403	ERROR_423	此账号已被锁定,请稍后再试！