商户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`	未招募	创客不存在，或存在但尚未加入当前项目
`RECRUITED_UNSIGNED`	已招募待签约	已加入当前项目，但实名、活体、签约任一未完成，或历史签约已无法覆盖当前项目要求
`RECRUITED_SIGNED`	已招募已签约	已加入当前项目，且同税地资格完整、签约仍在有效期内

1.5.4 招募异步任务状态

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

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

1.5.5 结算单状态

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

1.5.6 结算明细状态

状态码	状态描述	说明
1	待支付	明细已创建，等待支付
2	支付成功 / 已完成	当前实现中可获取回单的成功状态
3	支付失败	明细支付失败
4	拒绝支付 / 其他失败态	明细未成功完成

说明：

个别内部状态与对外接口状态描述之间存在历史兼容差异。

商户接入时，应始终以接口返回结果和本文档说明为准，不建议直接推断平台内部枚举含义。

1.5.7 交付物审核状态

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

1.5.8 发票状态

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

二、核心设计理念

2.1 项目中心化模式

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

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

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

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

先查询项目列表和项目详情

再围绕项目查询招募状态、发起招募、查询额度

之后围绕项目创建结算单并上传交付物

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

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

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

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

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

在招募前查询创客状态

招募后等待异步回调

结算前查询额度

结算后按明细上传交付物

结算完成后根据需要发起开票

2.3 异步招募与回调收口

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

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

同步响应负责记录“是否已受理”“是否需要立即拦截”

异步回调负责更新“签约链接是否生成”“是否已签约”“最终失败原因”

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

recruitBatchNo

projectId

platformUserId

taskId

同步受理结果

异步最终状态

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

同步 accepted=true 不代表已经签约成功，只代表该创客的任务已进入处理链路

商户前端若需要展示“可去签约”，应以 SIGN_URL_READY 回调或状态查询结果为准，而不是以同步受理结果为准

2.4 资格复用与有效期覆盖

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

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

创客是否已经加入当前项目

创客在当前项目所属税地下是否具备完整资格

历史合同的有效期是否仍能覆盖当前项目的要求

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

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：需要招募新创客

建议顺序：

先调用 POST /merchantapi/v2/projects/queryRecruitStatus

如返回未招募或待签约，再调用 POST /merchantapi/v2/projects/recruit

保存同步返回中的 taskId

等待异步回调收口最终状态

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

建议调用：

POST /merchantapi/v2/projects/makers/quota

重点确认：

eligible=true

receiveMethodQuotas[].availableQuota 足够覆盖本次结算金额

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

创建结算单：

POST /merchantapi/v2/settlements

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

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

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

查询结算单详情，确认主单状态和每条明细状态

对成功明细调用回单接口

如项目要求交付物，再按明细上传交付文件

后续按需查询企业账户和开票余额

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`	业务数据；若开启通知加密则为密文，否则为明文 JSON

3.5.3 验签与解密规则

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

校验外层 sign

如果 data 为加密串，先解密 data

再解析业务 JSON

按业务主键完成幂等更新

通知签名与普通 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/makers/quota`	查询单个创客可结算额度
批量查询创客额度	POST	`/merchantapi/v2/projects/makers/quota/batch`	批量查询创客可结算额度
上传交付物	POST	`/merchantapi/v2/projects/upload-deliverable`	上传结算明细对应交付物
查询已上传交付物	POST	`/merchantapi/v2/projects/query-deliverables`	查询结算明细下历史交付物
查询结算单列表	GET	`/merchantapi/v2/settlements`	分页查询结算单列表
查询结算单详情	GET	`/merchantapi/v2/settlements/{settlementId}`	查询结算单详情
创建结算单	POST	`/merchantapi/v2/settlements`	创建结算单
发起支付	POST	`/merchantapi/v2/settlements/{settlementId}/pay`	对已创建结算单发起支付
获取结算回单	GET	`/merchantapi/v2/settlement-details/{detailId}/receipt`	获取结算回单
查询自由职业者信息	POST	`/merchantapi/v2/makers/query`	批量查询自由职业者信息
解绑自由职业者	POST	`/merchantapi/v2/makers/unbind`	按平台用户 ID 解绑自由职业者
查询企业账户信息	GET	`/merchantapi/v2/account/queryMerchantAccountInfo`	查询企业账户列表与余额信息
查询可开票余额	GET	`/merchantapi/v2/invoice/queryAvailableInvoiceBalance`	查询按税地和税目归集的可开票余额
开票申请	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`	顶层结果码，`0` 表示接口调用成功
`message`	顶层结果描述
`data`	业务数据
`timestamp`	响应时间戳
`requestId`	平台侧请求标识，联调和问题排查时请保留
`encrypted`	当前对外响应中通常为 `false`
`signature`	响应签名，商户建议校验

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
      }
    ]
  }
}

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": "创建成功，待审核"
  }
}

