GPT ADMIN API WIKI 文档
GPT ADMIN API API WIKI
GPT管理后台的API文档
接口调试
可以使用接口中提供的Curl命令进行调试,推荐安装jq来进行Json的序列化显示。
安装方式
Mac os
brew install jq
Windos
官网下载: https://stedolan.github.io/jq/
接口参数格式
目前接口部分使用 HTTP 的 Body 来进行参数传递,接口支持 application/json 的 Body 格式
同时也支持 application/x-www-form-urlencoded 的 Body 格式
两种方式均需要在 Header 中注明内容类型的属性。
请勿使用from-data传递Payload
接口返回说明
第一层 http code返回码,目前常见返回码如下
Http code | 说明 |
---|---|
200 | 调用成功 |
400 | 调用失败,返回自定义错误 |
401 | 鉴权失败 |
403 | 权限不足,没有调用权限 |
500 | 服务器本身出错 |
第二层 接口返回内容中的status和error字段
对于status,我们有如下规定
- status 是一个自然数
- status = 0表示接口调用成功
- status => 0 表示接口调用失败,这一部分错误号是每个接口独立的,同一个错误码在不用接口中会表示不一样的错误,具体错误说明在接口中会说明
错误说明
- 请求体错误,如请求体格式不对此错误一般伴随http 400 返回码
- 请求体错误,如缺少必要的请求参数、参数不合法,此错误一般伴随http 400 返回码
- 所请求的接口对于所携带的token其所属用户来说权限不足,此错误一般伴随http 403 返回码
- 所请求的接口使用了权限控制,但未在系统中登记权限路由名称,此错误一般伴随http 403 返回码
- 所请求的接口使用了权限控制,但未在系统中登记权限路由所属角色关联,此错误一般伴随http 403 返回码
error
为字符串,会给出status的具体错误原因描述,可信赖字段,可直接展示至前端页面
errors (用于表单验证)
为一个对象,会给出status的具体错误原因描述,这个字段适用于程序开发中的错误调试,不应该把他的返回内容作为代码逻辑判断的条件。也不应直接在前端页面显示。
示例
{
"status": 1,
"errors": {
"account": " account 不能为空",
"code": " code 不能为空"
}
}
接口地址说明
http | https | |
---|---|---|
线下 | http://47.112.148.159:9201/ | http://47.112.148.159:9201/ |
预发布 | ||
正式 | 暂无 |
鉴权
接口使用的是基于 rfc6750 的Bearer Token 基于JWT来进行鉴权
我们的Bearer Token 使用的是,在实际业务中并不需要每次调用接口前都去获取Token。
在Token的有效期内可以直接用现有的Token进行接口调用,目前我们的Token 有效期为24小时,过期后则立即失效。此外客户端也可以对Token进行自解,来判断token有效期
访问需要鉴权的接口共需要两步:
- 判断当前Token是否存在或过期,若有异常则重新通过登录授权接口获取Token 。(通过账号密码进行验证,移动端额外需要设备唯一标识传至头部信息)
- 在Http Header中携带已保存的Token。
- 头部信息描述 key为Authorization value为登陆接口返回的Token。
系统鉴权 access
获取Bearer Token
GET_BEARER_TOKEN
获取系统中所使用的
token
curl --request POST \
--url '${API_HOST}/api/access/token' \
--header 'Content-Type: application/json' \
--data-raw '{"token":"xxxxx"}' | jq
{
"status": 0,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImFjcC1hcGkifQ.eyJjb2RlIjoiM2MwZTMyYTciLCJkZXZpY2UiOiI0NSIsImF1ZCI6MzAzLCJpc3MiOiJhY3AtYXBpLWRldmVsb3BtZW50Iiwic3ViIjoiYWNwX21vYmlsZV91c2VyIiwiaWRlbnQiOiIyMGM2MDRiZCIsImlhdCI6MTY1NTk3ODQ5MywiZXhwIjoxNjU2MDY0ODkzfQ.SOXPoyApPWgmQGEkHBiXEjrjkS0FJ4zJxCFTU2Cpiuw",
"token_method": "HS256",
"token_type": "Bearer",
"expire_time": 1656064893
}
}
GET_ACCESS_TOKEN
HTTP Method
POST
HTTP Request
/api/oauth/access
Request Parameters Body
{
"token":"xxxxx",
"state":""
}
Title | Description | Type | Tips |
---|---|---|---|
token | access token | String | 从oa获取,用该token获取子系统的token |
Request Parameters Query
无
Response Data
Title | Type | Description | Tips |
---|---|---|---|
status | int | 状态 0 正常 1为失败 | |
token | string | token 字符串 |
|
token_method | string | 加密方式 | |
token_type | string | token 的类型,目前应该固定为 Bearer |
|
expire_time | int | 过期时间 |
将Token的中段Base64Decode后,可以序列化为一个Payload对象'
Token Payload:
{
"aud": 13, //用户ID
"iss":"we-gather-api-{环境变量}", //当前环境
"sub":"we-gather-user", //颁发方
"iat":1573116338, //颁发时间
"exp":1573119938 //过期时间
}
Payload
Title | Description | Type | Tips |
---|---|---|---|
aud | string | 使用管理员ID | |
iss | string | 颁发方 | |
sub | int | 使用方 | |
iat | int | 颁发时间 | |
exp | int | 过期时间 |
Log
日期 | 作者 | 内容 |
---|---|---|
2023/10/10 | 荀立强 | 新增 |
账号登陆
GET_TOKEN_BY_ACCOUNT
HTTP Method
POST
HTTP Request
/api/oauth/login
Request Parameters Body
{
"account":"xxxxx",
"password":"123456"
}
Title | Description | Type | Tips |
---|---|---|---|
account | 账号 | String | 和oa账号一致 |
password | 密码 | String | 初始密码:123456 |
Request Parameters Query
无
Response Data
Title | Type | Description | Tips |
---|---|---|---|
status | int | 状态 0 正常 1为失败 | |
token | string | token 字符串 |
|
token_method | string | 加密方式 | |
token_type | string | token 的类型,目前应该固定为 Bearer |
|
expire_time | int | 过期时间 |
日期 | 作者 | 内容 |
---|---|---|
2023/10/10 | 荀立强 | 新增 |
{
"status": 0,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IndnX2FkbWluX2FwaSJ9.eyJpc3MiOiJ3Z19hZG1pbl9hcGkiLCJzdWIiOiJzZGsiLCJpZGVudCI6IjBjYzNjYzBjOGFiZjRiODQ4ZjgxODNkYTllOWY5ZGZjIiwiaWF0IjoxNjgxNDQ1MDg4LCJleHAiOjE2ODIwNDk4ODgsIm5hbWUiOiJcdTgzNDBcdTdhY2JcdTVmM2EifQ.o9Ajx0UdXGcdSVDWaWFpseqJg5dBzoS-MgnKV3TBa3c",
"token_method": "HS256",
"token_type": "Bearer",
"expire_time": 1682049888
}
}
用户
用户列表筛选项
GET_USER_SEARCH_ITEM
HTTP Method
GET
HTTP Request
/api/users/search_item
Request Parameters Query
无
Request Parameters Body
无
Response Data
Title | Description | Type | Required | Tips |
---|---|---|---|---|
status | 状态:0成功 非0失败 | integer | 是 | |
data | 数据详情 | object | 是 |
data
Title | Description | Type | Required | Tips |
---|---|---|---|---|
status | 状态:0成功 非0失败 | integer | 是 | |
data | SearchItem |
object | 是 |
SearchItem
Title | Description | Type | Required | Tips |
---|---|---|---|---|
可筛选的key | 可筛选的key | []Search |
是 | 可在query中使用 |
Search
可筛选的值
Title | Description | Type | Required | Tips |
---|---|---|---|---|
label | 展示文本 | string | 是 | |
value | 可筛选值 | int | 是 |
Response Data Json
{
"status": 0,
"data": {
"rights_status": [
{
"label": "未开通",
"value": 0
},
{
"label": "生效中",
"value": 1
},
{
"label": "已过期",
"value": 2
}
]
}
}
用户列表
GET_USER_LIST
HTTP Method
GET
HTTP Request
/api/users
Request Parameters Query
Title | Description | Type | Required | Tips |
---|---|---|---|---|
id | 集微GPT用户ID | string | 否 | JWGPTYH000000001 |
nickname | 用户昵称 | string | 否 | |
phone | 搜索手机号 | string | 否 | |
created_at | 注册时间 | [datetime, datetime] | 否 | [2023-04-01 12:12:01,2023-04-02 12:12:01] |
rights_status | 权益状态 | int | 否 | 0未开通 1生效中 2已过期 |
sort | 排序方式 | string | 否 | asc正序、默认倒叙 |
Request Parameters Body
无
Response Json
{
"status": 0,
"data": {
"current_page": 1,
"last_page": 1,
"total": 1,
"data": [
{
"id": 1,
"user_id": 1,
"rights_status": 1,
"created_at": "2023-10-10T10:34:55.000000Z",
"mobile": "18352764050",
"nickname": "爱集微",
"avatar": "jwImg/avatar/2020/02/28/15828720842371blob",
"gpt_user_id": "JWGPTYH000000001"
}
]
}
}
Response Data
Title | Description | Type | Tips |
---|---|---|---|
date | 订单数据 | Object |
Date Object
Title | Description | Type | Tips |
---|---|---|---|
id | GPT用户ID | int | |
user_id | 集微用户ID | int | |
nickname | 昵称 | string | |
mobile | 手机号 | string | |
avatar | 头像 | string | |
rights_status | 权益状态 | int | 0未开通 1生效中 2已过期 |
gpt_user_id | GPT用户ID格式化 | string | 仅展示用,业务逻辑依然用 id 字段 |
Log
日期 | 作者 | 内容 |
---|---|---|
2023/10/10 | 荀立强 | 新增 |