点薪-结算平台接口文档 v2.2.1

欢迎使用点薪灵活用工结算平台。本文档详细描述了开发者接入平台所需的所有接口规范。

更新日志

版本	日期	更新内容
v2.2.1	2025-10-30	1. 2.14 账户信息新增运营商账户字段 2. 2.11 新增开票支持 `OP`(运营商)/`SPI`(服务商) 主体区分 3. 2.9 查询结果新增运营商服务费字段
v2.1.1	2025-06-13	新增创建结算订单回参 settlementDetail 字段
v2.0.9	2025-05-28	新增结算接口支付宝类型

1. 公共部分

1.1 公共请求参数

参数	类型	必须	描述信息
appId	string	是	平台分配的客户端ID
sign	string	是	签名字符串
timestamp	long	是	当前时间戳 (毫秒)

1.2 公共返回参数

参数	类型	必须	描述信息
success	boolean	/	成功
code	int	/	返回状态值
msg	string	/	异常信息
data	object	/	返回数据

1.3 加密及签名

1. 筛选：获取所有请求参数，不包括空值数据，剔除 sign 参数，同时加上 appId 参数

2. 排序：将参数按照第一个字符的健值 ASCII 码递增排序（字母升序排序）,如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推

3. 拼接：请求参数json字符串 + appId + appSecret + timestamp（appId和appSecret由平台方提供）

4.签名：使用 MD5 进行签名，得到 sign 签名数据

1.4 请求路径

沙箱环境：https://beta.dianxingg.cn/

生产环境：https://www.dianxingg.cn/

2.1 获取 TOKEN

获取Token是调用API接口的第一步，相当于创建了一个登录凭证，其他接口都需要依赖于Token来鉴权。在调用任何其他业务接口时，将有效的Token作为公共请求参数放在请求header中。key是dxtoken, value是获取的token值。

POST /openapi/auth/token

请求参数

参数	类型	必填	描述
loginName	string	是	用工企业登录账号（支持邮箱/手机号）

返回参数

参数	类型	描述
token	string	鉴权Token，请放入Header: `dxtoken`
expiresIn	int	Token有效期(秒)

{ "loginName": "your_account" }

{
  "success": true,
  "code": 200,
  "msg": "成功",
  "data": {
    "token": "your_token_string",
    "expiresIn": 7200
  }
}

2.2 新增任务

POST /openapi/task/v2/addTask

请求参数

参数	类型	必填	描述
spCreditCode	string	是	服务商统一社会信用代码
serviceTypeName	string	是	业务大类名称
invoiceTypeName	string	是	发票内容名称
name	string	是	任务名称
address	string	是	任务执行地址
describe	string	是	任务详细描述
calculationType	string	是	计价方式枚举： `DAY`: 天 `WEEK`: 周 `MONTH`: 月 `QUARTER`: 季度 `YEAR`: 年 `TIME`: 次 `ITEM`: 件
taskPrice	number	是	任务预算金额
recruitmentNumber	int	是	招募人数
settleRule	string	是	结算规则说明
notes	string	否	任务备注

返回参数

参数	类型	描述
taskId	string	任务ID

{
    "name": "物流配送",
    "address": "上海市浦东新区",
    "describe": "快递配送业务",
    "calculationType": "DAY",
    "taskPrice": 200000,
    "recruitmentNumber": 100,
    "spCreditCode": "91360XXXX",
    "serviceTypeName": "现代服务",
    "invoiceTypeName": "服务费",
    "settleRule": "200元/天"
}

{
  "success": true,
  "code": 200,
  "msg": "成功",
  "data": { "taskId": "TSK202506230001" }
}

2.3 编辑任务

POST /openapi/task/v2/editTask

请求参数

参数	类型	必填	描述
taskId	string	是	原任务ID
status	string	是	任务状态： `DRAFT`: 草稿 `AUDIT`: 待审核
name	string	是	任务名称
...	-	-	其他字段同新增任务

返回参数

参数	类型	描述
taskId	string	新生成的任务ID

{"taskId": "TSK001", "status": "DRAFT", "name": "新名称"}

{"success":true, "data": {"taskId": "TSK002"}}

2.4 查看任务

POST /openapi/task/v2/getTaskDetail

请求参数

参数	类型	必填	描述
taskId	string	是	任务ID

返回参数

参数	类型	描述
status	string	任务状态： `DRAFT` 草稿 `AUDIT` 待审核 `ONGOING` 进行中 `CLOSE` 已关闭 `REJECT` 已驳回
name	string	任务名称

{"taskId": "TSK001"}