4.4.4 关键说明

创建成功不代表项目立即可用。

项目必须审核通过后，才能用于招募、额度和结算。

4.4.5 项目审核结果通知

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

触发时机：

项目审核通过

项目审核驳回

外层通知包：

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

业务 payload：

项目审核通知的业务字段与“查询项目详情接口”的响应字段保持一致，商户可直接复用项目详情的数据结构进行解析。
其中最需要重点关注的字段包括：

字段	说明
`projectId`	项目 ID
`projectName`	项目名称
`auditStatus`	审核状态：`0/1/2`
`auditStatusDesc`	审核状态描述
`rejectReason`	驳回原因；审核通过时通常为空
`status`	项目状态
`statusDesc`	项目状态描述

处理建议：

项目审核通知建议以 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,
    "serviceRate": 1.50,
    "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
  }
}

4.5.4 关键说明

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_UNSIGNED",
    "statusDesc": "已招募待签约"
  }
}

4.6.4 关键说明

该接口是“招募前置判断接口”，适合用于商户前端展示“去招募”“去签约”“已完成”之类的状态。

平台先判断创客是否已经加入当前项目，再判断同税地资格是否完整。

即使创客在别的项目下同税地已经签约，只要还没加入当前项目，这里仍返回 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
      }
    ]
  }
}

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。

若客户端配置了回调加密，则 data 不是明文 JSON，而是加密后的字符串；商户需要先解密，再解析业务字段。

解密后的业务数据核心字段如下：

字段	说明
`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`	任务完成时间

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

先校验外层回调签名

如 data 为加密数据，先解密 data

再以 taskId 或 recruitBatchNo + platformUserId 做幂等更新

SIGN_URL_READY 时更新待签约状态并向前端暴露签约入口

SIGNED 时更新为已签约可结算，并记录 contractId

FAILED 时记录 errorCode / errorMessage 并允许人工或业务重试

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

平台在处理招募任务时直接命中“已签约”结果，例如命中当前项目历史有效签约或同税地资格复用

平台先返回 SIGN_URL_READY，创客通过签约链接完成签约后，平台再以 SIGNED 收口最终结果

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

4.8 查询创客额度接口

4.8.1 接口说明

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

4.8.2 请求参数（需加密）

POST /merchantapi/v2/projects/makers/quota

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

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

4.8.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
      }
    ]
  }
}

4.8.4 关键说明

创客不存在、未入项、未完成资格时，不一定返回业务错误，而是直接返回：

eligible=false

reasonCode

eligibleDesc

0 额度

这类返回并不表示接口失败，而是表示“当前创客在当前项目下暂不具备结算条件”。

商户前端若需要展示失败原因，建议直接使用 eligibleDesc，不要自行硬编码推断。

totalAvailableQuota 是摘要值，适合快速判断“当前是否还有额度”；真正落单时仍应结合具体 receiveMethodQuotas[].availableQuota 判断。

单方式额度口径：

availableQuota = min(personalAvailableQuota, sharedAvailableQuota)

4.9 批量查询创客额度接口

4.9.1 接口说明

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

4.9.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.9.3 响应参数（明文+签名）

顶层返回：

projectId

currentMonth

totalCount

eligibleCount

ineligibleCount

results

