百福得开放平台
  • 接口文档
  • 开发指南
2023-09-26
目录

开发前必读

# 开发前必读

本文档面向第三方开发者，全面介绍百福得开放平台的接入流程、核心概念及业务模块。建议在开发前仔细阅读，以确保顺利接入。

# 一、平台概述

百福得开放平台提供企业福利数字化解决方案，支持以下核心能力：

能力模块 说明
免密登录 支持 PC/H5/小程序多端的单点登录接入
组织架构同步 部门、员工信息的实时同步与管理
积分/收银台体系 用户积分查询、扣款、退款
订单管理 订单查询、对账、物流跟踪
用户资金 账户余额、明细查询、资金发放
差旅管理 出差申请、行程核销
勋章体系 企业勋章创建、发放、管理
消息推送 系统消息、通知对接

# 二、环境信息

# 2.1 域名地址

环境 域名 用途
测试环境 https://open-dbenefit-stage.dongfangfuli.com 开发联调、功能验证
生产环境 https://open-dbenefit.dongfangfuli.com 正式业务运行

# 2.2 东福出口IP

如贵方系统有 IP 白名单限制，需放行以下东福服务器出口 IP：

环境 出口IP
东福生产环境 139.224.23.188
东福测试环境 139.224.23.188
东福办公环境 58.246.229.90,58.247.132.250,112.64.110.163

提示

上线前请务必在测试环境完成全部功能验证，再切换至生产环境。

# 2.2 更新日志

日期 更新内容
2025-03-05 积分支付增加结果3.4查询接口
2024-06-26 增加消息对接接口规范示例
2023-05-17 部门&用户推送调整为异步保存
2023-05-05 离职日期支持置空
2023-03-09 增加支付回调&退款回调标准接口
2023-02-27 增加对账单接口和支付单查询
2023-01-05 新增勋章类接口
2022-12-16 福豆充值支持子账户传参

# 三、接入准备

# 3.1 获取应用凭证

接入前需向百福得平台申请以下凭证：

凭证 说明 获取方式
appId 应用唯一标识 平台分配
appSecret 应用密钥，用于接口签名 平台分配

安全提示

  • appSecret 是双方保管的密钥，请勿在 HTTP 请求中传递
  • 一旦泄露，请立即联系平台申请更换
  • 生产环境与测试环境的凭证相互独立

# 3.2 技术准备

项目 要求
开发语言 不限，支持 HTTP 请求即可
签名算法 MD5
时间戳格式 毫秒级 Unix 时间戳
编码格式 UTF-8
网络协议 HTTPS

# 3.3 示例代码

快速开始

完整的接入示例代码（Java/C#/GO/NodeJs/PHP/Python）已开源，请参考：bfd-open-demo (opens new window)

# 四、接口调用规范

# 4.1 调用流程

┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
│  获取凭证    │ --> │  调用业务接口    │ --> │  处理响应    │
│ (accessToken)│     │ (携带签名)       │     │ (JSON格式)   │
└─────────────┘     └─────────────────┘     └─────────────┘
1
2
3
4

核心步骤：

  1. 获取 AccessToken - 使用 appId + appSecret 换取访问令牌（有效期 7200 秒）
  2. 构造请求参数 - 按规范添加公共参数（appId、timestamp、sign 等）
  3. 生成签名 - 使用 MD5 算法对所有参数签名
  4. 调用接口 - 发送 HTTP 请求，处理返回结果

# 4.2 请求格式

  • Content-Type：application/json 或 URL 地址栏传参
  • HTTP 方法：POST（部分接口支持 GET）
  • 编码格式：UTF-8

注意

获取 AccessToken 接口不支持 application/json 传参，请使用application/x-www-form-urlencoded或 URL 参数格式。

# 4.3 公共参数

所有业务接口均需携带以下公共参数：

参数名 类型 必填 说明
appId String 是 应用唯一标识
timestamp String 是 毫秒级时间戳，偏差需在 5 分钟内
sign String 是 MD5 签名值

# 4.4 响应格式

{
  "code": 0,
  "msg": "OK",
  "data": { }
}
1
2
3
4
5
字段 类型 说明
code Integer 返回码，0 表示成功，其他表示错误，详见错误码
msg String 错误信息（成功时为 "OK"）
data Object 业务数据（错误时可能为空）

