vipnub/oil

Fork 0

Files

T

vipnub ae94c1dc00 修改回调接口解析参数的方式

2026-09-20 21:15:35 +08:00

46 KiB

Raw Permalink Blame History

企油通 · 企业通用对接接口文档（第 7 章）

来源：在线 API 文档中心 https://apidoc.worknoya.vip/project/cxt_oop/7 企业通用对接.html 文档最后更新：2026-08-24 16:29 本文件整理时间：2026-09-01

0. 给 Claude Code 的使用说明

本文件是单文件完整接口手册，包含：对接流程图、公共约定（信封 / 签名 / 通道 / 错误码）、23 个接口的完整入参出参表。
所有接口均为 POST，路径形如 /enterprise/api/...，域名（测试 / 正式不同）需线下向对接人员索取，文中统一写作 {接口域名}。
金额单位不统一，务必逐接口确认：7.7 / 7.9 / 7.10 / 7.11 / 7.12 / 7.13 / 7.14 用分；7.16 / 7.17 / 7.19 / 7.20 / 7.21 / 7.23 用元。
表格列含义：参数名 | 必填 | 类型 | 说明 | 示例。
已停用内容（智慧油客通道 passageway=3、接口 7.3）保留说明但不要用于新开发。

1. 对接流程总览

四个阶段：企业创建 → 发放油费 → 司机加油 → 获取发票。左侧为业务方（慧明）动作，右侧为企油通接口。

flowchart TD
    subgraph A["1 企业创建"]
        A1["创建企业<br/>（提交营业执照、指定手机号等）"] --> A2["7.2 企业申请创建"]
        A2 --> A3["线下：企业支付宝/平安开户及配置"]
        A3 --> A4["7.5 企业账户信息查询"]
    end

    subgraph B["2 发放油费"]
        B1["添加司机和发放额度"] --> B2["7.7 运单油费下发"]
        B2 --> B3{"是否额度调整"}
        B3 -->|否| B6["下发成功"]
        B3 -->|是| B4["7.17 获取支付凭证"]
        B4 --> B5["7.16 司机额度调整"]
        B5 --> B6
    end

    subgraph C["3 司机加油"]
        C1["司机用 H5 加油"] --> C2["7.15 H5 跳转地址（免登）"]
        C2 --> C3["7.9 运单加油明细查询"]
        C2 --> C4["7.10 运单加油明细推送（异步回调）"]
        C3 --> C5["7.19 支付回单获取"]
        C4 --> C5
    end

    subgraph D["4 获取发票"]
        D1["下载企业发票"] --> D2["7.14 企业发票下载接口"]
    end

    A4 --> B1
    B6 --> C1
    C5 --> D1

关键衔接字段

上游	产出字段	下游用途
7.22 企业列表	`business_license`	几乎所有接口的必填企业标识
7.7 运单油费下发	`batch_no` / `waybill_no_code`	7.8 查发放结果
7.17 获取支付凭证	`quota_id`	7.16 司机额度调整
7.9 加油明细	`order_code`	7.19 支付回单获取
7.20 提现	`out_trade_no` / `withdraw_no`	7.21 提现结果查询

2. 公共约定

2.1 请求信封

所有业务接口使用 application/json，外层信封固定为：

{
  "appId": "9470****8424",
  "timestamp": 1775030405,
  "sign": "b3c1****e9f2",
  "params": "{\"business_license\":\"9132****127B\",\"passageway\":2}"
}

⚠️ params 必须是 JSON 字符串（需转义），不是 JSON 对象。 用 form 表单方式提交会被解析为空，典型报错「营业执照号不能为空」。

curl -X POST "https://{接口域名}/enterprise/api/receipt/getPaymentReceipt" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "appId": "9470****8424",
    "timestamp": 1775030405,
    "sign": "b3c1****e9f2",
    "params": "{\"passageway\":2,\"business_license\":\"9132****127B\",\"order_code\":\"2025****1105571\",\"mobile\":\"186****6666\"}"
  }'

2.2 通用响应结构

{
  "status": "ok",          // ok | error
  "data": { },              // 业务数据
  "message": "Success",
  "serialNo": "2025****6656",
  "sign": "LGPc****7A="
}

2.3 登录态

本章节业务接口均不需要携带登录态 token，直接用 appId + business_license 调用即可。7.1 企业登录 为可选接口。

2.4 签名规则

7.16 司机额度调整、7.17 获取支付凭证 必须真实 RSA 验签调用，否则返回 403「本接口要求签名调用（RSA 验签），当前调用未通过真实签名」。
H5 免登地址（7.15）签名算法： ksort → http_build_query → urldecode → 大写 MD5 → SHA1withRSA → base64
- 不传 creditcode 时，参与签名字段 = appId + mobile + timestamp
- 传 creditcode 时，参与签名字段 = appId + creditcode + mobile + timestamp（漏签会验签失败）
业务接口的密钥、公私钥与具体拼签字段请向对接人员索取。

2.5 支付通道（passageway）

编码	通道	状态
1	支付宝企业码	可用
2	平安银行	可用
3	智慧油客	🚫 已停用，不再受理新接入，请勿在入参中传 3
4	企油通	仅出现在 7.22 返回的已绑定通道中

历史上绑定过智慧油客的企业，查询类接口返回值中仍可能出现 passageway = 3，属历史数据。

2.6 企业状态与凭证状态枚举