results[] 中除单创客额度字段外，还额外返回：

字段	说明
errorCode	单条结果码
errorMessage	单条结果描述

4.9.4 关键说明

顶层通常仍返回 code=0。

单条结果中的参数错误、标识冲突、创客不存在、未入项、未具备资格，会通过单条 errorCode / errorMessage 表达。

商户在做批量导入、批量结算前预检时，建议优先使用该接口，而不要循环调用单创客额度接口。

对于批量接口，商户应按单条结果处理成功与失败，不能只看顶层 code。

4.10 上传交付物接口

4.10.1 接口说明

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

4.10.2 请求参数（需加密）

POST /merchantapi/v2/projects/upload-deliverable

{
  "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	是	HTTPS 文件地址

4.10.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"
  }
}

4.10.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.11 查询已上传交付物接口

4.11.1 接口说明

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

4.11.2 请求参数（需加密）

POST /merchantapi/v2/projects/query-deliverables

{
  "detailId": "2034461359380058114"
}

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

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

返回字段包括：

detailId

totalCount

deliverables[].deliverableId

deliverables[].deliverableNo

deliverables[].deliveryDate

deliverables[].description

deliverables[].verifyStatus

deliverables[].verifyStatusDesc

deliverables[].rejectReason

deliverables[].uploadTime

deliverables[].verifyTime

deliverables[].fileCount

deliverables[].files[]

4.11.4 关键说明

结果按上传时间倒序返回。

若当前明细没有任何交付物记录，接口仍然成功返回，totalCount=0。

商户若只需要最新一次上传记录，建议取返回列表的第一条，而不要自行假定同一明细只会有一条交付物记录。

4.12 查询结算单列表接口

4.12.1 接口说明

分页查询结算单列表。

4.12.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-dd`
endTime	String	否	结束日期，格式 `yyyy-MM-dd`，且不能晚于当前日期

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

返回字段：

total

page

size

pages

list[]

list[] 中常见字段：

settlementId

settlementNo

projectId

projectName

taxCompanyName

receiveMethod

totalAmount

totalCount

status

statusDesc

createTime

paymentTime

completeTime

successCount

failCount

4.12.4 关键说明

该接口适合用于商户后台分页检索结算单，不建议用于查询单笔实时支付结果。

联调阶段如果查询不到结果，建议优先核对 projectId、状态过滤条件、时间范围和结算单号是否一致。

当前实现中，若查询结果为空，接口会直接返回业务异常“查询结果不存在”，而不是返回空列表。

当同时传 startTime 和 endTime 时，要求 startTime <= endTime。

endTime 不能大于当前日期。

4.13 查询结算单详情接口

4.13.1 接口说明

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

4.13.2 请求参数

GET /merchantapi/v2/settlements/{settlementId}

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

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

响应常见字段：

settlementId

settlementNo

projectId

projectName

taxCompanyName

receiveMethod

totalAmount

totalCount

status

statusDesc

createTime

paymentTime

completeTime

remark

successCount

failCount

details[]

details[] 常见字段：

detailId

detailNo

merchantDetailNo

amount

idCardHash

status

paymentTime

failureReason

remark

4.13.4 关键说明

明细中返回的是身份证哈希值，而不是明文身份证号。

若商户需要对账，应优先使用 merchantDetailNo 作为商户侧明细主键，不建议依赖身份证相关字段做关联。

4.14 创建结算单接口

4.14.1 接口说明

创建结算单。

4.14.2 请求参数（需加密）

POST /merchantapi/v2/settlements

{
  "projectId": "2016422018623922178",
  "merchantSettlementNo": "MERCHANT_SETTLEMENT_001",
  "receiveMethod": "bank",
  "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`
remark	String	否	结算备注，最长 200
notifyUrl	String	否	异步通知地址，最长 200
details	Array	是	结算明细列表，至少 1 条，最多 200 条

单条 details[] 参数：

参数	类型	必填	说明
merchantDetailNo	String	是	商户明细号
amount	BigDecimal	是	结算金额
phone	String	否	手机号，与 `platformUserId` 至少传一个
platformUserId	String	否	平台用户 ID，与 `phone` 至少传一个
paymentAccount	Object	是	收款账户信息
remark	String	否	明细备注