# 五、签名机制

所有接口请求均需携带签名参数 sign，用于验证请求合法性。

# 5.1 签名规则

  1. 将 appSecret 加入参数列表（但不参与 HTTP 传输）
  2. 对所有参数的 key 进行字典升序（ASCII 升序）排列
  3. 按 key1value1key2value2... 格式拼接字符串（去除首尾空格）
  4. 使用 MD5 算法计算签名值（32位小写）

# 5.2 签名示例

假设请求参数如下：

参数名 参数值
appId abc123
timestamp 1597300776947
appSecret your_app_secret

签名步骤：

  1. 参数按 key 升序排列：appId, appSecret, timestamp
  2. 拼接字符串：appIdabc123appSecretyour_app_secrettimestamp1597300776947
  3. MD5 加密后得到签名值

详细签名说明及 Java/PHP/Python 代码示例请参考：MD5签名

# 5.3 签名注意事项

  • URL 地址栏中除 sign 外的所有参数均需参与签名计算
  • 参数值为空字符串时，仍需参与签名（格式为 key）
  • 参数值为 null 或不传时，不参与签名

# 六、登录接入方案

# 6.1 方案对比

方案 前提条件 推荐度
签名登录（新版） 无需先同步用户信息 ⭐⭐⭐ 兼容
授权码登录（旧版） 需先同步用户信息 ⭐ 兼容

# 6.2 签名登录（新版推荐）

适用场景： 合作伙伴（工会）暂时缺少授权中心，无法提供免登授权接口。

接入流程：

┌─────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────┐
│  用户   │ -> │ 客户系统签名 │ -> │ 百福得验签  │ -> │ 登录成功 │
│ 访问    │    │ 生成免密链接 │    │ 跳转商城    │    │         │
└─────────┘    └─────────────┘    └─────────────┘    └─────────┘
1
2
3
4

接入步骤：

  1. 调用方根据 appId、appSecret、时间戳、账号等信息进行 MD5 签名
  2. 前端根据生成的免密链接，直接重定向到百福得验签地址
  3. 验证通过则登录福利商城系统，失败则跳转错误页

参考文档：

  • [1.6 PC/H5 免密授权登录](/接口文档/01.一、免密登录/06.1.6 免密授权登录（客户方应用内嵌东福H5页面）/)
  • [1.7 小程序免密授权登录](/接口文档/01.一、免密登录/07.1.7 免密授权登录（客户方小程序跳转百福得小程序）/)

# 6.3 授权码登录（旧版）

前置条件

该方案要求接入方的用户信息已存在于百福得系统中。若不存在，请先同步用户信息，参考组织架构同步

接入流程：

┌─────────┐    ┌──────────────┐    ┌──────────────┐    ┌─────────┐
│ 获取    │ -> │ 获取授权码    │ -> │ 重定向授权   │ -> │ 登录成功 │
│ AccessToken    │ auth_code    │    │ 地址验证     │    │         │
└─────────┘    └──────────────┘    └──────────────┘    └─────────┘
1
2
3
4

接入步骤：

  1. 调用方根据 appId、appSecret 获取授权访问凭证 AccessToken
  2. 根据用户账号、AccessToken 获取账号授权码 auth_code
  3. 根据 auth_code、AccessToken 重定向到授权地址
  4. 验证通过则登录福利商城系统，失败则跳转错误页

参考文档：

  • [1.1 获取accessToken](/接口文档/01.一、免密登录/01.1.1 获取accessToken/)
  • [1.3 获取临时授权码](/接口文档/01.一、免密登录/03.1.3 【旧版】根据账号获取临时授权码)
  • [1.4 授权码登录](/接口文档/01.一、免密登录/04.1.4 【旧版】授权码登录)

# 七、技术支持

如在接入过程中遇到问题，请按以下方式联系：

渠道 联系方式
技术支持 请联系您的百福得对接人
文档反馈 如发现文档问题，欢迎反馈

建议开发前准备：

  • [ ] 已获取测试环境 appId 和 appSecret
  • [ ] 已配置测试环境 IP 白名单
  • [ ] 已阅读 MD5签名 文档
  • [ ] 已确定接入的登录方案（签名登录/授权码登录）
  • [ ] 已明确需要对接的业务模块

祝接入顺利！

1.1 获取accessToken→

Theme by Vdoing