Skip to content

胡边 / weishu-wiki

Go to a project
Toggle navigation
Toggle navigation pinning

App 接口定义

Last edited by hubian
Page History

引言

  1. 本文档主要用于微数贷APP端与后端交互的restful接口定义

  2. 完整的返回内容Response结构为

    {
"code": 0,                   # 状态码，0为正常，500为服务端错误，1001往后即为对应的业务错误返回。
"data":"业务数据",            # 接口返回内容的具体值
"message":"服务端错误",       # 给前端友好提示信息 
"stackTrace":"异常堆栈",      # 500 情况下的错误堆栈信息
}

    后文当中的接口返回内容，都是只表述为【data】里面的内容（注意Key值为驼峰写法，非下划线写法！！！）

  3. 当接口没有指定【Service 子函数逻辑】则标明该API的controller不需要划分子逻辑，实际上即为该API，就一个Controller函数调用一个Service函数或者不调用Service函数，直接Controller里面返回

目录

  • 用户模块
  • 认证模块
  • 银行卡模块
  • 产品模块
  • 贷款（业务）模块
  • 合同模块

1. 用户模块

1.1 用户登录

POST : /app/api/app/customer/login

请求参数RequestBody:

{
    "phoneNumber":"181xxxxxxxx",
    "password":"123456"
}

返回内容Response:

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "customer": {
        "address": "XX市XXX区XXX路XXX号XXX室",
        "cardNumber": "6242286020120432",
        "education": "本科",
        "id": "b03c4039-16de-437d-888f-7f7dbd9a6b14",
        "identifier": "561568413547773374",
        "location": "武汉",
        "marriage": "已婚",
        "name": "孙清",
        "phone": "15848376296",
        "reside": "",
        "status": "还贷中"
    }
}

1.2 用户注册

POST : /app/api/app/customer/register
请求参数RequestBody:

{
    "phoneNumber":"181xxxxxxxx",
    "password":"123456"
}

返回内容Response:

{
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "customer": {
        "address": "",
        "cardNumber": "",
        "education": "",
        "id": "b03c4039-16de-437d-888f-7f7dbd9a6b14",
        "identifier": "",
        "location": "",
        "marriage": "",
        "name": "",
        "phone": "15848376296",
        "reside": "",
        "status": "未认证"
    }
}

【service 子函数逻辑】

锁定到对应的短信服务商

通过该短信服务商，发送短信注册验证码

1.3 用户修改密码

PUT : /app/api/app/customer/{customerId}/password

{
    "oldPassword":"111111",
    "newPassword":"123456"
}

返回内容Response:

{
}

【Service 子函数逻辑】

锁定到对应的短信服务商

通过该短信服务商，发送短信确认修改密码的确认验证码

2. 认证模块

2.1 获取认证汇总状态

GET : /app/api/authentication/{customerId}

返回内容Response

{
    "identifierAuthencation": "finished",
    "faceAuthencation": "unfinished",
    "mobileOperatorAuthencation": "finished",
    "ecommerceAuthencation": "unfinished",
    "jobAuthencation": "finished",
    "linkmanAuthentication": "finished"
}

【Service 子函数逻辑】

获取该用户的各个认证信息列表

把列表信息转移成对应的返回内容格式

2.2 身份认证

2.2.1 获取身份整体信息：

GET : /app/api/authentication/{customerId}/identifierAuthencation
返回内容Response:

{
    "id":"xxxxxxxxxxxxx",
    "scaned_name":"扫描的姓名",
    "input_name":"人工输入的姓名",
    "scaned_identifier":"扫描的身份证号",
    "input_identifier":"输入的身份证号",
    "scaned_address":"扫描的地址",
    "scaned_valid_date":"扫描的有效期",
    "face_identify":"人脸识别认证码",
    "reside":"居住状况",
    "location":"居住所在地",
    "address":"居住详细地址",
    "education":"学历",
    "marriage":"婚姻状况"
}