枚举组	值
企业状态 `status`	`pending` 待完善 / `submitted` 待审核 / `approved` 审核通过 / `rejected` 审核拒绝 / `frozen` 已冻结
企业码状态 `alipay_status`	`opening` 开通中 / `opened` 开通完成 / `unsigned` 解约 / `canceling` 注销中 / `canceled` 已注销
凭证状态（7.17）	`active` 生效中 / `inactive` 已作废 / `expired` 已过期 / `frozen` 已冻结
提现状态（7.20/7.21）	`system_processing` / `bank_processing` / `success` / `failed`
回单状态（7.19）	`ready` / `generating` / `not_found` / `ambiguous` / `unsupported`

2.7 通用错误码

HTTP	message	含义
403	企业不存在或无权访问	传入的 `business_license` 不属于当前 appId
403	企业已被冻结，无法访问	目标企业处于冻结状态（仅 7.16 / 7.17）
403	该商户未开通企业列表查询权限	未开通权限却调用 7.22
403	无权为该用户签发凭据	7.15 免登：目标司机所属企业不在你名下
403	本接口要求签名调用（RSA 验签），当前调用未通过真实签名	7.16 / 7.17 未通过验签
404	该商户名下暂无企业	名下没有任何可用企业

3. 接口清单

编号	名称	方法与路径	备注
7.1	企业登录（可选）	`POST /enterprise/api/auth/login`	可选，业务接口无需 token
7.2	企业申请创建	`POST /enterprise/api/zhyk/openAnAccount`
7.3	企业账户信息推送（智慧油客）	回调	🚫 已停用
7.4	企业账户信息推送（平安银行）	回调 `POST .../callback/ygzf/enterpriseAccountCallback`	我方推送给接入方
7.5	企业账户信息查询	`POST /enterprise/api/zhyk/accountQuery`
7.6	企业信息查询	`POST /enterprise/api/zhyk/getEnterpriseInfo`
7.7	运单油费下发	`POST /enterprise/api/zhyk/createAndSendQuota`	单次最多 100 人
7.8	运单发放结果查询	`POST /enterprise/api/zhyk/waybillBatch`
7.9	运单加油明细查询	`POST /enterprise/api/zhyk/waybillQuotaDetail`
7.10	运单加油明细推送（异步）	回调 `POST .../callback/ygzf/waybillConsumeCallback`	我方推送给接入方
7.11	获取企业账户余额	`POST /enterprise/api/zhyk/distributable`	支付宝通道不支持
7.12	司机钱包金额查询	`POST /enterprise/api/zhyk/driverBalanceQuery`
7.13	司机钱包明细查询	`POST /enterprise/api/zhyk/driverWalletQuery`
7.14	企业发票下载接口	`POST /enterprise/api/zhyk/invoice`
7.15	H5 跳转地址（免登）	H5 URL
7.16	司机额度调整	`POST /enterprise/api/quota/adjustVoucher`	须签名
7.17	获取支付凭证	`POST /enterprise/api/quota/getVoucherList`	须签名
7.18	司机三证信息保存	`POST /enterprise/api/zhyk/saveDriverDoc`	含 OCR
7.19	支付回单获取（平安银行）	`POST /enterprise/api/receipt/getPaymentReceipt`	仅 passageway=2
7.20	司机提现到银行卡（平安银行）	`POST /enterprise/api/driver-withdraw/withdrawToBank`	异步
7.21	提现结果查询（平安银行）	`POST /enterprise/api/driver-withdraw/queryWithdraw`
7.22	企业列表查询	`POST /enterprise/api/enterprise/list`	需开通权限
7.23	平安银行消费回调测试接口	`POST /enterprise/api/zhyk/testPinganConsume`	🚫 仅测试环境

4. 接口详情

7.1 企业登录（可选）

POST /enterprise/api/auth/login

本接口为可选。本章节业务接口均不需要携带登录态 token，直接用 appId + business_license 调用即可。

请求参数

参数名	必填	类型	说明	示例
appId	是	string	平台分配	9470****8424
sign	是	string	签名	-
params.username	是	string	企业登录账户（企业注册手机号）	186****331
params.password	否	string	登录密码（配置免密登录后可不填）	11111111

响应 data

字段	类型	说明
token	string	认证 token（后续接口 Header 携带）
expires_in	number	token 过期时间（秒），如 7200
enterprise_info.id	number	企业 ID
enterprise_info.number	string	企业编号
enterprise_info.name	string	企业名称
enterprise_info.status	string	企业状态，见 2.6
enterprise_info.alipay_status	string	企业码状态，见 2.6

7.2 企业申请创建

POST /enterprise/api/zhyk/openAnAccount

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码。已存在的企业须归属本 appId，否则 403	9132****127B
params.business_license_url	是	string	营业执照照片地址	https://xxx.png
params.passageway	是	string	通道，多个用英文逗号分隔（1 支付宝企业码 / 2 平安银行）	1,2
params.company_name	是	string	企业名称	cxt专用测试油费
params.contact_mobile	是	string	企业联系人电话	136****3502
params.contact_name	是	string	企业联系人姓名	cxt专用测试油费

响应 data

字段	类型	说明
enterprise_number	string	企业编号
status	number	0 失败 / 1 待审核 / 2 审核成功
msg	string	信息，如「创建成功,待审核」

7.3 企业账户信息推送（智慧油客）🚫 已停用

POST http://dev.general.worknoya.work/callback/ygzf/enterpriseAccountCallback