{"success":true, "data": {"name": "物流", "status": "ONGOING"}}

2.5 客户签约（免签可跳过）

POST /openapi/task/v2/create

请求参数

参数	类型	必填	描述
taskId	string	是	任务ID
name	string	是	姓名
idCard	string	是	身份证号
phone	string	是	手机号
bankcardId	string	是	银行卡号
gender	string	是	性别: `MAN` 男, `WOMAN` 女
credentialsFrontInfoFile	string	是	证件人像面 Base64
credentialsBackInfoFile	string	是	证件国徽面 Base64
bankName	string	否	开户行

返回参数

参数	类型	描述
msg	string	操作提示（如：请点击短信链接进行签署）

{
    "taskId": "TSK202506230001",
    "idCard": "510402199310225113",
    "credentialsFrontInfoFile": "aliqua in",
    "credentialsFrontInfoFileName": "______.kar",
    "credentialsBackInfoFile": "enim ea",
    "credentialsBackInfoFileName": "__.so",
    "name": "王梓瑜",
    "bankcardId": "6214862846572222",
    "gender": "MAN",
    "phone": "17340094007"
}

{"success":true, "data":{"msg":"请求成功，请点击短信链接"}}

2.6 签约结果查询

POST /openapi/task/v2/getSign

请求参数

参数	类型	必填	描述
taskId	string	是	任务ID
idCard	string	是	身份证号

返回参数

参数	类型	描述
status	string	状态：`SIGNED` 已签约，`UNSIGN` 未签约
fileName	string	协议文件名
data	string	协议文件 Base64

{"taskId":"TSK001","idCard":"510..."}

{"success":true,"data":{"status":"SIGNED", "fileName":"xx.pdf"}}

2.7 创建结算订单

POST /openapi/settlement/v2/addSettlement

请求参数

参数	类型	必填	描述
taskId	string	是	任务ID
settlementMethod	string	是	支付方式： `CMB` 招商银行 `ALI_PAY` 支付宝 `OFFLINE` 线下支付
payrollUserList	list	是	收款人列表（见下表）
settlementRemarks	string	否	结算备注

payrollUserList 结构

参数	类型	必填	描述
name	string	是	姓名
idCard	string	是	身份证号
phone	string	是	手机号
bankcardId	string	是	收款账号
settlementAmount	string	是	发放金额
bankcardType	string	否	账户类型（银行账户；支付宝账户） (若Method=CMB，此字段不可传ALI_PAY)

返回参数

参数	类型	描述
settlementInfoId	string	结算单ID
settlementNo	string	订单编号

{
    "payRemarks": "",
    "payrollUserList": [
        {
            "bankcardId": "6222022302002292439",
            "bankcardType": "银行账户",
            "idCard": "510402199310225113",
            "name": "王梓瑜",
            "payeeRemarks": "银行下发测试",
            "phone": "17340094007",
            "settlementAmount": "1"
        },
        {
            "bankcardId": "17340094007",
            "bankcardType": "支付宝账户",
            "idCard": "510402199310225113",
            "name": "王梓瑜",
            "payeeRemarks": "支付宝下发测试",
            "phone": "17340094007",
            "settlementAmount": "2"
        }
    ],
    "settlementMethod": "ALI_PAY",
    "settlementRemarks": "",
    "taskId": "TSK202506230001"
}
}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "success": true,
        "settlementInfoId": "da2b5f81d8d5416200e5fad5cd079a9b",
        "settlementNo": "2025062318040007",
        "errorSettlementDetail": null,
        "settlementDetail": [
            {
                "settlementDetailId": "1678d0718d071b798e8cf681f08e47da",
                "name": "王梓瑜",
                ...
            },
            {
                "settlementDetailId": "895369381bf15793c673c9c61fcd8931",
                "name": "王梓瑜",
                ...
            }
        ]
    }
}
    }
}

2.8 付款结算

POST /openapi/settlement/v2/paySettlement

请求参数

参数	类型	必填	描述
settlementInfoId	string	是	结算ID

返回参数

参数	类型	描述
success	boolean	业务状态 (true: 成功)

{"settlementInfoId": "da2b5f81d8d5416200e5fad5cd079a9b"}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "success": true
    }
}

2.9 发放结果查询

POST /openapi/settlement/v2/getSettlementDetail

请求参数

参数	类型	必填	描述
settlementInfoId	string	是	结算ID

返回参数

参数	类型	描述
settlementStatus	string	订单状态： `SUCCESS`: 发放成功 `FAIL`: 发放失败 `PAYING`: 发放中 `TOBEPAID`: 待付款
settlementDetail	list	明细列表（见下表）