2.2.2 提交份证认证信息

POST : /app/api/authentication/{customerId}/identifierAuthencation/identifierInfo
请求参数RequestBody

{
    "scaned_name":"扫描的姓名",
    "input_name":"人工输入的姓名",
    "scaned_identifier":"扫描的身份证号",
    "input_identifier":"输入的身份证号",
    "scaned_address":"扫描的地址",
    "scaned_valid_date":"扫描的有效期"
}

返回内容Response

{
    "id":"xxxxxxxxxxxxx",       # identifierAuthentication 实体Id
    "scaned_name":"扫描的姓名",
    "input_name":"人工输入的姓名",
    "scaned_identifier":"扫描的身份证号",
    "input_identifier":"输入的身份证号",
    "scaned_address":"扫描的地址",
    "scaned_valid_date":"扫描的有效期",
    "face_identify":"",
    "reside":"",
    "location":"",
    "address":"",
    "education":"",
    "marriage":""
}

【service 子函数l逻辑】：

判断是否允许二次验证（修改）

调用OCR进行验证，取得验证结果

取得验证结果，是否通过的逻辑分流处理，数据是否插入到数据库

2.2.3 提交人脸识别认证

POST : /app/api/authentication/{customerId}/faceAuthencation
请求参数RequestBody

{
    "faceIdentify":"xxxxxxxxx-xxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxx"
}

返回内容Response

{
    "id":"xxxxxxxxxxxxx",       # identifierAuthentication 实体Id
    "scaned_name":"扫描的姓名",
    "input_name":"人工输入的姓名",
    "scaned_identifier":"扫描的身份证号",
    "input_identifier":"输入的身份证号",
    "scaned_address":"扫描的地址",
    "scaned_valid_date":"扫描的有效期",
    "face_identify":"xxxxxxxxxxxxxxxx-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxx",
    "reside":"",
    "location":"",
    "address":"",
    "education":"",
    "marriage":""
}

2.2.4 提交身份认证里面的其他基本信息（包括人脸识别信息）

POST: /app/api/authentication/{customerId}/identifierAuthencation/basicInfo
说明： 前台APP调用完人脸识别的SDK之后，通过验证之后，调用该接口把其余的信息填充进来
请求参数RequestBody: 

{
    "id":"xxxxxxxxxxxxx",             # identifierAuthentication 实体Id
    "face_identify":"人脸识别认证码",
    "reside":"居住状况",
    "location":"居住所在地",
    "address":"居住详细地址",
    "education":"学历",
    "marriage":"婚姻状况"
}

返回内容Response

{
    "id":"xxxxxxxxxxxxx",
    "scaned_name":"扫描的姓名",
    "input_name":"人工输入的姓名",
    "scaned_identifier":"扫描的身份证号",
    "input_identifier":"输入的身份证号",
    "scaned_address":"扫描的地址",
    "scaned_valid_date":"扫描的有效期",
    "face_identify":"人脸识别认证码",
    "reside":"居住状况",
    "location":"居住所在地",
    "address":"居住详细地址",
    "education":"学历",
    "marriage":"婚姻状况"
}

2.4 手机运营商认证

GET : /app/api/authentication/{customerId}/mobileOperatorAuthencation
PUT : /app/api/authentication/{customerId}/mobileOperatorAuthencation
POST : /app/api/authentication/{customerId}/mobileOperatorAuthencation

2.5 电商账号认证

GET : /app/api/authentication/{customerId}/ecommerceAuthencation
PUT : /app/api/authentication/{customerId}/ecommerceAuthencation
POST : /app/api/authentication/{customerId}/ecommerceAuthencation

2.6 职业信息认证

2.6.1 获取职业认证信息：

GET : /app/api/authentication/{customerId}/jobAuthencation
返回内容Response

