Swan Product Api


  • administrators

    增值产品对接接口文档

    api校验

    通过校验的形式确定接入用户的合法性、身份、权限,以及保证请求本身没有被中间篡改。当用户使用API时,应首先向凡泰极客申请api key和api secret

    请求公共参数

    每个调用API请求都必须包含以下公共参数,无论POST还是GET,公共参数都放在url里面以“query string"的方式请求

    参数名 说明 示例
    key api key,唯一代表一个用户的身份 2762aee5-4fa8-437e-85af-1dbfbe466298
    ts 请求的时间戳,格式为ISO8601格式,精确到毫秒。如果不带时区,默认为+0800,即北京时间 2015-08-29T12:31:24.556
    nonce 请求随机字符串,用于保证即便同样的请求,每次产生的签名都不同。``用户应保证每次产生一个随机字符串. 最短8字符,最长32字符。 zXwagyl3ksf
    sigVer 签名算法版本,目前只支持“1” 1
    sig 请求签名,产生方式详见下面 heBO3tbI1FHfhvt5x5cpswMlsCE=

    header通用参数

    所有请求的header里面需要添加X-Consumer-Custom-ID参数,参数值为调用接口的用户id,具体值可以询问凡泰极客

    请求签名如何使用

    签名的使用方式是:

    1. 在请求被发送前根据请求数据和api secret产生一个密钥,并作为请求参数sig的值。sig将会和其他参数一起发给服务器;
    2. 服务器端收到请求后,根据请求数据和内部保存的api secret重新计算一个签名,并将其与请求中sig参数值比较,以决定该请求是否合法。

    步骤1 将所有参数排序和拼接

    将请求中query string和body中所有参数放到一起,按照参数名字典升序排序,以"参数名=参数值"格式拼接每一个参数,最后将所有参数用"&"拼接到一起。 这些拼接到一起的参数包括所有公共参数和api特定的参数

    所谓 按照参数名字典升序排序,举个例子:
    假设有一系列参数的key和value: key2=v2&key1=v1&key4=v4&key3=v3
    参数名字是:key2, key1, key4, key3
    按照字典序排序后是:key1, key2, key3, key4
    排序,然后拼接的参数字符串则是: key1=v1&key2=v2&key3=v3&key4=v4
    

    注意:如果参数的值为空,则该参数不参与拼接和计算。

    步骤2 产生签名

    将步骤1的结果根据api secret产生一个HMAC Sha1摘要(注意:摘要应为2进制格式),并且以Base64编码产生签名. 将步骤1的结果传入HMAC Sha1 进行计算时,要对字符串进行UTF8编码。Mac和部分Linux操作系统默认会采用UTF8编码,所以开发时无需特别指定;但如果是Windows中文版,则会采用GBK编码。在这种情况下,需要在您使用的开发平台上明确指定使用UTF8进行sig的生成。

    sig = base64HmacSha1(apiSecret, encode(unifiedString, 'utf-8'))
    

    接口文档

    增值产品接口

    1. 新增增值产品

    {POST} /api/v1/open/adviserZone/forward/category
    
    RequestBody
    字段 类型 描述
    name string 名称
    picture string 图片
    desc string 描述
    link string 链接
    resourceId string 增值产品原id,用户平台的id
    sucess
    HTTP/1.1 200
    

    2. 增值产品列表

    {GET} /api/v1/open/adviserZone/forward/category
    
    QueryParam
    字段 类型 描述
    available 【可选】 Boolean 名称
    status 【可选】 number 状态 (0, "未上架"),(1, "审核中"),(2, "已拒绝"),(3, "已上架")
    page 【可选】 number 分页号码,默认0
    size 【可选】 number 分页大小,默认10
    sucess
    {
        "content": [
            {
                "id": "5ec38c6d501c0400012bc03f",
                "name": "sunhuiT2", 
                "order": 9, //顺序
                "creator": "@staff_super_M00000:111111.finogeeks.com",
                "creatorName": "超级管理员",
                "updater": "@staff_super_M00000:111111.finogeeks.com",
                "updaterName": "超级管理员",
                "createAt": 1589873773104,
                "updateAt": 1590034636382,
                "tid": "111111.finogeeks.com",
                "mid": "M00000",
                "articleNo": 0,  //文章数量
                "forwardNo": 0,  //转发数量
                "shareNo": 0,   //分享数量
                "viewNo": 0,    //查看数量
                "likeNo": 0,   //点赞数量
                "visitorNo": 0,  //查看
                "available": true,
                "status": 3,
                "groupIds": [  //权限组织
                    "49049240-e0f0-11e9-ac8b-bb3b44d95466",
                ],
                "picture": "https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg",
                "desc": "hello world",
                "link": "https://www.baidu.com",
                "resourceId":"123"
            },
            {
                "id": "5ec35180a7d1c70001a2fcaa",
                "name": "staff1-t",
                "order": 12,
                "creator": "@staff_super_M00000:111111.finogeeks.com",
                "creatorName": "超级管理员",
                "updater": "@staff_super_M00000:111111.finogeeks.com",
                "updaterName": "超级管理员",
                "createAt": 1589858688036,
                "updateAt": 1590041553782,
                "tid": "111111.finogeeks.com",
                "mid": "M00000",
                "articleNo": 0,
                "forwardNo": 0,
                "shareNo": 0,
                "viewNo": 0,
                "likeNo": 0,
                "visitorNo": 0,
                "available": true,
                "status": 3,
                "groupIds": [
                    "49049240-e0f0-11e9-ac8b-bb3b44d95466",
                ],
                "picture": "https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg",
                "desc": "hello world",
                "link": "https://www.baidu.com"
            }
        ],
        "pageable": {
            "sort": {
                "sorted": false,
                "unsorted": true
            },
            "pageSize": 10,
            "pageNumber": 0,
            "offset": 0,
            "unpaged": false,
            "paged": true
        },
        "totalElements": 10,
        "last": true,
        "totalPages": 1,
        "sort": {
            "sorted": false,
            "unsorted": true
        },
        "numberOfElements": 10,
        "first": true,
        "size": 10,
        "number": 0
    }
    

    3. 修改增值产品

    注意:修改增值产品需要先下架

    {PUT} /api/v1/open/adviserZone/forward/category/:id
    
    RequestBody
    字段 类型 描述
    name 【可选】 string 名称
    picture 【可选】 string 图片
    desc 【可选】 string 描述
    link 【可选】 string 链接
    order 【可选】 Int 顺序
    groupIds 【可选】 []string 权限组织id列表

    4. 删除增值产品

    {DELETE} /api/v1/open/adviserZone/forward/category/:id
    
    sucess
    HTTP/1.1 200
    

    5. 增值产品上下架

    {PUT} /api/v1/open/adviserZone/forward/category/available
    
    字段 类型 描述
    categoryId String 名称
    available Boolean true 上架 false 下架
    sucess
    HTTP/1.1 200
    

    文章接口

    1. 新增文章

    {POST} /api/v1/open/adviserZone/forward/articles
    
    RequestBody
    字段 类型 描述
    categoryId String 增值产品id
    available Boolean 是否上架,华西固定为true
    originAuthor string 专家作者
    originAvatar string 专家头像
    originGroup string 专家组织
    link string 文章链接
    sourceId string 文章源Id
    type string 文章类型 : 观点文章 TIMELINE, 长文章 LONG, 转载文章 REPRINT, 行业文章 INDUSTRY,华西选择LONG
    Content Json [<br/> {<br/> "type": "RICH_TEXT",<br/> "data": {<br/> "rich": {<br/> "richText": "富文本内容",<br/> "cover": {<br/> "url": "https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1590473639104&di=769911b15d3e8c34fedebf59812e2098&imgtype=0&src=http%3A%2F%2Fi2.hdslb.com%2Fbfs%2Farchive%2F821e33991046355e89b9de5fe4a82c10707c9ebc.jpg",<br/> "width": 1080,<br/> "height": 297<br/> }<br/> }<br/> }<br/> }<br/> ]
    text string 文本内容
    title string 标题

    2. 编辑修改文章

    要先下架文章,才能编辑文章

    {PUT} /api/v1/open/adviserZone/forward/articles/:id 
    
    RequestBody
    字段 类型 描述
    categoryId String 增值产品id
    available Boolean 是否上架,华西固定为true
    originAuthor string 专家作者
    originAvatar string 专家头像
    originGroup string 专家组织
    link string 文章链接
    sourceId string 文章源Id
    type string 文章类型 : 观点文章 TIMELINE, 长文章 LONG, 转载文章 REPRINT, 行业文章 INDUSTRY,华西选择LONG
    Content Json [<br/> {<br/> "type": "RICH_TEXT",<br/> "data": {<br/> "rich": {<br/> "richText": "富文本内容",<br/> "cover": {<br/> "url": "https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1590473639104&di=769911b15d3e8c34fedebf59812e2098&imgtype=0&src=http%3A%2F%2Fi2.hdslb.com%2Fbfs%2Farchive%2F821e33991046355e89b9de5fe4a82c10707c9ebc.jpg",<br/> "width": 1080,<br/> "height": 297<br/> }<br/> }<br/> }<br/> }<br/> ]
    text string 文本内容
    title string 标题

    3. 文章上下架

    {PUT} /api/v1/open/adviserZone/forward/articles/available
    
    RequestBody
    字段 类型 描述
    articleIds []String 多个文章id
    available Boolean true 上架 false 下架
    sucess
    HTTP/1.1 200
    

    4. 获取文章列表

    {GET} /api/v1/open/adviserZone/forward/articles 
    
    sucess
    {
        "content": [
            {
                "tid": "000000.finogeeks.com",
                "mid": "M00000",
                "id": "5d6d00dc974e6e00013e6508",
                "adviserId": "@staff_super:000000.finogeeks.com",
                "title": "普通的富文本文章",
                "contents": [
                    {
                        "type": "RICH_TEXT",
                        "data": {
                            "rich": {
                                "richText": "",
                                "cover": {
                                    "url": "5d6d00d9d20c160001090040",
                                    "width": 488,
                                    "height": 201
                                }
                            }
                        }
                    }
                ],
                "text": "体育消费政策加码 国资划转社保提速",
                "readNo": 615,
                "status": 3,
                "createAt": 1567424732010,
                "keywords": [
                    "股票",
                    "基金",
                    "股权"
                ],
                "originAuthor": "",
                "type": "LONG",
                "articleId": "AR1909021945328800001",
                "categoryId": "5ecc9ffa03c4940001c7a9d4",
                "recommend": true,
                "available": true,
                "auditor": "@staff_super_M00000:000000.finogeeks.com",
                "auditTime": 1590496850491,
                "referNo": 3,
                "shareNo": 2,
                "likeNo": 0,
                "updater": "@staff_super_M00000:000000.finogeeks.com",
                "updateAt": 1590496828734,
                "version": 2,
                "categoryName": "TD",
                "creatorName": "超级管理员",
                "updaterName": "超级管理员",
                "auditorName": "超级管理员",
                "visitorNo": 191
            }
        ],
        "pageable": {
            "sort": {
                "sorted": false,
                "unsorted": true
            },
            "pageSize": 20,
            "pageNumber": 0,
            "offset": 0,
            "unpaged": false,
            "paged": true
        },
        "totalElements": 551,
        "last": false,
        "totalPages": 28,
        "sort": {
            "sorted": false,
            "unsorted": true
        },
        "numberOfElements": 20,
        "first": true,
        "size": 20,
        "number": 0
    }
    

    5. 删除文章

    删除文章之前,需要先调接口将文章下架

    {DELETE} /api/v1/open/adviserZone/forward/articles/:id
    
    sucess
    HTTP/1.1 200