gxwebsoft/mp-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1e2ec82c18ac00ee67dcf46fd4d4afa0759b3611
mp-java/docs/一站式平台对接-接口文档.md
T

9.1 KiB
Raw Blame History

汇吉采 ↔ 一站式代理平台 对接接口文档

版本：v1.0 适用：汇吉采标书购买平台（下称「官方网」）与一站式代理平台（下称「一站式」）之间双向数据互通。 相关：鉴权规则见 docs/一站式平台推送-接口鉴权规范.md；建表见 src/main/resources/sql/hjc_init.sql。

0. 概述

方向 触发时机 接口 位置
入向（一站式 → 官方网） 项目流程走到「发布中标公告」时 POST {官方网}/api/hjc/push/project 官方网接收标书/中标公告数据，按 projectNo upsert 落库
出向（官方网 → 一站式） C 端购买标书支付成功后 / 退款时 POST {一站式}/api/biz/createPurchaseDetails 官方网把购买记录/订单信息推送到一站式落盘

共享凭证（双方约定，不通过网络传输明文密钥）：

参数 值 说明
appKey HJC_Official_Website 调用方标识，明文放请求头
password vQ8$kR3#mW6@xP2!nF 签名密钥（Secret），仅参与签名，不进报文

1. 鉴权规范（双向通用）

请求头携带：

Header 示例 说明
appKey HJC_Official_Website 双方一致
timestamp 202604080103 格式 yyyyMMddHHmm（24 小时，北京时区，精确到分）
sign 9f7c…（32位小写hex） 签名值

签名算法：sign = MD5(appKey + password + timestamp)（无分隔符，小写 32 位）。

校验顺序（任一步不过即拒绝，建议返回 401/400）：

  1. appKey == HJC_Official_Website
  2. timestamp 与接收方服务器当前时间差 ≤ ±10 分钟（防重放）
  3. 用约定 password 重算 MD5(appKey+password+timestamp)，与 sign 不区分大小写比对

完整规则、示例（Python/Java）与「明文 password 头」兼容退路见 docs/一站式平台推送-接口鉴权规范.md。

2. 入向接口：一站式 → 官方网（接收标书/中标公告）

2.1 接口地址

POST {官方网BaseUrl}/api/hjc/push/project

官方网侧需在 SecurityConfig 放行该路径（已内置，/api/hjc/push/project 为公开接口，鉴权由本接口的 appKey/sign 自行校验）。

2.2 请求头

Header 值
appKey HJC_Official_Website
timestamp yyyyMMddHHmm
sign MD5(appKey+password+timestamp)
tenantId 10626（官方网当前固定租户，必传，作为落库租户）
Content-Type application/json

2.3 请求体字段

字段 类型 必填 说明 对应内部字段
projectNo string ✔ 项目编号 project_no（upsert 主键）
projectName string ✔ 项目名称 project_name
tenderPrice number 标书价格/信息服务费 tender_price
files string(JSON/逗号分隔) 标书附件 tender_file
tenderOnsaleTime string 开售时间 yyyy-MM-dd HH:mm:ss onsale_time
tenderOffsaleTime string 停售时间 yyyy-MM-dd HH:mm:ss offsale_time
bulletinName string 公告标题 bulletin_title
customerName string 招标人 tenderer
supplierName string 中标公司 winner_supplier
bidAmount number 中标金额 bid_amount
content string 公告正文 bulletin_content
fileList string(JSON/逗号分隔) 公告附件 bulletin_file_list
needSellTender number 是否卖标书 0/1 need_sell
sellingMethod number 售卖方式 1公司财务 2公众号 3交易中心 4政采云 selling_method

2.4 响应

{
  "code": 0,
  "message": "接收成功",
  "data": { "id": 12, "projectNo": "ZB-2026-0001", "projectName": "xxx", "dataSource": "PUSH", "status": 1 }
}
  • code == 0 成功；code != 0 失败（如 message=鉴权失败 / 租户ID不能为空 / 项目编号不能为空）。

2.5 落库规则（官方网侧）

  • 按 projectNo upsert：不存在则插入（tenantId=请求头tenantId，status=1 上架，dataSource=PUSH，saleCount=0）；已存在则更新推送到字段。
  • 兼容性：tenderOnsaleTime/tenderOffsaleTime 支持 yyyy-MM-dd HH:mm:ss、yyyyMMddHHmmss、ISO 带 T 三种格式解析；解析失败置空。
  • 其余标书项目字段（分类、上下架、人工维护数据）仍可在管理后台手工调整。

3. 出向接口：官方网 → 一站式（推送购买记录/订单）