{
"career": "经理",
"companyAddress": "XX市XXX区XXX路XXX号XX楼XXX室",
"companyArea": "XX区",
"companyCity": "上海",
"companyName": "XXXX有限公司",
"companyPhone": "18628645372",
"companyProvince": "XX省",
"id": "24c76562-eb01-4035-b843-3de35d85d68a",
"industry": "房产中间",
"salary": "10000"
}

2.6.2 修改职业认证信息：

PUT : /app/api/authentication/{customerId}/jobAuthencation
请求参数RequestBody

    "career": "工程师",
    "companyAddress": "XX市XXX区XXX路XXX号XX楼XXX室",
    "companyArea": "XX区",
    "companyCity": "武汉",
    "companyName": "XXXX有限公司",
    "companyPhone": "13536576671",
    "companyProvince": "XX省",
    "id": "2af27272-006f-4486-90b9-d24a1719aa0f",
    "industry": "房产中间",
    "salary": "8000"

返回内容Response

    "career": "工程师",
    "companyAddress": "XX市XXX区XXX路XXX号XX楼XXX室",
    "companyArea": "XX区",
    "companyCity": "武汉",
    "companyName": "XXXX有限公司",
    "companyPhone": "13536576671",
    "companyProvince": "XX省",
    "id": "2af27272-006f-4486-90b9-d24a1719aa0f",
    "industry": "房产中间",
    "salary": "8000"

2.6.3 提交职业认证信息：

POST : /app/api/authentication/{customerId}/jobAuthencation

请求参数RequestBody

    "career": "普通员工",
    "companyAddress": "XX市XXX区XXX路XXX号XX楼XXX室",
    "companyArea": "XX区",
    "companyCity": "上海",
    "companyName": "XXXX有限公司",
    "companyPhone": "13278119558",
    "companyProvince": "XX省",
    "id": "5a8dbb62-18a0-4c16-89fb-de589c78ea68",
    "industry": "IT",
    "salary": "8000"

返回内容Response

    "career": "普通员工",
    "companyAddress": "XX市XXX区XXX路XXX号XX楼XXX室",
    "companyArea": "XX区",
    "companyCity": "上海",
    "companyName": "XXXX有限公司",
    "companyPhone": "13278119558",
    "companyProvince": "XX省",
    "id": "5a8dbb62-18a0-4c16-89fb-de589c78ea68",
    "industry": "IT",
    "salary": "8000"

2.7 紧急联系人认证

2.7.1 获取紧急联系人认证信息

GET : /app/api/authentication/{customerId}/linkmanAuthentication
返回内容Response

    "firstName": "沈守信",
    "firstPhone": "15310474732",
    "firstRelation": "母亲",
    "id": "6773516e-20d1-424d-a4ee-0b55ae3e7254",
    "secondName": "沈守信",
    "secondPhone": "15391439816",
    "secondRelation": "父亲"

2.7.2 修改紧急联系人认证信息

PUT : /app/api/authentication/{customerId}/linkmanAuthentication
请求参数RequestBody

    "firstName": "毛娜",
    "firstPhone": "13453200978",
    "firstRelation": "母亲",
    "secondName": "陈伟",
    "secondPhone": "13112453688",
    "secondRelation": "父亲"

返回内容Response

    "firstName": "毛娜",
    "firstPhone": "13453200978",
    "firstRelation": "母亲",
    "id": "8038a205-d8d9-42b9-8b6b-1982a51acf54",
    "secondName": "陈伟",
    "secondPhone": "13112453688",
    "secondRelation": "父亲"

2.7.3 提交紧急联系人认证信息

POST : /app/api/authentication/{customerId}/linkmanAuthentication
请求参数RequestBody

    "firstName": "熊振忠",
    "firstPhone": "13035069184",
    "firstRelation": "母亲",
    "secondName": "毛硕",
    "secondPhone": "18631520544",
    "secondRelation": "父亲"

返回内容Response

    "firstName": "熊振忠",
    "firstPhone": "13035069184",
    "firstRelation": "母亲",
    "id": "2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da",
    "secondName": "毛硕",
    "secondPhone": "18631520544",
    "secondRelation": "父亲"