Detail 结构

参数	类型	描述
settlementStatus	string	单笔状态(同上)
serviceCharge	number	服务费
operatorAmount	number	运营商服务费
operatorName	string	运营商名称
settlementRemarks	string	失败原因

{"settlementInfoId": "da2b5f81d8d5416200e5fad5cd079a9b"}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "settlementNo": "2025103013170011",
        "settlementStatus": "SUCCESS",
        "settlementDetail": [
            {
                "settlementDetailId": "b284fe021e2588a94821aea6295c878b",
                "name": "王梓瑜",
                "idCard": "510402199310225113",
                "phone": "17340094007",
                "bankcardId": "17340094007",
                "settlementAmount": 0.30,
                "serviceCharge": 0.01,
                "serialNumber": "10300002",
                "settlementStatus": "FAIL",
                "settlementTime": "2025-10-30 13:17:08",
                "settlementReceiptFileId": null,
                "settlementRemarks": "AGF415X - 未查询到户口信息",
                "payeeRemarks": "测试",
                "operatorAmount": 0.00,
                "operatorId": "9001",
                "operatorName": "安徽点薪网络科技有限公司"
            },
            {
                "settlementDetailId": "cbb20e9619b5ad0c77f161a1f35c3b0c",
                "name": "王梓瑜",
                "idCard": "510402199310225113",
                "phone": "17340094007",
                "bankcardId": "6214862846572222",
                "settlementAmount": 1.00,
                "serviceCharge": 0.04,
                "serialNumber": "10300001",
                "settlementStatus": "SUCCESS",
                "settlementTime": "2025-10-30 13:17:08",
                "settlementReceiptFileId": "01dda81cccdd3ec5c17d16234b99d541",
                "settlementRemarks": null,
                "payeeRemarks": "测试",
                "operatorAmount": 0.01,
                "operatorId": "9001",
                "operatorName": "安徽点薪网络科技有限公司"
            }
        ]
    }
}
}

2.10 回执单下载

POST /openapi/settlement/v2/downloadReceipt

请求参数

参数	类型	必填	描述
settlementInfoId	string	是	结算ID
settlementDetailId	string	是	明细ID

返回参数

参数	类型	描述
fileName	string	文件名
data	string	文件字节 Base64

{
    "settlementInfoId": "da2b5f81d8d5416200e5fad5cd079a9b",
    "settlementDetailId": "1678d0718d071b798e8cf681f08e47da"
}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "fileName": "52d528be73004a7ab7db7f184ccb068b.pdf",
        "data": "JVBERXXXXXXXXX"
    }
}

2.11 新增开票

POST /openapi/invoice/v2/addInvoiceInfo

请求参数

参数	类型	必填	描述
settlementInfoIds	array	是	结算ID集合
receiptFile	string	是	验收单Base64
receiptFileName	string	是	验收单文件名
invoiceType	string	是	发票类型： `APPRECIATION_E` 电子专票 `APPRECIATION` 纸质专票
invoiceEmail	string	是	接收邮箱
subjectType	string	否	开票主体：`SPI` 服务商(默认)，`OP` 运营商
invoiceCategoryName	string	否	运营商开票类目 (OP时必填)

返回参数

参数	类型	描述
invoiceInfoId	string	开票ID

{
    "settlementInfoIds": ["da2b5f81d8d5416200e5fad5cd079a9b"],
    "receiptFile": "base64_string",
    "receiptFileName": "验收单.pdf",
    "invoiceType": "APPRECIATION_E",
    "invoiceEmail": "fvpts4.o86@163.com",
    "subjectType": "OP",
    "invoiceCategoryName": "现代服务*测试"
}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "invoiceInfoId": "INV202506240001"
    }
}

2.12 开票信息详情

POST /openapi/invoice/v2/getInvoiceInfoDetail

请求参数

参数	类型	必填	描述
invoiceInfoId	string	是	开票ID

返回参数

参数	类型	描述
invoiceStatus	string	状态： `reviewed` 待审核 `nouploaded` 待上传 `invoiced` 已开票 `rejected` 已驳回

{"invoiceInfoId":"INV202506240001"}

{"success":true, "data":{"invoiceStatus":"invoiced"}}

2.13 发票下载

POST /openapi/invoice/v2/downloadInvoice

请求参数

参数	类型	必填	描述
invoiceInfoId	string	是	开票ID

返回参数

参数	类型	描述
fileName	string	文件名
data	string	文件 Base64

{"invoiceInfoId":"INV001"}

{"data":{"fileName":"发票.pdf","data":"..."}}

2.14 账户信息