3.1 接口地址

POST {一站式BaseUrl}/api/biz/createPurchaseDetails

3.2 触发时机

  • 支付成功后（官方网 PUT /api/hjc/order/mark-paid 置已付）自动推送，请求状态 status=PAID。
  • 退款时（官方网 POST /api/hjc/order/refund 置已退款）推送，请求状态 status=REFUNDED。

3.3 请求头

Header 值
appKey HJC_Official_Website
timestamp yyyyMMddHHmm
sign MD5(appKey+password+timestamp)
Content-Type application/json

password 不进请求头；sign 每次发送须按新的 timestamp 重新计算。

3.4 请求体字段

字段 类型 说明
idempotencyKey string 幂等键，HJC_ORD_<orderNo>
orderNo string 官方网订单号（一站式去重键）
projectNo string 项目编号
projectName string 项目名称
tenderPrice number 标书单价（信息服务费）
quantity number 购买数量
totalAmount number 订单总额
buyer.enterpriseName string 购买企业名称
buyer.creditCode string 企业统一社会信用代码
buyer.contactName string 经办人姓名
buyer.contactPhone string 经办人手机号
buyer.contactEmail string 经办人邮箱
paidAt string 支付时间 yyyy-MM-dd HH:mm:ss
payMethod string WECHAT_NATIVE / ALIPAY
status string PAID（已支付）/ REFUNDED（已退款）
invoiceStatus string NONE / APPLIED / ISSUED

请求体示例：

{
  "idempotencyKey": "HJC_ORD_HJC2026080101ABCD",
  "orderNo": "HJC2026080101ABCD",
  "projectNo": "ZB-2026-0001",
  "projectName": "xxx采购项目",
  "tenderPrice": 500.00,
  "quantity": 1,
  "totalAmount": 500.00,
  "buyer": {
    "enterpriseName": "某某科技有限公司",
    "creditCode": "91110XXXX",
    "contactName": "张三",
    "contactPhone": "13800000000",
    "contactEmail": "a@b.com"
  },
  "paidAt": "2026-08-01 10:30:00",
  "payMethod": "WECHAT_NATIVE",
  "status": "PAID",
  "invoiceStatus": "NONE"
}

3.5 响应约定

  • 一站式按自身 API 返回；官方网侧把 HTTP 2xx 视为成功，否则记入推送日志（hjc_order_push_log）待重试。
  • 幂等：建议一站式以 orderNo/idempotencyKey 去重，同单重复提交返回成功、不重复插入。

3.6 重试策略（官方网侧）

  • 失败（非 2xx / 网络异常）写入 push_status=2，next_retry_time = now + 30min，attempt_count + 1。
  • 由定时任务 retryPendingPush() 扫描待推送/失败记录重发；重发时 timestamp/sign 重新计算。

4. 字段映射总表

一站式字段 含义 官方网内部字段
projectNo 项目编号 hjc_bid_project.project_no
projectName 项目名称 project_name
tenderPrice 标书价格 tender_price
files 标书附件 tender_file
tenderOnsaleTime 开售时间 onsale_time
tenderOffsaleTime 停售时间 offsale_time
bulletinName 公告标题 bulletin_title
customerName 招标人 tenderer
supplierName 中标公司 winner_supplier
bidAmount 中标金额 bid_amount
content 公告正文 bulletin_content
fileList 公告附件 bulletin_file_list
needSellTender 是否卖标书 need_sell
sellingMethod 售卖方式 selling_method

5. 配置清单（待双方/部署方填写）

项 值 位置
官方网 base-url http://<官方网域名>/api 一站式侧调用方配置
一站式 base-url http://<一站式域名> mp-java/application.yml → hjc.one-stop.base-url
createPurchaseDetails 路径 /api/biz/createPurchaseDetails hjc.one-stop.create-purchase-details-path
appKey HJC_Official_Website 双方约定
password vQ8$kR3#mW6@xP2!nF 双方约定
租户 ID 10626 官方网请求头 tenantId

6. 待确认事项

  1. 出向 sign 拼接顺序（appKey+password+timestamp）与一站式既有算法是否一致；不一致请给出一站式现网签名规范。
  2. timestamp 格式、时区、±10min 窗口是否认可。
  3. createPurchaseDetails 字段名是否需与一站式现网入参完全一致（现按本表定义）；如需调整字段名请给出一站式入参清单。
  4. 入向：一站式调用官方网 /api/hjc/push/project 时是否也按同一套 appKey/timestamp/sign 鉴权（本表默认对称鉴权）。
Reference in New Issue View Git Blame Copy Permalink