3. 银行卡模块

3.1 获取用户银行卡汇总信息

GET : /app/api/customer/{customerId}/bankCard/list
返回内容Response

[
{
"name": "陈达",
"id"”: "2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da",
"card_number": "6225xxxxxxxxxxxxx",
"deposit_bank": "招商银行上海闵行支行",
"bank_code":"512312",
"create_date":"2017-11-11 11:11:11" 
"status":""
"customer":"2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da"
}
]

3.2 获取银行卡详细信息

GET : /app/api/customer/{customerId}/bankCards/{bankCardId}
返回内容Response

{
"id"”: "2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da",
"name": "陈达",
"card_number": "6225xxxxxxxxxxxxx",
"deposit_bank": "招商银行上海闵行支行",
"bank_code":"512312",
"create_date":"2017-11-11 11:11:11" 
"status":""
"customer":"2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da"
}

3.3 银行卡解绑

DELETE : /app/api/customer/{customerId}/bankCards/{bankCardId}

当用户已用该银行卡做收款的时候，不允许解绑！
跟用户的贷款申请，和放宽记录，来判断这个银行卡是否是可以接棒解绑

3.4 绑定新银行卡

POST: /app/api/customer/{customerId}/bankCards
用户银行卡个数不可以超过三个！
请求参数RequestBody

{
"name": "陈达",
"card_number": "6225xxxxxxxxxxxxx",
"deposit_bank": "招商银行上海闵行支行",
"bank_code":"512312"
}

返回内容Response

{
"id"”: "2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da",
"card_number": "6225xxxxxxxxxxxxx",
"deposit_bank": "招商银行上海闵行支行",
"bank_code":"512312",
"create_date":"2017-11-11 11:11:11" 
"status":""
"customer":"2e4039ab-7fb5-4a4d-b028-b92c0a0ce3da"
}

4. 产品模块

4.1 获取当前生效的产品信息

GET : /app/api/product/enabled
返回内容Response

    "id":"xxxxxxxx-xxxxxxx",
    "name":"产品名称",
    "min_amount":"最小金额(int)",
    "max_amount":"最大金额(int)",
    "min_term":"最短期限天数(int)",
    "max_term":"最长期限天数(int)",
    "service_rate":"服务费比率(float)",
    "outdate_rate":"逾期管理费比率(double)",
    "outdate_fee":"逾期管理服务费(double)",
    "create_date":"创建时间(datetime)",
    "publish_date":"发布时间(datetime)",
    "update_date":"最后更新时间(datetime)",
    "expire_date":"失效时间(datetime)",
    "status":"enabled"

5. 贷款业务模块

5.1 获取历史贷款记录

GET : /app/api/loanApply/history?customerId={customerId} (必选参数) 返回内容Response为一个List，List里面单个的元素内容为：

    "id":"xxxxx-xxxxxxx-xxxxx",
    "apply_amount":"申请金额(int)",
    "actual_amount":"实际金额(int)",
    "term":"期限天数(天数)",
    "service_rate":"服务费比率(float)",
    "outdate_rate":"逾期管理费比率(double)",
    "outdate_fee":"逾期管理服务费(double)",
    "repay_date":"还款日期(datetime)",
    "status":"已还款/已逾期/已拒绝",
    "refuse_code":"拒绝码",
    "refuse_reason":"拒绝原因",
    "customer":"customerId",
    "product":"productId"

5.2 申请贷款

POST : /app/api/loanApply
请求参数RequestBody:

    "apply_amount":"申请金额(int)",
    "term":"期限天数(天数)",
    "customer":"customerId",
    "product":"productId"

返回内容Response

    "id":"xxxxx-xxxxxxx-xxxxx",
    "apply_amount":"申请金额(int)",
    "actual_amount":"实际金额(int)",
    "term":"期限天数(天数)",
    "service_rate":"服务费比率(float)",
    "outdate_rate":"逾期管理费比率(double)",
    "outdate_fee":"逾期管理服务费(double)",
    "repay_date":"还款日期(datetime)",
    "status":"已还款/已逾期/已拒绝",
    "refuse_code":"拒绝码",
    "refuse_reason":"拒绝原因",
    "customer":"customerId",
    "product":"productId"

