原文链接： API接口设计和业务逻辑

api 接口是不同程序之间的” 外交语言 “。程序之间通过发送请求参数至接口 url，经过后台处理逻辑，返回所需的结果。

一份完整的接口文档，包含了业务流程、业务要素和交易结构，也部分影响了数据库表设计。

产品、研发、测试可以根据接口文档进行产品设计、开发、测试，毫不夸张的说懂得了接口设计，间接就懂了产品的设计思路。

剩下的工作无非是对细节的填充和文档以及对外沟通讲解，授人以鱼不如授人以渔，我的文章只主要讲渔，一些实例作为示范，以达到知行合一的效果。

以下阐述接口设计的基本设计逻辑和业务逻辑，基于此结合视频课程讲解，以达到具备业务设计的能力。

一、接口设计逻辑

1、接口调用双方：

调用方：根据接口地址传参

被调用方：提供接口服务和地址

查询接口：适合异步结果返回场景

通知接口：适合异步结果通知，以及消息推送场景

2、公共参数

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，放在 header 或 url 参数中。

例如：

版本 version1.0.1

产品代码 10000

项目编码 04055

3、接口入参

接口入参，用于传给接口被调用方的数据，接口被调用方获取到接口调用方的参数后，进行逻辑处理或者保持数据。例如：

授信流水号

客户姓名

客户身份证

4、接口出参

接口被调用方根据处理逻辑结构，接口出参会实时返回给接口调用方，

例如：

响应码（code）

信息描述（message）

响应数据（data）

其中接口响应码可以一个字段，也可以分成两个字段

• 共用一个字段：
  接口成功：0000；

接口失败：

9999 接口失败；

8888 黑名单；

6666 营业时间校验；

5555 年龄校验。

…

• 两个状态用两个字段
  分别是接口响应状态和业务处理状态
  接口响应状态：成功 0000；失败 9999
  业务处理状态：成功、失败、处理中

如果业务处理失败，返回错误原因分类

错误原因

• (证件照片模糊) 1001
• (人脸照模糊) 1002
• 风控原因拒绝 1003
• …..

二、业务逻辑

1、授信流程

• 授信前置校验
  接口描述：校验客户是否命中黑名单，额度互斥等规则
  入参：手机号、姓名、身份证号
  出参：是否通过、拒绝原因
• 授信申请接口
  接口描述：发起授信申请，需要返回是否已受理申请
  入参：
  授信流水号、授信流水号、手机号、 姓名、 身份证号、 身份证正面照片 、身份证背面照片、 大头照 、反欺诈信息 jason 、风险信息 jason 。
  出生日期 、身份证有效期开始时间 、身份证有效期结束时间 、签发机关 、民族、 身份证地址、 性别。

出参：

状态：0000 成功 or9999 失败。

• 授信通知接口
  接口描述：通知授信申请结果
  入参：用户编号 、授信流水号、审核结果 、拒绝错误码 、拒绝原因 、下一次申请时间间隔
  出参：无
• 授信接口查询
  接口描述
• 查询授信申请的处理结果（成功 / 失败 / 处理中）
• 入参
  授信流水号
• 出参
  授信流水号、 审核结果、 用户编号、 拒绝错误码、 拒绝原因、 下一次申请时间
• 额度利率查询
  接口描述：查询账户信息，如授信额度、可用额度

入参：用户编号

出参：额度状态、 授信额度、 可用额度、 合同生效日期 、合同失效日期 年利率

2、用信接口

• 用信申请借款

接口描述：发起借款申请

入参：用户编号 、处理流水号、 贷款金额、 贷款期数、 还款方式 、优惠券 Code、 银行卡号等

出参：状态：0000 成功 or9999 失败。

• 借款试算接口

接口描述：试算客户借款的应还金额

入参：用户编号 贷款金额 贷款期数 还款方式 优惠券 Code

出参：总还款本金 、总利息金额 、总还款金额、 优惠总金额

list {每期到期还款日 、每期还款总额、 每期还款本金、 每期还款利息、 每期优惠金额}end list

• 用信申请查询

接口描述：主动查询还款结果状态

入参：用户编号 、借据号

出参：放款状态、拒绝原因、拒绝码值、放款日期

• 用信申请通知
  接口描述：接收异步的还款结构通知

入参：用户编号 、借款处理流水号 、放款状态 、拒绝码值、 拒绝原因 、放款日期。