🚫 智慧油客通道下线，仅为存量对接方保留历史说明，不再受理新接入。新接入请使用 7.4。

字段结构与 7.4 一致，区别在 params.passageway = 3。

7.4 企业账户信息推送（平安银行）

POST http://dev.general.worknoya.work/callback/ygzf/enterpriseAccountCallback （我方 → 接入方 的回调推送，地址为示例的测试环境地址，实际由接入方提供并配置）

推送参数

参数名	必填	类型	说明	示例
params.account	是	string	企业银行账户（平安银行）	12****78
params.account_bank	是	string	开户行	苏州银行
params.account_name	是	string	开户名	沙*弟
params.enterprise_name	是	string	企业名	测试沙*弟2
params.business_license	是	string	统一社会信用代码，须归属本 appId，否则 403	9132****1276
params.passageway	是	number	通道：1 支付宝 / 2 平安银行	2

期望响应 data：account / enterprise_name / business_license。

7.5 企业账户信息查询

POST /enterprise/api/zhyk/accountQuery

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码，须归属本 appId	9132****1276
params.passageway	是	string	1 支付宝企业码 / 2 平安银行	2

响应 data

字段	类型	说明
account	string	企业账户号
account_bank	string	开户行
account_name	string	开户名
passageway	number	1 支付宝 / 2 平安银行 / 3 智慧油客（已停用，仅历史数据）
enterprise_name	string	企业名称
business_license	string	营业执照
status	number	1 审核中 / 2 开户成功

7.6 企业信息查询

POST /enterprise/api/zhyk/getEnterpriseInfo

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.passageway	是	string	1 支付宝企业码 / 2 平安银行	2
params.company_name	是	string	企业名称	cxt专用测试油费
params.contact_mobile	是	string	企业联系人电话	185****2667
params.contact_name	是	string	企业联系人姓名	测试

响应 data

字段	类型	说明
enterprise_id	number	企业 id
is_new	boolean	是否新企业
can_pay	boolean	是否可支付
password	string	密码
message	string	信息

7.7 运单油费下发

POST /enterprise/api/zhyk/createAndSendQuota

请求参数

参数名	必填	类型	说明	示例
params.batch_no	是	string	发放批次号。⚠️ 当前为全平台唯一，非「接入方内唯一」，建议加企业前缀	9478****_215I
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.passageway	是	string	1 支付宝企业码 / 2 平安银行	2
params.institution_id	否	string	企业码通道下必填，待系统分配	-
params.waybill_list	是	array	运单列表	-
├ waybill_no	是	string	运单号。⚠️ 全平台唯一，建议加企业前缀	WB20****_215G
├ employee_list	是	array	发放人员信息，单次最大 100 条	-
│ ├ mobile	是	string	手机号	156****6611
│ ├ id_card	是	string	身份证号（平安银行通道下必填）	4***************11
│ ├ name	是	string	姓名	苏**
│ ├ quota_amount	是	number	金额（分）	160
│ ├ voucher_name	是	string	凭证名称	运单卡
│ ├ effective_start	是	string	凭证生效开始时间（须小于制度生效时间；为空即当日生效）	-
│ ├ effective_end	是	string	凭证生效结束时间（须大于开始时间；为空代表长期有效）	-
│ └ waybill_no_code	是	string	唯一流水号（外部透传，失败回查用）。⚠️ 全平台唯一	WB20****_001220215I
└ institution_config	否	object	制度配置	-
├ name	否	string	制度名称	平安默认制度
├ effective_start	否	string	生效开始时间	2026-03-06 00:00:00
├ effective_end	否	string	生效结束时间	2029-12-31 23:59:59
└ description	否	string	制度描述	油卡充值制度

响应 data：status（1 成功 / 2 失败）、msg（如「运单信息正在处理，请稍后查看结果」）。下发为异步处理，结果用 7.8 按 batch_no 查询。

7.8 运单发放结果查询

POST /enterprise/api/zhyk/waybillBatch

请求参数

参数名	必填	类型	说明	示例
params.batch_no	是	string	批次号	9478****_203
params.business_license	否	string	传了则必须归属本 appId，否则 403	9132****127B

响应 data

字段	类型	说明
batch_no	string	批次号
status	number	整批状态：1 待处理 / 2 处理中 / 3 全部成功 / 4 部分成功 / 5 处理失败
list[].id	number	记录 ID
list[].batch_no	string	批次号
list[].waybill_no	string	运单号
list[].waybill_no_code	string	运单唯一编号
list[].mobile	string	手机号
list[].id_card	string	身份证
list[].name	string	姓名
list[].quota_amount	number	发放额度（分）
list[].voucher_name	string/null	凭证名称
list[].effective_start / effective_end	string/null	凭证有效期
list[].handle_status	number	单条状态：1 待处理 / 2 成功 / 3 失败
list[].remark	string	备注
list[].error_msg	string	失败原因（handle_status=3 时有值，否则空串）
list[].create_time / update_time	string	创建 / 更新时间

7.9 运单加油明细查询

POST /enterprise/api/zhyk/waybillQuotaDetail

请求参数

参数名	必填	类型	说明	示例
params.business_license	否	string	传了必须归属本 appId；不传返回名下全部企业聚合数据，须开通权限，`page_size` 上限 200	-
params.waybill_no	否	string	运单号	-
params.waybill_no_code	否	string	运单唯一编号	-
params.iphone	否	string	司机手机号（注意字段名拼写）	186****6666
params.passageway	是	number	1 支付宝企业码 / 2 平安银行	2
params.month	是	string	查询月份，格式 `YYYY-MM`	2025-12
params.page	是	number	页码	1
params.page_size	是	number	每页条数	20