POST /openapi/vsa/v2/getCompanyAccountInfo

请求参数

无

返回参数

参数	类型	描述
spName	string	服务商名称
virtualSubAccountEntities	list	账户列表

Account Entity 结构

参数	类型	描述
openBankType	string	银行类型 (CMB/ALI_PAY)
availableAmount	number	可用余额
operatorVirtualSubAccountData	object	运营商子账户（如下）

Operator 结构

参数	类型	描述
operatorName	string	运营商名称
availableAmount	number	运营商可用余额

{}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "spName": "某某服务商",
        "virtualSubAccountEntities": [
            {
                "accountId": "f65e4668f19ee74800d1c65bca4009cf",
                "openBankType": "ALI_PAY",
                "spName": "某某服务商",
                "accountNum": "2088882700944367555",
                "openBankName": "支付宝-备付金账户",
                "availableAmount": 0.31,
                "unavailableAmount": 0.00,
                "operatorVirtualSubAccountData": {
                    "accountId": "5445c74cb17322a44631bc31ec78cedb",
                    "openBankType": "CMB",
                    "operatorName": "某某运营商",
                    "accountNum": "551908386110106",
                    "openBankName": "招商银行合肥政务区支行",
                    "availableAmount": 8.76,
                    "unavailableAmount": 0.00
                }
            }
        ]
    }
}

2.15 提现

POST /openapi/vsa/v2/accountTook

请求参数

参数	类型	必填	描述
accountId	string	是	账户信息ID
tookAmount	string	是	提现金额
collectingAccount	string	是	收款账号
collectingBank	string	是	收款银行
sameBank	boolean	是	是否是相同的银行
collectingBankNumber	string	否	总行行号

返回参数

参数	类型	描述
accountId	string	提现流水ID

{
    "accountId": "ACCT123456",
    "collectingAccount": "6222000011112222",
    "tookAmount": "1000.00",
    "sameBank": true,
    "collectingBank": "招商银行",
    "collectingBankNumber": "308584000013"
}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "accountId": "WITHDRAW_ID_123"
    }
}

2.16 提现状态

POST /openapi/vsas/v2/accountTookStatus

请求参数

参数	类型	必填	描述
accountId	string	是	提现流水ID

返回参数

参数	类型	描述
tradingHours	string	交易时间
tradingStatus	string	交易状态： `SUCCESS`: 成功 `IN_PROGRESS`: 提现中 `FAIL`: 失败
bankResult	string	银行返回结果
remarks	string	备注

{"accountId":"WITHDRAW_ID_123"}

{"success":true, "code":200, "msg":"操作成功", "data":{
    "tradingStatus":"SUCCESS",
    "bankResult":"交易成功",
    "tradingHours":"2025-06-24 10:00:00"
}}

2.17 查看充值记录

POST /openapi/vsas/v2/getRechargeAccountSettlementPage?current=当前页&size=页数据量

请求参数

参数	类型	必填	描述
accountId	string	是	账户信息ID
beginTime	string	否	开始时间 (yyyy-MM-dd HH:mm:ss)
endTime	string	否	结束时间 (yyyy-MM-dd HH:mm:ss)

返回参数

参数	类型	描述
serialNumber	string	流水号
settlementAmount	string	金额
tradingHours	string	交易时间

{
    "accountId": "ACCT123456",
    "beginTime": "2024-10-01 00:00:00",
    "endTime": "2024-10-31 23:59:59"
}

{
    "success": true,
    "code": 200,
    "msg": "操作成功",
    "data": {
        "records": [
             {
                "serialNumber": "RECHARGE_SN_001",
                "collectingAccount": "1234567890",
                "settlementAmount": "5000.00",
                "tradingHours": "2024-10-22 06:35:04",
                "remarks": "充值"
             }
        ],
        "total": 1,
        "size": 10,
        "current": 1
    }
}

2.18 完税证明

POST /openapi/dpp/v2/getDutyPaidProof

请求参数

参数	类型	必填	描述
queryTime	string	是	时间 (yyyy-MM)

返回参数

参数	类型	描述
status	string	状态： `uploaded` 已上传 `tobeuploaded` 待上传
proof	string	文件 Base64

{"queryTime":"2025-05"}

{"data":{"status":"uploaded","proof":"JVBER..."}}

3. 请求示例 (Java)
import cn.hutool.json.JSONConfig;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import okhttp3.*;
import org.apache.commons.codec.digest.DigestUtils;

public class RequestOpenApiDemo {
    private static final String APP_ID = "7438991352";
    private static final String APP_SECRET = "88113fbe...";

