API接口设计和业务逻辑

发布日期：2022/8/24 11:36:32      浏览量：

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接口文档的骨架，其信息流、文件流都是统一的，其本质是在历史实践经验+基本设计原则的共同基础上决定的。