响应 data.order_list[]

字段	类型	说明
business_license	string	营业执照编码
order_code	string	订单号（7.19 获取回单的入参）
waybill_no	string	运单号
waybill_no_code	string	运单唯一编号
quota_id	string	员工凭证（通道侧编号）
iphone	string	员工手机号
passageway	number	1 支付宝 / 2 平安 / 3 智慧油客（历史）
station_code / station_name	string	加油站编号 / 名称
litter	string	加油量（升）
oil_name	string	油品名称
oil_price	number	油价原价（分）
actual_oil_price	number	油价实际价（分）
pay_fee	number	实付（分）
pay_time	string	支付时间
consume_amount	number	额度占用（分）

data.pageInfo：total / page / pageSize。

7.10 运单加油明细推送（异步）

POST http://dev.general.worknoya.work/callback/ygzf/waybillConsumeCallback （我方 → 接入方 的异步消费推送）

推送参数 params.order_list[]

字段	必填	类型	说明
waybill_no	是	string	运单号
order_code	否	string	订单号
waybill_no_code	是	string	运单唯一编号
quota_id	是	string	员工凭证
passageway	是	number	1 支付宝 / 2 平安 / 3 智慧油客（历史）
station_code	否	string	加油站编号
station_name	是	string	加油站名称
pay_fee	是	number	实付费用（分）
pay_time	是	string	支付时间
consume_amount	是	number	占用运单金额（分）
litter	是	string	油量（升）
oil_name	是	string	油品名
oil_price	是	number/null	油品原价（分）
actual_oil_price	是	number/null	油品实际价格

⚠️ 推送用 multipart/form-data，不是 JSON 请求体：业务参数放在表单字段 params 里（JSON 字符串）。

PHP：php://input 在这种 Content-Type 下恒为空，必须取 $_POST['params'] 再 json_decode
Java(Spring)：用 @RequestParam("params") String params，@RequestBody 取不到

接入方需返回：{"code":"100","msg":"Success"}

测试环境可用 7.23 模拟一笔平安消费来联调本回调。

7.11 获取企业账户余额

POST /enterprise/api/zhyk/distributable

说明

平安银行（passageway=2）：实时查询企业在平安银行的主账户余额（银行侧实时查询，不读本地缓存），即当前可发放凭证的资金上限。请按需查询，避免高频轮询。
智慧油客（passageway=3）：预付钱包余额，🚫 已停用，仅存量对接方。
支付宝企业码（passageway=1）：无独立资金账户概念，返回 400「该通道不支持查询账户信息」。
返回金额单位统一为分。
查司机凭证余额请用 7.12。

请求参数

参数名	必填	类型	说明
params.business_license	是	string	营业执照编码，须归属本 appId（平安通道下该校验恒强制）
params.passageway	是	string	2 平安银行 / 3 智慧油客（已停用）

响应 data

字段	类型	说明
balance	string	账户余额（分）；平安=主账户账面余额
available_balance	string	可用余额（分）；平安=已扣除冻结/止付金额

常见错误

HTTP	message	含义
400	该通道不支持查询账户信息	传了 passageway=1
400	营业执照号不能为空	未传 business_license
400	企业信息错误	查不到对应企业
403	企业不存在或无权访问	不属于当前 appId
400	平安银行未配置 / 平安银行企业账户未配置	尚未完成平安开户与账户配置（见 7.2 / 7.4）
400	4001 账户余额查询失败：xxx	银行侧查询未成功，可稍后重试

7.12 司机钱包金额查询

POST /enterprise/api/zhyk/driverBalanceQuery

请求参数

参数名	必填	类型	说明	示例
params.business_license	否	string	传了必须归属本 appId；不传只聚合名下企业，须开通权限，`page_size` 上限 200	-
params.passageway	是	string	1 支付宝 / 2 平安银行	2
params.mobile	是	string	司机手机号	185****2666
params.id_card	是	string	司机身份证号	3***************24
params.page / params.page_size	是	number	分页	1 / 20

响应 data

字段	类型	说明
mobile	string	员工手机号
totalGrantAmount	number	钱包发放总金额（分）
availableBalance	number	当前可用余额（分）
list[].enterprise_name	string	企业名称
list[].business_license	string	企业营业执照编码
list[].total_amount	string	该企业下该司机凭证总额（分）
list[].available_amount	string	该企业下可用余额（分）
pageInfo	object	total / page / pageSize

7.13 司机钱包明细查询

POST /enterprise/api/zhyk/driverWalletQuery

请求参数

参数名	必填	类型	说明	示例
params.business_license	否	string	传了必须归属本 appId；不传只聚合名下企业，须开通权限，`page_size` 上限 200，流水默认只回溯近 1 个月	-
params.passageway	是	string	1 支付宝 / 2 平安银行	2
params.mobile	是	string	司机手机号	186****6666
params.id_card	是	string	司机身份证号	3***************17
params.page / params.page_size	是	number	分页	1 / 20

响应 data

