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

协议查询

协议查询

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

入参：

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

出参:

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

已签约协议下载

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

入参

用户编号、借据号

出参

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

文件处理

文件上传

接口描述：使用此接口上传文件（身份证正反面照片、人脸照等），返回上传到文件id

入参

用户编号 、流水号、 场景、 文件Base64 类型

出参

文件id

文件下载

接口描述：使用此接口下载文件

入参

文件id

出参

文件Base64 类型

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