paymentAccount 参数：

参数	类型	必填	说明
accountNo	String	是	收款账号
accountName	String	否	账户名
phone	String	否	预留手机号

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

响应常见字段：

settlementId

settlementNo

merchantSettlementNo

projectId

projectName

taxCompanyName

receiveMethod

totalAmount

totalCount

totalTax

totalNetAmount

status

statusDesc

createTime

remark

paymentInitiated

paymentFailureReason

details[]

4.14.4 关键说明

创建结算单前，建议商户先完成两项预检：

当前创客在项目下具备可结算资格

当前收款方式下的 availableQuota 足够覆盖结算金额

merchantSettlementNo 和 merchantDetailNo 都应由商户自行保证稳定唯一，避免幂等冲突。

在未提供 makerId 的情况下，商户至少需要保证 phone 或 platformUserId 中有一个能稳定定位到目标创客。

4.14.5 结算结果通知

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

重要：

结算结果通知地址是在“创建结算单”时确定的。

POST /merchantapi/v2/settlements/{settlementId}/pay 本身不再单独接收新的 notifyUrl。

适用场景：

创建结算单后，商户又单独调用了支付接口

商户希望通过通知而不是轮询来接收结算最终结果

外层通知包：

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

业务 payload 核心字段：

字段	说明
`settlementId`	结算单 ID
`settlementNo`	平台结算单号
`merchantSettlementNo`	商户结算单号
`projectId`	项目 ID
`receiveMethod`	收款方式
`totalAmount`	结算总金额
`totalNetAmount`	税后总金额
`totalTax`	总税费
`status`	结算单状态：`0/1/2/3`
`statusDesc`	结算状态描述
`paymentTime`	支付时间
`completeTime`	完成时间
`successCount`	成功笔数
`failCount`	失败笔数
`detailList[]`	明细结果列表

detailList[] 常见字段：

字段	说明
`detailId`	明细 ID
`detailNo`	平台明细号
`merchantDetailNo`	商户明细号
`amount`	金额
`netAmount`	税后实发金额
`status`	明细状态
`statusDesc`	明细状态描述
`failReason`	失败原因
`completeTime`	明细完成时间

处理建议：

商户建议先按 settlementId 或 merchantSettlementNo 更新主单，再按 merchantDetailNo 更新明细。

不建议仅依据同步创建响应里的 paymentInitiated=true 判断支付成功。

结算结果通知与结算详情查询应结合使用：通知负责“收口”，查询负责“补数”和“复核”。

4.15 发起支付接口

4.15.1 接口说明

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

4.15.2 请求参数（需加密）

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

{
  "confirmPay": true
}

Path 参数：

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

请求体参数（需加密）：

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

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

响应常见字段：

settlementId

settlementNo

projectId

projectName

receiveMethod

status

paymentStatus

paymentTime

expectedTime

totalAmount

totalCount

successCount

failCount

processingCount

details[]

paymentStatus 当前常见取值：

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

4.15.4 关键说明

已完成或已拒绝的结算单不能重复支付。

支付中的结算单再次发起支付时，商户应谨慎处理重试逻辑。

confirmPay 的作用是显式确认本次支付动作，建议商户仅在人工确认或流程节点明确时调用。

商户若实现自动重试，应先查询结算单详情确认当前状态，避免并发重复发起。

4.16 获取结算回单接口

4.16.1 接口说明

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

4.16.2 请求参数

GET /merchantapi/v2/settlement-details/{detailId}/receipt

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

4.16.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"
  }
}

4.16.4 关键说明

当前接口直接返回 Base64 编码的回单文件内容。

只有成功完成支付的明细才允许获取回单。

商户若需要长期留存回单，建议在收到成功结果后自行落盘或转存，不建议每次展示时重复拉取。

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

4.17.1 接口说明

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

4.17.2 请求参数（需加密）

POST /merchantapi/v2/makers/query

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