【Service 子函数逻辑】

调用审批规则链,进入“后台”的审批状态逻辑业务流程

5.3 查看贷款详细信息

GET : /app/api/loanApply/{loanApplyId}
返回内容Response 

 {   
    "id":"xxxxx-贷款申请记录-实体ID-xxxx",
    "apply_amount":"申请金额(int)",
    "actual_amount":"实际金额(int)",
    "term":"期限天数(天数)",
    "service_rate":"服务费比率(float)",
    "outdate_rate":"逾期管理费比率(double)",
    "outdate_fee":"逾期管理服务费(double)",
    "repay_date":"还款日期(datetime)",
    "status":"已还款/已逾期/已拒绝",
    "refuse_code":"拒绝码",
    "refuse_reason":"拒绝原因",
    "customer":"customerId",
    "product":"productId",    
    "loan_repay_record": {
        "id":"xxxxx-还款记录-实体ID-xxxx",
        "repay_time":"还款时间(datetime)",
        "amount":"还款金额(double)",
        "card_number":"还款卡号",
        "bank_name":"还款银行卡银行名称",
        "status":"状态",
        "messags":"",
        "loan_apply":"xxxxx-贷款申请记录-实体ID-xxxx"
    }
}

5.4 还款操作

POST : /app/api/loanApply/{loanApplyId}/bankCard/{bankCardId} 请求参数: 无
返回内容Response

{
        "id":"xxxxx-还款记录-实体ID-xxxx",
        "repay_time":"还款时间(datetime)",
        "amount":"还款金额(double)",
        "card_number":"还款卡号",
        "bank_name":"还款银行卡银行名称",
        "status":"状态",
        "messags":"",
        "loan_apply":"xxxxx-贷款申请记录-实体ID-xxxx"
}

【Service 子函数逻辑】

调用代扣接口，进行代扣操作

生成还款记录

扣款如果失败，需要根据失败原因逻辑分流，是否自动进行重复代扣？？？

6. 合同模块

6.1 注册协议

GET : /app/api/contract/registrationAgreement?customerId=xxxx-客户实体Id-xxxx POST : /app/api/contract/template/registrationAgreement?customerId=xxxx-客户实体Id-xxxx

6.6 服务协议

GET : /app/api/contract/template/serviceAgreement?customerId=xxxx-客户实体Id-xxxx

6.2 代扣协议

GET : /app/api/contract/template/withholdingAgreement?customerId=xxxx-客户实体Id-xxxx POST : /app/api/contract/template/withholdingAgreement?customerId=xxxx-客户实体Id-xxxx

6.3 借款/贷款协议

GET : /app/api/contract/template/loanAgreement?customerId=xxxx-客户实体Id-xxxx POST : /app/api/contract/template/loanAgreement?customerId=xxxx-客户实体Id-xxxx

6.4 淘宝授权协议

GET : /app/api/contract/template/ltaobaoAgreement?customerId=xxxx-客户实体Id-xxxx POST : /app/api/contract/template/loanAgreement?customerId=xxxx-客户实体Id-xxxx

6.5 京东授权协议

GET : /app/api/contract/template/jindongAgreement?customerId=xxxx-客户实体Id-xxxx POST : /app/api/contract/template/jindongAgreement?customerId=xxxx-客户实体Id-xxxx

合同模块的操作实现都是一样的，大相径庭，service子函数逻辑就统一进行说明

【Service 子函数逻辑】

合同编号逻辑

根据合同模版和用户信息，生成注册协议，运营商授权书 ，淘宝授权书，京东授权书内容

根据合同模版和用户信息，加上贷款申请记录，生成注服务协议，代扣协议，借款协议的内容