字段	类型	说明
mobile	string	员工手机号
totalGrantAmount	number	钱包发放总金额（分）
availableBalance	number	当前可用余额（分）
transactionDetails[].business_license	string	营业执照编码
transactionDetails[].transactionId	string	交易唯一标识（前缀+时间戳+序号）
transactionDetails[].amount	number	变动金额（正数=发放增量，负数=消费减少量，分）
transactionDetails[].transactionType	string	`adjust_increase`=发放 / `adjust_decrease`=消费
transactionDetails[].transactionTime	string	交易时间
transactionDetails[].remark	string	交易备注
pageInfo	object	total / page / pageSize

7.14 企业发票下载接口

POST /enterprise/api/zhyk/invoice

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码，须归属本 appId（枚举名下企业用 7.22）	9137****LX3K
params.passageway	是	string	1 支付宝企业码 / 2 平安银行	2
params.month	是	string	查询月份 `YYYY-MM`	2026-03
params.mobile	否	string	司机手机号；传入则仅返回该司机相关发票与加油明细，不传返回该企业该月全量	186****6666

响应 data

字段	类型	说明
business_license	string	企业营业执照编号
invoice	array	发票地址集
order_list[]	array	加油明细，字段同 7.9（order_code / waybill_no / quota_id / iphone / passageway / station_code / station_name / litter / oil_name / oil_price / actual_oil_price / pay_fee / pay_time / consume_amount，金额单位分）

7.15 H5 跳转地址（司机免登加油）

地址

测试环境：http://dev.paytaskpage.worknoya.vip/#/
正式环境：https://paytaskpage.worknoya.vip/#/

参数

参数名	必填	说明
appId	是	平台 ID（线下向对接人员获取）。可用企业级通道 appId，或商户级 appId（即调用本章其他接口的 appId）
mobile	是	司机手机号
timestamp	是	请求时间
sign	是	验签，见下
creditcode	否	企业营业执照编号（统一社会信用代码）。传了则本次登录固定到该企业

签名规则（重要）

不传 creditcode：签名参与字段 = appId + mobile + timestamp
传 creditcode：参与字段 = appId + creditcode + mobile + timestamp（未入签会验签失败）
算法：ksort → http_build_query → urldecode → 大写 MD5 → SHA1withRSA → base64

携带 creditcode 后的行为

只在该企业内按手机号定位司机；该企业不存在、未通过审核、或司机不在该企业 → 报错。
⚠️ 该企业必须处于审核通过状态（7.22 返回 status = approved），否则返回「企业尚未通过审核」。
本次登录固定在该企业：响应 enterprise_locked = true，locked_business_license 为该企业营业执照编号；该会话内后续接口（余额、凭证、订单、支付等）取数一律归属该企业。
使用商户级 appId 时，若司机所属企业不在你名下 → 403「无权为该用户签发凭据」（无论是否传 creditcode）。

关于支付通道：本地址与支付通道无关，同一条链接对任何通道的企业都适用，落地页由系统按企业实际使用的通道自动判定，对接方无需按通道切换地址。

登录响应字段

字段	类型	说明
data.enterprise_locked	boolean	本次登录是否已固定企业（传了 creditcode 即 true）
data.locked_business_license	string	固定的企业营业执照编号；未固定时为空串

调用示例

# 不指定企业
https://paytaskpage.worknoya.vip/#/?appId=ykd5daaa&mobile=1859673&timestamp=20251212184431&sign=iwxE****g==#/

# 指定企业（creditcode 须一并入签）
https://paytaskpage.worknoya.vip/#/?appId=ykd5daaa&mobile=1859673&creditcode=9132127B&timestamp=20251212184431&sign=iwxEg==#/

7.16 司机额度调整

POST /enterprise/api/quota/adjustVoucher

business_license 必传且须归属本 appId；quota_id 必须属于该企业。本接口须签名（RSA 验签）调用。

请求参数

参数名	必填	类型	说明	示例
params.passageway	是	string	1 支付宝 / 2 平安银行	2
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.quota_id	是	number	凭证主键 ID（来自 7.17 响应 `data.list.quota_id`）	12345
params.change_type	是	string	变更类型：`02` 增加额度 / `03` 减少额度	02
params.amount	否	number	调整金额（元），change_type=02/03 时必传	100.00
params.operation_reason	否	string	操作原因（最长 200 字符）	油费补发
params.waybill_no	否	string	运单号	A22****2222

响应 data：success（boolean）、message、quota_id。

7.17 获取支付凭证

POST /enterprise/api/quota/getVoucherList

business_license 传入时须归属本 appId。本接口须签名（RSA 验签）调用。

请求参数

参数名	必填	类型	说明	示例
params.passageway	是	string	1 支付宝 / 2 平安银行	2
params.business_license	否	string	传了必须归属本 appId（否则 403）；不传须已开通对应权限，否则 400	9132****127B
params.mobile	是	string	司机手机号	185****2666
params.id_card	是	string	司机身份证号	3***************24
params.page	否	number	页码，默认 1	1
params.page_size	否	number	每页条数，默认 20	20

响应 data.list[]

字段	类型	说明
quota_id	number	凭证主键 ID（7.16 的入参）
quota_number	string	通道侧凭证编号
quota_name	string	凭证名称
total_amount	number	凭证总额度（元）
available_amount	number	可用余额（元）
used_amount	number	已使用额度（元）
freeze_amount	number	冻结金额（元）
effective_start / effective_end	string	凭证生效起止时间
status	string	`active` / `inactive` / `expired` / `frozen`
status_text	string	生效中 / 已作废 / 已过期 / 已冻结
created_time	string	创建时间
employee_id / employee_no / employee_name / mobile	-	员工信息
institution_name	string	关联制度名称