参数	类型	必填	说明
phoneNumbers	Array	否	手机号列表，最多 50 个。与 `platformUserIds` 二选一
platformUserIds	Array	否	平台用户 ID 列表，最多 50 个。与 `phoneNumbers` 二选一

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

响应主字段：

makers[]

单条 makers[] 常见字段：

makerId

name

idCard

idType

country

address

phone

platformUserId

platformName

platformUserName

status

taxCompanyQualifications

createTime

updateTime

errorCode

errorMessage

4.17.4 关键说明

该接口是查询接口，不负责保存或更新自由职业者信息。

单条查询失败时，会在单条结果中返回 errorCode / errorMessage。

phoneNumbers 和 platformUserIds 两者至少传一种，但不能同时传。

商户应根据自己的查询入口二选一：按手机号查，或按 platformUserId 查。

该接口采用“部分成功”模式，单条异常不会阻断其他条目的返回。

4.18 解绑自由职业者接口

4.18.1 接口说明

按平台用户 ID 解绑自由职业者。

4.18.2 请求参数（需加密）

POST /merchantapi/v2/makers/unbind

{
  "platformUserId": "USERID_001"
}

参数	类型	必填	说明
platformUserId	String	是	平台用户 ID

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

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

4.18.4 关键说明

该接口主要用于处理商户侧 platformUserId 异常绑定场景。

解绑属于纠错动作，不建议作为正常招募链路的一部分频繁调用。

解绑前建议先核对历史招募任务、结算记录和业务订单，避免把仍在使用中的绑定关系解除。

4.19 查询企业账户信息接口

4.19.1 接口说明

查询商户企业账户列表及其金额信息。

4.19.2 请求参数

GET /merchantapi/v2/account/queryMerchantAccountInfo

无业务请求体。

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

响应主字段：

accountList[]

单条 accountList[] 字段：

字段	说明
accountId	账户 ID
accountType	账户类型（展示字段，如银行卡/支付宝/微信支付，不建议作为稳定枚举依赖）
accountUserName	账户持有人姓名
accountUserIdCard	账户持有人身份证号
account	账户号
accountName	账户名称
bankName	开户行名称
rechargeAccount	充值账号，部分渠道或配置下可能为空
rechargeAccountName	充值账号名称，部分渠道或配置下可能为空
availableAmount	可用金额
settleAmount	结算中税后金额
otherAmount	结算中其他金额
freezeAmount	冻结金额

4.19.4 关键说明

企业账户接口是账户维度的主查询入口。

项目详情里的账户信息只是项目维度摘要，不应替代本接口。

商户若涉及充值、余额校验或财务对账，应以本接口为准。

accountType 当前返回展示值，不保证可作为长期稳定枚举使用；如需程序分支，建议不要仅依赖该字段文案。

4.19.5 充值上账通知

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

触发时机：

商户企业账户发生充值到账

平台完成上账并记录为成功后，向商户推送到账结果

回调地址来源：

非某个 API 业务接口请求参数

由平台为当前商户 API 客户端预先配置 rechargeNotifyUrl

外层通知包：

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

业务 payload：