    public static void main(String[] args) throws Exception {
        // 示例：调用获取Token接口
        String url = "https://beta.dianxingg.cn/openapi/auth/token";
        long timestamp = System.currentTimeMillis();
        
        // 构造参数 (示例参数对象)
        RequestParam param = new RequestParam();
        param.setLoginName("your_account");

        // 1. 排序并生成JSON字符串 (Hutool特性)
        JSONObject entries = JSONUtil.parseObj(param, JSONConfig.create().setNatureKeyComparator());
        String jsonString = JSONUtil.toJsonStr(entries);
        
        // 2. 签名: json + appId + appSecret + timestamp
        String concat = jsonString + APP_ID + APP_SECRET + timestamp;
        String sign = DigestUtils.md5Hex(concat);

        // 3. 发送请求
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
                .url(url)
                .method("POST", RequestBody.create(MediaType.parse("application/json"), jsonString))
                .addHeader("appId", APP_ID)
                .addHeader("sign", sign)
                .addHeader("timestamp", String.valueOf(timestamp))
                .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}
                    

4. 常见问题 (FAQ)

1. loginName如何获取？

用工企业对应的 loginName 具有唯一性，运营风控准入后将同步生效，请咨询您的运营对接人。

2. 如何判断发票文件类型？

返回数据中包含 fileName，您可以通过文件后缀名（如 .pdf, .zip）进行判断。data 字段为文件的 Base64 编码，建议使用 Hutool 的 Base64.decodeToFile(receiptFile, FileUtil.createTempFile(receiptFileName, true)); 方法。

https://www.hitoy.org/tool/file_base64.php

3. 系统禁默时间？

为了保障资金安全，平台与银行方设定了每日 22:00 至次日 07:00 为禁默时间，期间禁止发起充值与下发请求。

4. 计价方式枚举值

DAY: 天
WEEK: 周
MONTH: 月
QUARTER: 季度
YEAR: 年
TIME: 次
ITEM: 件

5. payrollUserList排序问题

推荐参考hutool的 JSONUtil.parseObj(body, JSONConfig.create().setNatureKeyComparator()); 这个方法。

点薪排序小工具：https://oss.dianxin.love/tool.html

6. serviceTypeName 如何获取？

匹配不同园区时会提供各园区主体的相关发票类目配置单，如有需要请联系：@梓瑜

7. 是否有接口限流政策？

为了维持平台程序稳定，接口限流为：100/60s

DX-PLATFORM API

点薪-结算平台接口文档 v2.2.1

更新日志

1. 公共部分

1.1 公共请求参数

1.2 公共返回参数

1.3 加密及签名

1. 筛选：获取所有请求参数，不包括空值数据，剔除 sign 参数，同时加上 appId 参数

2. 排序：将参数按照第一个字符的健值 ASCII 码递增排序（字母升序排序）,如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推

3. 拼接：请求参数json字符串 + appId + appSecret + timestamp（appId和appSecret由平台方提供）

4.签名：使用 MD5 进行签名，得到 sign 签名数据

1.4 请求路径

沙箱环境：https://beta.dianxingg.cn/

生产环境：https://www.dianxingg.cn/

2.1 获取 TOKEN

获取Token是调用API接口的第一步，相当于创建了一个登录凭证，其他接口都需要依赖于Token来鉴权。在调用任何其他业务接口时，将有效的Token作为公共请求参数放在请求header中。key是dxtoken, value是获取的token值。

请求参数

返回参数

2.2 新增任务

请求参数

返回参数

2.3 编辑任务

请求参数

返回参数

2.4 查看任务

请求参数

返回参数

2.5 客户签约（免签可跳过）

请求参数

返回参数

2.6 签约结果查询

请求参数

返回参数

2.7 创建结算订单

请求参数

payrollUserList 结构

返回参数

2.8 付款结算

请求参数

返回参数

2.9 发放结果查询

请求参数

返回参数

Detail 结构

2.10 回执单下载

请求参数

返回参数

2.11 新增开票

请求参数

返回参数

2.12 开票信息详情

请求参数

返回参数

2.13 发票下载

请求参数

返回参数

2.14 账户信息

请求参数

返回参数

Account Entity 结构

Operator 结构

2.15 提现

请求参数

返回参数

2.16 提现状态

请求参数

返回参数

2.17 查看充值记录

请求参数

返回参数

2.18 完税证明

请求参数

返回参数

3. 请求示例 (Java)

4. 常见问题 (FAQ)

1. loginName如何获取？

2. 如何判断发票文件类型？

3. 系统禁默时间？

4. 计价方式枚举值

5. payrollUserList排序问题