出参： 无

三、还款接口

• 还款试算
  接口描述：发起试算返回本次还款的金额

入参：用户编号、借据号 、还款方式

出参：还款总额 、还款本金、 还款利息 、还款罚息

• 还款申请
  接口描述: 发起还款申请

入参：用户编号 、还款流水号 、还款方式、 借据号、 还款金额、 银行卡卡号

出参：还款状态、失败码值、失败原因

• 还款结果通知
  接口描述：主动通知调用方还款结果

入参：用户编号 、还款流水号、 还款状态 、失败码值、失败原因、 还款完成时间

出参：无

• 还款结果查询
  接口描述: 查询还款申请的处理结果（成功 / 失败 / 处理中）

入参：用户编号 、还款处理流水号

出参：还款流水号 、还款状态、 失败码值、 失败原因 、还款完成时间、 还款卡号 、还款本金 、还款利息 、还款罚息 、还款总金额。

• 还款计划查询
  接口描述：查询借据的还款计划

入参：用户编号 、借据号

出参: list{期次、状态、 到期还款日、 罚息、 优惠金额、 本期应还款 、本期应还本金 、本期应还利息}end list

协议查询

• 协议查询
  接口描述：查询授信 / 绑卡 / 借款流程需要签署的协议

入参：

协议类型、 签订时间 、用户姓名、 身份证号码、 申请金额、 用户编号 、申请期数、 还款方式、 银行卡号码、 手机号码

出参:

协议列表、协议名字 、协议类型、协议内容、强制阅读时间、阅读顺序、协议内容类型

• 已签约协议下载
  接口描述：查询授信 / 绑卡 / 借款流程已签署的协议

入参

用户编号、借据号

出参

协议列表、协议名字 、协议类型 、协议内容、 协议内容类型

文件处理

API接口设计和业务逻辑

原创 呱说产品 呱说产品;)

呱说产品

微信号 guatalk

功能介绍 某互联网银行产品经理，金融科技自媒体，免费帮助300+同学解决产品职场问题，关注他还可以加入全国金融产品群。

2022-08-10 08:32 发表于江苏

收录于合集 #信贷流程和系统设计 16个

‍‍

api接口是不同程序之间的”外交语言“。程序之间通过发送请求参数至接口url，经过后台处理逻辑，返回所需的结果。

一份完整的接口文档，包含了业务流程、业务要素和交易结构，也部分影响了数据库表设计。

产品、研发、测试可以根据接口文档进行产品设计、开发、测试，毫不夸张的说懂得了接口设计，间接就懂了产品的设计思路。

剩下的工作无非是对细节的填充和文档以及对外沟通讲解，授人以鱼不如授人以渔，我的文章只主要讲渔，一些实例作为示范，以达到知行合一的效果。

以下阐述接口设计的基本设计逻辑和业务逻辑，基于此结合视频课程讲解，以达到具备业务设计的能力。

一、接口设计逻辑

1、接口调用双方：

调用方：根据接口地址传参

被调用方：提供接口服务和地址

查询接口：适合异步结果返回场景

通知接口：适合异步结果通知，以及消息推送场景

2、公共参数

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，放在header或url参数中。

例如：

版本 version1.0.1

产品代码10000

项目编码 04055

3、接口入参

接口入参，用于传给接口被调用方的数据，接口被调用方获取到接口调用方的参数后，进行逻辑处理或者保持数据。例如：

授信流水号

客户姓名

客户身份证

4、接口出参

接口被调用方根据处理逻辑结构，接口出参会实时返回给接口调用方，

例如：

响应码（code）

信息描述（message）

响应数据（data）

其中接口响应码可以一个字段，也可以分成两个字段

• 共用一个字段：
  接口成功：0000；

接口失败：

9999 接口失败；

8888 黑名单；

6666 营业时间校验；

5555 年龄校验。

…

• 两个状态用两个字段
  分别是接口响应状态和业务处理状态
  接口响应状态：成功0000；失败9999
  业务处理状态：成功、失败、处理中

如果业务处理失败，返回错误原因分类

错误原因

• (证件照片模糊) 1001
• (人脸照模糊) 1002
• 风控原因拒绝 1003
• …..

二、业务逻辑

1、授信流程

• 授信前置校验
  接口描述：校验客户是否命中黑名单，额度互斥等规则
  入参：手机号、姓名、身份证号
  出参：是否通过、拒绝原因