{
  "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`	备注

处理建议：

建议以 dealId 作为上账通知的主幂等键。

商户若需要做账户余额展示，建议收到通知后仍再调用企业账户查询接口做一次余额校验。

若商户系统区分“资金到账”和“可发起结算”，建议将上账通知作为资金事件，而不要混同为结算事件。

4.20 查询可开票余额接口

4.20.1 接口说明

查询按税地和税目归集的可开票余额。

4.20.2 请求参数

GET /merchantapi/v2/invoice/queryAvailableInvoiceBalance

无业务请求体。

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

响应主字段：

taxCompanyData[]

单条 taxCompanyData[]：

字段	说明
taxCompanyId	税地公司 ID
taxCompanyName	税地公司名称
invoiceDataList	该税地下可开票税目列表

单条 invoiceDataList[]：

字段	说明
taxCategoryName	税目名称
hasInvoiceFee	已开票金额
applyInvoiceFee	申请中金额
ableInvoiceFee	可开票金额

4.20.4 关键说明

该接口是开票申请前的查询入口。

商户应优先根据该接口判断是否具备开票条件。

可开票余额按税地和税目维度聚合，商户在开票前应先确认要申请的结算单是否落在同一归集口径下。

4.21 开票申请接口

4.21.1 接口说明

发起开票申请。

4.21.2 请求参数（需加密）

POST /merchantapi/v2/invoice/apply

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

参数	类型	必填	说明
projectId	String	条件必填	请求体优先；未传时仅在 client 已绑定默认项目时可省略。多项目商户建议始终显式传入
outSettlementNoList	Array	是	结算单编号列表
invoiceType	Integer	否	当前默认 1，表示专票
invoiceAddress	String	否	发票抬头地址
invoicePhone	String	否	发票抬头电话
invoiceAcctNo	String	否	发票抬头银行账户
invoiceBankName	String	否	发票抬头开户行
remark	String	否	备注
notifyUrl	String	否	通知地址，最长 200

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

返回常见字段：

invoiceId

taxCompanyId

taxCategoryName

invoiceAmount

invoiceType

invoiceAddress

invoicePhone

invoiceAcctNo

invoiceBankName

remark

invoiceStatus

fileList

4.21.4 关键说明

outSettlementNoList 中的结算单必须属于当前商户和当前项目。

若结算单已经处于开票中或已开票，不允许重复申请。

申请金额不能超过当前可开票余额。

建议商户在调用前先使用可开票余额接口确认目标税地和税目下的余额是否足够，再组织申请单。

开票申请返回成功只代表申请已创建，不代表发票文件已经生成。

4.21.5 发票结果通知

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

触发时机：

发票申请进入处理中

发票开具完成并生成附件

发票申请被拒绝

外层通知包：

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

业务 payload：

发票结果通知的业务字段与“查询发票详情接口”的响应字段保持一致，商户可直接复用发票详情的数据结构进行解析。
核心字段通常包括：

字段	说明
`invoiceId`	发票 ID
`taxCompanyId`	税地 ID
`taxCategoryName`	税目名称
`invoiceAmount`	发票金额
`invoiceType`	发票类型
`remark`	审核意见或备注
`invoiceStatus`	发票状态：`0开票中 / 1已开票 / 2拒绝开票`
`fileList[]`	发票附件列表

处理建议：

建议以 invoiceId 做幂等更新。

当 invoiceStatus=1 时，再处理 fileList 中的发票附件展示或归档。

若商户系统对开票流程做了审批或财务节点控制，建议把“开票申请成功”和“发票已开具”明确拆成两个不同状态。

4.22 查询发票详情接口

4.22.1 接口说明

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

4.22.2 请求参数

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

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

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

返回字段与开票申请响应一致，通常包括：

invoiceId

taxCompanyId

taxCategoryName

invoiceAmount

invoiceType

invoiceAddress

invoicePhone

invoiceAcctNo

invoiceBankName

remark

invoiceStatus

fileList[]

fileList[]：

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

4.22.4 关键说明

当发票已生成电子文件时，通常可通过 fileList 获取文件下载地址。

商户若需要在自身系统展示开票附件，建议以 invoiceStatus=已开票 作为展示前提。

五、安全设计

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	当前结算单打款失败，请勿再次操作

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

错误码	说明
40403	文件数量超限
40404	不支持的文件格式

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"
}

使用说明

先确认请求签名正确。

再确认服务端能成功解密请求体。

最后确认商户侧能正常验证响应签名。

该接口通过后，再进入业务接口联调。

错误码说明

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

九、注意事项

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

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

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

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

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

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

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

联调和问题排查时请保留 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	结算金额必须大于0
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字符

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	此账号已被锁定,请稍后再试！

一、背景与目标#

1.1 业务背景#

1.2 设计原则#

1.3 设计目标#

1.4 术语说明#

1.5 常见状态对照表#

1.5.1 项目状态#

1.5.2 项目审核状态#

1.5.3 招募状态#

1.5.4 招募异步任务状态#

1.5.5 结算单状态#