外层还含 data.total / data.page / data.page_size。

7.18 司机三证信息保存

POST /enterprise/api/zhyk/saveDriverDoc

说明

回传司机三证信息（身份证 / 驾驶证 / 行驶证）。仅更新已存在司机：司机须已是该企业员工（可先通过 7.7 建档），否则报错。
姓名与身份证号会走实名二要素核验；证件图片支持外链，系统转存后入库。
图片自动识别（OCR）：驾驶证 / 行驶证若「只传图片、不传字段」，系统会自动 OCR 补全空字段（显式传入的字段优先，不覆盖）；识别失败时降级为仅保存图片，不影响接口成功。身份证号以入参 id_card 为准。
三证均必传，且每证「图片和字段不能同时为空」：
- 身份证：id_card_front_image（图片）或 id_card（字段，已必填）
- 驾驶证：driver_license_image（图片）或 driver_license_no / driver_license_vehicle_type / driver_license_valid_period / driver_license_expiry_date（任一字段）
- 行驶证：vehicle_licenses 至少一条有效行（该行 url 图片，或 plate_no/model/reg_date/owner 任一字段）

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.mobile	是	string	司机手机号	186****6666
params.name	是	string	司机姓名（实名二要素核验）	张**
params.id_card	是	string	司机身份证号（定位司机 + 实名核验）	3***************17
params.id_card_front_image	否	string	身份证正面照地址	https://xxx.png
params.driver_license_image	否	string	驾驶证照片地址	https://xxx.png
params.driver_license_no	否	string	驾驶证号	3***************17
params.driver_license_vehicle_type	否	string	准驾车型	C1
params.driver_license_valid_period	否	string	驾驶证有效期开始	2020-09-05
params.driver_license_expiry_date	否	string	驾驶证到期日	2026-09-05
params.vehicle_licenses	否	array	行驶证列表（至少一条有效行）	-
├ url	否	string	行驶证照片地址	https://xxx.png
├ plate_no	否	string	车牌号	苏A****88
├ model	否	string	车辆型号	解放J6
├ reg_date	否	string	注册日期	2021-05-01
└ owner	否	string	车主	张**

响应 data：status（1 成功）、msg、employee_number（司机编号）。

7.19 支付回单获取（平安银行）

POST /enterprise/api/receipt/getPaymentReceipt

说明

按订单号获取该笔平安（passageway=2）消费订单对应的银行电子回单（PDF / 图片）。
单订单查：order_code 来自 7.9 返回的 data.order_list.order_code，一次查一笔、返回单条。
银行电子回单通常在交易入账后（可能当日晚些 / T+1）才生成，首次查询可能返回 generating，请按 receipt_status 稍后重试；ready 时 receipt.pdf_url 方有下载地址。
通道：当前仅支持平安银行，其他通道返回 receipt_status=unsupported。
回单下载地址为 COS 带签名 URL，有效期有限，请及时下载保存。

请求参数

参数名	必填	类型	说明	示例
params.passageway	是	number	2 平安银行（当前仅支持 2）	2
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.order_code	是	string	订单号（= 7.9 的 `data.order_list.order_code`）	2025****1105571
params.mobile	否	string	司机手机号，传入则做辅助校验（与订单司机不一致时报错）	186****6666
params.consume_time	否	string	消费时间（展示 / 辅助），不传则取该笔交易时间	2026-04-06 12:30:05

响应 data

字段	类型	说明
receipt_status	string	`ready` 已就绪（可下载） / `generating` 获取中（稍后重试） / `not_found` 超时间窗未获取到（终态） / `ambiguous` 多笔同特征需人工核对（终态） / `unsupported` 暂不支持该通道
message	string	状态文案
order	object/null	订单信息（unsupported 时为 null）
order.order_code	string	订单号
order.passageway	number	2 平安银行
order.amount	string	交易金额（元）
order.trade_time	string	交易时间（到秒）
order.trade_status	string	交易状态，如 success
order.merchant_name / store_name	string	商户名称 / 门店名称
order.driver_name / driver_mobile	string	司机姓名 / 手机号
order.consume_time	string	消费时间
receipt	object/null	回单地址（unsupported 时为 null；非 ready 时下方 url 为空串）
receipt.pdf_url	string	回单 PDF 下载地址（COS 带签名，权威件；仅 ready 有值）
receipt.image_url	string	回单图片下载地址（可选附带；仅 ready 有值）

调用示例

curl -X POST "https://{接口域名}/enterprise/api/receipt/getPaymentReceipt" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "appId": "9470****8424",
    "timestamp": 1775030405,
    "sign": "b3c1****e9f2",
    "params": "{\"passageway\":2,\"business_license\":\"9132****127B\",\"order_code\":\"2025****1105571\",\"mobile\":\"186****6666\"}"
  }'

成功响应（回单已就绪）：

{
  "status": "ok",
  "data": {
    "receipt_status": "ready",
    "message": "回单已就绪",
    "order": {
      "order_code": "2025****1105571",
      "passageway": 2,
      "amount": "100.00",
      "trade_time": "2026-04-06 12:30:05",
      "trade_status": "success",
      "merchant_name": "中国石油****销售分公司",
      "store_name": "****加油站",
      "driver_name": "张**",
      "driver_mobile": "186****6666",
      "consume_time": "2026-04-06 12:30:05"
    },
    "receipt": {
      "pdf_url": "https://****/pingan/receipt/20260406/****.pdf?sign=****",
      "image_url": "https://****/pingan/receipt/20260406/****.jpg?sign=****"
    }
  },
  "message": "Success",
  "serialNo": "2025****6656",
  "sign": "LGPc****7A="
}