• 授信申请接口
  接口描述：发起授信申请，需要返回是否已受理申请
  入参：
  授信流水号、授信流水号、手机号、 姓名、 身份证号、 身份证正面照片 、身份证背面照片、 大头照 、反欺诈信息 jason 、风险信息 jason 。
  出生日期 、身份证有效期开始时间 、身份证有效期结束时间 、签发机关 、民族、 身份证地址、 性别。

出参：

状态：0000成功 or9999失败。

• 授信通知接口
  接口描述：通知授信申请结果
  入参：用户编号 、授信流水号、审核结果 、拒绝错误码 、拒绝原因 、下一次申请时间间隔
  出参：无
• 授信接口查询
  接口描述
• 查询授信申请的处理结果（成功/失败/处理中）
• 入参
  授信流水号
• 出参
  授信流水号、 审核结果、 用户编号、 拒绝错误码、 拒绝原因、 下一次申请时间
• 额度利率查询
  接口描述：查询账户信息，如授信额度、可用额度

入参：用户编号

出参：额度状态、 授信额度、 可用额度、 合同生效日期 、合同失效日期 年利率

2、用信接口

• 用信申请借款

接口描述：发起借款申请

入参：用户编号 、处理流水号、 贷款金额、 贷款期数、 还款方式 、优惠券Code、 银行卡号等

出参：状态：0000成功 or9999失败。

• 借款试算接口

接口描述：试算客户借款的应还金额

入参：用户编号 贷款金额 贷款期数 还款方式 优惠券Code

出参：总还款本金 、总利息金额 、总还款金额、 优惠总金额

list {每期到期还款日 、每期还款总额、 每期还款本金、 每期还款利息、 每期优惠金额}end list

• 用信申请查询

接口描述：主动查询还款结果状态

入参：用户编号 、借据号

出参：放款状态、拒绝原因、拒绝码值、放款日期

• 用信申请通知
  接口描述：接收异步的还款结构通知

入参：用户编号 、借款处理流水号 、放款状态 、拒绝码值、 拒绝原因 、放款日期。

出参： 无

三、还款接口

• 还款试算
  接口描述：发起试算返回本次还款的金额

入参：用户编号、借据号 、还款方式

出参：还款总额 、还款本金、 还款利息 、还款罚息

• 还款申请
  接口描述:发起还款申请

入参：用户编号 、还款流水号 、还款方式、 借据号、 还款金额、 银行卡卡号

出参：还款状态、失败码值、失败原因

• 还款结果通知
  接口描述：主动通知调用方还款结果

入参：用户编号 、还款流水号、 还款状态 、失败码值、失败原因、 还款完成时间

出参：无

• 还款结果查询
  接口描述:查询还款申请的处理结果（成功/失败/处理中）

入参：用户编号 、还款处理流水号

出参：还款流水号 、还款状态、 失败码值、 失败原因 、还款完成时间、 还款卡号 、还款本金 、还款利息 、还款罚息 、还款总金额。

• 还款计划查询
  接口描述：查询借据的还款计划

入参：用户编号 、借据号

出参:list{期次、状态、 到期还款日、 罚息、 优惠金额、 本期应还款 、本期应还本金 、本期应还利息}end list

协议查询

• 协议查询
  接口描述：查询授信/绑卡/借款流程需要签署的协议

入参：

协议类型、 签订时间 、用户姓名、 身份证号码、 申请金额、 用户编号 、申请期数、 还款方式、 银行卡号码、 手机号码

出参:

协议列表、协议名字 、协议类型、协议内容、强制阅读时间、阅读顺序、协议内容类型

• 已签约协议下载
  接口描述：查询授信/绑卡/借款流程已签署的协议

入参

用户编号、借据号

出参

协议列表、协议名字 、协议类型 、协议内容、 协议内容类型

文件处理

• 文件上传
  接口描述：使用此接口上传文件（身份证正反面照片、人脸照等），返回上传到文件id
• 入参
  用户编号 、流水号、 场景、 文件Base64 类型
• 出参
  文件id
• 文件下载
  接口描述：使用此接口下载文件
• 入参
  文件id
• 出参
  文件Base64 类型

以上即为一份简化版本的api接口文档的骨架，其信息流、文件流都是统一的，其本质是在历史实践经验+基本设计原则的共同基础上决定的。