1.5.6 结算明细状态#

1.5.7 交付物审核状态#

1.5.8 发票状态#

二、核心设计理念#

2.1 项目中心化模式#

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

2.3 异步招募与回调收口#

2.4 资格复用与有效期覆盖#

2.5 标识绑定与 URL 化简化#

三、快速开始#

3.1 准备工作#

3.2 五步快速接入#

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

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

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

Step 4：验证创客侧链路#

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

3.3 下一步#

3.4 异步通知总览#

3.5 异步通知通用规范#

3.5.1 回调方式#

3.5.2 外层通知包#

3.5.3 验签与解密规则#

3.5.4 成功判定与重试#

3.5.5 幂等处理建议#

四、接口设计#

4.1 核心接口列表#

4.1.1 通用请求头#

4.1.2 通用响应格式#

4.1.3 通用接入约定#

4.2 加密测试接口#

4.2.1 接口说明#

4.2.2 请求参数（需加密）#

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

4.2.4 关键说明#

4.3 查询项目列表接口#

4.3.1 接口说明#

4.3.2 请求参数#

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

4.3.4 关键说明#

4.4 创建项目接口#

4.4.1 接口说明#

4.4.2 请求参数（需加密）#

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

4.4.4 关键说明#

4.4.5 项目审核结果通知#

4.5 查询项目详情接口#

4.5.1 接口说明#

4.5.2 请求参数#

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

4.5.4 关键说明#

4.6 查询创客招募状态接口#

4.6.1 接口说明#

4.6.2 请求参数（需加密）#

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

4.6.4 关键说明#

4.7 批量招募创客接口#

4.7.1 接口说明#

4.7.2 请求参数（需加密）#

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

4.7.4 关键说明#

4.7.5 招募回调说明#

4.8 查询创客额度接口#

4.8.1 接口说明#

4.8.2 请求参数（需加密）#

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

4.8.4 关键说明#

4.9 批量查询创客额度接口#

一、背景与目标

1.1 业务背景

1.2 设计原则

1.3 设计目标

1.4 术语说明

1.5 常见状态对照表

1.5.1 项目状态

1.5.2 项目审核状态

1.5.3 招募状态

1.5.4 招募异步任务状态

1.5.5 结算单状态

1.5.6 结算明细状态

1.5.7 交付物审核状态

1.5.8 发票状态

二、核心设计理念

2.1 项目中心化模式

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

2.3 异步招募与回调收口

2.4 资格复用与有效期覆盖

2.5 标识绑定与 URL 化简化

三、快速开始

3.1 准备工作

3.2 五步快速接入

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

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

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

Step 4：验证创客侧链路

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

3.3 下一步

3.4 异步通知总览

3.5 异步通知通用规范

3.5.1 回调方式

3.5.2 外层通知包

3.5.3 验签与解密规则

3.5.4 成功判定与重试

3.5.5 幂等处理建议

四、接口设计

4.1 核心接口列表

4.1.1 通用请求头

4.1.2 通用响应格式

4.1.3 通用接入约定

4.2 加密测试接口

4.2.1 接口说明

4.2.2 请求参数（需加密）

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

4.2.4 关键说明

4.3 查询项目列表接口

4.3.1 接口说明

4.3.2 请求参数

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

4.3.4 关键说明

4.4 创建项目接口

4.4.1 接口说明

4.4.2 请求参数（需加密）

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

4.4.4 关键说明

4.4.5 项目审核结果通知

4.5 查询项目详情接口

4.5.1 接口说明

4.5.2 请求参数

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

4.5.4 关键说明

4.6 查询创客招募状态接口

4.6.1 接口说明

4.6.2 请求参数（需加密）

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

4.6.4 关键说明

4.7 批量招募创客接口

4.7.1 接口说明

4.7.2 请求参数（需加密）

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

4.7.4 关键说明

4.7.5 招募回调说明

4.8 查询创客额度接口

4.8.1 接口说明

4.8.2 请求参数（需加密）

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

4.8.4 关键说明

4.9 批量查询创客额度接口

4.9.1 接口说明