回单获取中（需稍后重试，url 为空串）：

{
  "status": "ok",
  "data": {
    "receipt_status": "generating",
    "message": "回单尚未生成，请稍后重试",
    "order": { "order_code": "2025****1105571", "passageway": 2, "amount": "100.00", "trade_time": "2026-04-06 12:30:05", "trade_status": "success", "merchant_name": "中国石油****销售分公司", "store_name": "****加油站", "driver_name": "张**", "driver_mobile": "186****6666", "consume_time": "2026-04-06 12:30:05" },
    "receipt": { "pdf_url": "", "image_url": "" }
  },
  "message": "Success",
  "serialNo": "2025****6657",
  "sign": "LGPc****7A="
}

不支持的通道（passageway 非 2）：

{
  "status": "ok",
  "data": {
    "receipt_status": "unsupported",
    "message": "暂不支持该通道，当前仅支持平安银行(passageway=2)",
    "order": null,
    "receipt": null
  },
  "message": "Success",
  "serialNo": "2025****6658",
  "sign": "LGPc****7A="
}

7.20 司机提现到银行卡（平安银行）

POST /enterprise/api/driver-withdraw/withdrawToBank

说明

把司机凭证可用余额提现到指定银行账户，仅支持平安银行（passageway=2）。
异步受理：受理成功返回 data.status=bank_processing，最终结果轮询 7.21。
幂等：out_trade_no 由接入方保证唯一；同一 out_trade_no 重复提交返回同一笔，不会重复打款。
跨行到账：建议同时传收款联行号 in_acct_bank_node。
金额单位为元。

请求参数

参数名	必填	类型	说明	示例
params.passageway	是	number	2 平安银行（当前仅支持 2）	2
params.business_license	是	string	付款企业营业执照编码，须归属本 appId	9132****127B
params.id_card	是	string	提现司机身份证号（在该企业内定位司机）	3***************17
params.in_acct_no	是	string	收款银行账户号（6~32 位数字）	6222****0123
params.in_acct_name	是	string	收款人户名	张**
params.amount	是	string	提现金额（元，正数，最多 2 位小数）	100.00
params.out_trade_no	是	string	第三方交易号（幂等键，接入方系统内唯一）	OUT****0001
params.in_acct_bank_node	否	string	收款联行号（CNAPS，12 位数字；跨行建议传）	3051****0013
params.in_acct_bank_name	否	string	收款开户行 / 支行名称	银行支行

响应 data

字段	类型	说明
withdraw_no	string	提现单号（系统生成，查询用）
out_trade_no	string	第三方交易号（原样返回）
status	string	`system_processing` / `bank_processing` / `success` / `failed`
amount	string	提现金额（元）
fee_rate	string	提现手续费率（%）
fee_amount	string	提现手续费（元）
arrival_amount	string	到账金额（元 = 提现金额 − 手续费）

调用示例

curl -X POST "https://{接口域名}/enterprise/api/driver-withdraw/withdrawToBank" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "appId": "9470****8424",
    "timestamp": 1775030405,
    "sign": "b3c1****e9f2",
    "params": "{\"passageway\":2,\"business_license\":\"9132****127B\",\"id_card\":\"3***************17\",\"in_acct_no\":\"6222****0123\",\"in_acct_name\":\"张**\",\"amount\":\"100.00\",\"out_trade_no\":\"OUT****0001\",\"in_acct_bank_node\":\"3051****0013\"}"
  }'

受理成功：

{
  "status": "ok",
  "data": {
    "withdraw_no": "WD****12345",
    "out_trade_no": "OUT****0001",
    "status": "bank_processing",
    "amount": "100.00",
    "fee_rate": "1.00",
    "fee_amount": "1.00",
    "arrival_amount": "99.00"
  },
  "message": "Success",
  "serialNo": "2025****6656",
  "sign": "LGPc****7A="
}

7.21 提现结果查询（平安银行）

POST /enterprise/api/driver-withdraw/queryWithdraw

查询 7.20 发起的提现单最终状态。受理后按需轮询，直到 data.status 为 success 或 failed。

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	付款企业营业执照编码，须归属本 appId	9132****127B
params.out_trade_no	是	string	提现时传入的第三方交易号	OUT****0001
params.withdraw_no	否	string	提现单号（与 out_trade_no 二选一，优先 out_trade_no）	WD****12345

响应 data

字段	类型	说明
withdraw_no / out_trade_no	string	单号
status	string	`system_processing` / `bank_processing` / `success` / `failed`
amount / fee_rate / fee_amount / arrival_amount	string	金额（元）与费率（%）
fail_reason	string	失败原因（status=failed 时有值，否则空串）
finished_at	string	完成时间（终态时有值，否则空串）

7.22 企业列表查询

POST /enterprise/api/enterprise/list

枚举本 appId 名下的企业，用于获取其他接口所需的 business_license。需先开通企业列表查询权限，未开通返回 403。

请求参数

参数名	必填	类型	说明	示例
params.page	否	number	页码，默认 1	1
params.page_size	否	number	每页条数，默认 20，上限 100（超出按 100 处理）	20
params.name	否	string	企业名称模糊筛选	物流
params.status	否	string	状态精确筛选：pending / submitted / approved / rejected / frozen	approved

