1041 lines
46 KiB
Markdown
1041 lines
46 KiB
Markdown
# 企油通 · 企业通用对接接口文档（第 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. 对接流程总览
|
||
|
||
四个阶段：企业创建 → 发放油费 → 司机加油 → 获取发票。左侧为业务方（慧明）动作，右侧为企油通接口。
|
||
|
||
```mermaid
|
||
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`，外层信封固定为：
|
||
|
||
```json
|
||
{
|
||
"appId": "9470****8424",
|
||
"timestamp": 1775030405,
|
||
"sign": "b3c1****e9f2",
|
||
"params": "{\"business_license\":\"9132****127B\",\"passageway\":2}"
|
||
}
|
||
```
|
||
|
||
> ⚠️ **`params` 必须是 JSON 字符串（需转义），不是 JSON 对象。**
|
||
> 用 form 表单方式提交会被解析为空，典型报错「营业执照号不能为空」。
|
||
|
||
```bash
|
||
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 通用响应结构
|
||
|
||
```json
|
||
{
|
||
"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 | 固定的企业营业执照编号；未固定时为空串 |
|
||
|
||
**调用示例**
|
||
|
||
```text
|
||
# 不指定企业
|
||
https://paytaskpage.worknoya.vip/#/?appId=ykd5daaa&mobile=1859673×tamp=20251212184431&sign=iwxE****g==#/
|
||
|
||
# 指定企业（creditcode 须一并入签）
|
||
https://paytaskpage.worknoya.vip/#/?appId=ykd5daaa&mobile=1859673&creditcode=9132127B×tamp=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 有值） |
|
||
|
||
**调用示例**
|
||
|
||
```bash
|
||
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\"}"
|
||
}'
|
||
```
|
||
|
||
成功响应（回单已就绪）：
|
||
|
||
```json
|
||
{
|
||
"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 为空串）：
|
||
|
||
```json
|
||
{
|
||
"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）：
|
||
|
||
```json
|
||
{
|
||
"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 | 到账金额（元 = 提现金额 − 手续费） |
|
||
|
||
**调用示例**
|
||
|
||
```bash
|
||
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\"}"
|
||
}'
|
||
```
|
||
|
||
受理成功：
|
||
|
||
```json
|
||
{
|
||
"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. 对接注意事项（易踩坑汇总）
|
||
|
||
1. **`params` 必须是 JSON 字符串**，不是对象；form 表单提交会被解析为空。
|
||
2. **金额单位不统一**：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 用「元」。代码里应集中做单位转换。
|
||
3. **`batch_no` / `waybill_no` / `waybill_no_code` 当前是全平台唯一**，不是接入方内唯一 —— 务必加企业前缀，否则可能与其他接入方撞号。
|
||
4. **7.16 / 7.17 必须真实 RSA 验签**，否则 403。
|
||
5. **不要再传 `passageway=3`**（智慧油客已停用）；但查询返回值中可能出现 3，属历史数据，解析时要兼容。
|
||
6. **平安通道下 `id_card` 必填**（7.7 的 employee_list）。
|
||
7. **7.7 是异步的**，成功只代表受理；结果必须用 7.8 按 `batch_no` 查。单批人员上限 100。
|
||
8. **`business_license` 归属校验**：几乎所有接口都会校验该执照是否属于当前 appId，不属于直接 403。
|
||
9. **不传 `business_license` 的聚合查询**（7.9 / 7.12 / 7.13 / 7.17）需要额外权限，且 `page_size` 上限 200；7.13 默认只回溯近 1 个月流水。
|
||
10. **7.19 回单需重试**：`generating` 时稍后再查（可能 T+1）；下载地址是带签名的临时 URL，需及时转存。
|
||
11. **7.20 提现幂等**靠接入方的 `out_trade_no`，重复提交不会重复打款；结果需轮询 7.21。
|
||
12. **7.11 平安余额是银行侧实时查询**，避免高频轮询。
|
||
13. **7.15 传 creditcode 时必须一并入签**，且目标企业须 `approved`。
|
||
14. **接口域名**（测试 / 正式不同）与 appId、密钥均需线下向对接人员获取。
|