响应 data

字段	类型	说明
list[].enterprise_name	string	企业名称
list[].business_license	string	营业执照编号（其他接口的 business_license）
list[].status	string	企业状态，见 2.6
list[].passageway	array	已绑定通道编码，如 `[1,2]`（1 支付宝企业码 / 2 平安银行 / 3 智慧油客（已停用，仅历史数据） / 4 企油通）
list[].passageway_text	array	已绑定通道名称，与 passageway 一一对应，如 `["支付宝","平安银行"]`
pageInfo	object	total / page / pageSize（已按上限收敛后的实际值）

出于安全考虑，本接口不下发企业内部 ID、商户号、联系人手机号等字段。

7.23 平安银行消费回调测试接口（🚫 仅测试环境）

POST /enterprise/api/zhyk/testPinganConsume

说明

测试环境无法触发真实的平安银行线下消费，本接口用于人工模拟一笔消费，方便联调 7.10 的接收端。
在名下企业已存在的平安凭证上模拟消费（不会创建新凭证；司机须已通过 7.7 建档并持有有效凭证）。
调用成功会真实扣减该凭证可用余额，并按 7.10 推送逻辑异步推送到你配置的回调地址（通常 ≤60 秒的下一轮推送周期出队）。
🚫 仅测试环境开放，生产环境一律返回 403。

请求参数

参数名	必填	类型	说明	示例
params.business_license	是	string	营业执照编码，须归属本 appId	9132****127B
params.id_card	是	string	司机身份证号（须已是该企业员工且持有有效平安凭证）	3***************17
params.amount	是	number	消费金额（元）	8.88

响应 data：trade_no（模拟消费流水号）、cert_no（扣款凭证编号）、amount（元）、message。

常见错误

HTTP	message	含义
403	该接口仅测试环境可用	生产环境调用（硬闸门，与配置无关）
400	消费金额不合法	amount 未传 / 非数字 / ≤0
400	企业信息不存在	business_license 不属于当前 appId，或企业不存在
400	未找到该身份证号对应的司机	id_card 未匹配到司机
400	该司机不属于此企业	司机存在但不在该企业下
400	该司机暂无有效的平安凭证，请先通过 createAndSendQuota 发放凭证	需先走 7.7 建档发凭证

5. 对接注意事项（易踩坑汇总）

params 必须是 JSON 字符串，不是对象；form 表单提交会被解析为空。
金额单位不统一：7.7/7.8/7.9/7.10/7.11/7.12/7.13/7.14 用「分」；7.16/7.17/7.19/7.20/7.21/7.23 用「元」。代码里应集中做单位转换。
batch_no / waybill_no / waybill_no_code 当前是全平台唯一，不是接入方内唯一 —— 务必加企业前缀，否则可能与其他接入方撞号。
7.16 / 7.17 必须真实 RSA 验签，否则 403。
不要再传 passageway=3（智慧油客已停用）；但查询返回值中可能出现 3，属历史数据，解析时要兼容。
平安通道下 id_card 必填（7.7 的 employee_list）。
7.7 是异步的，成功只代表受理；结果必须用 7.8 按 batch_no 查。单批人员上限 100。
business_license 归属校验：几乎所有接口都会校验该执照是否属于当前 appId，不属于直接 403。
不传 business_license 的聚合查询（7.9 / 7.12 / 7.13 / 7.17）需要额外权限，且 page_size 上限 200；7.13 默认只回溯近 1 个月流水。
7.19 回单需重试：generating 时稍后再查（可能 T+1）；下载地址是带签名的临时 URL，需及时转存。
7.20 提现幂等靠接入方的 out_trade_no，重复提交不会重复打款；结果需轮询 7.21。
7.11 平安余额是银行侧实时查询，避免高频轮询。
7.15 传 creditcode 时必须一并入签，且目标企业须 approved。
接口域名（测试 / 正式不同）与 appId、密钥均需线下向对接人员获取。

46 KiB Raw Permalink Blame History Unescape Escape

企油通 · 企业通用对接接口文档（第 7 章）

0. 给 Claude Code 的使用说明

1. 对接流程总览

2. 公共约定

2.1 请求信封

2.2 通用响应结构

2.3 登录态

2.4 签名规则

2.5 支付通道（passageway）

2.6 企业状态与凭证状态枚举

2.7 通用错误码

3. 接口清单

4. 接口详情

7.1 企业登录（可选）

7.2 企业申请创建

7.3 企业账户信息推送（智慧油客）🚫 已停用

7.4 企业账户信息推送（平安银行）

7.5 企业账户信息查询

7.6 企业信息查询

7.7 运单油费下发

7.8 运单发放结果查询

7.9 运单加油明细查询

7.10 运单加油明细推送（异步）

7.11 获取企业账户余额

7.12 司机钱包金额查询

7.13 司机钱包明细查询

7.14 企业发票下载接口

7.15 H5 跳转地址（司机免登加油）

7.16 司机额度调整

7.17 获取支付凭证

7.18 司机三证信息保存

7.19 支付回单获取（平安银行）

7.20 司机提现到银行卡（平安银行）

7.21 提现结果查询（平安银行）

7.22 企业列表查询

7.23 平安银行消费回调测试接口（🚫 仅测试环境）

5. 对接注意事项（易踩坑汇总）

46 KiB

Raw Permalink Blame History